openrig 实战：用 Node.js 与 tmux 装配 Claude Code 和 Codex 多模型工作台

1. openrig 到底想解决什么问题

第一次看到openrig这个名字，我下意识把它拆成了 “open” 和 “rig” 两部分。rig 在英文里除了“装备、装置”，在工程语境里还有“搭建、装配”的意思，比如 rig up a system。所以 openrig 从命名上就带着一种“把某套东西开放地组装起来”的意味。结合它出现在 Claude Code、Codex、Node.js、tmux 这一串关键词旁边，我基本能判断：这不是一个孤立的工具，而是一套围绕命令行 AI 编程助手做环境编排、会话管理和多模型接入的实践方案。

先把话说在前面，openrig目前并不是一个像 npm 上那种有明确版本号、有官方文档站点的成熟包。它更像是一个“约定俗成的工程实践集合”——把 Claude Code、Codex CLI 这类终端里的 AI 编程代理，和 Node.js 运行时、tmux 会话复用、本地模型服务（比如 LM Studio）这些东西拼装成一套顺手的工作台。你搜 openrig，搜到的往往不是一篇官方 README，而是一堆零散的配置片段、踩坑记录和热词。这恰恰说明它处在“实践先行、文档滞后”的阶段，也意味着谁先把这套装配逻辑讲清楚，谁就能帮后来者省下大量试错时间。

那它到底解决什么问题？我自己的体会是三个痛点。第一，AI 编程助手越来越多，Claude Code 一个、Codex 一个，将来可能还有别的，每个都要单独装、单独配、单独登录，环境一乱就互相打架。第二，这些工具都是命令行交互式的，一旦终端关掉，会话就没了，长任务跑到一半断掉非常难受。第三，很多人想用本地模型或者第三方 API 来跑这些 CLI，但配置项藏在各种环境变量和 JSON 文件里，官方文档又写得比较克制，导致“装是装上了，就是跑不通”。

openrig 的思路，就是用 Node.js 作为统一的运行时底座，用 tmux 作为会话的“容器”，把 Claude Code 和 Codex 这类 CLI 代理挂进去，再通过环境变量和配置文件把它们指向不同的模型后端。这样你的一套机器上可以同时存在多个代理、多个模型、多个会话，互不干扰，关掉终端也不丢状态。下面我就按这个思路，把整套装配过程拆开讲。

2. Node.js 是整个装配的地基，版本选错后面全白搭

2.1 为什么这类 CLI 工具都盯着 Node.js

Claude Code 和 Codex CLI 这类工具，本质上是用 JavaScript/TypeScript 写的命令行程序，通过 npm 分发。你执行npm install -g的时候，npm 会去 registry 拉包，然后 Node.js 运行时负责把它跑起来。所以 Node.js 不是可选项，是硬依赖。很多人以为“我装了 Node 就行了”，其实版本差异会直接决定工具能不能启动。

我见过最典型的报错就是热词里那条error installing 24.21.0: node.js v24.21.0 is not yet released or is not available。这个错误的本质是：你或者某个安装脚本指定了一个还不存在的 Node 版本号。Node.js 的版本发布是有节奏的，偶数版本走 LTS（长期支持），奇数版本是过渡版。你在网上看到别人写24.21.0，可能只是他本地恰好装了这个版本，但那个版本在你的时间点上根本没发布，或者已经被标记为不可用。安装脚本一旦写死版本号，就会直接失败。

所以我的第一条经验是：永远优先装 LTS 版本，不要追最新的奇数版，也不要在脚本里写死小版本号。LTS 版本经过更长时间的验证，npm 生态兼容性最好。你去 Node.js 官网下载页，认准标着 “LTS” 的那个大按钮就行，别去点 “Current”。

2.2 三个平台的安装方式与验证

Windows 用户最省事的方式是去 Node.js 官网下载.msi安装包，双击一路下一步。安装完成后打开 PowerShell 或 CMD，执行：

node -v npm -v

两条命令都能打印出版本号，说明装好了。如果node -v报“不是内部或外部命令”，八成是安装时没勾选 “Add to PATH”，重新跑一遍安装程序，把那个选项勾上。

macOS 用户我建议用 Homebrew，一条命令搞定：

brew install node@lts

如果你已经装了别的版本，可以用brew link --overwrite --force node@lts切换。注意 Homebrew 装的 Node 有时候和系统自带的会有 PATH 优先级冲突，装完记得which node确认一下指向的是/opt/homebrew/bin/node而不是/usr/local/bin/node。

Ubuntu 用户别直接用apt install nodejs，那个版本往往很旧。推荐用 NodeSource 的源，或者更稳妥一点，用 nvm 来管理多版本：

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash source ~/.bashrc nvm install --lts nvm use --lts

