openrig实战：Claude Code与Codex多代理本地环境搭建指南

1. 从“openrig”说起：一个把 Claude Code 和 Codex 装进同一台机器的实战思路

第一次看到 “openrig” 这个词，我脑子里蹦出来的不是某个具体软件，而是一种“把工具架起来”的感觉——rig 在英文里本来就有“装配、搭台子”的意思，open 则暗示这套东西是开放的、可拼装的。结合最近圈子里被反复念叨的 Claude Code、Codex、Node.js、tmux 这几个词，我基本能判断出：这是一套围绕“本地 AI 编码代理运行环境”的搭建方案，目标是把命令行里的智能编码助手跑顺、跑稳，并且能在同一台机器上同时容纳多个代理工具，互不打架。

我自己从去年开始就在 Ubuntu 和 Windows 双平台上折腾这类工具，踩过的坑包括 Node.js 版本对不上、tmux 会话被误杀、代理端点返回 404、组织策略把订阅权限锁死等等。这些问题单看都是小毛病，凑在一起就足够让人一晚上搭不起来环境。所以这篇内容我不打算写成官方文档的复读机，而是按一个真实搭建者的视角，把 openrig 这套思路拆开：它要解决什么问题、核心组件怎么选、每一步为什么这么做、出错之后往哪儿查。

适合读这篇的人有三类：第一类是刚听说 Claude Code 或 Codex，想在自己电脑上跑起来但被 Node.js 和终端环境卡住的新手；第二类是已经装过但总在代理、会话、配置上翻车的进阶用户；第三类是想把多个编码代理统一管理、做本地化编排的老手。不管你属于哪一类，下面的内容都尽量给到可以直接抄的步骤和判断依据，而不是“你自己看着办”。

2. openrig 的整体设计与组件选型逻辑

2.1 为什么是 Node.js 打底，而不是别的运行时

Claude Code 和 Codex 这类命令行代理工具，绝大多数发行方式都是 npm 包。npm 是 Node.js 生态的包管理器，所以 Node.js 基本是绕不开的地基。有人会问，能不能用 Bun 或者 Deno 替代？实测下来，部分工具确实能在 Bun 上跑，但官方文档和社区排错案例几乎都围绕 Node.js 展开，一旦出问题，你很难找到对应 Bun 的解决方案。搭建环境的第一原则是“减少变量”，所以 openrig 选择 Node.js 作为统一运行时，是性价比最高的决定。

版本选择上有个很现实的坑。热搜里出现过 “error installing 24.21.0: node.js v24.21.0 is not yet released” 这种报错，本质是版本号写错了或者源里还没有这个版本。我的建议是直接用 LTS 版本，也就是长期支持版。LTS 的稳定性经过大规模验证，npm 包兼容性最好。截至我写这篇内容时，Node.js 20.x 和 22.x 的 LTS 都是安全选择。不要盲目追最新的大版本，新版本刚发布时，很多原生模块还没编译好对应的二进制包，装到一半报错是常事。

安装方式上，Windows 用户直接去 Node.js 官网下载 LTS 的 msi 安装包最省心，安装时记得勾选“自动安装必要工具”那一项，它会帮你把编译原生模块需要的构建工具一起装上。Ubuntu 用户我更推荐用 NodeSource 的源或者 nvm 来装，nvm 的好处是可以在多个 Node 版本之间切换，万一某个工具只兼容旧版本，你随时能切回去，不用卸载重装。

提示：装完 Node.js 后，终端里执行node -v和npm -v各确认一次。两个命令都能输出版本号，才算真正装好。只装 Node 没装 npm 的情况虽然少见，但确实遇到过。

2.2 tmux 在 openrig 里扮演什么角色

很多人第一次接触 tmux 会疑惑：我开个终端不就能跑命令了吗，为什么还要多一层？答案在于“会话保持”和“多路复用”。Claude Code 和 Codex 这类代理工具，运行过程中可能需要长时间等待模型响应，如果你用 SSH 连到远程机器，网络一抖，终端断开，正在跑的会话就没了。tmux 的作用是把会话和终端窗口解耦：窗口断了，会话还在后台跑，你重新连上去 attach 回来，一切照旧。

另一个作用是分屏管理。openrig 的思路是同时容纳多个代理，比如左边一个 Claude Code 会话，右边一个 Codex 会话，下面再开一个窗口看日志。用 tmux 的 pane 和 window，一台终端就能管好几个任务，不用开一堆标签页来回切。这在调试代理端点、对比两个工具输出的时候特别有用。

