openrig 编排 Claude Code 与 Codex：tmux 多会话管理实战

1. openrig 到底是什么：一个把 Claude Code 和 Codex 装进 tmux 的编排层

第一次看到 openrig 这个名字，我下意识以为是某个硬件云台或者机械臂项目，毕竟 “rig” 这个词在工程语境里常指一套组装好的设备。但把它和 Claude Code、Codex、Node.js、tmux 这几个热搜词放在一起，方向就清楚了：这是一个围绕命令行 AI 编程助手做会话编排与进程管理的工具层。说白了，它解决的不是“模型聪不聪明”的问题，而是“你同时开着 Claude Code 和 Codex，怎么让它们在一个终端里各干各的、互不打架、还能随时切回来”的问题。

我自己的日常是这样的：一个窗口跑 Claude Code 处理重构和长上下文理解，另一个窗口跑 Codex 做补全和快速改写，中间还要开 tmux 分屏看日志、跑测试。以前全靠手动开四五个终端标签，切来切去，session 一断就得重来。openrig 这类工具的价值就在于把这些会话抽象成可管理的“装置”，用一层轻量编排把 Node.js 运行时、CLI 进程、tmux 会话串起来。它适合谁？适合已经在用 Claude Code 或 Codex、但被多会话管理折磨过的开发者；也适合刚装完 Node.js、正准备第一次跑 Claude Code 的新手，因为一开始就用对结构，后面少踩很多坑。

需要先说明一点：openrig 目前并不是一个官方大厂产品，更像是社区里围绕 CLI 助手生态长出来的编排实践集合。所以下面讲的内容，一部分来自我对这类工具常见设计的拆解，一部分来自我自己搭类似结构时的实操经验，哪些是通用原理、哪些是合理推断，我会在文中标清楚。

2. 为什么需要 openrig：多助手并行的真实痛点

2.1 单开一个 Claude Code 很爽，开两个就开始乱

Claude Code 刚上手的时候，体验是惊艳的。你在项目根目录敲下命令，它读代码、改文件、跑终端命令，一气呵成。但只要你开始同时处理两个任务，比如一个会话在改后端接口，另一个会话在调前端组件，问题立刻出现。两个进程共享同一个工作目录，文件改动互相覆盖；终端输出混在一起，你根本分不清哪条是哪个会话打的；更麻烦的是，Claude Code 执行终端命令时如果卡住，整个终端就僵在那里，你连 Ctrl+C 都要犹豫会不会把另一个会话也干掉。

Codex 这边情况类似。Codex CLI 的交互模式和 Claude Code 不完全一样，它对配置文件的读取、对组织设置的校验都有自己的逻辑。热搜里那条 “codex is ignoring 1 unrecognized configuration setting” 就是典型症状：你在配置里多写了一个它不认识的字段，它不报错，只是默默忽略，然后行为和你预期不一致，你排查半天才发现是配置项写错了。当 Claude Code 和 Codex 同时跑，两套配置、两套环境变量、两套认证状态混在一起，出问题的概率是指数级上升的。

2.2 tmux 不是万能药，但它是目前最稳的地基

很多人第一反应是用 tmux 分屏。对，tmux 确实是这个场景下最可靠的地基，因为它把“终端会话”和“终端窗口”解耦了。你的 Claude Code 跑在一个 tmux session 里，就算你关掉终端窗口、断掉连接，那个 session 还在后台活着，下次 attach 回去，上下文原封不动。这一点对长任务特别关键：Claude Code 在跑一个大型重构，可能要十几分钟，你不可能一直盯着屏幕。

但裸用 tmux 也有代价。你得手动命名 session、手动分 pane、手动在每个 pane 里 cd 到正确目录、手动启动对应的 CLI。一天下来，光是这些重复动作就消耗不少注意力。openrig 要做的，就是把这套手动流程固化下来：一个命令拉起一整套 rig，Claude Code 在左 pane，Codex 在右 pane，日志在下方 pane，每个 pane 的工作目录、环境变量、启动命令都预先配好。你只需要 attach 进去，直接干活。

2.3 Node.js 是这一切的运行时底座