nvm 的好处是你可以同时装好几个 Node 版本，随时切换。做 openrig 这种多工具装配的时候，不同工具对 Node 版本的要求可能不一样，nvm 能让你少很多麻烦。

2.3 npm 全局目录的权限坑

装完 Node 之后，紧接着就会遇到 npm 全局安装的权限问题。Linux 和 macOS 上，如果你直接用系统 Node，npm install -g会往/usr/lib/node_modules写，普通用户没权限，于是你就得加sudo。加了sudo之后，装出来的包属主是 root，后面升级、卸载又会出问题，形成恶性循环。

正确的做法是给 npm 配一个用户级的全局目录：

mkdir -p ~/.npm-global npm config set prefix '~/.npm-global'

然后把~/.npm-global/bin加到 PATH 里。在~/.bashrc或~/.zshrc末尾加一行：

export PATH=~/.npm-global/bin:$PATH

重新 source 一下配置文件，之后所有npm install -g都不需要 sudo 了。这一步看着小，但它决定了你后面装 Claude Code、Codex 的时候顺不顺。我见过太多人卡在权限上，反复 sudo 把环境搞乱，最后只能重装系统。

提示：如果你用的是 nvm，nvm 已经帮你把全局目录设到用户空间了，不需要再手动配 prefix。这也是我推荐 nvm 的原因之一。

3. tmux 不是可选项，它是长任务会话的保险绳

3.1 为什么 AI 编程代理特别需要 tmux

Claude Code 和 Codex 这类工具的工作模式是“你给它一个任务，它在终端里持续输出、执行命令、读写文件”。一个稍微复杂的重构任务，它可能跑十几分钟甚至更久。如果你直接在普通终端里跑，一旦网络抖动、SSH 断开、或者你不小心关了窗口，进程就收到 SIGHUP 挂掉了，前面的工作全白费。

tmux 解决的就是这个问题。它创建一个独立于终端的会话（session），你的终端只是“附着”到这个会话上。终端断了，会话还在后台跑；你重新连上来，tmux attach一下就回到原来的界面，输出还在，进程还活着。对于 openrig 这种要同时管理多个 AI 代理的场景，tmux 还能让你在一个窗口里开多个 pane，左边跑 Claude Code，右边跑 Codex，下面开个 shell 看日志，效率直接翻倍。

3.2 安装与最小可用配置

Ubuntu/Debian：

sudo apt update sudo apt install tmux

macOS：

brew install tmux

Windows 原生没有 tmux，但如果你用 WSL2，那里面就是完整的 Linux 环境，直接apt install tmux即可。这也是我推荐 Windows 用户走 WSL2 路线的原因——Claude Code、Codex、tmux 在 Linux 环境下体验最一致。

装完之后，我建议先改一下前缀键。tmux 默认前缀是Ctrl+b，和很多编辑器的快捷键冲突。改成Ctrl+a更顺手，在~/.tmux.conf里写：

set -g prefix C-a unbind C-b bind C-a send-prefix set -g mouse on set -g history-limit 50000

set -g mouse on让你可以用鼠标滚轮翻历史、点选 pane，对新手非常友好。history-limit调大是因为 AI 代理的输出量很大，默认的 2000 行很快就滚没了，查历史的时候很痛苦。

3.3 一套适合 openrig 的会话组织方式

我的习惯是给每个项目建一个独立的 tmux 会话，会话名就用项目名：

tmux new -s myproject

进去之后按Ctrl+a再按%左右分屏，按Ctrl+a再按"上下分屏。我通常这样安排：左边大 pane 跑 Claude Code，右上角跑 Codex，右下角留一个普通 shell 用来执行 git 命令、看文件。这样三个上下文都在一个屏幕里，切换成本极低。

如果你要临时离开，按Ctrl+a再按d就是 detach，会话转入后台。回来的时候：

tmux ls tmux attach -t myproject

tmux ls会列出所有会话，你能看到每个会话开了多久、有几个窗口。这个命令我每天要敲几十遍，强烈建议记牢。

注意：tmux 会话是存在内存里的，机器重启就没了。如果你需要跨重启保留，得配合 tmux-resurrect 这类插件，但那是进阶话题，初期不用折腾。

4. Claude Code 与 Codex 的安装、登录与模型接入

4.1 Claude Code 的安装路径与常见报错

Claude Code 通过 npm 分发，安装命令是：

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

装完之后执行claude就能启动。第一次启动会让你登录，走浏览器授权流程。这里有几个高频坑。

第一个是热词里那条your organization has disabled claude subscription access for claude code。这个报错的意思是：你登录的账号所属组织，在管理后台把 Claude Code 的访问权限关掉了。这不是你本地环境的问题，而是账号策略问题。解决办法要么是找组织管理员开权限，要么换一个个人账号登录。很多人折腾半天重装、换 Node 版本，其实方向完全错了。