tmux 的安装很简单，Ubuntu 上sudo apt install tmux，macOS 上brew install tmux。Windows 原生没有 tmux，但如果你用 WSL2，那里面就是完整的 Linux 环境，tmux 照装不误。我个人的习惯是给每个代理工具建一个命名会话，比如tmux new -s claude和tmux new -s codex，这样tmux ls一眼就能看清哪个会话在跑什么。

2.3 多代理共存的目录与配置隔离思路

openrig 这个名字里的“open”还有一层含义：不把鸡蛋放在一个篮子里。Claude Code 和 Codex 各有各的配置文件、缓存目录、认证信息。如果全塞在一个目录里，轻则配置互相覆盖，重则认证串号。我的做法是按工具分目录，每个工具一个独立的工作区。

具体来说，在用户主目录下建一个rig文件夹，里面再分claude、codex、shared三个子目录。claude和codex各自放对应工具的配置和项目文件，shared放两个工具都可能用到的公共资源，比如本地模型的服务地址、通用的提示词模板。这样即使某个工具的配置写坏了，也不会波及另一个。

配置隔离还有一个好处是排查问题方便。当 Codex 报 “ignoring 1 unrecognized configuration setting” 这类警告时，你能立刻定位到是哪个配置文件里的哪个键写错了，而不是在一堆混杂的配置里大海捞针。

3. 核心细节解析与实操要点

3.1 Claude Code 的安装与首次配置

Claude Code 的安装入口是 npm。在终端里执行npm install -g @anthropic-ai/claude-code，全局安装。这里有个细节：如果你在 Ubuntu 上遇到权限报错，不要直接加sudo了事，那样装出来的包归属 root，后续升级和调用都可能出权限问题。正确做法是配置 npm 的全局目录到用户目录下，或者用 nvm 管理 Node，nvm 装出来的全局包天然就在用户空间里，不会有权限烦恼。

装完之后，第一次运行claude命令，它会引导你做认证。认证方式通常有两种：一种是走官方账号的订阅授权，另一种是配置 API 密钥。热搜里出现过 “your organization has disabled claude subscription access for claude code” 这种提示，意思是你的组织策略把订阅访问关掉了。遇到这种情况，要么找管理员开通，要么改用 API 密钥的方式接入。API 密钥方式更灵活，也方便后面接入第三方模型。

配置 API 密钥时，环境变量是最稳妥的方式。在~/.bashrc或~/.zshrc里加一行export ANTHROPIC_API_KEY="你的密钥"，然后source一下让配置生效。不要把密钥硬编码在项目文件里，那样一旦项目被分享出去，密钥就泄露了。

3.2 Codex 的安装与配置要点

Codex 的安装同样走 npm，命令是npm install -g @openai/codex或者对应的包名，具体以官方发布为准。安装过程本身不复杂，复杂的是配置。Codex 对配置文件的格式比较敏感，热搜里那条 “codex is ignoring 1 unrecognized configuration setting. check for typos or d” 就是典型的配置键名拼写错误导致的警告。它不会直接报错退出，而是忽略那个设置继续跑，结果就是你以为某个功能开了，其实没开。

我的经验是，Codex 的配置文件改完之后，一定要用工具自带的校验命令过一遍，或者至少启动时仔细看输出里的警告。警告里提到的行号和键名，逐个核对。常见的拼写错误包括把model写成modle、把provider写成providor，这类错误肉眼扫一遍很难发现，但工具会明确告诉你。

Codex 接入第三方模型是很多人关心的点。热搜里 “codex接入deepseek” 说明大家有把 Codex 接到国产模型上的需求。思路是配置一个兼容 OpenAI 接口格式的端点，把 base URL 指向第三方服务，模型名填对应的名称。这里的关键是端点必须兼容/responses这个路径，热搜里 “cc switch local proxy failed while handling codex endpoint /responses” 就是端点不兼容导致的代理失败。配置之前先确认第三方服务的接口文档，看它是否支持 Codex 需要的请求格式。

3.3 代理与端点配置的常见陷阱

“cc switch local proxy failed” 这个报错值得单独拿出来说。它的字面意思是本地代理在处理 Codex 的/responses端点时失败了。这类问题通常有三个原因：一是代理服务本身没启动或者端口不对；二是代理转发的目标地址写错了；三是请求格式在转发过程中被改坏了。

排查顺序应该是从下往上：先确认代理进程在跑，用curl直接打代理的本地端口，看有没有响应；再确认代理配置里的目标地址和密钥正确；最后抓包或者看代理日志，确认转发出去的请求体格式和目标服务期望的一致。很多人一上来就怀疑模型服务有问题，其实问题往往出在本地代理这一层。

