1. 从零认识 openrig它到底解决什么问题第一次看到 openrig 这个名字很多人会以为是某个硬件支架或者开源机械臂项目。实际上它跟物理世界没有半点关系而是一套围绕 AI 编程助手做多模型编排与终端会话管理的工具链方案。简单说openrig 要解决的核心痛点是当你同时使用 Claude Code、Codex 这类命令行 AI 编程工具时如何让它们稳定共存、自由切换模型后端、并且在长时间任务里不丢失上下文。我接触这套东西的起因很实际。团队里有人用 Claude Code 写前端有人用 Codex 处理 Python 脚本还有人想把本地 LM Studio 的模型接进来省钱。结果就是每个人的终端里塞满了各种环境变量、代理配置、API Key一旦换机器或者换项目就全乱套。openrig 这类方案的价值就在于把这些零散的配置收敛成一套可复现的骨架。它适合谁三类人最需要一是刚接触 Claude Code 或 Codex、被安装和配置卡住的新手二是需要在多个模型供应商之间切换的中高级开发者三是想把本地模型和云端模型混用、控制成本的技术负责人。如果你只是偶尔用一次 AI 写代码那确实用不上但只要你的日常工作流里 AI 编程工具占比超过三成这套编排思路就值得花时间搭起来。需要提前说明的是openrig 并不是一个官方发布的单一软件包它更像是一种工程实践约定——把 Node.js 运行时、tmux 会话管理、模型路由配置、CLI 工具安装这几件事组合成一套稳定的工作环境。下面我会按照实际搭建顺序把每个环节的原理、参数和踩坑点讲透。2. 环境底座Node.js 与 tmux 的选型逻辑2.1 为什么 Node.js 版本选择是第一道坎Claude Code 和 Codex 的 CLI 版本绝大多数都是基于 Node.js 生态分发的这意味着 Node.js 的版本直接决定了你能不能装上、装完能不能跑。热搜里那条error installing 24.21.0: node.js v24.21.0 is not yet released就是典型的版本号写错导致的报错——很多人看到教程里写了个大版本号就照抄结果那个版本根本还没正式发布。我的建议很明确永远优先选 LTS 版本。截至我写这篇内容时Node.js 的 LTS 主线在 20.x 和 22.x 之间这两个版本对 Claude Code 和 Codex 的兼容性最稳。奇数版本如 21.x、23.x属于过渡版本生命周期短某些原生模块编译时容易出问题。安装方式上我不推荐直接用系统包管理器装。原因很简单Ubuntu 自带的 apt 源里 Node.js 版本往往滞后一到两年而 Claude Code 这类工具更新频繁版本太旧会直接报不支持。我实测下来最省心的方案是用 nvmNode Version Manager来管理多版本# 安装 nvm curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash # 重新加载 shell 配置 source ~/.bashrc # 安装并切换到 LTS 版本 nvm install --lts nvm use --lts nvm alias default lts/* # 验证 node -v npm -v用 nvm 的好处是当某个工具要求特定 Node 版本时你可以随时nvm install 20 nvm use 20切换不会污染系统环境。Windows 用户可以用 nvm-windows逻辑一样只是安装包换成 exe。注意如果你在 Windows 上遇到node.js v24.21.0 is not yet released这类报错先执行nvm list available看看实际可安装的版本列表不要凭记忆写版本号。2.2 tmux被低估的会话保命工具tmux 在 openrig 这套方案里的角色是保证长时间 AI 任务不中断。你想想这个场景让 Claude Code 跑一个重构任务可能要十几分钟甚至更久期间你要去看日志、切窗口、甚至 SSH 断线重连。如果没有 tmux终端一关任务就没了。tmux 的核心概念只有三个会话session、窗口window、面板pane。我通常这样组织# 创建一个名为 ai-work 的会话 tmux new -s ai-work # 在会话内按 Ctrlb 然后按 % 垂直分屏 # 按 Ctrlb 然后按 水平分屏 # 按 Ctrlb 然后按方向键切换面板 # 脱离会话任务继续在后台跑 # 按 Ctrlb 然后按 d # 重新连接会话 tmux attach -t ai-work # 查看所有会话 tmux ls实际使用中我会把一个面板留给 Claude Code一个面板留给 Codex第三个面板用来看日志或者跑测试。这样三个工具的输出互不干扰切换成本几乎为零。Ubuntu 上安装 tmux 就是一行sudo apt install tmuxmacOS 用brew install tmux。提示tmux 默认的前缀键是 Ctrlb如果你觉得别扭可以在~/.tmux.conf里改成 Ctrla跟 screen 保持一致肌肉记忆更容易迁移。3. Claude Code 与 Codex 的安装配置实战3.1 Claude Code 安装从 npm 到首次运行Claude Code 的安装本身不复杂复杂的是网络环境和账号权限。先说过安装# 全局安装 npm install -g anthropic-ai/claude-code # 验证安装 claude --version装完之后第一次运行claude它会引导你完成认证。这里有几个高频问题需要提前知道。第一个是your organization has disabled claude subscription access for claude code这个报错。它的含义是你的账号所属组织关闭了 Claude Code 的访问权限。这种情况通常出现在企业账号上解决办法是换个人账号或者让管理员在组织设置里开启对应权限。这不是技术问题是权限配置问题折腾命令行没用。第二个是note: claude code might not be available in your country。这个提示说明当前网络环境不在服务覆盖范围内。我的处理方式是检查自己的网络配置是否符合工具的使用要求确保在合规前提下使用。第三个是 VS Code 集成。如果你用 VS Code可以装 Claude Code 的官方扩展然后在设置里配置 CLI 路径。实测下来VS Code 里的体验和终端里基本一致但终端里用 tmux 管理多会话更灵活。我的习惯是日常小任务用 VS Code 扩展大任务丢到 tmux 里跑。3.2 Codex 安装Windows 与 Ubuntu 的差异处理Codex 的安装路径和 Claude Code 类似也是 npm 全局包为主。但 Windows 用户会遇到更多坑我单独说一下。Windows 上推荐用 PowerShell 而不是 CMD因为 CMD 对某些 npm 脚本的兼容性不好。安装命令npm install -g openai/codex codex --version如果遇到codex is ignoring 1 unrecognized configuration setting这个警告说明你的配置文件里有一个键名拼错了。Codex 的配置文件通常在~/.codex/config.json或项目根目录的.codex文件里。我的排查方法是先把配置文件备份然后逐段注释掉看警告什么时候消失就能定位到具体哪一行有问题。Ubuntu 上的安装基本一致但要注意权限问题。如果你用sudo npm install -g装出来的包属主是 root普通用户运行时可能读不到配置。正确做法是配置 npm 的全局目录到用户目录下mkdir -p ~/.npm-global npm config set prefix ~/.npm-global echo export PATH~/.npm-global/bin:$PATH ~/.bashrc source ~/.bashrc npm install -g openai/codex这样装出来的包都在你的用户目录下不需要 sudo也不会污染系统。3.3 模型后端切换本地与云端的混合策略openrig 这套方案最有价值的部分就是模型后端的灵活切换。热搜里提到的cc switch local proxy failed while handling codex endpoint /responses和使用 cc switch 接入 deepseek v4, qwen, glm等模型说的都是同一件事通过一个中间层把 Claude Code 或 Codex 的请求转发到不同的模型供应商。这个中间层的原理不复杂。Claude Code 和 Codex 都支持自定义 API 端点base URL你只要把端点指向本地的一个转发服务转发服务再根据配置把请求路由到 DeepSeek、Qwen、GLM 或者 LM Studio 的本地模型即可。我实测下来配置的关键在于三点一是端点路径要匹配Codex 用的是/responsesClaude Code 用的是/v1/messages路径写错就会报local proxy failed二是 API Key 的传递方式要一致有的供应商用 Bearer Token有的用自定义 header三是超时设置要放宽本地模型首次加载可能要好几十秒。如果你要把 Claude Code 接到 LM Studio 的本地模型上大致流程是在 LM Studio 里启动本地服务记下端口默认 1234然后在 Claude Code 的配置里把 base URL 指向http://localhost:1234/v1模型名填 LM Studio 里加载的模型标识。这样请求就不会出本机速度和隐私都有保障。注意本地模型的能力和云端模型差距明显适合做代码补全、格式转换这类轻任务复杂的架构设计还是建议用云端模型。4. 多工具协同的工作流设计4.1 用 tmux 编排 Claude Code 与 Codex 的分工工具装好了接下来是怎么让它们协同。我的做法是按任务类型分工Claude Code 擅长理解大段上下文和做重构Codex 在生成独立函数和脚本上响应更快。所以我会在 tmux 里开三个面板面板一Claude Code负责读整个项目、做跨文件修改面板二Codex负责写独立工具函数、生成测试用例面板三普通 shell跑 git 命令、看测试输出这种分工的好处是两个 AI 工具的上下文互不污染。你让 Claude Code 读了一堆文件之后它的上下文窗口占用很高这时候再让它做别的事效率会下降。分开之后每个工具都在自己最擅长的场景里工作。实际操作中我会用 tmux 的send-keys命令做半自动化。比如把一段需求同时发给两个工具对比它们的输出# 向指定面板发送命令 tmux send-keys -t ai-work:0.0 claude 重构这个函数 Enter tmux send-keys -t ai-work:0.1 codex 重构这个函数 Enter这样你可以直观看到两个模型对同一个问题的不同解法取长补短。4.2 配置文件的分层管理多工具协同最大的隐患是配置冲突。Claude Code、Codex、npm、nvm 各自都有一堆配置文件散落在 home 目录的各个角落。我的做法是建一个~/ai-rig目录把所有配置集中管理然后用软链接指回原位。目录结构大概是这样~/ai-rig/ ├── claude/ │ └── settings.json ├── codex/ │ └── config.json ├── tmux/ │ └── tmux.conf └── scripts/ ├── switch-model.sh └── start-session.sh然后用软链接ln -sf ~/ai-rig/claude/settings.json ~/.claude/settings.json ln -sf ~/ai-rig/codex/config.json ~/.codex/config.json ln -sf ~/ai-rig/tmux/tmux.conf ~/.tmux.conf这样做的好处是换机器的时候只要把ai-rig目录拷过去重新建软链接整个环境就恢复了。比逐个工具重新配置快得多也不容易漏掉某个隐藏文件。4.3 会话恢复与任务续跑AI 编程任务经常是跨天的。今天让 Claude Code 改了一半明天接着改怎么保证上下文不丢我的经验是两条腿走路一是 tmux 会话不关机器不重启就能一直 attach 回去二是重要任务的中间结论手动落到文件里比如让 AI 把当前进度写成PROGRESS.md下次直接让它读这个文件。tmux 会话在机器重启后会丢失这是它的局限。如果你需要跨重启恢复可以用 tmux-resurrect 这个插件它能保存和恢复会话布局。安装方式是在~/.tmux.conf里加一行插件声明然后用 tpmtmux plugin manager管理。不过我的建议是别过度依赖插件关键任务的进度落盘才是王道。5. 常见报错与排查速查5.1 安装类报错报错信息根本原因解决方式node.js v24.21.0 is not yet released版本号不存在或未发布用nvm list available查实际可用版本改用 LTSerror installing后跟版本号npm 源里没有该版本检查 npm registry 配置或换用官方源permission denied安装全局包全局目录属主是 root配置 npm prefix 到用户目录command not found: claude全局 bin 目录不在 PATH把 npm 全局 bin 加入 PATH5.2 运行类报错cc switch local proxy failed while handling codex endpoint /responses这个报错我遇到过好几次排查下来无非三种原因转发服务的端点路径没配对Codex 请求的是/responses但你配的是/v1/responses转发服务的进程没起来端口没人监听API Key 没传对供应商直接拒绝了请求。排查顺序就是先curl一下转发服务的健康检查端点确认进程活着再看日志里的请求路径和实际配置是否一致。codex is ignoring 1 unrecognized configuration setting是配置键名拼写错误。Codex 的配置校验比较严格多一个下划线或者大小写不对都会报。我的做法是把配置文件里的键名跟官方文档逐个对照或者干脆删掉可疑的那一行看警告是否消失。your organization has disabled claude subscription access是账号权限问题前面说过了换账号或者找管理员开权限命令行层面无解。5.3 模型接入类问题接入 DeepSeek、Qwen、GLM 这类第三方模型时最常见的坑是模型名写错。每个供应商的模型标识都不一样比如 DeepSeek 可能是deepseek-chatQwen 可能是qwen-max写错了就会返回 404 或者模型不存在。我的习惯是先用curl直接调供应商的 API 确认模型名可用再填到配置文件里。另一个坑是上下文长度。Claude Code 默认假设后端支持很长的上下文但有些第三方模型或者本地模型的上下文窗口小得多请求一长就报错。解决办法是在配置里限制单次请求的 token 数或者把大任务拆成小任务分批处理。提示接入任何第三方模型之前先用一个最简单的请求验证连通性别一上来就跑复杂任务否则报错了你分不清是配置问题还是模型能力问题。6. 我踩过的坑和几条实在建议搭这套环境的过程中有几个教训是文档里不会写的我单独拎出来说。第一个是关于 Node.js 版本切换的。我曾经在一个项目里同时需要 Node 18 和 Node 20因为两个 AI 工具的依赖树不一样。当时图省事直接改了系统 Node结果另一个工具崩了。后来老老实实用 nvm在 tmux 的不同面板里用不同 Node 版本问题就解决了。nvm 的nvm use是 per-shell 生效的这正好跟 tmux 的面板隔离特性契合。第二个是关于 tmux 会话命名的。我一开始随便起名字时间长了tmux ls出来一堆0、1、2根本分不清哪个是哪个。后来改成按项目命名比如proj-web、proj-api一眼就能找到。这个习惯看似小事但每天省下的切换时间累积起来很可观。第三个是关于配置备份的。我有一次重装系统忘了备份~/.claude目录结果所有自定义配置全丢了重新配花了两个小时。从那以后我就把ai-rig目录放进了私有 git 仓库每次改配置就 commit 一次。配置文件版本化之后不仅能恢复还能看到自己什么时候改了什么排查问题时特别有用。第四个是关于本地模型的预期的。我一开始想着用 LM Studio 的本地模型完全替代云端省钱又隐私。实测下来本地模型在代码补全这种短任务上还行但一旦涉及跨文件理解、复杂重构质量差距就出来了。现在的策略是本地模型做初筛和格式化复杂任务还是交给云端。这个分工不是技术限制是能力边界的现实。最后分享一个 tmux 的小技巧如果你经常需要同时看多个 AI 工具的输出可以用tmux synchronize-panes把多个面板的输入同步这样你敲一次命令所有面板同时执行。适合做对比测试但平时记得关掉不然会误操作。这套 openrig 的搭建思路核心不是某个具体工具而是把环境、会话、模型路由这三层解耦。环境层用 nvm 管版本会话层用 tmux 管生命周期模型层用转发服务管路由。三层各司其职任何一层出问题都不会牵连其他层。这个结构搭好之后你换工具、换模型、换机器成本都很低。