第二个是note: claude code might not be available in your country. check supported co...。这类提示通常和账号所在区域、支付方式有关，属于服务可用性层面的限制，不是技术配置能绕过的。遇到这种提示，先确认自己的账号状态是否正常，不要盲目去改网络配置，那既没用也不安全。

第三个是 Windows 上的路径问题。Claude Code 在 Windows 原生 CMD 里跑，有时候会因为路径分隔符和 shell 差异出问题。我的建议是 Windows 用户统一在 WSL2 里操作，或者用 Git Bash，能规避掉大部分诡异报错。

4.2 Codex CLI 的安装与配置校验

Codex CLI 同样是 npm 包，安装命令类似：

npm install -g @openai/codex

装完执行codex启动。Codex 的配置比 Claude Code 稍微复杂一点，因为它支持多种模型后端，配置项散落在环境变量和配置文件里。热词里那条codex is ignoring 1 unrecognized configuration setting. check for typos or d...就是典型的配置项拼写错误。Codex 启动时会读取配置文件，遇到它不认识的键就会警告。这个警告本身不致命，但说明你的配置没生效，得回去检查拼写。

我的做法是：每次改完配置，先跑一次codex看启动日志，确认没有 unrecognized setting 的警告，再去干正事。配置文件的格式通常是 TOML 或 JSON，缩进和引号很容易写错，用编辑器的语法高亮能省不少事。

还有一个热词是codex无法加载组织设置。这个和 Claude Code 的组织权限问题类似，属于账号层面的策略限制。Codex 如果绑定了某个组织，而组织没有开启相应权限，就会加载失败。处理思路一样：确认账号状态，必要时切换账号。

4.3 把模型后端指向本地或第三方

这是 openrig 最有价值的部分。很多人不想只用官方默认模型，而是想接本地跑的模型（比如 LM Studio 起的服务），或者接第三方 API。Claude Code 和 Codex 都支持通过环境变量覆盖默认的 API 端点。

以接入本地模型为例，LM Studio 默认在http://localhost:1234/v1提供一个兼容 OpenAI 格式的接口。你可以在启动 Codex 前设置：

export OPENAI_BASE_URL=http://localhost:1234/v1 export OPENAI_API_KEY=lm-studio

然后启动codex，它就会把请求发到本地。注意OPENAI_API_KEY这里随便填一个非空值就行，本地服务一般不校验，但很多客户端要求这个变量必须存在，不填会直接报错。

Claude Code 接本地模型稍微麻烦一点，因为它默认走 Anthropic 的接口格式。你需要一个中间层做协议转换，或者使用支持 Anthropic 格式的本地服务。这块的配置因工具版本而异，我的建议是先把官方默认链路跑通，确认工具本身没问题，再去折腾模型替换。顺序反了的话，出了问题你分不清是工具没装好还是模型没接对。

热词里提到的cc switch local proxy failed while handling codex endpoint /responses就是典型的“中间层转换失败”。这类报错通常出在代理层，可能是请求格式不匹配、可能是流式响应处理有问题。排查的时候先看代理层的日志，再看 Codex 的日志，逐层定位，不要一上来就怀疑模型本身。

5. 多工具共存时的环境隔离与冲突排查

5.1 环境变量是最容易打架的地方

Claude Code 和 Codex 都读环境变量，而且有些变量名是通用的，比如OPENAI_API_KEY、OPENAI_BASE_URL。如果你在同一个 shell 里同时配了两套，后配的会覆盖先配的，导致其中一个工具连到错误的端点。我踩过这个坑：本来 Claude Code 走官方，Codex 走本地，结果因为环境变量互相覆盖，两个都连到了本地，Claude Code 直接报协议不兼容。

解决办法是用不同的 shell 会话或不同的 tmux pane 来隔离环境。tmux 的每个 pane 是独立的 shell 进程，你在 pane A 里 export 的变量不会影响 pane B。所以我前面建议左边跑 Claude Code、右上跑 Codex，不只是为了看着方便，更是为了环境隔离。如果你非要在同一个 shell 里切换，那就写两个脚本，一个负责 export Claude 的变量并启动，另一个负责 Codex 的，用完就关掉 shell，别让变量残留。

5.2 全局包版本冲突的处理

npm install -g装的包都在同一个全局目录里，如果两个工具依赖同一个库的不同版本，npm 会尽量做扁平化处理，但偶尔还是会冲突。表现是某个工具启动时报Cannot find module或者版本不匹配的错。

排查方法是看报错里提到的模块路径，然后：

npm ls -g --depth=0

列出所有全局包的顶层依赖，看看有没有重复或版本异常的。如果确认是冲突，最干净的办法是用 nvm 给不同工具分配不同的 Node 版本，各自装各自的全局包，彻底隔离。这也是我反复强调 nvm 的原因——它不只是版本管理，更是环境隔离的手段。

