1. openrig 到底是个什么东西第一次看到 openrig 这个名字我下意识以为是某个硬件外设的开源项目毕竟 rig 这个词在英文里本就有“装配、设备”的意思。但翻了一圈社区讨论和实际代码之后才明白它其实是一个围绕 AI 编程助手做本地化编排与调度的工具层核心目标是把 Claude Code、Codex 这类命令行 AI 编程工具跟本地的 Node.js 运行时、tmux 会话管理、以及各种第三方模型接口串起来形成一个可复用、可切换、可观测的工作台。说白了openrig 解决的是一个很具体的痛点当你同时用 Claude Code 写一个模块、用 Codex 跑另一个仓库的重构、还想让它们调用本地 LM Studio 里的模型或者 DeepSeek、Qwen、GLM 这类第三方接口时你会发现自己陷入了一个极其混乱的状态——多个终端窗口、多套环境变量、多个 API Key、不同的模型配置、时不时断掉的会话还有那些让人抓狂的报错比如cc switch local proxy failed while handling codex endpoint /responses或者the gpt-5.6-sol model is not supported when using codex。openrig 想做的事情就是把这些零散的东西收拢到一个统一的编排层里。它适合谁我觉得有三类人特别需要第一类是已经在用 Claude Code 或 Codex 做日常开发的工程师手里有多个项目、多个模型来源需要一个统一入口第二类是想在本地跑模型、又不想放弃云端模型能力的开发者需要在本地和远程之间灵活切换第三类是刚接触这类工具的新手被 Node.js 安装、环境变量配置、API 接入这些前置步骤卡住需要一个相对完整的参考路径。这篇文章我会从整体设计思路讲到具体实操把 openrig 涉及的核心环节拆开来说包括 Node.js 环境、tmux 会话、Claude Code 与 Codex 的接入、第三方模型的切换以及那些我实际踩过的坑。2. 整体设计与思路拆解2.1 为什么需要一个编排层而不是直接用原生命令Claude Code 和 Codex 本身都是命令行工具单独用起来并不复杂。Claude Code 装完之后在项目目录里跑起来它就能读文件、执行终端命令、改代码Codex 也是类似的交互模式。但问题在于当你把这两个工具放在同一个工作流里事情就开始变得复杂了。我举个实际场景我手头有一个 Node.js 后端项目和一个前端项目后端重构我想用 Codex 来做因为它在某些代码生成任务上风格更稳前端组件的快速迭代我想用 Claude Code因为它的对话式交互更顺手。同时后端有些敏感逻辑我不想发到云端想走本地 LM Studio 的模型前端则可以走第三方 API。这时候我需要管理的东西就包括两套工具的安装和版本、两套 API 配置、本地模型和远程模型的切换逻辑、多个终端会话的保持、以及不同项目目录下的环境隔离。如果不用编排层我的做法就是开一堆终端标签页每个标签页里手动 export 不同的环境变量然后祈祷自己别搞混。这种做法的脆弱性在于一旦某个会话断了或者我关错了窗口恢复成本很高而且环境变量是全局的切换模型来源时很容易污染当前会话。openrig 的价值就在于把这些状态显式地管理起来用 tmux 做会话保持用统一的配置层做模型切换用 Node.js 做工具链的运行时基础。2.2 技术选型背后的逻辑openrig 选择 Node.js 作为运行时基础这个决定其实很自然。Claude Code 和 Codex 的 CLI 本身很多就是 Node.js 生态的产物安装方式通常是npm install -g或者通过 npx 调用。Node.js 20 的 LTS 版本提供了稳定的模块系统和较好的性能对于这类工具链来说够用且生态成熟。我在 Ubuntu 上装 Node.js 20 的时候习惯用 NodeSource 的源而不是系统自带的 apt 版本因为系统自带的往往版本太老跑新工具会报各种兼容错误。tmux 的引入是另一个关键决策。AI 编程助手的一个特点是会话时间长——你可能让它跑一个重构任务中间去开个会回来还想接着看它的输出。普通的终端窗口一旦关闭进程就没了。tmux 的会话保持能力让这些长任务可以在后台持续运行你随时 attach 回去看状态。而且 tmux 支持分屏你可以一个 pane 跑 Claude Code一个 pane 跑 Codex一个 pane 看日志这种布局对于多工具协同来说非常实用。至于模型切换层这是 openrig 最核心也最容易出问题的部分。Claude Code 和 Codex 各自有自己的模型配置方式Claude Code 通过环境变量或者配置文件指定 API 端点和 KeyCodex 也有类似的机制。当你想要在 DeepSeek、Qwen、GLM、本地 LM Studio 之间切换时本质上是在切换 API 端点、模型名称和认证信息。openrig 把这层抽象出来让你用一套配置描述多个模型来源然后在运行时选择用哪个。这个思路是对的但实现上会遇到很多细节问题比如不同模型对请求格式的要求不一样有些模型不支持某些参数有些端点对并发有限制。2.3 与直接使用 cc switch 这类方案的对比社区里有人用 cc switch 这类工具来做模型切换它的思路更轻量主要是改配置文件然后重启工具。openrig 如果要做编排层相比这种轻量方案的优势在于它能管理更复杂的状态——不只是模型切换还有会话管理、多工具协同、日志聚合。但代价是复杂度更高配置项更多出问题时排查链路更长。我的建议是如果你只是偶尔切换一下模型cc switch 这类工具足够了如果你每天都在多个工具、多个模型、多个项目之间切换那 openrig 这种编排层的价值才能体现出来。不要为了用而用工具的选择应该匹配你的实际工作流复杂度。3. 核心细节解析与实操要点3.1 Node.js 环境的正确安装方式Node.js 是这一切的基础装错了后面全是坑。我在 Ubuntu 上试过三种安装方式这里直接给结论。第一种是apt install nodejs这是最省事的但 Ubuntu 仓库里的版本通常落后好几个大版本。你装完之后跑node -v可能看到 v12 或者 v14而 Claude Code 和 Codex 通常要求 Node.js 18 以上最好是 20 LTS。版本不够会直接导致安装失败报错信息往往很隐晦比如某个模块的语法不支持。第二种是通过 NodeSource 的源安装这是我在生产环境里最常用的方式。具体步骤是先添加源然后 apt 安装curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - sudo apt-get install -y nodejs装完之后node -v应该显示 v20.xnpm -v也有对应版本。这个方式的好处是版本可控后续升级也方便。第三种是用 nvm 做版本管理。如果你需要在多个 Node.js 版本之间切换nvm 是最灵活的。安装 nvm 之后nvm install 20然后nvm use 20就行。但要注意nvm 管理的 Node.js 在 tmux 会话里可能会有路径问题因为 tmux 启动时加载的 shell 环境可能跟你当前 shell 不一样。我遇到过在 tmux 里跑node提示 command not found 的情况原因就是 nvm 的初始化脚本没有在 tmux 的 shell 里执行。解决办法是在.bashrc或.zshrc里确保 nvm 的初始化代码在非交互式 shell 里也能加载或者直接在 tmux 配置里指定 shell。提示装完 Node.js 之后先跑一个npm install -g npmlatest把 npm 自身升级到最新版能避免很多包管理相关的奇怪问题。3.2 tmux 会话管理的关键配置tmux 的默认配置对于跑 AI 编程工具来说有几个不方便的地方我通常会改几个设置。首先是鼠标支持。默认情况下 tmux 不响应鼠标滚动你在查看 Claude Code 的长输出时会很痛苦。在~/.tmux.conf里加上set -g mouse on就能解决。其次是历史缓冲区大小。AI 工具的输出可能非常长默认的滚动历史可能不够用。我一般设置set -g history-limit 50000这样能往回翻很多内容。第三是窗口和面板的编号方式。默认从 0 开始按键盘的时候不太顺手。设置set -g base-index 1和setw -g pane-base-index 1让编号从 1 开始符合直觉。第四是状态栏的信息展示。我习惯在状态栏显示当前会话名、窗口列表和时间方便快速定位。这个可以根据个人喜好配置核心是让状态可见。创建会话的时候我通常会给会话起有意义的名字比如tmux new -s claude-backend表示这是跑 Claude Code 的后端项目会话tmux new -s codex-frontend表示跑 Codex 的前端会话。这样在tmux ls的时候一眼就能看出哪个是哪个。attach 的时候用tmux a -t claude-backend就行。还有一个实用技巧是 tmux 的分屏。在 openrig 的场景下我经常一个窗口分三个 pane上面一个跑 Claude Code下面左边跑 Codex下面右边跑一个 tail 日志的命令。这样所有相关信息都在一个屏幕里不用来回切换。分屏的快捷键是Ctrlb然后%做垂直分割做水平分割。3.3 Claude Code 的安装与配置要点Claude Code 的安装方式随着版本更新有变化目前比较稳妥的方式是通过 npm 全局安装。在 Node.js 20 环境下执行npm install -g anthropic-ai/claude-code装完之后在项目目录里直接跑claude就能启动。第一次启动会引导你做认证通常是浏览器授权或者输入 API Key。这里有几个我踩过的坑。第一个是权限问题如果你用 sudo 装了 Node.jsnpm 全局安装可能会因为权限不足失败。解决办法是配置 npm 的全局目录到用户目录下或者用 nvm 管理 Node.js 避免 sudo。第二个是网络问题。Claude Code 需要访问 API 端点如果你的网络环境对某些域名有限制可能会卡在认证或者请求超时。这个需要根据实际网络环境处理我在这里不展开。第三个是 VS Code 集成。Claude Code 有 VS Code 扩展装完之后可以在编辑器里直接调用。配置的时候要注意扩展的版本和 CLI 的版本要匹配否则可能出现扩展找不到 CLI 的情况。在 VS Code 的设置里通常需要指定 Claude Code 的可执行文件路径。关于模型配置Claude Code 默认使用 Anthropic 的模型但你可以通过环境变量或者配置文件指定第三方端点。比如你想让它调用本地 LM Studio 的模型需要设置 API Base URL 指向本地的端口通常是http://localhost:1234/v1这种格式然后指定模型名称。但要注意不是所有模型都能完美兼容 Claude Code 的请求格式有些模型对 system prompt 的处理方式不同可能导致行为异常。3.4 Codex 的安装与模型接入Codex 的安装同样依赖 Node.js 环境通常也是 npm 全局安装。装完之后跑codex启动。Codex 的配置文件和 Claude Code 是分开的需要单独设置。Codex 接入第三方模型时最常见的需求是接入 DeepSeek。配置的核心是设置 API Base URL 和 API Key然后指定模型名称。但这里有个常见报错the gpt-5.6-sol model is not supported when using codex。这个错误通常是因为配置文件里残留了默认的模型名称而你的端点并不支持这个模型。解决办法是明确指定你实际要用的模型名称比如deepseek-chat或者deepseek-coder。另一个常见问题是codex is ignoring 1 unrecognized configuration setting。这个警告说明你的配置文件里有一个 Codex 不认识的配置项可能是拼写错误也可能是版本不匹配导致的。Codex 的配置项在不同版本间会有变化升级之后旧的配置可能失效。我的做法是每次升级 Codex 之后对照官方文档检查一遍配置文件把不认识的项删掉或者修正。还有一个问题是codex无法加载组织设置。这个通常跟认证状态有关可能是 token 过期或者组织配置变了。重新登录一次通常能解决。3.5 本地模型与第三方 API 的切换策略openrig 的核心能力之一是在本地模型和第三方 API 之间切换。本地模型我主要用 LM Studio它提供了一个兼容 OpenAI 格式的 API 端点默认在http://localhost:1234/v1。第三方 API 则包括 DeepSeek、Qwen、GLM 等。切换的关键在于统一配置管理。我的做法是维护一个模型配置文件里面列出所有可用的模型来源每个来源包含端点、Key、模型名称、以及一些特定参数。然后在启动 Claude Code 或 Codex 之前根据当前任务选择合适的来源把对应的环境变量 export 出去。这里有个细节要注意不同模型对上下文长度的支持不一样。本地模型通常上下文窗口较小如果你把一个大项目的全部代码都塞进去可能会超出限制导致截断或者报错。第三方 API 的上下文窗口通常更大但也要注意成本。我的经验是对于本地模型尽量只传相关的文件片段对于第三方 API可以利用更大的上下文但也要控制单次请求的规模。还有一个坑是并发限制。有些第三方 API 对并发请求数有限制如果你同时跑 Claude Code 和 Codex两个工具都在发请求可能会触发限流。解决办法是错开使用或者选择支持更高并发的端点。4. 实操过程与核心环节实现4.1 从零搭建 openrig 工作环境的完整流程假设你是一台全新的 Ubuntu 机器我从头走一遍流程。第一步更新系统包并安装基础工具sudo apt update sudo apt upgrade -y sudo apt install -y curl git tmux build-essential第二步安装 Node.js 20 LTS。用 NodeSource 的方式curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - sudo apt-get install -y nodejs node -v npm -v确认版本正确之后升级 npmsudo npm install -g npmlatest第三步配置 tmux。创建~/.tmux.conf写入以下内容set -g mouse on set -g history-limit 50000 set -g base-index 1 setw -g pane-base-index 1 set -g status-interval 5然后tmux source-file ~/.tmux.conf让配置生效。第四步安装 Claude Codenpm install -g anthropic-ai/claude-code第五步安装 Codexnpm install -g openai/codex注意 Codex 的包名可能随版本变化如果这个包名不对去官方文档确认最新的安装命令。第六步创建 tmux 会话并启动工具tmux new -s work在会话里你可以分屏然后分别启动 Claude Code 和 Codex。4.2 模型配置文件的编写与参数计算我通常会在~/.config/openrig/models.json里维护模型配置。一个典型的配置结构如下{ models: { local-lmstudio: { baseUrl: http://localhost:1234/v1, apiKey: not-needed, model: local-model-name, maxTokens: 4096, contextWindow: 8192 }, deepseek: { baseUrl: https://api.deepseek.com/v1, apiKey: your-key-here, model: deepseek-chat, maxTokens: 8192, contextWindow: 65536 }, qwen: { baseUrl: https://dashscope.aliyuncs.com/compatible-mode/v1, apiKey: your-key-here, model: qwen-max, maxTokens: 8192, contextWindow: 32768 } } }参数计算方面maxTokens是单次请求的最大输出 token 数contextWindow是模型支持的总上下文长度。这两个值要根据模型的实际能力来设置设大了会报错设小了会限制输出。一般来说本地模型的 contextWindow 在 8K 到 32K 之间第三方 API 的 contextWindow 可以到 64K 甚至 128K。切换模型的时候我写了一个简单的 shell 函数放在.bashrc里switch_model() { local model_name$1 local config$(jq -r .models[\$model_name\] ~/.config/openrig/models.json) export OPENAI_BASE_URL$(echo $config | jq -r .baseUrl) export OPENAI_API_KEY$(echo $config | jq -r .apiKey) export OPENAI_MODEL$(echo $config | jq -r .model) echo Switched to $model_name }这样在终端里跑switch_model deepseek就能快速切换。4.3 多工具协同的实际操作记录我实际使用时的布局是这样的一个 tmux 会话三个窗口。窗口 1 是 Claude Code跑在前端项目目录窗口 2 是 Codex跑在后端项目目录窗口 3 是日志和监控跑一些 tail 命令和系统状态查看。启动流程是先tmux new -s dev创建会话然后在窗口 1 里cd frontend claudeCtrlb c创建窗口 2cd backend codex再Ctrlb c创建窗口 3跑htop或者tail -f日志。这样做的实际体验是我可以在前端让 Claude Code 帮我改一个组件同时在后端让 Codex 重构一个模块两边互不干扰。需要看哪个就Ctrlb加数字切换窗口。如果某个任务跑得久我可以直接 detachCtrlb d去干别的事回来再 attach。一个实际遇到的问题是两个工具同时请求同一个第三方 API 时的限流。我遇到过 DeepSeek 的 API 在并发请求下返回 429 错误。解决办法是给两个工具配置不同的模型来源比如 Claude Code 走本地 LM StudioCodex 走 DeepSeek这样就不会互相影响。4.4 日志与状态监控的实现openrig 场景下日志监控很重要因为 AI 工具的输出往往很长而且出错时的信息可能被淹没在大量正常输出里。我的做法是在 tmux 窗口 3 里跑一个简单的日志聚合脚本把 Claude Code 和 Codex 的输出重定向到文件然后用tail -f同时监控。具体来说启动工具的时候用tee把输出同时写到终端和文件claude 21 | tee -a ~/logs/claude.log codex 21 | tee -a ~/logs/codex.log然后在监控窗口里tail -f ~/logs/claude.log ~/logs/codex.log这样任何一边出错我都能在监控窗口里看到。另外我还会定期检查系统资源因为本地模型跑起来很吃内存和 GPU。htop和nvidia-smi是我常用的两个命令。5. 常见问题与排查技巧实录5.1 安装阶段的典型报错与解决安装阶段最常见的问题是 Node.js 版本不对。报错信息可能是error installing 24.21.0: node.js v24.21.0 is not yet released or is not available这个错误看起来像是版本号问题但实际原因可能是你的 npm 源配置有问题或者你试图安装一个不存在的版本。解决办法是确认你要装的版本确实存在然后检查 npm 的 registry 配置。另一个常见问题是权限错误。如果你用 sudo 装了 Node.js然后不加 sudo 跑npm install -g会报 EACCES 错误。解决办法是配置 npm 的全局目录mkdir -p ~/.npm-global npm config set prefix ~/.npm-global export PATH~/.npm-global/bin:$PATH把最后一行加到.bashrc里。5.2 运行阶段的连接与认证问题运行阶段最常见的是认证失败。Claude Code 报your organization has disabled claude subscription access for claude code这个错误说明你的账号或者组织设置不允许使用 Claude Code。需要检查账号的订阅状态和组织设置。Codex 报codex登录不上可能的原因包括网络问题、token 过期、或者配置文件损坏。我的排查顺序是先检查网络连通性然后删除本地的认证缓存重新登录最后检查配置文件是否有语法错误。还有一个问题是cc switch local proxy failed while handling codex endpoint /responses。这个错误通常出现在你用 cc switch 这类工具做本地代理转发的时候。原因是代理层在处理 Codex 的/responses端点请求时出了问题可能是请求格式不匹配也可能是代理配置有误。解决办法是检查代理的日志确认它是否正确转发了请求以及目标端点是否支持 Codex 的请求格式。5.3 模型调用失败的排查思路模型调用失败的表现形式很多我整理了一个排查表报错信息可能原因排查方法model is not supported模型名称错误或端点不支持确认模型名称与端点文档一致unrecognized configuration setting配置项拼写错误或版本不匹配对照官方文档检查配置429 Too Many Requests并发超限或配额用完降低并发或更换端点context length exceeded输入超出模型上下文窗口减少输入内容或换更大窗口的模型connection refused本地模型服务未启动检查 LM Studio 是否运行timeout网络问题或端点响应慢检查网络增加超时时间排查的时候我习惯先用 curl 直接测试端点排除工具层的问题curl -X POST http://localhost:1234/v1/chat/completions \ -H Content-Type: application/json \ -d {model: local-model, messages: [{role: user, content: test}]}如果 curl 能通说明端点没问题问题在工具配置如果 curl 不通说明端点本身有问题。5.4 性能与资源占用的优化经验本地模型跑起来对资源消耗很大。我的经验是如果同时跑 Claude Code、Codex 和本地 LM Studio16GB 内存的机器会很吃力。优化方向有几个一是限制本地模型的并发数LM Studio 里可以设置二是给 tmux 会话设置资源限制用systemd-run或者cgroup做隔离三是错峰使用不要同时让两个工具跑重任务。另外tmux 的 history-limit 设太大也会占内存。50000 行是个比较平衡的值再大就要考虑机器内存了。5.5 我踩过的三个印象最深的坑第一个坑是环境变量污染。我在一个 tmux 窗口里切换了模型export 了新的 API Key然后切到另一个窗口发现另一个窗口的模型也变了。原因是 tmux 的窗口共享同一个 shell 环境export 是全局生效的。解决办法是在每个窗口里单独设置环境变量或者用env命令在启动工具时临时指定。第二个坑是 Node.js 版本冲突。我用 nvm 装了 Node.js 20但系统里还有一个 apt 装的 Node.js 14。在 tmux 里跑工具时有时候用的是 20有时候用的是 14导致行为不一致。解决办法是彻底卸载系统自带的 Node.js只用 nvm 管理。第三个坑是 API Key 泄露。我把配置文件提交到了 Git 仓库里面包含了真实的 API Key。虽然及时发现并撤销了但这是个严重的教训。现在我的做法是把配置文件放在~/.config下用.gitignore排除并且用环境变量引用 Key 而不是硬编码。6. 进阶玩法与扩展思路6.1 用脚本自动化模型切换手动切换模型还是麻烦我后来写了一个更完整的脚本根据当前项目目录自动选择模型。逻辑是读取项目根目录下的.openrig文件里面指定这个项目用哪个模型然后脚本自动 export 对应的环境变量。#!/bin/bash if [ -f .openrig ]; then model$(cat .openrig) switch_model $model fi把这个脚本加到 shell 的启动流程里每次进入项目目录就自动切换。6.2 多机协同的初步尝试我试过在两台机器上分别跑 Claude Code 和 Codex通过共享文件系统同步代码。这种方式的好处是资源分散一台机器跑本地模型另一台跑云端工具。但问题是状态同步很麻烦tmux 会话不能跨机器共享。目前我的做法是用 Git 做代码同步用共享的日志目录做状态监控但还不是完全自动化的方案。6.3 与 VS Code 的深度集成VS Code 的 Claude Code 扩展可以让你在编辑器里直接调用 Claude Code。配置的时候要注意扩展的设置里指定 CLI 路径以及确保 VS Code 的终端环境跟 tmux 环境一致。我遇到过在 VS Code 终端里跑 Claude Code 正常但在 tmux 里跑就报错的情况原因是两者的 PATH 不一样。解决办法是在 VS Code 的设置里明确指定 Node.js 和 npm 的路径。Codex 也有类似的编辑器集成方案但成熟度不如 Claude Code。我目前还是以命令行使用为主编辑器集成作为辅助。6.4 后续可以扩展的方向openrig 这个思路还可以往几个方向扩展。一是加入任务队列把多个 AI 编程任务排队执行避免并发冲突。二是加入结果缓存对于重复的代码生成请求直接返回缓存结果节省 API 调用。三是加入更细粒度的权限控制比如某些项目目录禁止 AI 工具访问敏感文件。这些扩展都需要在编排层做更多工作但方向是清晰的。我个人在实际操作中的体会是工具链的复杂度应该匹配你的实际需求。openrig 这套东西适合每天跟多个 AI 编程工具打交道的人如果你只是偶尔用一下 Claude Code那没必要搞这么复杂。但如果你已经感受到了多工具、多模型切换的痛苦那花时间搭建一套编排层是值得的。最后分享一个小技巧不管用什么工具养成把关键操作和报错记录到日志文件的习惯排查问题的时候能省很多时间。