openrig实战：用Node.js与tmux编排Claude Code和Codex终端AI工具

1. 从“openrig”说起：一个把终端AI编码工具串起来的脚手架

第一次看到“openrig”这个词，我脑子里蹦出来的不是某个具体软件，而是一类东西——把散落在终端里的 AI 编码工具统一编排起来的脚手架。你如果最近在折腾 Claude Code、Codex CLI 这类命令行 AI 助手，大概率会有同感：单个工具用起来都挺香，但一旦要在同一台机器上同时跑好几个、还要切换模型、还要管理会话、还要让它们各自待在自己的工作目录里，事情就开始变得混乱。openrig 要解决的，正是这种“工具一多就乱”的问题。

我先把话说在前面：openrig 不是一个官方大厂产品，它更像是一个围绕Node.js 运行时 + tmux 会话管理 + 多 AI CLI 编排组合出来的实践方案。它的核心价值在于，把 Claude Code、Codex 这类终端 AI 工具，通过一层轻量的“装置（rig）”组织起来，让它们共享环境、隔离会话、方便切换。你如果是那种每天要在终端里敲几十条命令、同时开着好几个 AI 助手帮你写代码、查文档、跑脚本的人，这套东西能省下你大量来回切换的力气。

适合谁来参考？三类人最合适。第一类是刚接触 Claude Code 或 Codex、还在纠结“装哪个、怎么装、装完怎么用”的新手，openrig 的思路能帮你一次性把环境理顺。第二类是已经在用这些工具、但被多会话、多模型切换折磨得够呛的中级用户。第三类是喜欢自己搭工作流、对 tmux 和 Node.js 有一定了解、想把 AI 编码助手真正嵌进日常开发流程的老手。不管你是哪一类，下面这些内容都能直接抄作业。

需要提前说明的是，openrig 本身并没有一个统一的官方定义，不同人嘴里的 openrig 可能指代不同的具体实现。我下面讲的，是基于这类工具最常见的组合方式和我自己实际搭过、跑过、踩过坑之后总结出来的一套可复现方案。核心关键词会围绕openrig、Claude Code、Codex、Node.js、tmux这几个展开，同时把安装、配置、切换、排错这些环节都讲透。

2. 整体设计思路：为什么是 Node.js + tmux + 多 CLI 的组合

2.1 为什么这类工具都绕不开 Node.js

你去看 Claude Code 和 Codex CLI 的安装说明，几乎第一步都是“先装 Node.js”。这不是巧合。这两个工具本质上都是Node.js 生态里的命令行程序，通过 npm 全局安装，然后以 CLI 的形式跑在你的终端里。所以 Node.js 不是可选项，而是地基。

这里有个新手最容易踩的坑：Node.js 版本。热词里那条error installing 24.21.0: node.js v24.21.0 is not yet released or is not available就是典型症状——你照着某个教程敲了一个并不存在的版本号，npm 直接报错。我的建议很明确：不要追最新的大版本号，直接用 LTS（长期支持版）。截至我写这篇内容时，Node.js 20.x 和 22.x 的 LTS 都是稳妥选择。Ubuntu 上装 Node.js 20+ 最省心的方式是用 NodeSource 的源，而不是系统自带的 apt 版本（系统自带的往往太旧）。

为什么强调 LTS？因为 Claude Code、Codex 这类工具依赖的底层库对 Node 版本有要求，太老的版本跑不起来，太新的非 LTS 版本又可能遇到依赖不兼容。LTS 是经过大量项目验证的“甜点区”。这一点我在好几台机器上反复验证过，用 LTS 出问题的概率明显低。

2.2 tmux 在这里扮演什么角色

如果说 Node.js 是地基，那 tmux 就是 openrig 这套方案的“骨架”。很多人第一次听说 tmux 会问：我直接开几个终端窗口不就行了，为什么要用 tmux？

答案在于会话的持久化和隔离。你想想这个场景：你让 Claude Code 在一个目录里帮你重构代码，同时让 Codex 在另一个目录里帮你写测试，两个任务都要跑好几分钟。如果你用的是普通终端窗口，一旦网络断了、SSH 掉了、或者你手滑关了窗口，这些正在跑的 AI 会话就全没了。而 tmux 的会话是独立于终端窗口存在的，你断开连接，会话还在后台跑，重新连上就能接着看。

