1. 从“openrig”说起：一个把 Claude Code 和 Codex 装进同一台机器的实战思路
第一次看到openrig这个词，我脑子里蹦出来的不是某个具体软件，而是一种“把工具架起来”的直觉——rig 在英文里本来就有“装配、搭台子”的意思，open 则暗示了开放、可组合。把这两个词放在一起，再结合Claude Code、Codex、Node.js、tmux这几个热搜词，基本能还原出它想解决的问题：在一台开发机上，把多个 AI 编程助手（Claude Code、Codex CLI 等）统一装好、配好、跑起来，并且让它们能长期稳定地在终端里待命。
这件事听起来简单，实际踩过的人都知道有多碎。Node.js 版本不对、npm 全局路径混乱、Claude Code 提示地区不可用、Codex 登录卡住、组织设置被禁用、tmux 会话里环境变量丢失、本地模型接不进来……每一个都能单独写一篇排错记录。openrig的价值就在于把这些零散环节收拢成一套可复现的装配流程，而不是每次换机器都从头翻教程。
这篇文章适合三类人看：第一类是刚接触 AI 编程助手、想在自己电脑或服务器上跑通 Claude Code 和 Codex 的开发者；第二类是已经在用但被环境问题反复折磨、想找一套稳定装配方案的人；第三类是想把本地模型（比如通过 LM Studio 暴露的接口）接进这些 CLI 工具、做私有化调用的人。我会按“整体设计思路 → 核心细节 → 实操流程 → 问题排查”的顺序展开，中间穿插我自己踩过的坑和实测有效的参数。
需要先说明一点：openrig本身并不是一个官方大厂产品，更像是一个社区里逐渐成型的“装配约定”。所以下面讲到的目录结构、脚本写法、参数选择，都是基于常见实践和我个人经验的合理补全，你可以直接抄，也可以按自己习惯改。核心目标只有一个——让 Claude Code 和 Codex 在同一台机器上和平共处，随时能调起来干活。
2. 整体设计与思路拆解：为什么这样装配更省心
2.1 把 Node.js 作为地基，而不是随便装一个版本
Claude Code 和 Codex CLI 本质上都是 Node.js 生态里的命令行工具，通过 npm 全局安装。很多人第一步就翻车，是因为系统自带的 Node.js 太老，或者用包管理器装了一个非 LTS 版本。热搜里那条error installing 24.21.0: node.js v24.21.0 is not yet released or is not available就是典型症状——你指定的版本号根本不存在，或者镜像源里还没同步。
我的建议很明确：用 Node.js LTS 版本，并且用版本管理器来管，而不是直接往系统里怼。原因有三个。第一，LTS 经过长时间验证，npm 生态兼容性最好，Claude Code 和 Codex 这类工具对 Node 版本敏感，非 LTS 容易遇到原生模块编译失败。第二，版本管理器（比如 nvm 或 fnm）让你可以在不同项目间切换 Node 版本，不会因为一个工具把全局环境搞脏。第三，卸载和重装成本极低，出问题直接换版本，不用动系统目录。
具体选哪个 LTS？截至我写这篇内容时，Node.js 20.x 和 22.x 都是稳妥选择。如果你追求新特性，22.x 更合适；如果追求最大兼容性，20.x 更保守。安装完之后用node -v和npm -v各确认一次，别嫌麻烦，这一步能省掉后面一半的怪问题。
2.2 全局安装目录要独立，别和系统包混在一起
npm 默认的全局安装路径在有些系统上需要 sudo 权限，这会导致两个后果：一是安装时频繁输密码，二是权限混乱后出现EACCES错误。更隐蔽的问题是，当你用不同 Node 版本时，全局包可能装到了旧版本的目录里，新版本里根本找不到命令。
我的做法是给 npm 配一个独立的全局目录，并且把它加进 PATH。这样无论怎么切换 Node 版本，全局命令的位置都是可控的。具体配置在实操部分会给命令。这里先记住原则：全局工具目录独立、PATH 显式声明、不依赖系统默认。
2.3 Claude Code 和 Codex 分开装、分开配，但共享终端会话
Claude Code 和 Codex 虽然都是 AI 编程助手，但它们的配置方式、登录机制、模型接入点并不一样。Claude Code 更偏向和 Anthropic 的服务对接，Codex 则有自己的登录和组织设置体系。热搜里出现的your organization has disabled claude subscription access for claude code和codex无法加载组织设置就是两类不同的问题。
所以装配思路上，我倾向于两者独立安装、独立配置，但在终端层面用 tmux 统一管理会话。tmux 的好处是：会话可以后台常驻，断网或关掉终端窗口后任务不中断；可以开多个 pane 分别跑 Claude Code 和 Codex，互不干扰；环境变量在会话内保持一致，不会因为新开窗口丢失。对于需要长时间跑代码生成、批量重构的场景，tmux 几乎是刚需。
2.4 本地模型接入要留好“旁路”
热搜里有一条很关键：claude code 调用lmstudio的本地模型。这说明不少人不想完全依赖云端服务，而是希望把本地推理接进来。LM Studio 可以在本机暴露一个兼容接口，Claude Code 和 Codex 通过配置 base URL 就能指向它。但这里有个前提：本地模型的接口格式、鉴权方式、模型名称必须和工具预期匹配，否则会出现cc switch local proxy failed while handling codex endpoint /responses这类报错。
所以在整体设计里，我会把“云端配置”和“本地配置”做成两套可切换的方案，而不是混在一起。云端用官方登录，本地用自定义 base URL 和 API key。切换时只改环境变量或配置文件，不动安装本身。这样即使本地模型服务没起来，也不影响云端工具的使用。
3. 核心细节解析与实操要点：每个环节的坑在哪里
3.1 Node.js 安装：版本、镜像、PATH 三件事
Node.js 安装本身不复杂，但细节决定后面顺不顺。第一，下载渠道优先选官网或可信镜像，别用来路不明的安装包。第二，安装方式上，Windows 可以用官方 installer，macOS 和 Linux 更推荐版本管理器。第三，安装完成后一定要确认 PATH 里 Node 和 npm 的路径指向正确。
如果你用 nvm，安装 Node 的命令大致是nvm install 22然后nvm use 22。用 fnm 的话是fnm install 22和fnm use 22。装完后which node（Windows 用where node）应该指向版本管理器管理的目录，而不是/usr/bin/node这种系统路径。这一步确认了，后面 npm 全局安装才不会乱。
注意：有些系统上同时存在多个 Node 来源，比如系统包管理器装了一个、官网 installer 装了一个、版本管理器又装了一个。
node -v显示的版本和你以为的可能不一致。装之前先which -a node看一眼，把多余的清理掉。
3.2 npm 全局目录配置：一次配好，长期受益
配置 npm 全局目录的命令不复杂，但很多人跳过这步，后面就不断遇到权限问题。以 macOS/Linux 为例，先建目录mkdir -p ~/.npm-global，然后npm config set prefix ~/.npm-global，最后把~/.npm-global/bin加进 PATH。Windows 下类似，目录换成用户目录下的某个路径，PATH 在系统环境变量里加。
配完之后用npm config get prefix确认，再用npm install -g装一个小工具测试，看命令能不能直接调用。这个测试很重要，因为 PATH 没生效的话，你会以为安装失败，其实是找不到命令。
3.3 Claude Code 安装与配置：登录、地区、订阅三个关卡
Claude Code 的安装通常是通过 npm 全局包完成，装完后运行命令会引导登录。这里常见的三个问题：一是地区限制提示，热搜里note: claude code might not be available in your country就是这类；二是订阅访问被组织禁用，your organization has disabled claude subscription access for claude code；三是登录后 token 过期或缓存异常。
我的处理原则是：先确认账号本身的可用状态，再排查本地配置。本地配置一般放在用户目录下的隐藏文件夹里，登录信息、缓存、设置都在那。遇到登录异常，最直接的办法是清掉本地配置重新登录，而不是反复试。清之前记得备份，避免把有用的设置一起删了。
另外，VS Code 里配置 Claude Code 是另一个常见需求。热搜里vscode配置claude code、claude code for vs code、vscode接入claude code都指向这个场景。核心思路是：先在终端里把 Claude Code 跑通，再在 VS Code 的集成终端里调用同一个命令。不要指望 VS Code 插件能绕过终端配置，底层还是同一套。
3.4 Codex 安装与配置：登录、组织设置、配置项拼写
Codex 的安装同样走 npm 全局包。装完后运行会要求登录，登录方式可能是浏览器回调或设备码。热搜里codex登录、codex安装 windows桌面版、codex cli都是这个环节的搜索。登录成功后，配置一般写在用户目录的配置文件里。
Codex 有一个很容易忽略的点：配置项拼写。热搜里codex is ignoring 1 unrecognized configuration setting. check for typos or d就是配置项写错导致的。Codex 对配置键名比较严格，多一个字母、少一个下划线都可能被忽略。我的建议是：改配置前先看官方文档或--help输出，确认键名；改完后用工具自带的校验命令检查一遍，别等运行时报错才回头找。
组织设置加载失败（codex无法加载组织设置）通常和账号权限或网络请求有关。先确认账号是否属于某个组织、组织是否允许使用 Codex，再排查本地网络和代理设置。如果公司网络有拦截，可能需要换网络环境测试。
3.5 tmux 会话管理：让工具常驻，不随终端关闭而退出
tmux 的安装很简单，macOS 用 brew，Ubuntu 用 apt，Windows 可以在 WSL 里用。装完后核心操作就几个：tmux new -s work新建会话，Ctrl+b d脱离会话，tmux attach -t work重新接入，tmux ls列出会话。
我习惯给 Claude Code 和 Codex 各开一个窗口或 pane。这样一边跑代码生成，一边跑测试或日志，互不干扰。tmux 里环境变量是继承自创建会话时的 shell，所以如果你在会话创建后才改 PATH 或 API key，需要重新加载配置或新建会话。这个细节很多人踩过：明明在终端里配好了，tmux 里却找不到命令。
提示：如果你用 tmux 跑长时间任务，建议开启日志记录，方便事后回看。
tmux pipe-pane可以把 pane 输出写到文件里，排查问题时很有用。
3.6 本地模型接入：base URL、模型名、接口格式要对齐
把 LM Studio 的本地模型接进 Claude Code 或 Codex，核心是配置 base URL 和模型名称。LM Studio 默认在本机某个端口暴露兼容接口，你需要在工具配置里把 API 地址指向它，并填一个 LM Studio 里已加载的模型名。鉴权方面，本地服务通常不校验 key，但工具可能要求填一个非空值，随便填一个占位即可。
常见的报错cc switch local proxy failed while handling codex endpoint /responses通常意味着接口路径或请求格式不匹配。Codex 可能期望/responses这样的端点，而本地服务暴露的是另一套路径。解决办法是查清楚工具实际请求的路径，再在本地服务或中间层做适配。如果本地服务不支持该路径，就需要一个轻量转发层，把请求转成双方都能理解的格式。
4. 实操过程与核心环节实现：从零到跑通的完整记录
4.1 环境准备：确认系统、清理旧版本、装版本管理器
先确认系统类型和架构。macOS 用uname -m看是 Intel 还是 Apple Silicon；Linux 用uname -a；Windows 建议在 WSL2 里操作，避免路径和权限的额外麻烦。然后清理旧的 Node 安装：如果用系统包管理器装过，先卸载；如果之前用 installer 装过，删掉对应目录。
装版本管理器。macOS/Linux 下 nvm 的安装脚本可以从官方仓库获取，fnm 也可以用 brew 或 cargo 装。Windows 原生环境可以用 nvm-windows，但更推荐 WSL。装完后新开终端，确认nvm --version或fnm --version能输出。
接着装 Node LTS：nvm install 22，nvm use 22，nvm alias default 22。最后确认node -v输出 v22.x，npm -v输出对应版本。这一步做完，地基就打好了。
4.2 npm 全局目录与 PATH 配置：给出可直接复制的命令
macOS/Linux：
mkdir -p ~/.npm-global npm config set prefix ~/.npm-global echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc source ~/.bashrc npm config get prefix如果你用 zsh，把~/.bashrc换成~/.zshrc。Windows PowerShell 下，先建目录，再npm config set prefix "C:\Users\你的用户名\.npm-global"，然后在系统环境变量 Path 里加C:\Users\你的用户名\.npm-global。配完新开终端，npm config get prefix应该输出你设置的路径。
测试：npm install -g npm-check-updates，然后运行ncu --version。能输出版本号，说明全局目录和 PATH 都对了。
4.3 安装 Claude Code 并完成首次登录
全局安装命令通常是npm install -g加上包名。装完后运行对应命令，会进入登录流程。如果是浏览器回调，按提示在浏览器里完成授权；如果是设备码，复制码到指定页面确认。登录成功后，工具会在用户目录写入配置和 token。
首次登录后，建议跑一个简单任务验证，比如让它解释一段代码或生成一个小函数。如果提示地区不可用或订阅被禁用，先确认账号状态，再检查本地是否有残留的旧配置。清配置的通用做法是找到用户目录下的工具配置文件夹，重命名备份后重新登录。
VS Code 里使用的话，在集成终端里直接调用同一个命令即可。如果 VS Code 终端找不到命令，检查 VS Code 是否继承了正确的 PATH，必要时在设置里指定终端环境。
4.4 安装 Codex 并处理配置项
Codex 的安装同样是npm install -g加包名。装完运行登录命令，按提示完成。登录后检查配置文件，确认键名拼写正确。如果不确定有哪些配置项，运行--help或查看官方文档。
配置本地模型时，在配置文件里设置 base URL 和模型名。如果遇到unrecognized configuration setting，逐项核对键名，把不认识的项先注释掉，确认工具能正常启动后再逐条加回。组织设置加载失败时，先确认账号权限，再检查网络请求是否被拦截。
4.5 tmux 会话搭建：让两个工具同时待命
安装 tmux 后，新建一个会话：tmux new -s airig。在会话里开两个 pane：Ctrl+b %垂直分屏，或Ctrl+b "水平分屏。一个 pane 跑 Claude Code，一个跑 Codex。需要脱离时Ctrl+b d，回来时tmux attach -t airig。
如果希望开机自动创建会话，可以写一个简单脚本，在登录时检查会话是否存在，不存在则新建并启动工具。这样每次连上机器，工具已经在待命状态。
4.6 本地模型接入的配置示例
假设 LM Studio 在本机某端口暴露接口，模型名为local-model。在 Claude Code 或 Codex 的配置里，把 API base 指向该地址，模型名填local-model，API key 填一个占位字符串。保存后运行一个简单请求测试。
如果报错提示端点不匹配，检查工具实际请求的路径。必要时在本地服务前加一个转发层，把工具的请求路径映射到本地服务的实际路径。转发层可以用 Node.js 写一个几十行的小服务，也可以用现成的工具。关键是先把请求和响应的格式对齐，再谈稳定性。
5. 常见问题与排查技巧实录：这些坑我都踩过
5.1 安装类问题速查表
| 现象 | 可能原因 | 处理方式 |
|---|---|---|
node.js v24.21.0 is not yet released | 指定了不存在的版本号 | 改用 LTS 版本，如 20 或 22 |
EACCES权限错误 | npm 全局目录需要 sudo | 配置独立全局目录并改 PATH |
| 命令找不到 | PATH 未生效或全局目录不对 | 确认npm config get prefix和 PATH |
| 安装卡住 | 网络或镜像源问题 | 换镜像源或检查网络 |
| 原生模块编译失败 | Node 版本与模块不兼容 | 换 LTS 版本重装 |
5.2 登录与账号类问题
地区提示、订阅禁用、组织设置加载失败，这三类问题本质都不在本地工具，而在账号和服务端策略。我的排查顺序是：先确认账号能正常登录网页端，再确认账号是否有对应服务的权限，最后才查本地配置。本地配置的问题通常表现为 token 过期、缓存损坏，清掉重登即可。
注意：清配置前先备份，尤其是你手动改过的设置。有些工具的配置文件夹里同时存了登录信息和自定义配置，一刀切会丢东西。
5.3 配置项与本地模型类问题
配置项拼写错误是最冤的，因为工具往往只给一个警告，不告诉你具体哪项错了。我的做法是：改配置时一次只改一项，改完立即验证。本地模型接入时，先用 curl 直接测本地服务的接口，确认服务本身正常，再配到工具里。这样能把问题范围缩小到“工具配置”还是“本地服务”。
cc switch local proxy failed while handling codex endpoint /responses这类报错，重点看端点路径和请求体格式。用抓包或日志把工具发出的请求记录下来，和本地服务期望的格式对比，差异一目了然。
5.4 tmux 与环境变量类问题
tmux 会话里找不到命令，通常是因为会话创建时的 PATH 和当前 shell 不一致。解决办法是：改完 PATH 后重新创建会话，或者在 tmux 配置里显式加载 shell 配置。另一个常见问题是后台会话被系统清理，可以调整 tmux 的保持策略，或配合系统服务让会话常驻。
5.5 我个人的几条避坑经验
第一，所有配置改动都记下来，包括改了哪个文件、加了哪行、为什么改。出问题时这份记录比搜索引擎管用。第二，先跑通云端，再折腾本地，云端链路短，容易定位问题；本地模型涉及服务、端口、格式多层，放在后面处理。第三，不要同时改多个变量，一次只动一个，验证后再动下一个。第四，保留一个能用的最小配置，折腾新功能时复制一份出来改，别把主配置搞坏。
这套装配思路我在几台机器上重复过，从 Ubuntu 服务器到 macOS 笔记本，核心步骤一致，差异主要在安装方式和路径。把 Node.js 地基打牢、全局目录配好、两个工具分开配置、tmux 管住会话，剩下的就是按需接本地模型和调参数。真正花时间的从来不是安装本身，而是遇到报错时能不能快速定位到是哪一层的问题。把层次分清楚，排查就有方向了。
