1. 从“openrig”说起：一个把 Claude Code 和 Codex 装进同一副骨架的思路
第一次看到 “openrig” 这个词，我脑子里蹦出来的不是某个具体软件，而是一种“机架”的隐喻——rig 在英文里本来就有“装配、装置、台架”的意思，open 则点明了它的开放属性。把这两个词拼在一起，再结合热搜里高频出现的 Claude Code、Codex、Node.js、tmux 这几个关键词，基本能还原出它想解决的问题：把当下最主流的两个终端 AI 编程助手，统一装配到一套可复用、可切换、可远程托管的本地环境里。
我自己是从 Claude Code 刚开放那阵子就开始折腾的，后来又陆续在几台机器上装了 Codex CLI，中间踩过的坑可以说能写一本小册子。最典型的一个场景是：你在本地 VS Code 里用 Claude Code 写得好好的，突然想换 Codex 试试同一个任务，结果发现两套工具的配置目录、认证方式、模型接入点、会话管理逻辑完全不一样，切来切去像在两个平行宇宙里跳。openrig 这类思路的价值，就是把这套“平行宇宙”收敛成一个统一的机架——你只管把工具挂上去，剩下的环境隔离、会话保持、模型路由、远程访问，交给机架本身去处理。
这篇文章适合谁看？如果你已经在用或者准备用 Claude Code、Codex CLI，并且不满足于“装完能用就行”，而是想让它们在同一台机器上长期稳定共存、能远程连、能接本地模型、能随时切换，那这篇就是写给你的。如果你连 Node.js 都还没装过，也别急着关页面，我会从最基础的环境准备讲起，把每一步的“为什么”都说清楚，保证你照着做能跑通。
需要先说明一点：openrig 并不是一个官方标准名词，它更像是一个社区里逐渐成型的“装配范式”。所以下面我讲的内容，一部分来自我自己的实际配置经验，一部分是基于这类工具常见实践做的合理补全。你完全可以根据自己的机器情况做裁剪，核心思路是通用的。
2. 整体设计思路：为什么要把两个 CLI 装进同一个机架
2.1 核心矛盾：两套工具，两套世界观
Claude Code 和 Codex CLI 虽然都是终端里的 AI 编程助手，但它们的设计哲学差异很大。Claude Code 更偏向“会话式代理”，它会在你的项目目录里维护一套自己的上下文，能直接执行终端命令、读写文件，交互感很强；Codex CLI 则更偏向“任务式执行”，你给它一个指令，它去完成，中间过程相对收敛。这种差异导致它们的配置目录、认证缓存、会话状态存储方式都不一样。
如果你只是偶尔用其中一个，那无所谓。但如果你像我一样，日常要在两个工具之间来回切，问题就来了：环境变量会互相污染，认证 token 可能被覆盖，会话历史散落在不同目录里，时间一长你自己都记不清哪个配置对应哪个工具。更麻烦的是，当你想要远程访问的时候，两套工具各自的开销叠加起来，端口、进程、日志管理会变得非常混乱。
openrig 这类装配思路的第一个设计目标，就是用目录隔离代替环境变量隔离。具体做法是给每个工具分配独立的配置根目录，通过启动脚本在运行时注入对应的环境变量，而不是把变量写死在 shell 的 profile 里。这样做的好处是切换成本极低，你不需要 source 不同的配置文件，只需要调用不同的启动入口。
2.2 为什么是 Node.js 作为底座
热搜里 Node.js 的出现频率极高，这不是偶然。Claude Code 和 Codex CLI 本质上都是 Node.js 生态里的命令行工具，它们的安装、更新、依赖管理都依赖 npm 或类似的包管理器。所以 Node.js 的版本管理就成了整个机架的地基。
我强烈建议不要用系统自带的 Node.js。Ubuntu 上 apt 装的 Node 版本往往偏旧，Windows 上官网下载的安装包虽然省事，但一旦你要同时维护多个项目、多个 Node 版本，就会非常痛苦。我自己的做法是用版本管理器来管 Node，这样你可以随时在 18 LTS、20 LTS、22 LTS 之间切换，而不会影响系统其他部分。
这里有个细节值得展开：热搜里有一条 “error installing 24.21.0: node.js v24.21.0 is not yet released or is not available”，这其实是典型的版本号写错导致的。Node.js 的主版本号目前稳定在 20、22 这个区间，24 这种号段要么是未来的预览版，要么就是笔误。遇到这种报错，第一反应应该是去 Node.js 官网确认当前 LTS 版本号，而不是反复重试。我一般会锁定一个 LTS 大版本，比如 20.x，然后在这个大版本内跟进小版本更新，这样最稳。
2.3 tmux 在机架里的角色
tmux 这个词出现在热搜里，说明很多人已经意识到一个问题：终端 AI 助手的会话是“有状态”的。你开了一个 Claude Code 会话，正在让它重构一个模块，这时候如果你关掉终端或者网络断了，会话就没了。tmux 解决的正是这个问题——它让会话脱离终端窗口独立存在。
在 openrig 的装配思路里，tmux 扮演的是“会话容器”的角色。你可以把每个 AI 助手跑在独立的 tmux window 或 pane 里，这样即使你断开 SSH，会话依然在后台运行，下次连上来 attach 回去就行。更进一步，你可以用 tmux 的命名会话功能，给每个项目、每个工具分配固定的会话名，形成一套可预测的会话管理规范。
我自己的习惯是：一个项目一个 tmux session，session 名字就是项目名；session 里面按工具分 window，比如 window 0 是 Claude Code，window 1 是 Codex，window 2 是普通 shell 用来跑测试。这样我任何时候tmux attach -t 项目名就能回到完整的工作现场，非常省心。
2.4 方案选型的取舍：为什么不直接用 Docker
有人可能会问，既然要隔离，为什么不干脆每个工具一个 Docker 容器？我的实测结论是：对于终端 AI 助手这类需要频繁读写项目文件、需要访问本地模型服务、需要和宿主机终端深度交互的场景，Docker 的隔离反而会带来额外的摩擦。文件挂载、网络回环、GPU 透传（如果你跑本地模型）每一项都是成本。
openrig 的思路更轻——它不追求强隔离，而是追求“有序共存”。用目录隔离配置，用 tmux 隔离会话，用启动脚本隔离环境变量，三层轻量隔离叠加起来，已经能解决 95% 的冲突问题，而且几乎没有性能损耗和额外的运维负担。这是一个典型的“够用就好”的工程取舍。
3. 环境准备：Node.js、包管理器与基础工具链
3.1 Node.js 版本选择与安装方式对比
先把地基打牢。Node.js 的安装方式主要有三种：官网安装包、系统包管理器、版本管理器。我整理了一个对比表，你可以根据自己的场景选。
| 安装方式 | 适合场景 | 优点 | 缺点 |
|---|---|---|---|
| 官网安装包 | Windows 桌面、单版本需求 | 图形化、一步到位 | 多版本切换困难 |
| 系统包管理器 | Linux 服务器、快速尝鲜 | 命令简单 | 版本偏旧、权限问题多 |
| 版本管理器 | 多项目、多版本、长期使用 | 切换灵活、隔离干净 | 初次配置稍复杂 |
我个人的推荐是：只要你不是纯粹的一次性尝鲜，都用版本管理器。Linux 和 macOS 上可以用 nvm 或 fnm，Windows 上可以用 nvm-windows。安装完之后，锁定一个 LTS 版本，比如：
# 以 fnm 为例，安装并锁定 Node 20 LTS fnm install 20 fnm use 20 fnm default 20 node -v npm -v装完之后一定要验证node -v和npm -v都能正常输出。如果npm -v报错，多半是权限或者 PATH 没配好，这时候不要急着装工具，先把 Node 本身跑通。
提示：Windows 上用 nvm-windows 时，安装路径不要带空格和中文，否则后续 npm 全局包经常出玄学问题。这是我踩过好几次的坑。
3.2 全局包目录的规划
Node.js 装好之后，下一步是规划全局包的安装位置。默认情况下，npm 全局包会装到用户目录下的一个隐藏文件夹里，这个位置本身没问题，但如果你同时用多个 Node 版本，全局包是跟着版本走的，切换版本后之前装的工具就“消失”了。
我的做法是：把 AI 助手这类工具装在固定的 Node 版本下，并且不轻易切换这个版本。具体来说，我会专门用一个 LTS 版本作为“工具版本”，所有 CLI 工具都装在这个版本下，项目开发用另一个版本。这样工具链和项目依赖互不干扰。
# 查看当前全局包安装路径 npm root -g npm bin -g # 如果想把全局包集中管理，可以设置前缀（可选） npm config set prefix ~/.npm-global # 然后把 ~/.npm-global/bin 加入 PATH设置 prefix 的好处是所有全局工具集中在一个目录，备份和迁移都很方便。坏处是你需要手动维护 PATH。如果你嫌麻烦，用默认路径也完全没问题，只要记住它在哪里就行。
3.3 tmux 的安装与基础配置
tmux 在 Linux 上一般可以直接用包管理器装，macOS 上用 Homebrew，Windows 上则建议在 WSL 里用。装完之后，我建议先做几个基础配置，这些配置会直接影响你后续用 AI 助手的体验。
# ~/.tmux.conf 基础配置示例 set -g mouse on set -g history-limit 50000 set -g base-index 1 setw -g pane-base-index 1 set -g renumber-windows onmouse on让你可以用鼠标切换 pane 和滚动，history-limit调大是因为 AI 助手输出的内容往往很长，默认的滚动缓冲很快就不够用。base-index从 1 开始是个人习惯，这样 window 编号和键盘上的数字键对应更直观。
配置改完记得tmux source-file ~/.tmux.conf或者重开 tmux 生效。我建议在正式跑 AI 助手之前，先花十分钟熟悉一下 tmux 的基本操作：新建 session、分离、attach、切 window、切 pane。这几个操作熟练了，后面会顺很多。
3.4 终端环境的基础检查
在装 AI 助手之前，还有几个基础项要确认。第一是 shell 类型，bash 和 zsh 的配置文件不一样，别改错了文件。第二是 locale 设置，如果 locale 不是 UTF-8，AI 助手输出中文或特殊符号时可能乱码。第三是终端模拟器本身，有些老终端对 ANSI 转义序列支持不好，会导致界面错乱。
# 检查 locale locale # 如果输出里没有 UTF-8，需要设置 export LANG=en_US.UTF-8 export LC_ALL=en_US.UTF-8这几项看起来琐碎，但它们是后面所有步骤的前提。我见过太多人卡在“工具装好了但界面乱码”这种问题上，最后发现是 locale 没配。花五分钟检查，省两小时排查。
4. 核心装配：Claude Code 与 Codex 的安装与隔离配置
4.1 Claude Code 的安装与首次认证
Claude Code 的安装本身不复杂，通过 npm 全局安装即可。但认证环节是第一个容易卡住的地方。热搜里有一条 “your organization has disabled claude subscription access for claude code”，这说明认证是和账号体系绑定的，如果你用的是组织账号，可能需要管理员开启相应权限。
# 安装 Claude Code npm install -g @anthropic-ai/claude-code # 验证安装 claude --version安装完成后，第一次运行claude会引导你完成认证。认证方式通常有两种：一种是浏览器授权，一种是 API key。浏览器授权适合个人使用，API key 适合自动化或服务器环境。如果你在无图形界面的服务器上，浏览器授权会给你一个链接，你在本地浏览器打开完成授权后再把 code 贴回去。
认证信息一般会存在用户目录下的配置文件夹里。这里就是隔离的第一个关键点：如果你想让 Claude Code 的配置和 Codex 完全分开，可以通过环境变量指定配置目录。具体变量名以官方文档为准，思路是让每个工具读写自己的目录，互不干扰。
注意：认证 token 是有有效期的，长期不用的机器上 token 可能过期，需要重新认证。如果你把机器当作长期运行的“机架”，建议定期检查一次认证状态。
4.2 Codex CLI 的安装与配置要点
Codex CLI 的安装同样走 npm。热搜里 “codex is ignoring 1 unrecognized configuration setting” 这个报错很典型，意思是你的配置文件里有一个它不认识的配置项。这通常是因为你参考了旧版本的配置示例，而新版本改了字段名。
# 安装 Codex CLI npm install -g @openai/codex # 验证 codex --versionCodex 的配置文件一般是 TOML 或 JSON 格式，放在用户目录下的隐藏文件夹里。我的建议是：配置文件从最小可用开始，跑通之后再逐项加。很多人一上来就复制一大段网上找的配置，结果里面有一半字段是当前版本不支持的，报错信息又不够明确，排查起来很痛苦。
# 最小配置示例（字段名以你安装的版本为准） # 先只配置最核心的模型和认证相关项如果你要接入第三方模型服务，比如本地跑的模型或者兼容接口的云端服务，配置里通常需要指定 base URL 和模型名。这一步的关键是确认接口协议是否兼容——有些服务声称兼容，但实际在流式输出或工具调用上有差异，会导致 Codex 行为异常。
4.3 用目录隔离实现两套工具共存
现在到了 openrig 装配思路的核心环节：让 Claude Code 和 Codex 在同一台机器上共存而不打架。我的做法是建立一套清晰的目录结构：
# 建议的目录结构 ~/ai-rig/ ├── claude/ │ ├── config/ # Claude Code 配置 │ └── sessions/ # 会话记录 ├── codex/ │ ├── config/ # Codex 配置 │ └── sessions/ # 会话记录 ├── scripts/ │ ├── start-claude.sh │ └── start-codex.sh └── logs/每个工具通过启动脚本注入自己的配置目录环境变量，这样它们的配置和会话数据完全隔离。启动脚本的内容大致是这样：
#!/bin/bash # start-claude.sh export CLAUDE_CONFIG_DIR="$HOME/ai-rig/claude/config" export CLAUDE_SESSION_DIR="$HOME/ai-rig/claude/sessions" cd "$1" || exit 1 exec claudeCodex 的启动脚本同理，只是换成对应的环境变量。这样你调用start-claude.sh /path/to/project和start-codex.sh /path/to/project就能在同一个项目里用两套工具，而它们的配置互不污染。
提示：环境变量的具体名称一定要以你安装的版本官方文档为准，不同版本可能有变化。我上面写的是示意，不是让你照抄。
4.4 会话保持：把工具跑在 tmux 里
配置隔离做完之后，下一步是会话隔离。我前面说过，AI 助手的会话是有状态的，直接跑在终端里，断线就没了。用 tmux 包一层，问题就解决了。
# 创建一个项目专属 session tmux new-session -s myproject -c /path/to/project # 在 session 里开第一个 window 跑 Claude Code ./scripts/start-claude.sh /path/to/project # 新建 window 跑 Codex tmux new-window -n codex -c /path/to/project ./scripts/start-codex.sh /path/to/project # 分离 # Ctrl-b d这样即使你关掉终端、断开 SSH，两个工具都还在后台跑着。下次tmux attach -t myproject就能回到现场。如果你用的是远程服务器，这个体验提升是巨大的——你可以在通勤路上用手机 SSH 连上去看一眼进度，然后继续让它跑。
我自己的习惯是给 tmux session 起有意义的名字，比如项目名加日期，避免时间一长自己都忘了哪个 session 是干嘛的。另外 tmux 的 window 名字也手动改一下，默认是运行的程序名，改成 “claude” 和 “codex” 更直观。
5. 进阶玩法：本地模型接入、远程访问与多工具协同
5.1 让 Claude Code 调用本地模型
热搜里有一条 “claude code 调用 lmstudio 的本地模型”，这说明很多人想让 Claude Code 走本地推理，而不是走云端。这个需求很合理：本地模型没有网络延迟、没有用量限制、数据不出本机。但要注意，Claude Code 本身是为特定模型服务设计的，让它走本地模型通常需要本地服务提供一个兼容接口。
LM Studio 这类工具可以在本地起一个兼容接口的服务，然后你在 Claude Code 的配置里把 base URL 指向本地地址。这里的关键是接口协议要匹配，包括请求格式、流式响应格式、工具调用格式。如果本地服务的兼容层做得不完整，你可能会遇到“能对话但工具调用失败”或者“流式输出卡住”这类问题。
# 假设本地服务跑在 1234 端口 # 在 Claude Code 配置里指定 base URL（字段名以官方文档为准） # 然后测试一个简单任务，确认工具调用是否正常我的实测经验是：本地模型在纯对话任务上表现可以，但在需要复杂工具调用、多步推理的编程任务上，和云端大模型还有差距。所以我的用法是“混合”——简单任务走本地，复杂任务走云端，通过不同的启动脚本切换配置。
5.2 Codex 接入第三方模型服务的注意事项
Codex 接入第三方服务的思路类似，也是通过配置 base URL 和模型名。热搜里 “codex 接入 deepseek” 和 “使用 cc switch 接入 deepseek v4, qwen, glm 等模型” 都指向这个场景。这里我要提醒几个容易踩的坑。
第一是模型名要写对。不同服务商的模型命名规则不一样，写错了会直接报模型不存在。第二是上下文长度限制。第三方服务的上下文窗口可能和官方不同，如果你的任务需要长上下文，要确认服务商支持。第三是计费和限流。第三方服务通常有自己的计费规则，跑长任务之前最好确认一下额度。
# Codex 配置第三方服务的示意结构 # [model_providers.xxx] # base_url = "https://your-service-endpoint" # 具体字段以官方文档为准我一般会先用一个很小的任务测试连通性，比如让它“列出当前目录的文件”，确认基本功能正常，再逐步加大任务复杂度。这样出问题的时候容易定位是配置问题还是任务本身的问题。
5.3 远程访问：把机架放在服务器上
openrig 这类装配思路最有价值的场景之一，是把整套环境放在一台长期运行的服务器上，然后从任何地方远程访问。这样你的开发环境不再绑定在某台笔记本上，换设备、多设备协同都变得很自然。
实现方式很简单：服务器上装好 Node.js、tmux、两个 AI 助手，配好隔离目录和启动脚本，然后通过 SSH 连上去操作。tmux 保证会话不丢，SSH 保证访问安全。如果你需要更友好的界面，VS Code 的远程开发功能可以直接连到服务器，在本地编辑器里操作远程终端。
# 本地 SSH 配置示例（~/.ssh/config） # Host my-rig # HostName your-server-address # User your-username # Port 22这样你只需要ssh my-rig就能连上去，然后tmux attach回到工作现场。我实测下来，这种模式在换电脑、临时用别人机器、甚至用平板加键盘的场景下都非常顺滑。
注意：远程访问一定要做好基础安全措施，比如使用密钥认证、关闭密码登录、限制访问来源。这些是通用运维常识，不是针对某个工具的。
5.4 多工具协同的工作流设计
当 Claude Code 和 Codex 都能稳定跑起来之后，你可以开始设计协同工作流了。我的常用模式是“分工”：Claude Code 负责探索性、交互性强的任务，比如理解一个陌生代码库、边聊边改；Codex 负责目标明确、可以批量执行的任务，比如按规范重构一批文件、生成测试用例。
具体操作上，我会在 tmux 里开两个 window，一个跑 Claude Code 做“侦察”，把发现的问题和思路记下来；另一个跑 Codex 做“执行”，把侦察结果转化成具体改动。两个 window 共享同一个项目目录，所以改动是实时可见的。这种“侦察加执行”的分工，比单工具从头做到尾效率高不少。
另外一个小技巧是：把常用的启动命令写成 shell 函数或者 alias，放在你的 shell 配置里。比如rig-claude和rig-codex，这样你不需要每次敲完整路径。但要注意 alias 里不要写死项目路径，用参数传入更灵活。
6. 常见问题与排查技巧实录
6.1 安装与认证类问题速查
| 现象 | 可能原因 | 排查方向 |
|---|---|---|
| npm 安装报 404 | 包名写错或源不对 | 确认包名、检查 npm registry |
| 安装报版本不存在 | 版本号笔误 | 去官网确认当前 LTS 版本 |
| 认证失败 | token 过期或权限不足 | 重新认证、检查账号权限 |
| 组织访问被禁用 | 管理员未开启 | 联系管理员或换个人账号 |
| 命令找不到 | 全局 bin 不在 PATH | 检查 npm bin -g 并加入 PATH |
这张表里的每一条我都实际遇到过。最想强调的是“命令找不到”这一条——很多人装完工具后敲命令提示 not found，第一反应是重装，其实八成是 PATH 问题。先npm bin -g看看全局 bin 目录在哪，再echo $PATH看看在不在里面，基本就能定位。
6.2 配置类问题的排查思路
配置类问题最烦人的地方是报错信息往往不明确。比如 “codex is ignoring 1 unrecognized configuration setting” 只告诉你有一个配置项不认识，但不告诉你是哪一个。我的排查方法是二分法：把配置注释掉一半，看还报不报错，逐步缩小范围。
另一个常见问题是配置文件格式错误。TOML 对缩进和引号比较敏感，JSON 对逗号和括号敏感。我建议用编辑器自带的语法检查功能，或者用命令行工具验证格式。改配置之前先备份，改完出问题能快速回滚。
# 备份配置 cp config.toml config.toml.bak # 改完测试 codex --version # 先确认基本能跑 # 再跑一个最小任务6.3 会话与 tmux 相关的坑
tmux 用久了会遇到几个典型问题。第一是 session 太多忘了哪个是哪个，解决办法是起名规范加定期清理。第二是 pane 里的程序卡死，这时候不要直接关终端，先试试Ctrl-c，不行再tmux kill-pane。第三是复制粘贴不顺手，这个需要根据你的终端和 tmux 配置调，mouse on能解决大部分问题。
还有一个坑是环境变量在 tmux 里不生效。这是因为 tmux 启动时会继承当时的环境，如果你在 tmux 外面改了环境变量，里面的 session 不会自动更新。解决办法是在启动脚本里显式设置变量，而不是依赖外部环境。这也是我前面强调用启动脚本的原因之一。
6.4 本地模型接入的典型故障
本地模型接入最常见的问题是“连不上”和“连上了但行为异常”。连不上通常是地址或端口写错，或者本地服务没启动。行为异常则复杂得多，可能是接口协议不兼容、模型能力不足、上下文超限。
我的排查顺序是：先用 curl 直接测本地服务的接口，确认服务本身正常；再在 AI 助手里跑一个最简单的对话任务，确认基本连通；最后逐步加大任务复杂度，观察在哪一步开始出问题。这个顺序能帮你快速区分是“服务问题”还是“工具配置问题”。
# 测试本地服务是否可达 curl -s http://localhost:1234/v1/models # 如果返回模型列表，说明服务正常6.5 我踩过的三个印象最深的坑
第一个坑是在 Windows 上直接用官网安装包装 Node，然后又用 nvm 装了一个，结果两个版本打架，npm 全局包路径混乱，排查了一下午才发现是双版本冲突。教训是：一台机器上只保留一种 Node 管理方式。
第二个坑是把 API key 写在了 shell 的 profile 里，后来换 key 的时候忘了改，导致工具一直用旧 key 报错。教训是：认证信息尽量放在工具自己的配置目录里，不要散落在 shell 配置中。
第三个坑是tmux session 名字用了中文，在某些终端下 attach 时显示乱码，虽然不影响功能但很影响心情。教训是：session 名、window 名尽量用英文和数字，简单可预测最重要。
这三个坑的共同点是：都不是工具本身的 bug，而是环境管理不规范导致的。这也是 openrig 这类装配思路存在的意义——它强迫你把环境管理规范化，从而避免这些本可避免的问题。
7. 关于这套机架，我个人的几点使用体会
这套装配方式我用了有一段时间了，最大的感受是“稳定感”提升明显。以前每次换机器、换项目，都要重新折腾一遍环境，现在只要把~/ai-rig目录同步过去，启动脚本一跑，基本就能恢复工作状态。配置隔离带来的好处在长期使用中会越来越明显——你不会因为某次误操作把另一个工具的配置搞坏。
另一个体会是，不要追求一步到位。我见过很多人一上来就想把本地模型、远程访问、多工具协同全部配好，结果每个环节都卡住，最后哪个都没跑通。我的建议是分阶段：先把 Node.js 和单个工具跑通，再加第二个工具，再上 tmux，最后才考虑本地模型和远程。每一步都确认稳定了再往下走，这样出问题的时候容易定位。
最后分享一个小技巧：给你的启动脚本加一个--dry-run选项，只打印将要设置的环境变量和执行的命令，不实际启动工具。这样在调试配置的时候非常有用，你能清楚看到每个变量是什么值，而不用真的把工具跑起来。这个技巧帮我省了很多次“改了配置但不知道生效没有”的困惑。
这套东西后续还能怎么扩展？我目前在做的是把启动脚本和项目配置绑定，让每个项目有自己的工具偏好——有的项目默认用 Claude Code，有的默认用 Codex，启动时自动读取项目里的配置文件。这样进一步减少了手动切换的成本。如果你也在折腾类似的东西，欢迎交流你的做法。