热搜里 “node.js是干什么的”“node.js安装”“node.js lts下载” 出现频率极高，这不是偶然。Claude Code 和 Codex 的 CLI 本质上都是 Node.js 程序，它们依赖 Node 运行时来执行。你装 Node.js，不是为了写前端，而是为了跑这些 CLI 工具。这里有个很实际的坑：Node.js 版本选错，CLI 直接起不来。热搜里那条 “error installing 24.21.0: node.js v24.21.0 is not yet released” 就是有人试图装一个还不存在的版本，说明版本管理这块新手很容易迷糊。

我的建议很明确：用 LTS 版本，别追最新。截至我写这篇的时候，Node.js 20 LTS 和 22 LTS 是稳妥选择。Claude Code 和 Codex 对 Node 版本有最低要求，但通常不会要求你上最新的奇数版本。装的时候优先用 nvm 或 fnm 这类版本管理器，而不是直接去官网下载 pkg 安装包。原因很简单：不同项目可能依赖不同 Node 版本，版本管理器让你一条命令切换，不用反复卸载重装。

3. 核心组件拆解：openrig 的四个关键层

3.1 会话层：tmux 的 session、window、pane 三级结构

要理解 openrig 怎么编排，得先把 tmux 的三级结构吃透。session 是最外层，一个 session 可以理解为一个“工作空间”；window 是 session 里的标签页；pane 是 window 里的分屏。openrig 通常会为每个项目或每个任务创建一个独立 session，session 名字带项目标识，比如openrig-myapp。然后在 session 里开多个 window，一个 window 给 Claude Code，一个给 Codex，一个给日志和测试。

为什么用 session 隔离而不是 window 隔离？因为 session 可以独立 detach 和 attach。你上午在处理项目 A，下午切到项目 B，两个 session 互不干扰，attach 哪个就是哪个。如果用 window 隔离，所有项目挤在一个 session 里，window 数量一多，切换成本反而更高。这个设计选择背后的逻辑是：session 对应“上下文边界”，window 对应“任务类型”，pane 对应“并行子任务”。

3.2 进程层：Claude Code 与 Codex 的启动差异

Claude Code 和 Codex 虽然都是 CLI，但启动方式和交互模型有区别。Claude Code 更偏向“对话式代理”，启动后进入一个交互循环，你输入自然语言，它决定读哪些文件、跑哪些命令。Codex 的 CLI 则更接近“命令式助手”，你可以直接给它一个任务描述，它执行完返回结果。这个差异决定了它们在 tmux pane 里的启动参数不一样。

Claude Code 启动时通常需要指定工作目录和可能的模型配置。如果你要让它调用本地模型，比如通过 LM Studio 暴露的本地端点，还需要设置对应的环境变量。热搜里 “claude code 调用lmstudio的本地模型” 就是这个场景。Codex 这边，接入 DeepSeek 或其他第三方模型时，配置文件的写法又不同。openrig 在进程层的职责，就是把这些差异封装成配置，让每个 pane 启动时自动带上正确的参数和环境变量，而不是你每次手动 export 一堆变量。

3.3 配置层：环境变量、配置文件与优先级

这是最容易出问题的一层。Claude Code 和 Codex 都支持通过环境变量和配置文件两种方式设置参数，两者同时存在时，优先级规则不一样。一般来说，环境变量优先级高于配置文件，但具体到每个工具又有细节差异。热搜里 “codex is ignoring 1 unrecognized configuration setting” 提醒我们：配置文件里写了工具不认识的字段，它不会报错，只会忽略。这意味着你自以为配置生效了，实际上没有。

我的做法是：把配置分成两层。一层是“工具级配置”，放在各自的标准配置目录里，比如 Claude Code 的配置文件和 Codex 的配置文件分开管理，互不污染。另一层是“项目级配置”，放在项目根目录，通过 openrig 在启动时注入环境变量。这样切换项目时，工具级配置不变，项目级配置随项目走。排查问题时，先确认环境变量有没有覆盖配置文件，再确认配置文件里有没有拼写错误导致字段被忽略。

3.4 编排层：openrig 如何把前三层串起来

