1. 从零认识 openrig：它到底解决什么问题
第一次看到 openrig 这个名字，很多人会以为是某个硬件项目，毕竟 “rig” 这个词在英文里常指设备支架或者矿机机架。但如果你最近在折腾 Claude Code、Codex 这类终端 AI 编程助手，大概率已经在某个 issue 或者讨论帖里见过它。openrig 本质上是一个面向 AI 编程代理的运行时编排层，它把 Claude Code、Codex CLI 这些工具需要的环境依赖、会话管理、多路复用、代理转发等琐碎但关键的环节统一收拢到一个可复现的配置体系里。
说白了，你单独装 Claude Code 也能跑，单独装 Codex 也能跑，但当你同时要在同一台机器上管理多个代理会话、切换不同模型后端、在 tmux 里保持长会话不中断、还要处理 Node.js 版本冲突的时候，事情就开始变得恶心了。openrig 要做的就是把这些恶心事提前消化掉，给你一套开箱即用的骨架。
它适合什么人？三类：第一类是在 Ubuntu 或者 macOS 上做主力开发、想让 AI 代理常驻终端随时待命的工程师；第二类是需要频繁在 Claude Code 和 Codex 之间切换、对比不同模型输出质量的技术选型人员；第三类是想把 AI 编程代理接入本地模型或者第三方 API、但又不想每次手动改配置的折腾党。如果你只是偶尔用一下网页版对话，那 openrig 对你来说确实过重了，但只要你开始把 AI 代理当成日常工具链的一部分，它省下的时间会非常可观。
我最初接触 openrig 的契机很直接：我在一台 Ubuntu 开发机上同时装了 Claude Code 和 Codex CLI，结果 Node.js 版本被两个工具的要求来回拉扯，tmux 会话里的环境变量又经常丢失，每次重启终端都要重新 source 一遍配置。这种重复劳动累积起来非常消耗耐心，而 openrig 的核心价值就在于把这些配置固化成可版本管理的结构，而不是散落在.bashrc、.zshrc、.tmux.conf和各种临时笔记里。
2. 核心设计思路拆解：为什么是 Node.js + tmux 这套组合
2.1 Node.js 作为运行时基座的必然性
Claude Code 和 Codex CLI 目前的主流分发方式都是通过 npm 全局安装，这意味着 Node.js 是绕不开的依赖。但 Node.js 的版本管理本身就是一个小坑：系统自带的 Node.js 往往版本偏旧，而直接从官网下载最新版又可能遇到 “node.js v24.21.0 is not yet released or is not available” 这类报错，因为某些镜像源同步有延迟。
openrig 在这方面的设计思路是锁定 LTS 版本而不是追最新。我实测下来，Node.js 20 LTS 和 22 LTS 对 Claude Code 和 Codex 的兼容性最稳。原因很简单：这两个工具的底层依赖了一些原生模块，而最新版 Node.js 的 V8 引擎变更有时会导致原生模块编译失败。LTS 版本经过更长时间的生态验证，踩坑概率低得多。
具体操作上，我强烈建议用 nvm 或者 fnm 来管理 Node.js 版本，而不是直接用系统包管理器安装。系统包管理器装的 Node.js 升级时容易和已有全局包冲突，而 nvm 可以让你在不同项目间无缝切换版本。安装 nvm 的命令很直接：
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash装完之后记得重新加载 shell 配置，然后安装 LTS 版本：
nvm install --lts nvm use --lts nvm alias default lts/*这里有个细节值得注意：nvm alias default这一步很多人会漏掉，导致新开终端时又回到系统默认的旧版本 Node.js。设了 default alias 之后，每个新 shell 都会自动使用你指定的 LTS 版本，省去手动切换的麻烦。
2.2 tmux 在 AI 代理工作流中的角色
tmux 在这个体系里不是可选项，而是核心组件。原因在于 Claude Code 和 Codex 这类工具经常需要保持长会话，尤其是当你让代理执行一个耗时较长的重构任务时，如果终端会话因为网络波动或者误触关闭而中断，整个任务就白跑了。tmux 的会话保持能力让代理任务可以在后台持续运行，你随时可以 detach 再 attach 回来查看进度。
openrig 对 tmux 的集成思路是预设一套针对 AI 代理优化的配置。默认的 tmux 配置有几个问题：滚动缓冲区太小，代理输出大量日志时前面的内容会被截断；状态栏信息不够直观，你没法一眼看出当前会话跑的是 Claude Code 还是 Codex；窗口命名默认是数字，多个会话并行时容易搞混。
我自己的 tmux 配置里针对这几点做了调整。滚动缓冲区设到 50000 行，基本够代理跑完一个完整任务链。状态栏左侧显示会话名和窗口索引，右侧显示当前时间和主机名。窗口命名改成自动根据运行中的进程名来设置，这样一眼就能区分哪个窗口在跑 Claude Code、哪个在跑 Codex。
# ~/.tmux.conf 关键配置片段 set -g history-limit 50000 set -g status-left "[#S] #I:#W " set -g status-right "%H:%M %d-%b" set -g allow-rename on set -g automatic-rename onallow-rename和automatic-rename这两个选项配合使用，tmux 会根据当前窗口内运行的进程自动更新窗口名。当你在一个窗口里启动 Claude Code，窗口名会自动变成类似node或者claude的标识，比纯数字直观太多。
2.3 多代理共存的隔离策略
openrig 要解决的一个核心矛盾是：Claude Code 和 Codex 可能依赖不同版本的 Node.js，或者需要不同的环境变量配置。如果全部混在一个全局环境里，迟早会出问题。隔离策略有两种主流做法：一种是基于目录的隔离，每个代理在独立目录下运行，通过.nvmrc指定 Node.js 版本；另一种是基于容器的隔离，每个代理跑在独立容器里。
openrig 默认走的是目录隔离路线，因为容器方案虽然隔离更彻底，但文件系统挂载和网络配置的复杂度会显著上升，对于日常开发场景来说性价比不高。目录隔离的具体做法是在项目根目录放一个.nvmrc文件，内容就是版本号比如22，然后配合 nvm 的use命令自动切换。
但这里有个实际问题：Claude Code 和 Codex 通常是全局安装的，全局包在 nvm 的每个 Node.js 版本下是独立的。也就是说你在 Node.js 20 下npm install -g装的 Claude Code，切到 Node.js 22 之后就找不到了。openrig 的处理方式是在每个目标 Node.js 版本下都重新安装一遍全局工具，虽然多占一点磁盘空间，但避免了版本切换时的 “command not found” 问题。
3. 实操部署全流程：从裸机到多代理并行
3.1 基础环境准备与 Node.js 安装避坑
拿到一台干净的 Ubuntu 机器，第一步不是急着装 Claude Code，而是先把基础环境理顺。我习惯先更新系统包列表并安装编译工具链，因为后续 npm 安装原生模块时大概率需要：
sudo apt update sudo apt install -y build-essential curl git tmuxbuild-essential提供了 gcc、g++、make 等编译工具，很多 npm 原生模块在安装时会现场编译，缺了这些工具就会报错。tmux 前面已经解释过必要性，这里一并装上。
接下来装 nvm 和 Node.js LTS。这里有个常见坑：如果你之前用apt install nodejs装过系统版 Node.js，nvm 装完后可能会和系统版冲突。排查方法是which node看指向哪里，如果指向/usr/bin/node而不是~/.nvm/versions/node/...，说明 nvm 没有正确接管。解决办法是在.bashrc或.zshrc里确保 nvm 的初始化脚本在 PATH 设置之后加载。
Node.js 装好后，验证一下版本和 npm 是否正常：
node -v # 应输出 v22.x.x 或 v20.x.x npm -v # 应输出 10.x.x 或更高如果 npm 版本过低，可以单独升级：npm install -g npm@latest。但注意不要盲目追最新，npm 的大版本更新有时会改变依赖解析策略，导致原本能装的包突然报 peer dependency 错误。我一般保持在 Node.js LTS 自带的 npm 大版本内，只做小版本更新。
3.2 Claude Code 与 Codex 的安装与配置
Node.js 环境就绪后，安装 Claude Code 和 Codex 就是一条命令的事：
npm install -g @anthropic-ai/claude-code npm install -g @openai/codex但安装成功只是开始，配置才是真正花时间的地方。Claude Code 首次运行会引导你完成认证，如果你用的是订阅账号，直接按提示走 OAuth 流程即可。如果遇到 “your organization has disabled claude subscription access for claude code” 这类提示，说明你的账号类型或者组织策略有限制，需要联系管理员或者换用 API key 方式认证。
Codex 的配置类似，首次运行codex会提示你登录。如果你要用第三方 API 接入，比如 DeepSeek 或者本地模型，就需要手动编辑配置文件。Codex 的配置文件通常在~/.codex/config.json或者项目根目录的.codex.json。一个典型的第三方 API 配置长这样：
{ "model": "deepseek-chat", "apiBase": "https://api.deepseek.com/v1", "apiKey": "your-api-key-here" }这里要特别注意apiBase的格式，有些第三方服务要求带/v1后缀，有些不需要。填错了会报 404 或者连接超时。我踩过的坑是某次把apiBase写成了完整的 endpoint 路径，结果 Codex 在拼接请求时重复了路径段，导致一直 404。正确的做法是只填到版本号那一层，让工具自己去拼具体的 endpoint。
3.3 tmux 会话编排与代理启动脚本
环境配好之后，openrig 的编排能力就体现在启动脚本上。我习惯写一个start-agents.sh放在项目根目录，内容大致如下：
#!/bin/bash SESSION="agents" # 如果会话已存在则直接 attach tmux has-session -t $SESSION 2>/dev/null if [ $? -eq 0 ]; then tmux attach -t $SESSION exit 0 fi # 创建新会话，第一个窗口跑 Claude Code tmux new-session -d -s $SESSION -n "claude" tmux send-keys -t $SESSION:claude "cd ~/projects/myapp && claude" C-m # 第二个窗口跑 Codex tmux new-window -t $SESSION -n "codex" tmux send-keys -t $SESSION:codex "cd ~/projects/myapp && codex" C-m # 第三个窗口留作普通终端 tmux new-window -t $SESSION -n "shell" tmux send-keys -t $SESSION:shell "cd ~/projects/myapp" C-m tmux attach -t $SESSION这个脚本的逻辑是：先检查名为agents的 tmux 会话是否已存在，存在就直接 attach，不存在就新建。新建时创建三个窗口，分别跑 Claude Code、Codex 和一个普通 shell。send-keys后面的C-m相当于按回车键，让命令真正执行。
这样你每次开工只需要跑一次./start-agents.sh，三个窗口各司其职，切换用Ctrl-b加窗口号即可。比每次手动开三个终端再分别 cd 到项目目录再启动工具，效率提升非常明显。
3.4 多模型后端切换的配置管理
Claude Code 和 Codex 都支持切换模型后端，但切换方式不同。Claude Code 通过环境变量ANTHROPIC_BASE_URL和ANTHROPIC_API_KEY来指定自定义后端，Codex 则通过配置文件。如果你经常需要在官方 API、第三方 API 和本地模型之间切换，手动改配置会非常烦。
我的做法是用 shell 函数封装切换逻辑。在.bashrc里定义几个函数，比如use-deepseek、use-local、use-official，每个函数负责 export 对应的环境变量。这样切换时只需要敲一个命令，不用去翻配置文件。
use-deepseek() { export ANTHROPIC_BASE_URL="https://api.deepseek.com/anthropic" export ANTHROPIC_API_KEY="your-deepseek-key" echo "Switched to DeepSeek backend" } use-local() { export ANTHROPIC_BASE_URL="http://localhost:1234/v1" export ANTHROPIC_API_KEY="local" echo "Switched to local model backend" }这里有个细节：Claude Code 对ANTHROPIC_BASE_URL的路径拼接有特定要求，如果你填的 base URL 和它预期的路径结构不匹配，会报 “cc switch local proxy failed while handling codex endpoint /responses” 这类错误。实测下来，第三方服务如果兼容 Anthropic 的 API 格式，base URL 填到域名加/anthropic或者/v1通常能通，具体要看服务商的文档。
4. 常见故障排查与稳定性优化
4.1 安装阶段的典型报错与解决
Node.js 版本相关的报错是最高频的。除了前面提到的 “node.js v24.21.0 is not yet released” 之外，还有一种情况是 npm 全局安装时提示EBADENGINE，意思是当前 Node.js 版本不满足包的 engines 字段要求。解决办法要么升级 Node.js，要么用--force跳过检查，但后者有风险，可能导致运行时行为异常。
另一个常见问题是权限。如果你之前用sudo npm install -g装过东西，npm 的全局目录可能归 root 所有，后续用普通用户安装就会报EACCES权限错误。正确的做法是配置 npm 使用用户级全局目录：
mkdir -p ~/.npm-global npm config set prefix '~/.npm-global' export PATH=~/.npm-global/bin:$PATH把这几行加到.bashrc里，以后所有全局安装都不需要 sudo，也不会污染系统目录。
4.2 运行时的连接与认证问题
Codex 报 “codex is ignoring 1 unrecognized configuration setting” 通常是因为配置文件里有多余或者拼写错误的字段。Codex 对配置字段的校验比较严格，不认识的就直接忽略并警告。排查方法是逐字段对照官方文档，把不支持的字段删掉。虽然只是警告不影响运行，但配置多了之后容易掩盖真正的问题。
认证失败方面，Claude Code 的 “claude code might not be available in your country” 提示和账号地区设置有关，这个不是技术问题，按官方指引处理即可。Codex 的 “codex无法加载组织设置” 则通常是 API key 权限不足或者组织配置有问题，需要检查 key 的 scope 是否包含所需权限。
本地模型接入时最常见的错误是连接被拒绝。先确认本地模型服务确实在监听，用curl http://localhost:1234/v1/models测试一下。如果 curl 能通但 Claude Code 报错，那大概率是路径拼接问题，试试在 base URL 末尾加或者去掉/v1后缀，看哪种能通。
4.3 会话稳定性与资源占用优化
长时间跑 AI 代理任务时，Node.js 进程的内存占用会逐渐上升。如果机器内存有限，建议在 tmux 里跑代理时设置NODE_OPTIONS=--max-old-space-size=4096来限制堆内存上限，避免单个进程吃光内存导致系统卡死。
tmux 会话本身很轻量，但如果开了太多窗口且每个窗口都在跑代理，CPU 和内存压力会叠加。我的经验是同时最多跑两个代理会话，再多的话响应速度会明显下降。如果确实需要并行多个任务，考虑用队列方式串行执行，而不是全部同时跑。
另外，tmux 的history-limit虽然设大了方便回看日志，但每个窗口的滚动缓冲区都占内存。50000 行对大多数场景够用，如果你跑的任务输出特别多，可以临时调大，但任务结束后记得调回来。
5. 进阶玩法：把 openrig 思路扩展到更多场景
5.1 多项目并行时的目录与配置隔离
当你同时在多个项目上使用 AI 代理时，每个项目的依赖版本、环境变量、甚至模型后端可能都不一样。openrig 的目录隔离思路在这里可以进一步细化：每个项目根目录放一个.agentrc文件，记录该项目需要的 Node.js 版本、模型后端、API key 环境变量名等信息。启动脚本读取这个文件，自动完成环境切换。
这种做法的好处是配置跟着项目走，换机器或者分享给同事时，只要把项目目录拷过去，启动脚本就能还原出一致的环境。比把配置散落在全局 shell 配置文件里要清晰得多。
5.2 代理输出的日志归档与检索
AI 代理跑完任务后的输出往往包含有价值的决策过程，但 tmux 的滚动缓冲区不是持久化的，会话关闭就没了。我的做法是在启动脚本里加一个 pipe-pane，把每个窗口的输出同时写一份到日志文件：
tmux pipe-pane -t $SESSION:claude -o 'cat >> ~/logs/claude-$(date +%Y%m%d).log'这样代理的所有输出都会追加到按日期命名的日志文件里。后续想回顾某个任务的执行过程，直接 grep 日志文件就行，比在 tmux 里翻滚动缓冲区方便得多。日志文件建议定期清理，不然几个月下来会占不少磁盘空间。
5.3 与编辑器工作流的衔接
虽然 Claude Code 和 Codex 主要在终端里跑，但和 VS Code 的配合能进一步提升效率。VS Code 的集成终端可以直接 attach 到已有的 tmux 会话，这样你在编辑器里就能看到代理的运行状态，不用来回切换窗口。具体做法是在 VS Code 的settings.json里配置终端启动命令：
{ "terminal.integrated.profiles.linux": { "tmux-agents": { "path": "tmux", "args": ["attach", "-t", "agents"] } } }配置好后，在 VS Code 里新建终端时选择tmux-agents配置，就会直接 attach 到你的代理会话。写代码和看代理输出在同一个窗口里完成，上下文切换成本大幅降低。
这套 openrig 思路我用了大半年，最大的体会是：AI 编程代理的效率瓶颈往往不在模型本身，而在环境配置和会话管理的琐碎环节上。把这些环节理顺之后，你才能真正把注意力放在代理产出的内容上，而不是整天和版本冲突、环境变量、会话丢失作斗争。如果你也在用 Claude Code 或者 Codex，不妨从 tmux 会话编排和 Node.js 版本锁定这两件事开始，先把基础打牢，再逐步叠加更复杂的配置。