1. openrig 到底想解决什么问题
第一次看到 openrig 这个名字，很多人会以为是某个硬件机架项目，或者跟摄影器材有关。但把关键词铺开看——Claude Code、Codex、Node.js、tmux——方向就很清楚了：这是一个围绕 AI 编程助手做运行环境编排的工具。rig 在英文里有“装配、搭台子”的意思，open 则点明了它的开放属性。合起来，它要做的事情就是：把散落在各处的 AI 编码工具，装进一个统一、可复用、可切换的台子里。
为什么这件事值得单独做一个工具？因为现在用 AI 写代码的人，几乎都遇到过同一类麻烦。你在终端里装了 Claude Code，用着挺顺；过两天想试试 Codex 的命令行版本，发现两者的配置目录、环境变量、会话状态互相打架。再往后，你想让某个工具走本地模型，另一个走云端接口，切换一次要改一堆文件，改完还记不住上次改了什么。更别提 tmux 会话里跑着的长任务，一关终端就断了，第二天回来还得重新描述上下文。
openrig 的价值就在这个缝隙里。它不生产模型，也不替代任何一个 CLI 工具，它做的是把工具的运行环境标准化。你可以把它理解成一个“工位管理器”：每个 AI 助手有自己的抽屉（配置）、自己的电源（Node.js 运行时）、自己的工作台（tmux 会话），互不干扰，随时切换。对于同时用两三个 AI 编码工具、又不想每次重装重配的人来说，这个东西省下的是实打实的时间。
这篇文章适合三类人看。第一类是完全没接触过 Claude Code 或 Codex，想先搞清楚这套东西怎么搭起来的新手；第二类是用过但被环境问题折腾过，想找一套稳定方案的老手；第三类是对 Node.js、tmux 这些底层依赖不熟，每次装完就忘、忘了又搜的“半路出家”开发者。我会从环境准备一路讲到多工具协同，把每一步为什么这么做都说明白。
2. 环境底座：Node.js 与 tmux 的安装逻辑
2.1 为什么这两个依赖绕不开
Claude Code 和 Codex 的 CLI 版本，绝大多数都是基于 Node.js 生态分发的。你执行的那条安装命令，背后拉下来的是一个 npm 包，运行时依赖 Node 的解释器。所以 Node.js 不是可选项，是地基。而 tmux 的角色不太一样——它管的是“会话持久化”。AI 编码任务经常是长跑，一次重构可能跑十几分钟，中间还要来回确认。如果没有 tmux，终端一断，进程就没了，上下文也丢了。tmux 让这些任务跑在一个独立于你当前窗口的会话里，你随时可以 detach 走人，回来再 attach。
这里有个常见的认知偏差：很多人觉得 Node.js 装最新版最好。实际上 AI 编码工具的依赖链对 Node 版本相当敏感。热词里那条 “error installing 24.21.0: node.js v24.21.0 is not yet released” 就是典型症状——你照着某个教程敲了一个还不存在的版本号，npm 直接报错。正确做法是认准LTS（长期支持）版本，而不是追最新的奇数版。LTS 版本的依赖兼容性经过更充分的验证，出问题的概率低得多。
2.2 各平台的安装路径差异
不同系统装 Node.js 的方式差别不小，选错了后面会一直别扭。
Windows 用户最省事的是去 Node.js 官网下载 LTS 的安装包，一路下一步。但要注意，安装时勾选“Add to PATH”这一步不能漏，否则命令行里敲 node -v 没反应。装完之后建议再确认一下 npm 的版本，因为 npm 是随 Node 一起装的，两者版本要匹配。
macOS 用户如果已经装了 Homebrew，直接 brew install node@lts 这类命令最干净。但 Homebrew 装的 Node 有时候会和系统里其他方式装的版本冲突，导致 which node 指向的路径和你以为的不一样。装完务必用 which node 和 node -v 双重确认。
Ubuntu 这类 Linux 环境，我强烈建议用 NodeSource 的源来装，而不是系统自带的 apt 版本。系统自带的往往版本偏旧，跑新工具会报各种奇怪的错。NodeSource 的安装脚本会把正确的源加进去，之后 apt 装到的就是较新的 LTS。
tmux 的安装相对简单。Ubuntu 上 apt install tmux，macOS 上 brew install tmux，Windows 用户稍微麻烦一点，原生环境没有 tmux，通常的做法是在 WSL 里跑，或者用 Git Bash 配合其他方案。如果你主要在 Windows 上用 AI 编码工具，WSL 几乎是绕不开的一层，后面配置 Claude Code 时也会更顺。
2.3 验证环境是否真的就绪
装完不等于能用。我见过太多人装完 Node 就直接去装 Claude Code，结果卡在权限或者路径问题上。建议按这个顺序验证：
node -v npm -v tmux -V三条命令都要有正常输出。如果 node -v 报“command not found”，说明 PATH 没配好；如果 npm -v 报错但 node -v 正常，说明 npm 安装不完整，需要重装。tmux -V 输出的是版本号，能出来就说明可用。
还有一个容易被忽略的点：全局安装权限。npm 装全局包时，如果没配好目录权限，会报 EACCES 错误。Linux 和 macOS 上不要用 sudo 硬装，那样会把包的所有权搞乱。正确做法是配置一个用户级的全局目录，或者用 nvm 这类版本管理器来隔离环境。nvm 的好处是每个 Node 版本独立，切换方便，出问题直接换版本，不会污染系统。
3. Claude Code 的落地配置与常见卡点
3.1 安装之后先别急着用
Claude Code 装完之后，第一件事不是马上敲代码，而是确认它到底认不认你的环境。热词里有一条 “your organization has disabled claude subscription access for claude code”，这说明账号层面的权限问题会直接拦住你。如果你用的是组织账号，得先确认管理员有没有开放对应的访问权限。个人账号一般不会有这个问题，但登录环节仍然可能出岔子。
安装命令本身不复杂，npm 全局装即可。装完执行 claude 命令，它会引导你走一遍登录流程。这里的关键是登录方式的选择。有的环境走浏览器回调，有的环境需要手动粘贴 token。如果你在远程服务器或者 WSL 里操作，浏览器回调可能打不开，这时候要留意终端里给出的替代方案，通常是一个链接加一段验证码。
3.2 配置文件的位置与作用
Claude Code 的配置不是集中在一个文件里，而是分散在几个位置。用户级的配置通常在 home 目录下的隐藏文件夹里，项目级的配置则跟着项目走。理解这个分层很重要：用户级配置管的是“我是谁、我用哪个模型、我的默认行为是什么”，项目级配置管的是“这个项目有什么特殊规则”。
我建议的做法是：用户级配置只放最通用的设置，比如默认模型和认证信息；项目级配置放跟这个项目强相关的东西，比如忽略哪些文件、用哪个本地模型。这样换项目的时候不会互相干扰。很多人把所有配置都堆在用户级，结果 A 项目要用的设置污染了 B 项目，排查起来非常痛苦。
3.3 接入本地模型的坑
热词里 “claude code 调用 lmstudio 的本地模型” 是一个高频需求。想让 Claude Code 走本地模型，核心是改接口地址。Claude Code 默认连的是官方端点，你要把它指向本地跑的推理服务。LM Studio 这类工具会在本地起一个兼容接口的服务，你只需要把配置里的 base URL 改成类似 http://localhost:端口 的形式。
但这里有几个坑。第一，本地模型的上下文长度往往比云端小，Claude Code 默认的上下文预算可能超了，导致请求被截断或者报错。第二，本地模型的工具调用能力参差不齐，Claude Code 依赖模型能正确返回结构化的工具调用指令，如果本地模型这块支持不好，会出现“模型在胡说但工具没执行”的情况。第三，端口冲突。本地推理服务和你其他开发服务抢端口是常事，改配置前先用命令确认端口没被占用。
实测下来，本地模型适合做轻量级的代码补全和解释，复杂的多步重构还是云端模型更稳。把两者结合用，日常小任务走本地省额度，大任务走云端保质量，是比较务实的策略。
3.4 VS Code 里的集成方式
“vscode 配置 claude code” 也是热词常客。在 VS Code 里用 Claude Code，本质上是让编辑器调用你已经装好的 CLI，而不是重新装一个插件版。所以前提是你的终端里 claude 命令已经能正常工作。集成之后的好处是，你可以在编辑器里直接选中代码片段发给它，不用来回切窗口。
配置的时候注意工作目录。VS Code 打开的项目路径，要和 Claude Code 识别到的项目根目录一致，否则它读不到你的项目级配置。如果发现它总是用默认配置，先检查是不是工作目录没对上。另外，VS Code 的集成终端有时候环境变量和系统终端不一致，导致 claude 命令找不到。遇到这种情况，重启 VS Code 或者手动在集成终端里 source 一下配置文件通常能解决。
4. Codex 的安装与多工具共存策略
4.1 Codex 的安装路径与版本选择
Codex 的安装同样走 npm 全局包的路子，但它对 Node 版本的要求可能和 Claude Code 不完全一致。这就是多工具共存的第一道坎：两个工具依赖的 Node 版本如果有冲突，装在一起就会有一个跑不起来。热词里 “codex is ignoring 1 unrecognized configuration setting” 这类警告，很多时候就是配置格式对不上导致的，不一定是致命错误，但看着闹心。
我的建议是用 nvm 给不同工具分配不同的 Node 版本。nvm 可以让你在同一个系统里装多个 Node 版本，切换的时候只影响当前 shell 会话。你可以在一个终端窗口里切到 Node 18 跑 Claude Code，在另一个窗口切到 Node 20 跑 Codex，互不干扰。这比强行统一版本要灵活得多，尤其是当某个工具还没适配最新 Node 的时候。
4.2 配置隔离：别让两个工具读同一份配置
Claude Code 和 Codex 如果都用默认的配置路径，很容易出现互相覆盖的情况。解决办法是显式指定配置目录。大多数 CLI 工具都支持通过环境变量或者启动参数来指定配置位置。你可以在启动脚本里给每个工具设一个独立的环境变量，指向各自的配置文件夹。
这样做的好处不只是避免冲突，还方便备份和迁移。你的配置全在几个明确的目录里，换机器的时候直接拷过去就行，不用去猜哪个隐藏文件是干嘛的。我自己的习惯是给每个工具建一个以工具名命名的配置目录，里面再分用户级和项目级，结构清晰，出问题一眼能看出是哪层的事。
4.3 用 tmux 管理长任务会话
tmux 在这里不是可选项，是提效的关键。设想一个场景：你让 Codex 跑一个批量重构，预计要二十分钟。如果没有 tmux，你得守着终端，中途不敢关窗口。有了 tmux，你开一个命名会话，把任务丢进去，然后 detach，该干嘛干嘛。回来 attach 上去，任务跑完了，输出还在。
tmux 的基本操作不复杂，但有几个习惯值得养成。第一，给会话起有意义的名字，比如 codex-refactor 而不是默认的 0、1、2，这样你一眼知道哪个会话在干嘛。第二，在会话里先激活正确的 Node 版本再启动工具，因为 tmux 新开的会话可能不继承你当前 shell 的环境变量。第三，定期清理死会话，不然攒一堆没用的会话，找起来反而费劲。
tmux new -s codex-task # 在会话里切换 Node 版本并启动任务 nvm use 20 codex run ... # 按 Ctrl+b 然后 d 脱离会话 # 回来时 tmux attach -t codex-task这套流程跑顺之后，你可以同时开好几个会话，一个跑 Claude Code 的代码审查，一个跑 Codex 的批量修改，互不阻塞。这是单终端操作完全做不到的。
4.4 多工具切换的实际工作流
把 Claude Code 和 Codex 放在一起用，不是简单地“两个都装着”。它们各有擅长的场景。Claude Code 在理解项目结构、做跨文件分析上比较强，适合让它先读一遍代码库，给出修改建议。Codex 在执行明确的、范围限定的修改任务上更直接，适合拿着 Claude Code 的分析结果去落地。
我的实际工作流是这样的：先用 Claude Code 做一轮代码审查，让它指出潜在问题和改进点；然后把具体的修改任务拆成几条，丢给 Codex 在 tmux 会话里批量执行；执行完再用 Claude Code 复查一遍改动。两个工具通过共享同一个项目目录来协同，但配置和会话完全隔离。这样既发挥了各自的长处，又不会因为环境混在一起而互相干扰。
5. 那些文档里不会写的踩坑记录
5.1 安装报错的第一反应应该是看版本
热词里那条 “error installing 24.21.0: node.js v24.21.0 is not yet released” 值得单独说。这个错误的本质是：你照着某个来源敲了一个版本号，但这个版本根本不存在，或者还没正式发布。Node.js 的版本号有严格的规则，奇数版是开发版，偶数版是稳定版，LTS 又是从稳定版里挑出来的。你如果看到一个教程让你装某个具体的小版本号，先别急着敲，去官网确认这个版本是否真的存在。
更稳妥的做法是不指定具体小版本，用 LTS 这个标签让工具自己去解析当前最新的 LTS。这样既不会装到不存在的版本，也能自动跟上安全更新。只有在确实需要复现某个特定环境时，才去锁定具体版本号。
5.2 配置警告不等于配置错误
“codex is ignoring 1 unrecognized configuration setting. check for typos” 这类提示，很多人一看就慌，以为装坏了。实际上它只是说：你的配置文件里有一个字段它不认识，它选择忽略。这通常发生在你从旧版本升级上来，或者抄了一份别人新版本的配置但自己装的是旧版本。处理方式很简单：找到那个字段，确认是不是拼写问题，或者是不是当前版本不支持。如果功能正常，这个警告可以暂时不管；如果功能异常，再针对性排查。
关键是不要因为一个警告就重装整个环境。重装解决不了配置字段不匹配的问题，只会浪费 time。先定位是哪个字段，再决定是删掉它还是升级工具版本。
5.3 登录与权限问题的排查顺序
遇到登录失败或者权限被拒，排查要有顺序，不要东试一下西试一下。第一步，确认网络能正常访问认证服务；第二步，确认账号本身有没有对应的访问权限，组织账号尤其要注意管理员策略；第三步，确认本地存的认证信息有没有过期，过期的 token 会导致看似登录成功实则请求被拒；第四步，确认工具版本是不是太旧，旧版本可能用了已经废弃的认证流程。
这个顺序的逻辑是从外到内、从粗到细。先排除网络和账号这种大范围问题，再查本地凭证和版本这种细节问题。反过来查的话，你会在本地折腾半天，最后发现是账号权限没开。
5.4 本地模型接入后的性能预期管理
接入本地模型之后，很多人会失望：怎么比云端慢这么多，而且回答质量也下降了。这不是配置错了，是硬件决定的。本地推理的速度取决于你的显卡和内存，消费级硬件跑大参数模型，速度天然比云端集群慢。质量方面，本地能跑的模型参数量通常小于云端，能力有差距是正常的。
正确的预期是：本地模型用来做隐私敏感或者离线场景的任务，比如处理不能外发的代码；日常开发还是云端为主。把本地模型当成一个补充选项，而不是替代方案，心态就顺了。另外，本地模型的上下文窗口通常更小，喂给它太长的代码会截断，使用时要控制输入规模。
6. 把 openrig 的思路用起来
openrig 这个名字背后真正有价值的东西，不是某个具体命令，而是一种环境编排的思路：把每个 AI 编码工具当成一个独立的服务来管理，各有各的运行时、配置和会话，通过标准化的方式启动和切换。你哪怕不用这个工具本身，这套思路也值得借鉴。
具体落地就是三件事。第一，运行时隔离，用 nvm 这类工具让不同 Node 版本共存，别让工具之间抢版本。第二，配置隔离，每个工具一个配置目录，显式指定，不依赖默认路径。第三，会话隔离，用 tmux 给长任务开独立会话，任务和终端窗口解耦。这三件事做到位，你同时用三个 AI 编码工具也不会乱。
我在实际使用中发现，最容易出问题的往往不是工具本身，而是环境变量的继承。你在当前 shell 里配好的东西，新开的 tmux 会话、VS Code 的集成终端、后台启动的进程，都不一定继承得到。所以关键配置要么写进 shell 的启动文件，要么在每个会话里显式设置一遍。这个习惯养成之后，能省掉大量“为什么这里能用那里不能用”的困惑。
最后分享一个小技巧：给你的每个工具写一个启动脚本，脚本里把 Node 版本切换、环境变量设置、配置目录指定、tmux 会话创建这几步全包了。以后要用哪个工具，执行对应的脚本就行，不用每次手动敲一串命令。脚本本身也是文档，过几个月回来看，一眼就知道当时是怎么配的。这套东西搭起来花不了多少时间，但用起来是真的省心。
