1. 从“openrig”说起：一个把 Claude Code 和 Codex 装进同一台机器的实战思路
第一次看到 “openrig” 这个词，我下意识把它拆成了 “open” 和 “rig” 两半。rig 在英文里除了“装备、装置”，在工程语境里还有一层很实在的意思——把一堆零散的部件搭成一套能跑起来的系统。放到当下这个时间点，openrig 指向的东西其实非常明确：把 Claude Code、Codex 这类命令行 AI 编程助手，连同 Node.js、tmux 这些底层依赖，整合成一套可复用、可切换、可维护的本地开发环境。
我身边不少朋友最近都在折腾同一件事：一边想用 Claude Code 处理日常的代码理解和重构，一边又想用 Codex 跑一些批量任务或者接第三方模型，结果两台工具各自装一套 Node.js，版本还打架，终端窗口开了一堆，tmux 会话切来切去，最后自己都记不清哪个窗口跑的是哪个。openrig 这个标题背后真正要解决的，就是这种“工具越多越乱”的状态。
这篇文章适合谁看？如果你已经在用或者准备用 Claude Code、Codex，被 Node.js 版本、安装报错、模型接入、终端会话管理这些问题卡过，那这篇就是写给你的。我会从整体设计思路讲起，把 Node.js 环境、Claude Code 安装、Codex 安装、tmux 会话管理、第三方模型接入这几块拆开揉碎，再给出一套我自己实测下来比较稳的搭建流程。全程不涉及任何网络访问工具，只讲本地环境怎么搭、工具怎么配、坑怎么避。
需要先说明一点：openrig 不是一个官方发布的软件包，它更像是一种“环境搭建范式”的统称。所以下面所有内容，都是基于我作为一个长期折腾命令行工具的人，在这个场景下最可能采用的合理方案来展开的，你可以直接抄作业，也可以按自己的习惯调整。
2. 整体设计思路：为什么要把这些工具“捆”在一起
2.1 核心矛盾：工具各自为政带来的版本地狱
先说清楚问题在哪。Claude Code 和 Codex 本质上都是 Node.js 生态里的命令行工具，它们对 Node.js 版本有各自的要求。Claude Code 官方推荐较新的 LTS 版本，Codex 在不同阶段对 Node.js 版本的要求也不完全一致。如果你像我一样，先装了 Claude Code，过两天又想试 Codex，很容易出现这样的情况：全局 npm 里两个工具的依赖互相干扰，或者某个工具在 Node.js 24 上跑不起来，报出类似 “node.js v24.21.0 is not yet released or is not available” 这种让人一头雾水的错误。
我踩过的第一个坑就是：直接用系统自带的 Node.js，版本太老，装 Claude Code 时各种编译报错；后来手动升级到最新版，结果 Codex 又提示某些原生模块不兼容。折腾了一下午才明白，问题的根源不是工具本身，而是我把所有东西都塞进了同一个全局环境。
2.2 设计原则：隔离、可切换、可复现
openrig 这套思路的核心，我总结成三个词：隔离、可切换、可复现。
隔离的意思是，不同工具尽量用独立的 Node.js 版本管理，不要全部依赖系统全局的那一个。可切换的意思是，Claude Code 和 Codex 之间要能快速切换，包括模型接入的切换，比如今天用官方模型，明天想接本地模型或者第三方 API，不应该每次都改一堆配置文件。可复现的意思是，整套环境搭好之后，换一台机器或者重装系统，能照着步骤快速重建，而不是靠记忆。
基于这三个原则，我最终确定的方案是：用 Node.js 版本管理工具（比如 nvm 或 fnm）来管理多个 Node.js 版本，Claude Code 和 Codex 分别绑定到各自验证过的版本上；用 tmux 来管理终端会话，一个会话跑 Claude Code，一个会话跑 Codex，互不干扰；模型接入层面，通过环境变量和配置文件来区分不同后端，避免硬编码。
2.3 为什么选 tmux 而不是多开终端窗口
有人可能会问，多开几个终端窗口不就行了，为什么要用 tmux？我一开始也是这么想的，直到我的窗口数量超过了十个，每次找某个会话都要在任务栏里翻半天。tmux 的好处在于，它把会话和窗口解耦了。你可以创建一个名为 “claude” 的会话专门跑 Claude Code，再创建一个名为 “codex” 的会话跑 Codex，需要的时候一条命令切过去，不需要的时候 detach 掉，后台继续跑。
更重要的是，tmux 会话在 SSH 断开或者终端意外关闭后依然存活。我有一次跑一个长时间的代码分析任务，笔记本合盖休眠了一下，终端断了，但因为跑在 tmux 里，重新连上之后任务还在。这个体验一旦用过就回不去了。对于需要长时间运行 AI 编程助手的场景，tmux 几乎是必备的。
2.4 方案选型的取舍：为什么不追求“一键脚本”
网上有很多一键安装脚本，我也试过几个，但最后都放弃了。原因很简单：一键脚本把细节全藏起来了，一旦出错，你根本不知道是哪一步的问题。而 openrig 这套东西涉及 Node.js 版本、全局包路径、环境变量、模型配置多个层面，任何一个环节出问题都需要能定位。所以我更倾向于手动分步搭建，每一步都验证通过再进行下一步。慢是慢一点，但出问题时心里有数。
3. 核心细节解析：Node.js、Claude Code、Codex 的安装要点
3.1 Node.js 安装：版本选择比安装本身更重要
Node.js 是这一切的地基。很多人安装 Node.js 的方式是去官网下载一个安装包，双击下一步，装完事。这种方式在只用一个工具时没问题，但当你同时要跑 Claude Code 和 Codex 时，就会遇到版本冲突。
我的建议是，先装一个 Node.js 版本管理工具。在 macOS 和 Linux 上，nvm 是最成熟的选择；Windows 上可以用 nvm-windows，或者如果你用 WSL，直接按 Linux 的方式装 nvm。装好之后，不要急着装最新版，而是先确认 Claude Code 和 Codex 各自推荐的 Node.js 版本。
根据我的实测，Claude Code 在 Node.js 20 LTS 和 22 LTS 上都比较稳，Codex 对 Node.js 版本相对宽松，但建议不要用太老的版本。所以我的做法是：用 nvm 装一个 20 LTS 作为主力版本，再装一个 22 LTS 作为备用。具体命令如下：
# 安装 nvm（macOS/Linux） curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash # 重新加载 shell 配置 source ~/.bashrc # 或 ~/.zshrc # 安装 Node.js 20 LTS nvm install 20 nvm use 20 nvm alias default 20 # 再装一个 22 LTS 备用 nvm install 22装完之后用node -v和npm -v确认版本。这里有个细节：nvm 安装的 Node.js 是用户级别的，不会污染系统全局，这也是我推荐它的核心原因。如果你在 Windows 上，nvm-windows 的用法类似，但要注意安装时需要管理员权限，而且切换版本后可能需要重开终端才能生效。
提示：如果你之前用系统包管理器装过 Node.js，建议先卸载干净，否则 nvm 的版本切换可能不生效。用
which node确认当前用的是 nvm 管理的版本，而不是系统自带的。
3.2 Claude Code 安装：全局安装与路径问题
Node.js 就绪之后，Claude Code 的安装本身不复杂，但有几个细节容易翻车。标准做法是全局安装：
npm install -g @anthropic-ai/claude-code装完之后，直接运行claude命令，如果提示找不到命令，说明 npm 的全局 bin 目录没有加到 PATH 里。这是新手最常遇到的问题。解决办法是先查一下全局 bin 目录在哪：
npm config get prefix假设输出是/Users/yourname/.nvm/versions/node/v20.11.0，那么 bin 目录就是它下面的bin子目录。把这个路径加到你的 shell 配置文件里：
export PATH="$PATH:/Users/yourname/.nvm/versions/node/v20.11.0/bin"然后source一下配置文件，再运行claude应该就能识别了。我建议在 nvm 的配置里加上--no-use或者确保每次切换 Node.js 版本后重新确认全局包，因为 nvm 的全局包是按版本隔离的，你在 20 下装的 Claude Code，切到 22 之后可能就找不到了。
另一个常见问题是权限。如果你用sudo npm install -g，可能会把包装到系统目录，导致后续权限混乱。我的经验是，永远不要用 sudo 装全局 npm 包，如果遇到权限报错，说明 npm 的 prefix 配置有问题，应该去修 prefix，而不是加 sudo。
3.3 Codex 安装：注意配置文件的坑
Codex 的安装方式取决于你用的是哪个版本。如果是官方 CLI，通常也是通过 npm 全局安装。安装命令类似：
npm install -g @openai/codex装完之后运行codex，第一次会引导你登录或者配置 API。这里有个我踩过的坑：Codex 在启动时会读取配置文件，如果配置文件里有拼写错误或者不认识的字段，它会提示 “codex is ignoring 1 unrecognized configuration setting. check for typos or d...”。这个提示本身不致命，但如果你没注意到，可能会以为配置生效了，实际上被忽略了。
所以我的习惯是，每次改完 Codex 的配置文件，都仔细看一遍启动时的输出，确认没有 unrecognized setting 的警告。配置文件的位置通常在用户目录下的.codex或者.config/codex目录里，具体取决于版本。改配置之前先备份一份，出问题了直接还原。
还有一个问题是 Codex 的登录。如果你用的是官方服务，登录流程一般比较顺畅；如果遇到 “your organization has disabled claude subscription access” 这类提示，那通常是账号权限或者订阅状态的问题，跟本地环境无关，需要去账号层面解决。这类问题我在本地怎么折腾都没用，最后发现是账号设置的问题，白白浪费了一个小时。
3.4 tmux 会话管理：让两个工具各占一个“房间”
tmux 的安装很简单，macOS 上用brew install tmux，Ubuntu 上用apt install tmux。装完之后，我建议先建一个配置文件~/.tmux.conf，加上几行基础配置，让操作更顺手：
# 把前缀键改成 Ctrl+a，比默认的 Ctrl+b 更顺手 set -g prefix C-a unbind C-b bind C-a send-prefix # 开启鼠标支持 set -g mouse on # 窗口编号从 1 开始 set -g base-index 1 setw -g pane-base-index 1配置好之后，创建两个会话：
# 创建名为 claude 的会话 tmux new -s claude # 在会话里运行 Claude Code claude # 按 Ctrl+a 然后按 d 脱离会话 # 创建名为 codex 的会话 tmux new -s codex codex之后想切回 Claude Code，就tmux attach -t claude；想切到 Codex，就tmux attach -t codex。查看当前有哪些会话用tmux ls。这套操作熟练之后，切换工具就是一两秒的事，比在任务栏里找窗口快得多。
注意：tmux 会话里的环境变量是创建会话时继承的。如果你在创建会话之后切换了 Node.js 版本，会话里的版本不会自动更新。所以我的做法是，先确认好 Node.js 版本，再创建 tmux 会话。
4. 实操过程：从零搭一套可用的 openrig 环境
4.1 环境准备与版本确认
假设你现在是一台干净的机器，我们从零开始。第一步是确认系统环境。macOS 和 Ubuntu 的流程略有不同，但核心步骤一致。先确认 shell 类型，echo $SHELL，如果是 zsh，配置文件就是~/.zshrc，如果是 bash，就是~/.bashrc。后面的 PATH 配置要写到对应的文件里。
然后安装 nvm，装 Node.js 20 LTS，确认版本。这一步做完之后，先不要急着装 Claude Code 和 Codex，而是先确认 npm 的全局路径配置正确。运行npm config get prefix，记下这个路径，把它加到 PATH 里。这一步是整个流程里最容易被忽略但最重要的一步，PATH 没配好，后面所有全局命令都会找不到。
4.2 Claude Code 的安装与首次运行
Node.js 和 PATH 都确认无误后，安装 Claude Code：
npm install -g @anthropic-ai/claude-code安装完成后，运行claude --version确认安装成功。然后进入一个你的项目目录，运行claude启动。第一次启动会引导你完成认证或者配置。如果你用的是官方服务，按提示操作即可；如果你想接本地模型或者第三方 API，先别急着配，等基础流程跑通再说。
首次运行我建议先在一个测试目录里进行，不要直接在你的主力项目里跑。因为 Claude Code 会读取项目文件，万一配置有问题，可能产生意料之外的操作。测试目录里放几个简单的代码文件，跑一下基本的问答和文件读取，确认工具能正常工作。
4.3 Codex 的安装与配置分离
Codex 的安装类似：
npm install -g @openai/codex装完之后，先运行codex --help看看有哪些子命令和选项。然后运行codex进入交互模式，完成登录或 API 配置。这里我要强调一个经验：Codex 的配置尽量通过环境变量或者独立的配置文件来管理，不要把敏感信息直接写在命令行历史里。
如果你要接第三方模型，比如通过兼容接口接入其他模型服务，通常需要设置OPENAI_API_KEY和OPENAI_BASE_URL这两个环境变量。我的做法是在~/.zshrc里定义不同的函数来切换配置，比如：
# 切换到官方配置 codex-official() { export OPENAI_API_KEY="your-official-key" export OPENAI_BASE_URL="https://api.openai.com/v1" } # 切换到第三方配置 codex-thirdparty() { export OPENAI_API_KEY="your-thirdparty-key" export OPENAI_BASE_URL="https://your-thirdparty-endpoint/v1" }这样需要切换的时候，运行对应的函数就行，不用每次手动改环境变量。这个技巧同样适用于 Claude Code 接本地模型的场景。
4.4 tmux 会话编排与日常使用流程
环境都搭好之后，用 tmux 把两个工具编排起来。我的日常流程是这样的：开机后先打开终端，运行tmux attach -t claude进入 Claude Code 会话，处理需要深度理解的代码任务；需要跑批量任务或者用另一个模型时，按Ctrl+a然后按s列出所有会话，选择 codex 会话切过去。
如果你觉得每次 attach 太麻烦，可以在 shell 配置里加两个别名：
alias tc='tmux attach -t claude' alias tx='tmux attach -t codex'这样tc和tx两个命令就能快速切换。另外，tmux 会话如果意外被关闭，里面的进程也会终止。所以对于长时间运行的任务，我建议在 tmux 里再用nohup或者把任务放到后台，避免会话意外断开导致任务中断。
4.5 模型接入的切换策略
Claude Code 和 Codex 都支持接入不同的模型后端。Claude Code 可以接本地模型，比如通过 LM Studio 提供的兼容接口；Codex 可以接第三方 API。这里的关键是，不同后端的接口格式和认证方式可能不同，切换时要确保环境变量和配置文件同步更新。
我的做法是为每个后端准备一个独立的配置文件，切换时用软链接或者环境变量指向对应的配置。比如 Claude Code 的配置可以放在~/.claude/configs/目录下，每个后端一个文件，切换时用ln -sf更新软链接。这样比每次手动改配置安全得多，也不容易出错。
提示：接本地模型时，要确认本地服务的接口地址和端口，以及模型名称是否匹配。我遇到过接口地址写对了但模型名称写错，导致请求一直失败的情况，排查了半天才发现是模型名的问题。
5. 常见问题与排查技巧实录
5.1 安装类问题速查表
| 问题现象 | 可能原因 | 排查与解决 |
|---|---|---|
claude命令找不到 | npm 全局 bin 目录未加入 PATH | 运行npm config get prefix，把其下的 bin 目录加入 PATH |
node.js v24.21.0 is not yet released | Node.js 版本与工具要求不匹配 | 用 nvm 切换到 20 LTS 或 22 LTS |
| 全局安装报权限错误 | npm prefix 指向系统目录 | 修改 npm prefix 到用户目录，不要用 sudo |
| Codex 提示 unrecognized setting | 配置文件有拼写错误或多余字段 | 检查配置文件，删除不认识的字段 |
| 切换 Node.js 版本后工具失效 | nvm 全局包按版本隔离 | 在新版本下重新全局安装对应工具 |
这张表里的问题，我几乎每一个都实际遇到过。其中“切换 Node.js 版本后工具失效”这个坑最隐蔽，因为报错信息往往不会直接告诉你是因为版本切换导致的。我的经验是，每次用 nvm 切换版本后，都运行一下which claude和which codex，确认指向的是当前版本的路径。
5.2 模型接入类问题排查
模型接入的问题通常表现为请求失败、超时或者返回格式错误。排查思路是分层的：先确认网络能通到目标接口，再确认认证信息正确，最后确认请求格式符合接口要求。我遇到过一次 “cc switch local proxy failed while handling codex endpoint /responses” 的报错，最后发现是本地代理配置和 Codex 的接口路径不匹配，调整路径后就好了。
对于接本地模型的场景，我建议先用 curl 直接测试接口，确认接口本身能正常工作，再让 Claude Code 或 Codex 去调用。这样能把问题范围缩小，避免在工具层面瞎折腾。测试命令类似：
curl -X POST http://localhost:1234/v1/chat/completions \ -H "Content-Type: application/json" \ -d '{"model":"your-model","messages":[{"role":"user","content":"hello"}]}'如果 curl 能通，工具不通，那就是工具配置的问题；如果 curl 也不通，那就是本地服务的问题。
5.3 终端会话类问题
tmux 最常见的问题是会话里的环境变量不对。比如你在创建会话之后才设置了某个 API key，会话里是读不到的。解决办法是在创建会话之前设置好所有环境变量，或者在会话里手动 export。另一个问题是 tmux 会话里的终端尺寸不对，导致界面显示错乱，这个可以通过tmux resize-window或者重新 attach 解决。
还有一个我踩过的坑：在 tmux 会话里运行 Claude Code 时，如果会话是在旧版本 Node.js 下创建的，而你在外部切换了版本，会话里的 Claude Code 可能行为异常。所以我的习惯是，每次切换 Node.js 版本后，重建 tmux 会话，确保环境一致。
5.4 独家避坑心得
第一条心得：所有配置文件都纳入版本管理。我用一个私有的 git 仓库管理~/.zshrc、~/.tmux.conf、Claude Code 和 Codex 的配置文件。这样换机器时直接 clone 下来，改改路径就能用，不用凭记忆重配。第二条心得：每次改动环境后，记录一条日志，写清楚改了什么、为什么改、验证结果如何。这个习惯帮我省了很多重复排查的时间。
第三条心得：不要追求一次配到完美。openrig 这套环境是可以逐步演进的，先让 Claude Code 跑起来，再让 Codex 跑起来，最后再优化 tmux 和模型切换。一次性想配好所有东西，反而容易在某个环节卡住，导致整体进度停滞。我自己的环境就是迭代了三四次才稳定下来的。
6. 后续可以怎么扩展这套环境
这套环境搭好之后，其实还有很多可以扩展的方向。比如你可以把常用的项目目录做成 tmux 的 session 模板，一键创建带 Claude Code 和 Codex 的工作区。也可以写一个简单的 shell 脚本，在启动时自动检查 Node.js 版本、工具版本和配置文件状态，有问题提前报警。
另外，如果你同时用 VS Code，可以考虑把 Claude Code 和 Codex 的终端集成到 VS Code 的终端面板里，通过 VS Code 的任务配置来管理。不过我个人还是更习惯独立的 tmux 会话，因为 VS Code 的终端在窗口关闭时容易中断，而 tmux 会话是持久的。
最后分享一个小技巧：给 tmux 会话加上状态栏显示，把当前 Node.js 版本和当前使用的模型后端显示在状态栏上，这样一眼就能看出当前环境是什么状态，避免在错误的版本或配置下操作。这个配置在~/.tmux.conf里加几行就能实现，具体可以根据自己的需求调整。
