1. openrig 到底是个什么东西
第一次看到 openrig 这个名字，我下意识以为是某个硬件外设的开源项目，毕竟 rig 这个词在英文里常跟设备、装置挂钩。但翻了一圈社区讨论和实际代码之后才明白，它其实是一个围绕 AI 编程助手做本地化编排与调度的工具层，核心目标是把 Claude Code、Codex 这类命令行 AI 编程工具，跟本地的 Node.js 运行时、tmux 会话管理、以及各种第三方模型接口串起来，形成一个可复用、可切换、可观测的工作台。
说白了，openrig 解决的是一个很具体的痛点：当你同时用 Claude Code 写一个模块、用 Codex 跑另一个仓库的重构、还想让它们调用本地 LM Studio 里的模型时，你会发现自己不停地在终端窗口之间切换，环境变量改来改去，会话断了还得重来。openrig 想做的就是把这些零散的操作收拢到一个统一的编排层里，让你用一套配置管理多个 AI 编程助手的生命周期。
它适合谁？我觉得有三类人最需要：第一类是已经在日常开发里重度使用 Claude Code 或 Codex 的工程师，手头同时维护多个项目；第二类是想在本地跑模型、又不想放弃云端工具链的折腾党；第三类是团队里负责搭建 AI 辅助开发环境的人，需要一套能复制给同事的标准化方案。如果你只是偶尔用一下 AI 补全代码，那 openrig 可能有点重，但如果你已经把 AI 编程助手当成主力工具，这套东西能省下大量重复劳动。
需要先说明的是，openrig 目前并不是一个官方大厂背书的产品，更多是社区驱动的工具集合，所以它的配置方式、依赖版本、跟各家 CLI 的兼容性都会随上游变化而波动。这也是为什么我在后面会花不少篇幅讲版本锁定和排查技巧——这类工具最大的坑往往不在功能本身，而在依赖链的脆弱性。
2. 核心设计思路与方案选型拆解
2.1 为什么是 Node.js 作为底座
openrig 选择 Node.js 作为运行时底座，这个决定其实挺关键的。Claude Code 和 Codex 的 CLI 本身都是 npm 生态里的包，它们的安装、更新、版本管理都依赖 Node.js 的工具链。如果你用 Python 或者 Go 去写编排层，就得额外维护一套跨语言的进程调用逻辑，还得处理 npm 全局包路径的问题。用 Node.js 直接写，可以无缝调用 npm 的 API，也能直接读取 package.json 里的版本约束。
另一个原因是 Node.js 的异步 IO 模型天然适合管理多个子进程。openrig 需要同时盯着好几个 AI 助手的会话状态，哪个进程还活着、哪个已经退出、哪个卡在等待输入，这些都需要非阻塞的监听。用 Node.js 的 child_process 加事件循环，写起来比同步语言顺手得多。
不过这里有个版本坑必须提前说。Node.js 的版本迭代很快，有些新版本发布后 npm 上的包还没跟上，就会出现类似 "error installing 24.21.0: node.js v24.21.0 is not yet released or is not available" 这种报错。我的建议是锁定 LTS 版本，比如 Node.js 20.x 系列，这个版本在 Ubuntu 和 Windows 上的兼容性都经过大量验证。如果你在 Ubuntu 上装，别直接用 apt 里的默认版本，那个往往太老，用 NodeSource 的源或者 nvm 来装 20+ 更稳妥。
2.2 tmux 在编排里扮演的角色
tmux 这个东西，没用过的人觉得它只是个终端复用器，用过的人才知道它是远程开发和长时间任务的救命稻草。openrig 把 tmux 纳入核心依赖，逻辑很清晰：AI 编程助手的会话往往是长时运行的，你发起一个重构任务，它可能跑十几分钟甚至更久。如果直接在前台终端跑，一旦网络抖动或者你不小心关了窗口，整个会话就没了。
用 tmux 把每个 AI 助手的会话包起来，就相当于给每个任务分配了一个独立的、可断线重连的容器。你可以随时 detach 出去干别的，回头再 attach 回来看进度。openrig 在这个基础上又做了一层封装，用统一的命名规则管理这些 tmux 会话，比如按项目名加工具名来区分，这样你同时跑五个任务也不会搞混。
实测下来，tmux 的 session 管理在 Ubuntu 上非常稳，但在 Windows 上就需要额外注意。Windows 原生没有 tmux，得靠 WSL 或者 Cygwin 来提供。如果你是在 Windows 桌面版上折腾 Codex 和 Claude Code，建议直接在 WSL2 里搭环境，别在 PowerShell 里硬扛，否则 tmux 相关的功能会各种报错。
2.3 多模型接入的抽象层设计
openrig 另一个核心设计是模型接入的抽象层。现在市面上的 AI 编程工具，后端模型五花八门：Claude Code 默认走 Anthropic 的接口，Codex 走 OpenAI 的接口，但很多人想接 DeepSeek、Qwen、GLM 这些国产模型，或者干脆用 LM Studio 在本地跑。如果没有抽象层，每换一个模型就要改一堆配置，还容易出错。
openrig 的做法是定义一个统一的 provider 接口，把不同模型的 endpoint、认证方式、请求格式都封装在适配器里。你在配置文件里只需要写清楚用哪个 provider、哪个模型名，剩下的转换逻辑由 openrig 处理。这个思路跟 cc switch 那类工具很像，但 openrig 更强调跟 tmux 会话的联动，切换模型的时候会自动重启对应的会话，避免旧配置残留。
这里有个细节值得展开：不同模型的 API 兼容性差异很大。比如有些模型不支持 Codex 用的 /responses 端点，你硬接就会报 "cc switch local proxy failed while handling codex endpoint /responses" 这类错误。openrig 的适配器需要针对每个 provider 做端点映射，这也是为什么它的配置文件看起来有点复杂——复杂度没有消失，只是从你的手动操作转移到了配置里。
3. 环境搭建与核心配置实操
3.1 Node.js 与包管理器的安装细节
先把地基打好。在 Ubuntu 上，我习惯用 nvm 来管理 Node.js 版本，这样切换版本不用动系统级的配置。安装 nvm 之后，直接装 Node.js 20 的 LTS 版本：
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash source ~/.bashrc nvm install 20 nvm use 20 nvm alias default 20装完之后验证一下：
node -v npm -v如果 node -v 输出的是 v20 开头的版本，就对了。这里有个小坑：有些教程会让你用apt install nodejs，但 Ubuntu 仓库里的版本往往落后好几个大版本，装完可能连 Claude Code 的最低要求都达不到。所以别偷懒，老老实实用 nvm。
Windows 用户如果不想折腾 WSL，可以直接去 Node.js 官网下载 LTS 的安装包，双击安装就行。但要注意，Windows 上的 npm 全局包路径有时候会跟系统权限冲突，装 Claude Code 或 Codex 的时候如果报权限错误，用管理员权限打开终端再装一次。
3.2 Claude Code 与 Codex 的安装与验证
Node.js 就绪之后，装这两个 CLI 就是一行命令的事：
npm install -g @anthropic-ai/claude-code npm install -g @openai/codex装完分别跑一下claude --version和codex --version，能输出版本号就说明安装成功。如果报 "command not found"，大概率是 npm 的全局 bin 目录没加到 PATH 里。用npm config get prefix看一下全局路径，然后把这个路径下的 bin 目录加到 .bashrc 或 .zshrc 里。
这里要提醒一句：Claude Code 和 Codex 的登录方式不一样。Claude Code 通常需要你配置 API key 或者走订阅登录，Codex 则是走 OpenAI 的账号体系。如果你遇到 "your organization has disabled claude subscription access for claude code" 这种提示，说明你的账号权限被组织策略限制了，得找管理员开权限，或者换用 API key 的方式接入。
3.3 openrig 的配置文件结构
openrig 的核心是一个 YAML 或 JSON 格式的配置文件，我把它放在项目根目录下的.openrig/config.yaml。一个典型的配置长这样：
version: 1 defaults: node_version: "20" tmux_prefix: "rig" providers: anthropic: type: claude api_key_env: ANTHROPIC_API_KEY openai: type: codex api_key_env: OPENAI_API_KEY local: type: openai-compatible base_url: "http://localhost:1234/v1" model: "local-model" sessions: - name: frontend-refactor tool: claude provider: anthropic workdir: "./web" - name: backend-tests tool: codex provider: openai workdir: "./server"这个配置里，providers 段定义了可用的模型后端，sessions 段定义了要启动哪些 AI 助手会话。每个会话绑定一个工具、一个 provider、一个工作目录。openrig 启动的时候会遍历 sessions，为每个会话创建一个 tmux window，在里面拉起对应的 CLI。
配置文件的字段设计有几个讲究。api_key_env 用的是环境变量名而不是直接写 key，这是为了避免密钥泄露到版本控制里。base_url 允许你指向本地服务，比如 LM Studio 默认跑在 1234 端口，你把它填进去就能让 Claude Code 调用本地模型。workdir 让每个会话有独立的上下文，不会互相干扰。
3.4 tmux 会话的命名与生命周期管理
openrig 给每个会话生成的 tmux 名字遵循{prefix}-{session_name}的格式，比如rig-frontend-refactor。这样你在 tmux 里tmux ls的时候一眼就能看出哪些是 openrig 管的会话。
生命周期管理上，openrig 提供了几个子命令：openrig up启动所有会话，openrig down关闭所有会话，openrig status查看当前状态，openrig attach <name>连接到指定会话。这些命令本质上是对 tmux 命令的封装，但加了状态检查和错误处理。
我特别喜欢openrig status这个命令，它会输出一个表格，列出每个会话的名字、工具类型、provider、运行时长、最后活动时间。当你同时跑好几个任务的时候，这个表格比在 tmux 里一个个切窗口看要高效得多。
注意：tmux 会话在系统重启后不会自动恢复，openrig 目前也没有做持久化。如果你需要跨重启保持任务，得自己写个 systemd 服务或者用 cron 在开机时跑
openrig up。
4. 多模型接入与本地模型调用实战
4.1 接入 DeepSeek、Qwen、GLM 的配置方法
国产模型的接入是很多人关心的点。这些模型大多提供 OpenAI 兼容的 API，所以配置起来跟接 OpenAI 官方接口差不多，只是 base_url 和 model 名要改。以 DeepSeek 为例：
providers: deepseek: type: openai-compatible base_url: "https://api.deepseek.com/v1" api_key_env: DEEPSEEK_API_KEY model: "deepseek-chat"然后在 session 里把 provider 指向 deepseek 就行。Qwen 和 GLM 的配置逻辑一样，只是 base_url 和 model 名不同。这里的关键是确认你的模型是否支持 Codex 或 Claude Code 需要的端点。有些模型只提供 /chat/completions，不支持 /responses，那接 Codex 的时候就会报错。
我的经验是，接第三方模型之前先用 curl 测一下端点通不通：
curl -X POST https://api.deepseek.com/v1/chat/completions \ -H "Authorization: Bearer $DEEPSEEK_API_KEY" \ -H "Content-Type: application/json" \ -d '{"model":"deepseek-chat","messages":[{"role":"user","content":"hi"}]}'能正常返回就说明基础连通性没问题，再去配 openrig。
4.2 用 LM Studio 跑本地模型的完整流程
本地模型的好处是不花钱、数据不出门，坏处是配置麻烦、性能看机器。LM Studio 是目前比较好用的本地模型运行工具，它自带一个 OpenAI 兼容的 server。流程是这样的：
先在 LM Studio 里下载一个模型，比如 Qwen2.5-Coder 的 7B 或 14B 量化版，然后在 Local Server 标签页里启动 server，默认端口 1234。启动之后，在 openrig 里加一个 provider：
providers: lmstudio: type: openai-compatible base_url: "http://localhost:1234/v1" api_key_env: LMSTUDIO_API_KEY model: "qwen2.5-coder-7b-instruct"LM Studio 的 server 其实不校验 API key，但很多客户端要求必须有这个字段，所以随便填一个非空字符串就行，环境变量里设成LMSTUDIO_API_KEY=dummy。
实测下来，7B 的模型在 16GB 内存的机器上跑起来还算流畅，但做复杂重构的时候明显不如云端模型。14B 以上就需要 32GB 内存或者独立显卡了。如果你只是想让 Claude Code 调用本地模型做简单的代码补全和解释，7B 够用；如果要它理解整个仓库的上下文，还是得上更大的模型或者用云端。
4.3 模型切换时的会话重启策略
openrig 在切换 provider 的时候，会自动重启对应的 tmux 会话。这个设计是有原因的：Claude Code 和 Codex 在启动时会读取环境变量和配置文件，运行中改配置不会生效。如果不重启，你会以为切换成功了，实际上还在用旧模型。
重启策略上，openrig 默认是优雅关闭：先给会话发一个退出信号，等几秒让它保存状态，如果还没退出就强制 kill。这个等待时间可以在配置里调，默认 5 秒。如果你的任务正在写文件，建议把这个时间调长一点，避免数据损坏。
提示：切换模型前最好先让当前任务告一段落，别在它正在执行大操作的时候切。我有一次在 Codex 跑批量重命名的时候切了 provider，结果一半文件改了、一半没改，只能手动回滚。
5. 常见问题与排查技巧实录
5.1 安装阶段的典型报错与解决
安装阶段最容易遇到的就是 Node.js 版本问题。前面提到的 "error installing 24.21.0: node.js v24.21.0 is not yet released" 这种报错，通常是因为你的 npm 缓存里有一个不存在的版本号，或者某个包的 engines 字段写了一个还没发布的版本。解决办法是清缓存再装：
npm cache clean --force nvm install 20 nvm use 20 npm install -g @anthropic-ai/claude-code另一个常见问题是网络超时。npm 的默认源在国内访问有时候很慢，可以换成国内镜像源：
npm config set registry https://registry.npmmirror.com换完之后再装，速度会快很多。但要注意，有些包在镜像源上同步不及时，如果装的时候报 404，换回官方源再试一次。
5.2 会话启动失败的分层排查法
openrig 启动会话失败的时候，报错信息往往很笼统，只说 "session failed to start"。这时候需要分层排查：
| 排查层级 | 检查内容 | 常见问题 |
|---|---|---|
| 第一层 | Node.js 和 CLI 是否可用 | 版本不对、PATH 没配 |
| 第二层 | 环境变量是否设置 | API key 缺失、变量名拼错 |
| 第三层 | 网络是否可达 | 端点不通、代理配置问题 |
| 第四层 | tmux 是否正常 | 未安装、权限问题、会话名冲突 |
| 第五层 | 工作目录是否存在 | 路径写错、权限不足 |
我的习惯是从第一层开始逐层验证，别一上来就怀疑 openrig 本身。大部分问题其实出在环境变量和网络连通性上。比如 "codex is ignoring 1 unrecognized configuration setting" 这种警告，就是配置文件里有个字段名拼错了，Codex 不认识就忽略了，虽然不致命但说明配置有问题。
5.3 模型调用报错的快速定位
模型调用报错的花样就更多了。我整理了一个速查表：
| 报错信息 | 可能原因 | 解决方法 |
|---|---|---|
| model is not supported | 模型名写错或 provider 不支持 | 核对模型名，确认端点兼容性 |
| 401 Unauthorized | API key 无效或过期 | 重新生成 key，检查环境变量 |
| 429 Too Many Requests | 触发限流 | 降低并发，加退避重试 |
| context length exceeded | 输入超出模型上下文 | 精简输入，换更大上下文的模型 |
| connection refused | 本地服务没启动 | 检查 LM Studio server 是否在跑 |
"the 'gpt-5.6-sol' model is not supported when using codex" 这类报错，通常是配置文件里写了一个不存在的模型名，或者 provider 的模型列表没更新。解决办法是去 provider 的文档里查当前支持的模型名，别凭记忆写。
5.4 我踩过的三个坑
第一个坑是 tmux 会话名冲突。openrig 用 session name 生成 tmux 名，如果你两个项目的 session name 一样，第二个启动的时候就会报冲突。我后来养成的习惯是 session name 里带上项目前缀，比如web-refactor和api-refactor，避免重名。
第二个坑是环境变量没继承。openrig 启动 tmux 会话的时候，如果环境变量是在当前 shell 里 export 的，tmux 不一定能继承到。解决办法是在 openrig 的配置里显式声明需要的环境变量，或者用tmux setenv手动设置。我现在的做法是把所有 API key 写在一个.env文件里，openrig 启动时自动加载。
第三个坑是本地模型的端口占用。LM Studio 默认用 1234 端口，但有些其他服务也会用这个端口，导致启动失败。如果你遇到 "address already in use"，换个端口就行，LM Studio 的设置里可以改，openrig 的 base_url 也跟着改。
6. 与 VS Code 的协同工作流
6.1 在 VS Code 里调用 openrig 会话
虽然 openrig 是命令行工具，但它跟 VS Code 的配合可以很顺。我的做法是在 VS Code 的集成终端里跑 openrig，然后用 tmux 的分屏功能把多个会话并排显示。VS Code 的终端支持 tmux 的鼠标操作，切换窗口很方便。
另一个方式是用 VS Code 的 tasks 功能，把 openrig 的命令配成 task。比如在.vscode/tasks.json里加一个 task，一键启动所有会话：
{ "version": "2.0.0", "tasks": [ { "label": "openrig up", "type": "shell", "command": "openrig up", "problemMatcher": [] } ] }这样按 Ctrl+Shift+B 就能启动，不用每次手敲命令。
6.2 Claude Code 在 VS Code 里的配置要点
Claude Code 有官方的 VS Code 扩展，装完之后需要在设置里配置 API key 或者登录账号。如果你用 openrig 管理会话，其实可以不用扩展，直接在集成终端里跑 CLI 就行。但扩展的好处是有图形化的 diff 视图和快捷操作，看代码变更更直观。
配置的时候注意一点：扩展和 CLI 用的是同一套认证信息，如果你在 CLI 里登录了，扩展通常也能直接用。但如果遇到 "your organization has disabled claude subscription access" 这种提示，说明账号权限有问题，扩展和 CLI 都会受影响，得先解决账号层面的问题。
6.3 多仓库并行开发时的会话隔离
同时开发多个仓库的时候，会话隔离特别重要。openrig 的 workdir 配置让每个会话有独立的工作目录，但环境变量是共享的。如果你的两个项目需要不同的 API key 或者不同的模型配置，就得在 session 级别覆盖 provider。
我的做法是给每个项目单独写一个 openrig 配置文件，放在项目根目录下，启动的时候用openrig -c ./project-a/.openrig/config.yaml up指定配置。这样不同项目的会话完全隔离，互不影响。
7. 性能调优与长期维护建议
7.1 会话数量与系统资源的平衡
openrig 本身很轻量，但每个 AI 助手会话都是实打实的进程，会占内存和 CPU。Claude Code 和 Codex 的 CLI 在空闲时占用不大，但一旦开始处理任务，内存占用会明显上升。我实测下来，同时跑 3 到 4 个会话是比较舒服的，再多就会感觉到系统变卡。
如果你机器内存有限，建议按需启动会话，别一次性全开。openrig 支持单独启动某个会话：openrig up frontend-refactor，只启动指定的那个。用完就openrig down frontend-refactor关掉，释放资源。
7.2 日志收集与问题回溯
openrig 默认把每个会话的输出写到 tmux 的 scrollback buffer 里，但 buffer 有大小限制，跑久了早期的日志会被冲掉。我的做法是在配置里开启日志落盘，把每个会话的输出同时写到一个文件里：
sessions: - name: frontend-refactor tool: claude provider: anthropic workdir: "./web" log_file: "./logs/frontend-refactor.log"这样出问题的时候可以翻日志回溯，比在 tmux 里往上翻要靠谱。日志文件建议按天切割，不然跑几周就变成几百 MB 了。
7.3 版本升级的注意事项
openrig 依赖的上游工具更新很频繁，Claude Code 和 Codex 几乎每周都有新版本。升级之前一定要看 changelog，确认有没有破坏性变更。我有一次没看就升级了 Codex，结果它的配置文件格式变了，openrig 的适配器没跟上，所有会话都启动失败。
稳妥的做法是锁定版本，在 package.json 或者安装命令里指定版本号，别用 latest。等确认新版本没问题了再升。openrig 本身也建议锁定版本，别用npm install -g openrig@latest，用具体的版本号。
提示：升级前先备份配置文件，尤其是 provider 和 session 的定义。升级后先用一个测试会话验证，确认没问题再全量切换。
8. 一些个人体会
折腾 openrig 这套东西最大的感受是，AI 编程工具的生产力提升是真实的，但前提是你得把环境搭稳。我见过太多人兴冲冲装了 Claude Code，结果卡在 Node.js 版本上，折腾半天就放弃了。其实这些问题都有成熟的解法，只是信息散落在各处，需要有人把它们串起来。
另一个体会是，本地模型和云端模型不是替代关系，而是互补。简单的代码解释、格式转换、单元测试生成，本地 7B 模型完全够用，还不用花钱。复杂的架构重构、跨文件理解，还是得靠云端的大模型。openrig 的价值就在于让你能根据任务类型灵活切换，不用在工具之间反复横跳。
最后分享一个小技巧：把常用的 openrig 命令做成 shell alias，比如alias ou='openrig up'、alias os='openrig status'、alias od='openrig down'，每天能省下不少敲键盘的时间。这种小优化看起来不起眼，但日积月累下来对工作流的顺畅度提升很明显。