还有一个容易被忽略的点是端口冲突。本地代理默认用的端口如果被别的程序占了，代理启动时会报错或者静默失败。用lsof -i :端口号或者netstat查一下端口占用情况，换个空闲端口就能解决。

3.4 本地模型接入的配置方法

热搜里 “claude code 调用 lmstudio 的本地模型” 代表了一类很实际的需求：不想走云端，想在本地跑模型。LM Studio 这类工具可以在本地起一个兼容 OpenAI 接口的服务，然后 Claude Code 或 Codex 通过配置 base URL 指向本地端口来调用。

配置的关键是 base URL 要写全，包括协议、主机、端口和路径前缀。比如http://localhost:1234/v1这种格式。模型名称要填 LM Studio 里实际加载的模型标识，不能随便写。另外本地模型的上下文长度和响应速度跟云端差距明显，提示词要写得更精简，否则等半天出不来结果。

本地接入还有个坑是跨域和网络隔离。如果代理工具跑在 WSL 里，而 LM Studio 跑在 Windows 宿主机上，localhost 是不通的，得用宿主机的局域网 IP。这个细节不搞清楚，会一直以为是配置写错了。

4. 实操过程与核心环节实现

4.1 从零搭建 openrig 的完整步骤

我把整个搭建过程拆成可复现的步骤，按顺序执行基本不会出大问题。

第一步，装 Node.js。Windows 去官网下 LTS 的 msi，一路下一步，勾选自动安装工具。Ubuntu 用 nvm 装，命令是curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash，然后nvm install --lts。装完验证node -v和npm -v。

第二步，装 tmux。Ubuntu 上sudo apt update && sudo apt install tmux。装完tmux -V确认版本。

第三步，建工作目录。mkdir -p ~/rig/{claude,codex,shared}，把三个目录建好。

第四步，装 Claude Code。npm install -g @anthropic-ai/claude-code，然后配置 API 密钥到环境变量。

第五步，装 Codex。npm install -g @openai/codex，然后按官方文档写配置文件，注意键名拼写。

第六步，起 tmux 会话。tmux new -s claude起一个，在里面跑 Claude Code；Ctrl+b d脱离，再tmux new -s codex起另一个跑 Codex。

第七步，验证。在两个会话里分别发一条简单指令，看能否正常返回。如果某个工具报端点错误，回到代理配置那一步排查。

4.2 参数计算与选择依据

Node.js 版本的选择不是拍脑袋。假设你用的某个 npm 包依赖了原生模块，原生模块在安装时会根据当前 Node 的 ABI 版本编译。Node 的大版本之间 ABI 不兼容，所以如果你从 Node 18 升到 Node 20，之前编译好的原生模块可能就用不了了，需要重新编译。这就是为什么我强调用 LTS 并且不要频繁换大版本。

tmux 的会话数量也有讲究。每个会话会占用一定的内存，虽然不多，但如果你同时开十几个会话跑重负载任务，内存和 CPU 都会吃紧。我的经验是一台普通开发机上同时跑两到三个代理会话比较合适，再多就要考虑机器配置了。

代理端点的超时时间需要根据模型响应速度调整。云端模型通常几秒到几十秒返回，本地模型可能几十秒到几分钟。超时设太短，请求还没返回就被掐断；设太长，出问题时你要等很久才知道失败。我的做法是先设一个中间值，比如 120 秒，然后根据实际响应时间微调。

4.3 实操现场记录与关键命令

下面是我在 Ubuntu 上搭建时实际敲过的命令序列，供参考。

# 安装 nvm curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash source ~/.bashrc # 安装 Node LTS nvm install --lts nvm use --lts node -v npm -v # 安装 tmux sudo apt update sudo apt install -y tmux # 建工作目录 mkdir -p ~/rig/claude ~/rig/codex ~/rig/shared # 安装 Claude Code npm install -g @anthropic-ai/claude-code # 配置密钥 echo 'export ANTHROPIC_API_KEY="你的密钥"' >> ~/.bashrc source ~/.bashrc # 起 tmux 会话 tmux new -s claude # 在会话里运行 claude

Codex 的安装类似，把包名换成对应的即可。配置文件我放在~/rig/codex/config下，改完用codex --check-config之类的校验命令过一遍（具体命令以官方为准）。

4.4 多会话协同的操作技巧

tmux 的快捷键值得花十分钟记一下。Ctrl+b c新建窗口，Ctrl+b n切下一个窗口，Ctrl+b p切上一个，Ctrl+b %垂直分屏，Ctrl+b "水平分屏，Ctrl+b 方向键在分屏间移动。这些组合用熟了，管理多个代理会话会非常顺手。