编排层是 openrig 的核心。它读取一份声明式配置，这份配置描述了：要创建哪些 tmux session、每个 session 里有哪些 window 和 pane、每个 pane 的工作目录是什么、启动什么命令、注入哪些环境变量。然后它按顺序执行：创建 session、切分 pane、发送启动命令、设置 pane 标题。整个过程是幂等的，重复执行不会创建重复的 session，而是复用已有的。

这里有个设计上的取舍：是用 shell 脚本编排，还是用 Node.js 程序编排？shell 脚本胜在轻量、无依赖，但处理复杂逻辑和跨平台时很痛苦。Node.js 程序胜在逻辑表达能力强、可以复用 npm 生态，但要求你先装好 Node。openrig 既然和 Node.js 生态绑定这么深，用 Node.js 做编排层是合理选择。它可以直接调用 tmux 的命令行接口，也可以用 node-pty 这类库做更细粒度的控制。

4. 从零搭一套 openrig：完整实操流程

4.1 第一步：把 Node.js 环境装对

不管你用 macOS、Linux 还是 Windows，第一步都是把 Node.js 装对。我强烈建议用版本管理器，不要直接装系统级 Node。macOS 和 Linux 上用 nvm 或 fnm，Windows 上用 fnm 或 nvm-windows。装完之后验证：

node -v npm -v

输出应该是类似v20.x.x和10.x.x。如果版本低于 18，Claude Code 和 Codex 可能跑不起来。热搜里 “node.js lts下载” 和 “安装node.js” 的搜索量说明很多人卡在这一步，我的经验是：别去官网手动下载 pkg，用版本管理器一条命令搞定，省去权限和路径问题。

注意：Windows 上如果之前装过系统级 Node，先卸载干净再装版本管理器，否则 PATH 里会有多个 node，导致版本混乱。

4.2 第二步：安装并验证 Claude Code 与 Codex

Node 装好后，安装 Claude Code 和 Codex。具体安装命令以官方文档为准，通常是通过 npm 全局安装。装完后分别验证：

claude --version codex --version

如果提示命令找不到，检查 npm 全局 bin 目录有没有在 PATH 里。如果提示认证问题，比如热搜里 “your organization has disabled claude subscription access”，那是账号权限问题，不是安装问题，需要检查你的订阅状态。

Codex 这边如果遇到 “codex无法加载组织设置”，通常是配置文件里的组织标识写错了，或者网络请求被拦截。先确认配置文件路径正确，再确认字段拼写。热搜里 “codex登录” 和 “codex配置” 是高频问题，说明认证和配置是两大门槛。

4.3 第三步：配置 tmux 基础环境

tmux 的安装很简单，macOS 用 brew，Ubuntu 用 apt。装完后建议先配一份基础的 tmux.conf，至少设置这几项：前缀键改成 Ctrl+a（默认 Ctrl+b 和很多快捷键冲突）、开启鼠标支持、设置窗口编号从 1 开始、设置历史滚动行数。这些配置不直接影响 openrig，但能大幅提升日常使用体验。

验证 tmux 是否正常：

tmux new -s test

进去后按前缀键加 d detach，再tmux ls看 session 列表，再tmux attach -t test回去。这套动作练熟，后面用 openrig 才不会慌。

4.4 第四步：编写 openrig 编排配置

这是核心步骤。一份典型的 openrig 配置大概长这样（以 YAML 为例，具体格式取决于你用的实现）：

session: openrig-myapp root: /Users/me/projects/myapp panes: - name: claude command: claude env: ANTHROPIC_MODEL: claude-sonnet-4-20250514 - name: codex command: codex env: CODEX_MODEL: deepseek-chat - name: logs command: tail -f logs/app.log

这份配置描述了一个 session，三个 pane。openrig 读取后，会创建对应 tmux 结构，在每个 pane 里 cd 到 root，注入 env，执行 command。你只需要运行openrig up，然后tmux attach -t openrig-myapp，三个 pane 已经就位。

4.5 第五步：处理多模型接入的配置差异