更重要的是，tmux 让“一个窗口里管理多个 AI 工具”成为可能。你可以用 tmux 的窗格（pane）把 Claude Code、Codex、普通 shell 并排放在一个屏幕里，用快捷键切换。这就是 openrig 这类“装置”的核心体验——所有 AI 助手都在一个可控的容器里，而不是散落在十几个终端标签页中。

2.3 多 CLI 编排的核心矛盾

把 Claude Code 和 Codex 放在一起用，最大的矛盾是配置和会话的隔离。这两个工具各自有自己的配置目录、认证信息、会话历史。如果你不做隔离，它们可能会互相干扰，比如共享了某些环境变量导致模型调用出错。

openrig 这类方案的思路，通常是通过独立的工作目录 + 独立的环境变量 + tmux 会话命名来实现隔离。每个 AI 工具跑在自己的 tmux 会话或窗格里，工作目录指向不同的项目，环境变量按需注入。这样你就能在同一台机器上，干净地同时跑多个 AI 编码助手，互不打架。

我实测下来，这套隔离思路比“装一堆全局配置然后祈祷它们不冲突”要靠谱得多。尤其是当你需要切换不同模型（比如 Claude Code 接本地模型、Codex 接第三方 API）时，隔离几乎是必须的。

3. 环境准备：Node.js、tmux 与 AI CLI 的安装实操

3.1 Node.js 安装：Ubuntu 与 Windows 两条路线

先说 Ubuntu。系统自带的 apt 源里的 Node.js 版本通常偏旧，直接apt install nodejs很可能装到一个跑不动新版 CLI 的版本。我推荐用 NodeSource 的源来装 Node.js 20 LTS：

# 添加 NodeSource 源（以 Node.js 20 为例） curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - sudo apt-get install -y nodejs # 验证版本 node -v npm -v

装完之后node -v应该显示 v20.x.x。如果显示的是 v12 或 v14 这种老版本，说明你装到了系统自带的，需要先卸载再重装。

Windows 用户就简单多了，直接去 Node.js 官网下载 LTS 版本的安装包，一路下一步即可。装完在 PowerShell 里node -v验证。这里提醒一句：Windows 上装完 Node.js 后，建议重启一次终端，否则环境变量可能没生效，导致npm命令找不到。

注意：不要盲目追求最新版本号。热词里那个24.21.0 is not yet released的报错，就是因为有人照着不存在的版本号去装。认准官网标注的 LTS 版本，稳。

3.2 tmux 安装与基础配置

Ubuntu 上装 tmux 一条命令：

sudo apt-get install -y tmux

Windows 用户要注意，tmux 原生不支持 Windows。如果你在 Windows 上想用 tmux，通常的做法是在 WSL（Windows Subsystem for Linux）里装，或者用 Git Bash 配合一些替代方案。我的建议是，如果你认真想用 openrig 这套东西，在 WSL 里搭环境是最顺的，因为 Claude Code、Codex 这些工具在 Linux 环境下的兼容性最好。

tmux 装完后，建议改一下默认前缀键。默认是Ctrl+b，但很多人会改成Ctrl+a，因为更顺手。配置文件在~/.tmux.conf：

# 改前缀键为 Ctrl+a set -g prefix C-a unbind C-b bind C-a send-prefix # 开启鼠标支持 set -g mouse on # 窗格切换用 Alt+方向键，更直观 bind -n M-Left select-pane -L bind -n M-Right select-pane -R bind -n M-Up select-pane -U bind -n M-Down select-pane -D

改完tmux source-file ~/.tmux.conf生效。这几行配置看着简单，但能极大提升你同时管理多个 AI 会话时的操作效率。

3.3 Claude Code 与 Codex 的安装

这两个工具的安装方式类似，都是通过 npm 全局安装。Claude Code 的安装命令大致是：

npm install -g @anthropic-ai/claude-code

Codex CLI 的安装命令大致是：

npm install -g @openai/codex

装完之后，claude和codex这两个命令应该就能在终端里直接调用了。第一次运行会引导你登录或配置 API Key。

这里有个高频问题：登录不上。热词里codex登录不上、codex无法加载组织设置都是这类问题。常见原因有三个：一是网络环境导致认证请求超时；二是账号权限问题（比如组织禁用了某个订阅）；三是本地时间不准导致认证令牌校验失败。排查顺序建议是：先确认本地时间准确，再确认账号状态，最后检查网络。

