1. 从零认识 openrig：它到底解决什么问题
第一次看到 openrig 这个名字，很多人会以为是某个硬件支架或者开源机械臂项目。实际上，在当前的开发者圈子里，openrig 更多被提及的场景，是围绕 Claude Code、Codex 这类终端 AI 编程助手做环境编排和会话管理的一套思路或工具集合。它的核心价值不在于发明新模型，而在于把散落在 Node.js、tmux、本地模型服务、第三方 API 之间的碎片化配置，整合成一条能稳定跑起来的工作流。
我最初接触这个方向，是因为同时用 Claude Code 和 Codex 两个 CLI 工具，每次切换都要重新配环境变量、重新登录、重新确认模型端点，窗口开多了 tmux 会话也乱成一团。openrig 这类方案要解决的，正是这种“工具都能装，但装完不好用”的尴尬。它适合三类人：一是刚接触终端 AI 助手、被 Node.js 版本和安装报错劝退的新手；二是需要在多个模型供应商之间来回切换的进阶用户；三是想把本地模型（比如通过 LM Studio 跑的模型）接进 CLI 工作流的折腾党。
需要先说明的是，openrig 并不是一个官方统一发布的标准产品，它更像一个社区里逐渐成型的实践范式。你在不同文章里看到的 openrig，可能指一套目录结构、一组 shell 脚本，或者一个用来管理多会话的 tmux 配置。所以这篇内容不会假装它是某个固定软件，而是把它当作“终端 AI 助手环境编排”这个真实需求来拆解，把 Claude Code、Codex、Node.js、tmux 这几个关键词串成一条能落地的链路。
2. 环境底座：Node.js 安装与版本坑的完整拆解
2.1 为什么 Node.js 是绕不开的第一关
Claude Code 和 Codex 的 CLI 版本，绝大多数都是基于 Node.js 生态分发的。你执行npm install -g装的那个命令，本质上是一个 Node 脚本。这意味着 Node.js 的版本、npm 的源、全局 bin 目录的权限，任何一个环节出问题，后面全是连锁反应。我见过太多人卡在第一步，报错信息是error installing 24.21.0: node.js v24.21.0 is not yet released or is not available，这通常不是网络问题，而是版本号写错了，或者用的镜像源还没同步这个版本。
Node.js 的版本策略是双轨制：LTS（长期支持）和 Current（最新特性）。对于 openrig 这种要长期稳定运行的环境，我的建议是无脑选 LTS。Current 版本虽然新，但很多原生模块还没跟上，装 Claude Code 时容易遇到编译失败。截至我写这篇内容时，Node.js 20.x 和 22.x 的 LTS 都是比较稳的选择，具体用哪个看你的系统包管理器支持到哪。
2.2 三大平台的安装方式与避坑点
Windows 用户最容易踩的坑是权限和路径。官网下载.msi安装包一路下一步没问题，但装完后如果npm install -g报EACCES或EPERM，说明全局目录没有写权限。解决办法不是每次都开管理员终端，而是把 npm 的全局前缀改到用户目录下：
npm config set prefix "C:\Users\你的用户名\node_global" npm config set cache "C:\Users\你的用户名\node_cache"然后把C:\Users\你的用户名\node_global加进 PATH。这样以后装任何全局 CLI 都不需要管理员权限，省心很多。
macOS 用户如果用 Homebrew，直接brew install node@22就行，但要注意 Homebrew 装的 Node 和官网 pkg 装的可能会冲突。判断方法很简单，which node看路径，/opt/homebrew/bin/node是 Homebrew 的，/usr/local/bin/node是 pkg 的。冲突时优先保留一个，把另一个从 PATH 里去掉。
Ubuntu 用户我强烈建议用 NodeSource 的源，而不是apt install nodejs。系统自带的 Node 版本往往太老，跑不动新版 CLI。命令是：
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash - sudo apt-get install -y nodejs装完node -v确认版本。如果显示的还是老版本，检查一下hash -r刷新一下 shell 的命令缓存。
2.3 版本管理器的取舍：nvm 还是 fnm
如果你需要频繁在多个 Node 版本之间切换（比如一个项目要 18，另一个要 22），装个版本管理器是值得的。nvm 是最老牌的，但它在 Windows 上支持不好，而且每次开新 shell 都要 source 一下，启动慢。fnm 是 Rust 写的，速度快，跨平台，配置也更简单。我现在的做法是：主力机用 fnm，服务器上直接用系统级 Node，因为服务器不需要频繁切版本。
提示：不管用哪种方式装 Node，装完后一定要验证三件事——
node -v能出版本、npm -v能出版本、npm config get registry指向一个可用的源。这三件事都正常，再往下走。
3. Claude Code 与 Codex 的安装配置实战
3.1 Claude Code 安装：从 npm 到首次运行
Claude Code 的安装命令本身不复杂，但“装完能不能用”取决于登录和网络环境。标准流程是：
npm install -g @anthropic-ai/claude-code claude第一次运行claude会引导你登录。这里有个常见报错：your organization has disabled claude subscription access for claude code。这不是安装问题，而是账号层面的订阅权限没开。遇到这个，先确认你的账号类型是否支持 Claude Code，个人订阅和企业订阅的权限范围不一样。
另一个高频问题是note: claude code might not be available in your country。这个提示出现时，先别急着怀疑安装，检查一下你的终端环境变量里有没有残留的代理配置，或者系统时区、语言设置是否异常。很多时候是环境变量污染导致的误判。
Windows 用户如果不想用 WSL，可以直接装桌面版，但 CLI 版本的功能更新通常更快。VS Code 用户可以在扩展市场搜 Claude Code，装完后在设置里填 API 端点。如果你要接本地模型，比如 LM Studio 跑的服务，需要把端点改成http://localhost:1234/v1这类地址，具体端口看 LM Studio 的配置。
3.2 Codex 安装：那些让人抓狂的配置报错
Codex 的安装路径和 Claude Code 类似，但它的配置校验更严格。最常见的报错是codex is ignoring 1 unrecognized configuration setting. check for typos or d。这句话的意思是配置文件里有个键名拼错了，或者用了当前版本不支持的字段。Codex 的配置文件通常是~/.codex/config.toml或类似路径，打开后逐行核对键名，特别注意大小写和下划线。
codex无法加载组织设置这个报错，多半和登录态有关。先codex logout再codex login，重新走一遍授权流程。如果还不行，检查一下是不是同时装了多个版本的 Codex，which codex看看指向哪个。
Codex 接入 DeepSeek 是很多人关心的场景。核心思路是把 Codex 的模型端点指向 DeepSeek 的兼容接口，然后在配置里填对应的 API Key。这里的关键是确认 DeepSeek 的接口是否兼容 OpenAI 的/responses格式。如果不兼容，就需要一个中间层做转换。社区里有人用 cc switch 这类工具来做模型切换，原理就是帮你改配置文件里的端点地址和模型名。
3.3 安装后的验证清单
装完两个工具后，别急着写代码，先跑一遍验证：
| 检查项 | 命令 | 预期结果 |
|---|---|---|
| Node 版本 | node -v | 显示 LTS 版本号 |
| Claude Code 版本 | claude --version | 显示版本号 |
| Codex 版本 | codex --version | 显示版本号 |
| Claude 登录态 | claude后看是否提示登录 | 已登录则直接进交互 |
| Codex 登录态 | codex后看是否提示登录 | 已登录则直接进交互 |
| 配置文件语法 | 手动检查 config.toml | 无拼写错误 |
这个清单看着简单，但能帮你把 80% 的“装完不能用”问题挡在门外。
4. tmux 在 openrig 里的角色：会话管理的正确姿势
4.1 为什么终端 AI 助手需要 tmux
Claude Code 和 Codex 都是长时间运行的交互式进程。如果你直接在普通终端里跑，一旦网络抖动或者误触 Ctrl+C，会话就断了，之前的上下文可能丢失。tmux 的价值在于它把会话和终端窗口解耦——你可以关掉窗口，会话还在后台跑，下次tmux attach就能接回来。
在 openrig 的语境里，tmux 通常这样用：一个 window 跑 Claude Code，一个 window 跑 Codex，一个 window 跑本地模型服务，一个 window 看日志。每个 window 独立，互不干扰，切换用Ctrl+b加数字键。这种布局比开一堆终端标签页清爽得多，而且断线重连后一切照旧。
4.2 tmux 基础配置与 openrig 常用布局
默认的 tmux 配置比较简陋，建议在~/.tmux.conf里加几行：
# 把前缀键改成 Ctrl+a，更顺手 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 # 快速重载配置 bind r source-file ~/.tmux.conf \; display "Reloaded"openrig 的典型布局可以写成一个脚本，一键拉起：
#!/bin/bash tmux new-session -d -s openrig -n claude tmux send-keys -t openrig:claude 'claude' C-m tmux new-window -t openrig -n codex tmux send-keys -t openrig:codex 'codex' C-m tmux new-window -t openrig -n model tmux send-keys -t openrig:model 'echo "start your local model here"' C-m tmux new-window -t openrig -n logs tmux send-keys -t openrig:logs 'tail -f /tmp/openrig.log' C-m tmux attach -t openrig这个脚本跑完，你就有了一个四窗口的工作台。tmux attach -t openrig随时接回来，tmux kill-session -t openrig彻底关掉。
4.3 tmux 使用中的实操心得
第一个心得：不要在一个 pane 里跑两个交互式 CLI。有人为了省窗口，把 Claude Code 和 Codex 塞进同一个 pane 的上下分屏，结果输入焦点经常乱跳，回车按错地方。老老实实一个 pane 一个进程。
第二个心得：给 tmux 会话起有意义的名字。tmux new -s work比默认的数字会话好记太多。openrig 场景下，我习惯用openrig-claude、openrig-codex这种命名，一眼就知道里面跑的是什么。
第三个心得：日志要落盘。tmux 的capture-pane可以抓取当前 pane 的内容，但更稳妥的做法是让 CLI 自己输出日志到文件。Claude Code 和 Codex 一般都有 verbose 模式，开启后把输出重定向到文件，排查问题时不用靠翻屏。
5. 多模型切换与本地模型接入的实操细节
5.1 cc switch 这类工具的工作原理
cc switch 本质上是一个配置切换器。它帮你维护多套配置文件，每套对应一个模型供应商（比如 DeepSeek、Qwen、GLM），切换时把当前配置替换成目标配置。它的价值在于省去了手动改 config.toml 的麻烦，也降低了改错键名的风险。
使用这类工具时要注意：切换后最好重启一下 CLI 进程，因为很多 CLI 只在启动时读一次配置。如果你在会话中途切换，可能不生效。另外，切换前确认目标供应商的 API Key 已经填好，否则切过去也是报错。
5.2 接入 LM Studio 本地模型的完整步骤
LM Studio 可以在本地跑模型并暴露一个兼容 OpenAI 的接口。接入 Claude Code 或 Codex 的步骤大致是：
- 在 LM Studio 里加载一个模型，启动本地服务，记下端口（默认 1234）。
- 确认接口地址，通常是
http://localhost:1234/v1。 - 在 CLI 的配置里把 base URL 改成这个地址，API Key 随便填一个非空字符串（本地服务一般不校验）。
- 模型名填 LM Studio 里显示的那个名称。
- 保存配置，重启 CLI，发一条测试消息。
这里最容易出问题的是模型名不匹配。LM Studio 的模型名有时候带路径前缀，有时候只是文件名，要以它 API 返回的/v1/models列表为准。用curl http://localhost:1234/v1/models看一眼，复制准确的 id。
5.3 第三方 API 使用的注意事项
用第三方 API 时，第一要注意的是速率限制。很多第三方源有 QPS 或 TPM 限制，跑长任务时容易被限流。建议在配置里把并发调低，或者加一个重试逻辑。
第二要注意的是数据隐私。本地模型的数据不出机器，但第三方 API 的数据会经过对方服务器。如果处理的是敏感内容，优先用本地模型。
第三要注意的是接口兼容性。不是所有第三方 API 都完整实现了 OpenAI 的/responses格式。遇到cc switch local proxy failed while handling codex endpoint /responses这类报错，先确认对方的接口文档，看它支持哪些端点。不支持的话，要么换供应商，要么自己写一个转换层。
6. 常见报错速查与排查思路
6.1 安装类报错
| 报错信息 | 可能原因 | 解决方向 |
|---|---|---|
error installing 24.21.0: node.js v24.21.0 is not yet released | 版本号不存在或源未同步 | 换 LTS 版本，换官方源 |
EACCES/EPERM | 全局目录无写权限 | 改 npm prefix 到用户目录 |
command not found: claude | 全局 bin 不在 PATH | 检查 PATH，重开终端 |
npm ERR! network | 源不可达 | 换源，检查网络 |
6.2 登录与权限类报错
your organization has disabled claude subscription access这类报错，核心是账号权限。先确认账号类型，再确认订阅状态。如果是企业账号，可能需要管理员在后台开启 Claude Code 的访问权限。
codex无法加载组织设置通常是登录态过期或配置文件损坏。codex logout后删掉配置目录（先备份），再codex login重新生成。
6.3 配置类报错
codex is ignoring 1 unrecognized configuration setting是拼写问题。把 config.toml 里的键名和官方文档逐一对照，特别注意model、provider、api_key这些常用键的正确写法。
cc switch local proxy failed while handling codex endpoint /responses是端点兼容性问题。确认目标服务是否支持/responses路径，不支持就换端点或加转换层。
6.4 我的独家排查顺序
遇到问题，我一般按这个顺序排查：
- 看版本：Node、CLI、配置文件的版本是否匹配。
- 看日志：开 verbose 模式，看完整报错栈，不要只看最后一行。
- 看配置：逐行核对配置文件，特别是最近改过的地方。
- 看网络：
curl一下端点，确认服务可达。 - 看权限：文件和目录的读写权限是否正常。
这个顺序能覆盖绝大多数问题。最怕的是一上来就重装，重装完问题还在，时间全浪费了。
7. 把 openrig 用顺手的几个经验之谈
折腾这套东西大半年，我最大的体会是：稳定性比功能多更重要。一开始我追求把所有模型都接进来，配置改来改去，结果哪个都不稳。后来固定用一两个供应商，把配置写死，反而效率最高。
第二个体会是：tmux 会话要定期清理。跑了一周的会话里可能堆了几百行输出，attach 回去卡得要命。我现在的习惯是每天收工前tmux kill-session掉不用的会话，第二天重新拉。
第三个体会是：配置文件要版本管理。把~/.codex/config.toml、~/.tmux.conf这些放进一个 git 仓库，换机器时直接 clone 下来，省去重新配的麻烦。但注意 API Key 不要提交，用环境变量或者单独的 secrets 文件管理。
最后分享一个我常用的小技巧：给 Claude Code 和 Codex 各写一个 wrapper 脚本，放在~/bin下，脚本里预设好环境变量和配置路径。这样不同项目可以用不同的 wrapper，互不干扰。比如claude-work用一套配置，claude-personal用另一套，切换时只要敲不同的命令就行。这个做法比全局改配置灵活得多，也不容易搞乱。