如果你要让 Claude Code 调用本地模型，或者让 Codex 接入 DeepSeek，配置会更复杂。Claude Code 调用本地模型通常需要设置 API base URL 指向本地端点，同时设置一个占位 API key。Codex 接入第三方模型则要改它的配置文件，指定 provider 和 model。这两套配置不要混在一起，建议在 openrig 配置里为每个 pane 单独注入对应的环境变量，工具级配置文件保持干净。

提示：第三方模型接入时，先单独在终端里手动跑通，确认能正常对话，再写进 openrig 配置。否则出了问题你分不清是模型接入的问题还是编排的问题。

5. 常见问题与排查技巧实录

5.1 会话管理类问题速查

5.2 配置与认证类问题

Codex 的 “unrecognized configuration setting” 是最典型的配置问题。它的表现是：你改了配置，但行为没变。排查步骤是：先确认配置文件路径是否正确，再逐字段核对拼写，最后用工具的 verbose 模式看它实际加载了哪些配置。Claude Code 这边，如果遇到订阅访问被禁用，先确认账号状态，再确认是否在支持的地区使用。

5.3 我踩过的三个坑

第一个坑：Node 版本用最新奇数版。有次我图新鲜装了 Node 23，结果 Claude Code 的某个依赖编译失败。换回 20 LTS 立刻正常。第二个坑：tmux pane 里没设工作目录，Claude Code 在 home 目录启动，读不到项目文件，我还以为它坏了。第三个坑：环境变量在 openrig 配置里写了，但 tmux 启动时没继承，原因是 tmux server 的环境和当前 shell 不同步，需要tmux update-environment或者重启 tmux server。

6. 进阶玩法：让 openrig 更贴合你的工作流

6.1 按项目自动切换 rig

你可以在 shell 里加一个函数，cd 到某个项目目录时自动 attach 对应的 openrig session，不存在就创建。这样你不需要记 session 名字，进入项目目录就等于进入工作环境。实现方式是在 shell 的目录切换钩子里调用 openrig 的检查命令。

6.2 日志 pane 的自动化

日志 pane 不要只 tail 一个文件。可以写一个小脚本，根据当前项目自动选择要 tail 的日志文件，甚至把 Claude Code 和 Codex 的输出也 tee 一份到日志文件，方便事后回溯。这样即使 pane 被关掉，历史输出还在。

6.3 与 VS Code 的配合

热搜里 “vscode配置claude code” 和 “claude code for vs code” 说明很多人想在编辑器里用。我的做法是：VS Code 里用集成终端 attach 到 openrig session，这样编辑器里写代码，终端里跑助手，两边共享同一个工作目录，改动实时可见。不要在 VS Code 里另开一个独立的 Claude Code 进程，那样会和 openrig 里的会话冲突。

6.4 资源占用与性能

同时跑 Claude Code 和 Codex，再加上 tmux 和 Node 运行时，内存占用不小。如果机器配置一般，建议把不用的 pane 关掉，或者用 tmux 的remain-on-exit选项让进程退出后 pane 保留但不占资源。另外，Codex 和 Claude Code 在处理大文件时都会吃 CPU，别在同一个 pane 里同时跑两个重任务。

7. 我对 openrig 这类工具的真实看法

用了一段时间之后，我的体会是：openrig 的价值不在于它有多复杂，而在于它把“多助手并行”这件事从手动操作变成了声明式配置。以前我每天要花十几分钟在开终端、切目录、启动命令上，现在这些动作固化在配置里，一条命令搞定。省下来的时间不算多，但省下来的注意力很值钱。

另一个体会是：这类工具的上手门槛主要在环境准备，不在工具本身。Node.js 装对、tmux 用熟、Claude Code 和 Codex 各自能单独跑通，这三件事做完，openrig 的配置就是水到渠成。反过来，如果环境本身有问题，再好的编排工具也救不了。所以如果你刚开始，别急着上 openrig，先把基础三件套跑顺。

最后分享一个小技巧：openrig 的配置不要一次写太满。先写两个 pane，跑通，再加第三个。每加一个 pane 就验证一次，出问题容易定位。我见过有人一口气配了八个 pane，结果一个都跑不起来，排查起来像大海捞针。