提示：如果你在 VS Code 里用 Claude Code，可以装对应的 VS Code 扩展，然后在集成终端里调用。热词里的vscode配置claude code、claude code for vs code说的就是这个场景。扩展装完后，在 VS Code 的终端里跑claude即可，工作目录会自动指向你打开的项目。

4. 用 tmux 编排多个 AI 会话的完整实操

4.1 创建带命名的 tmux 会话

openrig 的核心操作，就是给每个 AI 工具分配一个独立的 tmux 会话。我习惯用工具名 + 项目名来命名，比如：

# 创建一个名为 claude-projectA 的会话 tmux new -s claude-projectA # 在另一个终端里创建 codex 的会话 tmux new -s codex-projectB

创建后你会进入这个会话。在里面cd到对应项目目录，然后启动对应的 AI 工具。这样每个会话就是一套独立的“工作台”。

想脱离会话但保持它在后台运行，按Ctrl+a然后按d（detach）。想重新连回去：

tmux attach -t claude-projectA

查看当前所有会话：

tmux ls

这套操作看起来朴素，但它是 openrig 能“同时管理多个 AI 助手”的基础。你可以开五个会话，分别跑 Claude Code、Codex、普通 shell、日志监控、测试运行，互不干扰。

4.2 单窗口多窗格：把 AI 工具并排摆开

如果你不想开那么多会话，也可以在一个 tmux 窗口里用窗格分割。比如左右分屏，左边 Claude Code，右边 Codex：

# 先创建会话 tmux new -s ai-work # 水平分割（左右） # 按 Ctrl+a 然后按 % # 垂直分割（上下） # 按 Ctrl+a 然后按 "

分好之后，用Ctrl+a加方向键在窗格间切换。每个窗格可以独立cd到不同目录、跑不同工具。这种布局特别适合“一个 AI 写代码、一个 AI 审查”的协作模式。

我个人的习惯是：主窗格跑 Claude Code 做主力开发，右侧窄窗格跑一个普通 shell 用来跑测试和 git 操作，底部窗格跑 Codex 做代码审查。一个屏幕，三件事同时推进。

4.3 环境变量隔离：让不同 AI 工具各用各的模型

这是 openrig 里最容易被忽略、但最关键的一环。Claude Code 和 Codex 都可能需要配置 API 端点、模型名称等。如果你把它们都写进全局的 shell 配置（比如~/.bashrc），就会互相覆盖。

正确的做法是按会话注入环境变量。你可以在启动 AI 工具前，在对应的 tmux 窗格里单独 export：

# 在 Claude Code 的窗格里 export ANTHROPIC_API_KEY="你的key" export ANTHROPIC_BASE_URL="你的端点" claude # 在 Codex 的窗格里 export OPENAI_API_KEY="你的key" export OPENAI_BASE_URL="你的端点" codex

这样两个工具的环境变量互不影响。如果你想让某个会话永久带上这些变量，可以在项目目录下放一个.env文件，启动前source一下。

注意：热词里claude code 调用lmstudio的本地模型、codex接入deepseek、使用cc switch 接入 deepseek v4, qwen, glm等模型说的都是这类“换模型”需求。核心操作就是改BASE_URL和模型名称这两个变量。改之前先确认你的端点支持对应的 API 格式，否则会报模型不支持的错。

4.4 会话持久化与断线恢复

tmux 最大的好处在这里体现。假设你正在让 Claude Code 跑一个耗时十分钟的重构任务，这时候你的 SSH 断了。普通终端下，任务直接挂掉。但在 tmux 里，任务还在后台跑。你重新 SSH 上来，tmux attach -t claude-projectA，一切照旧，输出还在滚动。

我强烈建议给 tmux 配一个“会话自动保存”的插件（比如 tmux-resurrect），这样即使机器重启，会话布局也能恢复。对于长期挂着 AI 任务的人来说，这个插件几乎是必备的。

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

5.1 安装与版本类问题速查

这张表里的每一条，我都在实际帮人排查时遇到过。尤其是最后一条，Ubuntu 用户十有八九会踩。

5.2 登录与认证类问题

codex登录不上、codex无法加载组织设置、your organization has disabled claude subscription access这几个热词，指向的都是认证环节。我的排查顺序是这样的：