我常用的布局是一个窗口里左右分屏，左边跑 Claude Code，右边跑 Codex，下面再开一个小 pane 用tail -f看日志。这样三个区域各司其职，一眼就能看到全局。如果某个代理卡住了，直接在那个 pane 里Ctrl+c中断，不影响另一个。

还有一个技巧是给 tmux 会话设自动保存。tmux 本身不保存会话状态，机器重启后会话就没了。可以用 tmux-resurrect 这类插件，定期把会话布局和运行状态存下来，重启后一键恢复。对于需要长期跑的任务，这个插件能省不少事。

5. 常见问题与排查技巧实录

5.1 安装阶段的典型报错与解决

安装阶段最常见的就是 Node.js 版本相关的报错。除了前面提到的版本号不存在，还有一种情况是 npm 源的问题。国内网络环境下，npm 默认源可能很慢甚至超时。解决办法是换成国内镜像源，npm config set registry https://registry.npmmirror.com，换完之后再装包会快很多。

另一个高频问题是权限。Ubuntu 上不加 sudo 装全局包报 EACCES，加了 sudo 又可能留下权限隐患。根治办法是用 nvm，或者手动把 npm 的全局目录改到用户目录下：npm config set prefix ~/.npm-global，然后把~/.npm-global/bin加到 PATH 里。

Windows 上偶尔会遇到安装脚本被安全策略拦截的情况。这时候需要以管理员身份运行终端，或者临时调整执行策略。具体命令是Set-ExecutionPolicy -Scope CurrentUser RemoteSigned，改完再装。

5.2 运行阶段的端点与认证问题

运行阶段最让人头疼的是端点问题。Codex 报/responses端点失败，Claude Code 报订阅不可用，本质上都是“请求没送到该去的地方”或者“送到了但对方不认”。排查这类问题，我习惯用一个最简请求去测端点：用curl直接打端点的健康检查路径，看返回什么。如果 curl 都不通，那问题在代理或网络层；如果 curl 通了但工具报错，那问题在工具的配置或请求格式上。

认证问题里，“组织已禁用订阅访问”这类提示属于策略层面的限制，本地怎么改都绕不过去，只能换认证方式或者找管理员。而 API 密钥无效、过期、额度用尽这类问题，换一个有效密钥就能解决。区分这两类问题的关键是看报错信息的措辞：提到 organization、policy、subscription 的，多半是策略；提到 invalid、expired、quota 的，多半是密钥本身。

5.3 配置文件的常见错误速查

这张表我建议存下来，遇到报错先对号入座，能省不少搜索时间。

5.4 独家避坑经验与操作禁忌

第一条禁忌：不要在同一个终端窗口里同时跑两个代理工具。它们的输出会混在一起，日志互相干扰，出了问题根本分不清是谁报的。用 tmux 分屏或者分会话，是基本纪律。

第二条经验：配置文件改之前先备份。cp config config.bak，改坏了随时能回滚。我见过太多人改配置改到一半忘了原始值，最后只能重装。

第三条经验：环境变量和配置文件不要同时设同一个参数。比如密钥既写在环境变量里又写在配置文件里，工具可能读到一个空的或者旧的，导致认证失败。选一种方式，坚持用到底。

第四条经验：本地模型接入时，先用最简单的提示词测通链路，再上复杂任务。链路没通就调复杂提示词，你分不清是链路问题还是提示词问题。

第五条经验：tmux 会话里的进程如果卡死，不要直接关终端窗口，那样会话可能变成僵尸。正确做法是 attach 进去，在对应 pane 里Ctrl+c，或者tmux kill-session -t 会话名干净地结束。

6. 关于 openrig 这套思路的延伸想法

openrig 这套东西搭起来之后，我发现它的价值不只是“能跑起来”，而是给了你一个可扩展的框架。今天你接的是 Claude Code 和 Codex，明天想加一个新的代理工具，只要它走 npm 安装、走命令行交互，就能塞进这个框架里。tmux 负责会话管理，Node.js 负责运行时，目录隔离负责配置不打架，这套组合的通用性很强。

我后来还在这个基础上加了一些自己的小工具，比如一个脚本用来自动检查各个代理的端点健康状态，发现不通就发通知；还有一个脚本用来在多个模型之间快速切换，改一下环境变量就换一个后端。这些都是在 openrig 的基本盘上长出来的，说明这套结构留足了扩展空间。

如果你也在搭类似的环境，我的建议是先把最小可用版本跑通，别一上来就追求完美配置。跑通之后再逐步加东西，每加一样就验证一样，这样出问题的时候你知道是刚加的那部分引起的。搭环境这件事，稳比快重要。