5.3 一个可复现的排查链路

我把上面这些坑整理成一条排查链路，遇到问题按顺序走：

这条链路的价值在于：它把“玄学问题”变成了“逐项排除”。我见过太多人一遇到报错就重装，重装完还是同样的错，因为根因根本没找到。按这个表走一遍，九成问题都能定位到具体环节。

6. 把 openrig 用顺手的几个实操心得

6.1 给每个项目写一个启动脚本

与其每次手动敲一堆 export 和启动命令，不如给每个项目写一个start.sh：

#!/bin/bash export OPENAI_BASE_URL=http://localhost:1234/v1 export OPENAI_API_KEY=local tmux new-session -d -s "$1" -c "$(pwd)" tmux send-keys -t "$1" "claude" C-m tmux split-window -h -t "$1" tmux send-keys -t "$1" "codex" C-m tmux attach -t "$1"

这个脚本做了几件事：创建以项目名命名的 tmux 会话，左边启动 Claude Code，右边启动 Codex，然后附着上去。你只需要./start.sh myproject，一套工作台就搭好了。脚本里的-c "$(pwd)"保证会话的工作目录是当前项目目录，避免 AI 代理在错误的目录里操作文件。

6.2 日志要留，但别留在终端里

AI 代理的输出量很大，全堆在终端里既占内存又难查。我的做法是在 tmux 里再开一个 pane，用tee把关键输出同时写到文件：

claude 2>&1 | tee -a ~/logs/claude-$(date +%F).log

这样终端里能实时看，文件里也留了底。出问题的时候翻日志比翻终端历史靠谱得多，尤其是 tmux 的 history-limit 再大也有上限。

6.3 别在 AI 代理会话里跑危险命令

这一点必须单独拎出来说。Claude Code 和 Codex 都有执行终端命令的能力，这是它们的核心价值，但也是风险点。我给自己定了几条规矩：涉及rm -rf、git reset --hard、数据库删表这类不可逆操作，一定先让代理把命令打印出来，我人工确认后再执行；重要项目在跑代理之前先git commit一次，保证随时能回滚；生产环境的凭证绝对不放在代理能读到的环境变量里。

热词里有个claude code如何直接执行终端命令，说明很多人对这个能力既好奇又担心。我的态度是：用，但要带着刹车用。代理再聪明也是概率模型，它可能把rm -rf ./build写成rm -rf ./，这种错误人类一眼能看出来，但如果你开了自动执行，它就直接跑下去了。

6.4 版本升级要留退路

Claude Code 和 Codex 都在快速迭代，新版本可能改了配置格式、改了环境变量名。我吃过一次亏：某次升级后，原来的配置文件里有个键被重命名了，工具启动直接报错，而当时我正在赶一个任务，临时去查文档很耽误事。

现在的做法是：升级前先npm ls -g记下当前版本号，升级后如果出问题，可以npm install -g @anthropic-ai/claude-code@旧版本号回退。同时把配置文件用 git 管理起来，每次改动都有记录，回退的时候直接 checkout。这套习惯看着麻烦，但真出事的时候能救命。

7. 关于 openrig 这套装配思路的延伸

openrig 这个名字背后，其实是一种很务实的工作方式：不追求某个“大一统”的工具，而是把几个各有所长的命令行程序，用 Node.js 和 tmux 这两样基础设施拼装起来，形成一个可复用、可隔离、可持久的工作台。Claude Code 擅长什么、Codex 擅长什么，你可以在不同的 pane 里同时用，让它们各干各的，而不是被迫二选一。

这套思路还能继续往外扩。比如你可以在 tmux 里再挂一个 pane 跑本地模型服务，或者挂一个文件监听工具，代理一改代码就自动跑测试。再比如你可以把启动脚本参数化，根据项目类型自动选择用哪个模型、开几个 pane。这些都不是 openrig 官方提供的能力，而是这套装配方式天然留出的扩展空间。

我在实际使用中最大的体会是：工具本身会变，但“用 tmux 管会话、用 Node 管运行时、用环境变量管配置”这三条底层逻辑不会轻易变。你把这三样吃透，将来不管冒出什么新的 AI 编程代理，你都能在半小时内把它接进自己的工作流。反过来，如果你每次都从零开始照着教程一步步点，那每换一个工具就要重新踩一遍坑。

最后分享一个小技巧：把你常用的 tmux 会话布局写成配置文件，用 tmuxinator 或者自己写脚本管理。我现在的项目启动脚本已经能做到“一条命令，五个 pane，三个代理，两个日志窗口”全部就位。这套东西搭一次，后面每个项目都能省下十几分钟的环境准备时间，累积下来相当可观。