1. 先看本地时间。系统时间偏差超过几分钟，认证令牌就会校验失败。date命令看一眼，不对就同步。
2. 再看账号状态。有些组织确实会禁用特定订阅的 CLI 访问，这种情况你换个人账号试一下就能确认。
3. 最后看网络。认证请求需要能正常到达服务端，如果一直超时，检查一下你的网络配置。

这三步走下来，九成的登录问题都能定位。

5.3 模型调用类问题

the 'gpt-5.6-sol' model is not supported when using codex这类报错，本质是你配置的模型名称和端点实际支持的模型对不上。解决思路很简单：去你的 API 提供方那里确认可用的模型列表，然后把配置里的模型名改成列表里真实存在的那个。

cc switch local proxy failed while handling codex endpoint /responses这种，通常是本地代理转发时端点路径或格式不匹配。检查你的代理配置里，Codex 的请求路径是不是/responses，以及代理是否正确转发了请求头。

5.4 配置类问题

codex is ignoring 1 unrecognized configuration setting这个警告，意思是你的配置文件里有一个它不认识的配置项。不影响使用，但建议清理掉，避免以后混淆。找到配置文件（通常在~/.codex/或项目目录下），删掉那个不认识的键即可。

5.5 独家避坑心得

说几个文档里不会写、但我踩过的坑。

第一，不要在 tmux 会话里用sudo跑 AI 工具。权限混乱会导致配置文件写到 root 目录下，之后你用普通用户跑就找不到配置了。

第二，Claude Code 和 Codex 的会话历史不要共享目录。它们各自的会话存储格式不同，混在一起容易出问题。让它们各用各的配置目录。

第三，切换模型后一定要重启 CLI。有些工具会缓存模型配置，你改了环境变量但不重启，它还是用旧的。这个坑我踩过不止一次。

第四，tmux 窗格太多会降低可读性。我一开始恨不得一个屏幕塞六个窗格，结果每个都窄得看不清输出。后来固定成最多三个窗格，体验反而更好。

6. 把 openrig 用顺手的几个进阶思路

6.1 用脚本一键拉起整套环境

每次手动开 tmux、分窗格、cd 目录、启动工具，太累。写个脚本一键搞定：

#!/bin/bash # openrig-start.sh SESSION="ai-work" tmux new-session -d -s $SESSION -n main tmux send-keys -t $SESSION:main "cd ~/projects/projectA && claude" C-m tmux new-window -t $SESSION -n review tmux send-keys -t $SESSION:review "cd ~/projects/projectB && codex" C-m tmux attach -t $SESSION

这个脚本跑完，你就直接进入一个已经准备好的工作环境。想加更多窗口，照着加就行。这种“一键拉起”的思路，正是 openrig 这类装置的价值所在。

6.2 让 AI 工具直接执行终端命令

热词里claude code如何直接执行终端命令是个高频疑问。Claude Code 这类工具本身就有执行 shell 命令的能力，但默认可能需要你确认。你可以在它的配置里调整权限策略，让它对某些安全命令自动执行。不过我的建议是保持确认机制，尤其是涉及删除、覆盖这类操作时，让 AI 先问你一句，能避免很多灾难。

6.3 本地模型与第三方 API 的接入

如果你想把 Claude Code 接到本地模型（比如通过 LM Studio 起的服务），核心就是改BASE_URL指向本地端口，模型名改成你本地加载的模型。Codex 接第三方 API 也是同理。这里的关键是确认 API 格式兼容——有些本地服务提供的是 OpenAI 兼容格式，有些不是，格式不对就会报错。

6.4 后续可以扩展的方向

这套 openrig 思路还能继续长。比如加一个日志窗格，实时看所有 AI 会话的输出；比如用 tmux 的 hook 在会话结束时自动发通知；比如把常用项目的启动配置做成模板，按项目名一键切换。我自己现在就在用一个“项目模板 + 一键拉起”的组合，每天开工前跑一条命令，五个窗格各就各位，省下的时间相当可观。

最后分享一个我个人的小习惯：每次搭好一套新的 openrig 环境，我都会把关键的配置、脚本、踩过的坑记在一个NOTES.md里，放在项目根目录。下次换机器或者过几个月再回来，照着笔记十分钟就能重建。这个习惯比任何记忆都靠谱。