1. 从openrig这个名字说起它到底想解决什么问题第一次看到openrig这个词我脑子里蹦出来的画面是矿场里的钻井平台——rig 在英文里本来就有钻井架、装备架的意思。放到 AI 编程工具的语境里这个命名其实挺传神它想做的就是给 Claude Code、Codex 这类命令行 AI 编程助手搭一个统一的装备架让你不用在多个工具、多个模型、多个终端会话之间来回折腾。先把结论摆在前面openrig不是一个模型也不是一个 IDE 插件它更像是一层编排与桥接层。从它关联的热词就能看出端倪——Claude Code、Codex、Node.js、tmux这四个词几乎勾勒出了它的全部技术底座。Claude Code 和 Codex 是当前最主流的两类终端 AI 编程代理agentNode.js 是它们的运行时依赖tmux 则是让这些长驻进程在后台稳定存活、随时可切换的会话管理工具。openrig要做的就是把这几样东西拧成一股绳。为什么这件事值得单独做一个项目因为实际用过 Claude Code 或 Codex 的人都知道痛点非常具体。你装完 Claude Code发现它默认走官方订阅想接本地模型比如 LM Studio 起的本地推理服务或者第三方 API就得改环境变量、改配置文件稍不留神就报cc switch local proxy failed while handling codex endpoint /responses这种让人一头雾水的错。你装完 Codex又发现它和 Claude Code 的配置格式、认证方式、模型命名规则完全不一样{detail:the gpt-5.6-sol model is not supported when using codex with a...}这类报错能让你排查半天。更别提还有codex is ignoring 1 unrecognized configuration setting这种配置写了但没生效的隐性坑。openrig的价值就在于它试图把这些碎片化的配置、认证、模型路由、会话管理统一到一个架子上。你不再需要为每个工具单独记一套配置语法也不用担心切换模型时把环境搞乱。对于同时用 Claude Code 和 Codex、又想在本地模型和云端模型之间灵活切换的开发者来说这就是刚需。这篇文章适合谁看三类人第一类是完全没接触过 Claude Code / Codex想从零搭一套能跑起来的环境的新手第二类是已经装了但被各种报错和配置冲突折磨过的中级用户第三类是想把 AI 编程代理集成进自己工作流、甚至想基于openrig思路做二次开发的老手。我会从环境准备一路讲到多工具协同、模型路由、会话保活把踩过的坑和验证过的方案都摊开讲。提示本文涉及的所有工具均为本地开发辅助工具配置过程全部在你自己的机器上完成不涉及任何网络代理相关内容。所有模型接入均指通过官方或本地推理服务提供的标准 API 接口。2. Node.js 运行时整个装备架的地基怎么打2.1 为什么 Claude Code 和 Codex 都绕不开 Node.jsClaude Code 和 Codex CLI 本质上都是 Node.js 写的命令行程序通过 npm 全局安装。这意味着你的 Node.js 版本直接决定了这两个工具能不能装、能不能跑。我见过太多人卡在第一步error installing 24.21.0: node.js v24.21.0 is not yet released or is not available——这个报错的意思是你试图安装的 Node.js 版本号根本不存在或者你的包管理器源里还没有这个版本。这里有个反直觉的点不是 Node.js 版本越新越好。Claude Code 和 Codex 对 Node.js 有明确的版本区间要求通常建议 LTS长期支持版本。截至我写这篇内容时Node.js 20.x 和 22.x 的 LTS 是最稳妥的选择。24.x 虽然新但很多 AI 工具的依赖链还没完全适配贸然上最新版容易遇到原生模块编译失败的问题。在 Ubuntu 上装 Node.js我不推荐直接用apt install nodejs因为系统源里的版本往往偏旧。更可靠的做法是用 NodeSource 的源或者用 nvmNode Version Manager做版本管理。nvm 的好处是你可以同时装多个版本随时切换这对需要测试不同工具兼容性的人来说非常实用。# 安装 nvm curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash # 重新加载 shell 配置 source ~/.bashrc # 安装 Node.js 20 LTS nvm install 20 nvm use 20 nvm alias default 20 # 验证 node -v npm -v装完之后node -v应该输出v20.x.x。如果你在 Windows 上建议直接去 Node.js 官网下载 LTS 版本的安装包安装时勾选Add to PATH省去手动配环境变量的麻烦。Windows 下用 nvm-windows 也可以但体验不如 Linux/macOS 顺滑偶尔会遇到权限问题。2.2 npm 全局目录与权限一个容易被忽略的坑Node.js 装好了接下来装 Claude Code 或 Codex 时很多人会遇到EACCES权限错误。这是因为 npm 默认的全局安装目录需要 root 权限。有两种解法一是每次都用sudo npm install -g但这会带来后续权限混乱二是把 npm 的全局目录改到用户目录下。# 创建用户级全局目录 mkdir -p ~/.npm-global # 配置 npm 使用该目录 npm config set prefix ~/.npm-global # 把该目录加入 PATH写入 ~/.bashrc 或 ~/.zshrc export PATH~/.npm-global/bin:$PATH source ~/.bashrc这样配完之后npm install -g就不需要 sudo 了后续升级工具也不会因为权限问题失败。这个细节看起来小但它能帮你避开后面一连串莫名其妙的报错。2.3 验证运行时是否真的就绪装完 Node.js 和 npm 之后别急着装 AI 工具先做一轮基础验证。我习惯跑这几个命令node -v # 确认版本 npm -v # 确认 npm 可用 npm config get prefix # 确认全局目录 which node # 确认 node 路径如果which node指向的是 nvm 管理的路径比如~/.nvm/versions/node/v20.x.x/bin/node说明 nvm 生效正常。如果指向/usr/bin/node那可能是系统自带的旧版本在干扰需要检查 PATH 顺序。注意如果你之前用 apt 装过 nodejsnvm 和系统版本可能共存导致node -v和which node结果不一致。这种情况下建议sudo apt remove nodejs清理掉系统版本避免版本冲突。3. Claude Code 与 Codex 的安装、认证与首次跑通3.1 Claude Code 的安装路径与认证方式Claude Code 通过 npm 全局安装npm install -g anthropic-ai/claude-code装完之后在终端输入claude就能启动。首次启动会引导你完成认证。这里有个关键分叉你是用官方订阅还是接第三方 API / 本地模型如果你用官方订阅直接按引导登录即可。但如果你看到your organization has disabled claude subscription access for claude code这个报错说明你的账号所属组织关闭了 Claude Code 的订阅访问权限。这种情况下你需要走 API Key 的方式或者联系组织管理员。接第三方 API 或本地模型时核心是配置环境变量。Claude Code 支持通过ANTHROPIC_BASE_URL和ANTHROPIC_API_KEY来指定自定义端点。比如你想让它调用 LM Studio 起的本地模型export ANTHROPIC_BASE_URLhttp://localhost:1234/v1 export ANTHROPIC_API_KEYlm-studio claudeLM Studio 默认在 1234 端口提供 OpenAI 兼容的 API。但要注意Claude Code 期望的是 Anthropic 格式的 API而 LM Studio 提供的是 OpenAI 格式两者并不完全兼容。这就是为什么很多人接本地模型时会失败——协议对不上。解决办法是用一个转换层比如 LiteLLM 之类的代理工具把 OpenAI 格式转成 Anthropic 格式或者直接用支持 Anthropic 协议的本地推理服务。3.2 Codex 的安装与它和 Claude Code 的差异Codex CLI 的安装方式类似npm install -g openai/codex但 Codex 的配置体系和 Claude Code 完全不同。Codex 用~/.codex/config.toml或环境变量来配置认证走 OpenAI 的 API Key 或登录流程。常见的报错codex登录不上通常和网络环境、API Key 有效性、或者组织设置有关。而codex无法加载组织设置则往往是因为你的账号在组织里没有对应的权限配置。Codex 接第三方模型比如 DeepSeek时需要改config.toml里的model_provider和base_url。这里有个大坑Codex 对模型名称有白名单校验你写一个它不认识的模型名就会报the gpt-5.6-sol model is not supported when using codex with a...。解决办法是查 Codex 官方文档支持的模型列表或者用它的model_providers自定义配置来绕过校验。3.3 两个工具的核心差异对照维度Claude CodeCodex CLI安装包anthropic-ai/claude-codeopenai/codex配置文件环境变量为主~/.codex/config.tomlAPI 协议Anthropic 格式OpenAI 格式本地模型接入需协议转换相对直接常见认证报错组织禁用订阅登录失败、组织设置加载失败模型名校验较宽松较严格有白名单这张表是我实际用下来总结的不是官方文档抄的。理解这些差异你才能在openrig这类编排层里正确地路由请求。3.4 首次跑通的验证清单装完两个工具后别急着上复杂配置先各自跑一个最小验证claude --version和codex --version确认安装成功在空目录下启动claude问一个简单问题确认能收到回复同样启动codex确认基础对话可用检查各自的配置文件位置确认没有语法错误我踩过的一个坑是Claude Code 和 Codex 同时装在全局目录下某些共享依赖版本冲突导致其中一个启动时报模块找不到。解决办法是给它们分别用独立的 Node.js 版本nvm 切换或者确保全局依赖树干净。4. tmux 会话保活让 AI 代理在后台稳定干活4.1 为什么 AI 编程代理需要 tmuxClaude Code 和 Codex 都是长驻进程一次任务可能跑几分钟甚至更久。如果你直接在 SSH 会话里跑网络一断进程就没了之前的工作全白费。tmux 解决的就是这个问题它创建一个持久化的终端会话你断开连接后会话继续存在重新连上就能恢复。更重要的是openrig这类编排工具往往需要同时管理多个 AI 代理会话——一个跑 Claude Code 处理前端代码一个跑 Codex 处理后端逻辑还有一个跑测试。用 tmux 可以给每个会话起个名字随时切换互不干扰。# 创建名为 claude-work 的会话 tmux new -s claude-work # 在会话里启动 Claude Code claude # 按 CtrlB 然后按 D 脱离会话进程继续运行 # 重新连接 tmux attach -t claude-work # 列出所有会话 tmux ls4.2 tmux 配置里值得改的几个默认项tmux 默认配置有几个反人类的地方我建议在~/.tmux.conf里改掉# 把前缀键从 CtrlB 改成 CtrlA更顺手 set -g prefix C-a unbind C-b bind C-a send-prefix # 开启鼠标支持可以点击切换面板 set -g mouse on # 设置更大的回滚缓冲区AI 输出很长默认 2000 行不够 set -g history-limit 50000 # 窗口编号从 1 开始 set -g base-index 1 setw -g pane-base-index 1history-limit这个特别重要。AI 代理的输出动辄几百行默认缓冲区很快就被冲掉了你想往上翻看之前的输出都翻不到。设成 50000 行之后基本够用。4.3 用 tmux 编排多代理工作流假设你要同时跑 Claude Code 和 Codex可以这样组织# 创建主会话 tmux new -s openrig -d # 在会话里创建第一个窗口跑 Claude Code tmux new-window -t openrig -n claude tmux send-keys -t openrig:claude claude C-m # 创建第二个窗口跑 Codex tmux new-window -t openrig -n codex tmux send-keys -t openrig:codex codex C-m # 创建第三个窗口跑日志监控 tmux new-window -t openrig -n logs tmux send-keys -t openrig:logs tail -f ~/.openrig/logs/*.log C-m这样你一个tmux attach -t openrig就能在三个窗口之间用CtrlA加数字切换。这套编排思路就是openrig想标准化的东西——把会话管理、进程启动、日志监控统一起来。提示tmux 会话在系统重启后会丢失。如果你需要开机自动恢复可以配合 systemd 服务或者写一个启动脚本在登录时自动重建会话。但要注意AI 代理的认证状态可能不会自动恢复需要重新登录。5. 模型路由与配置冲突那些报错背后的真实原因5.1cc switch local proxy failed到底在说什么这个报错cc switch local proxy failed while handling codex endpoint /responses是很多人切换模型时遇到的。拆开看cc switch是切换配置的动作local proxy是本地代理层codex endpoint /responses是 Codex 的响应接口。整句话的意思是切换配置时本地代理在处理 Codex 的/responses端点时失败了。根因通常有三个第一代理层没有正确识别 Codex 的 API 格式OpenAI 格式 vs Anthropic 格式第二切换后的模型端点不可达或返回了非预期格式第三配置文件里有残留的旧配置和新配置冲突。排查顺序我建议这样先确认目标模型端点能独立访问用 curl 直接打再检查代理层的日志看它把请求转发到了哪里最后对比新旧配置文件的差异。很多时候问题就出在配置文件里同时存在两套 provider 定义代理不知道该用哪个。5.2codex is ignoring 1 unrecognized configuration setting的隐性坑这个警告看起来无害但它意味着你写的某个配置项 Codex 根本不认识直接被忽略了。如果你以为这个配置生效了实际没有后面就会遇到明明配了却不工作的诡异现象。常见的 unrecognized setting 包括拼写错误的键名比如model_provider写成model_providers、版本不支持的配置项、放错层级的配置。解决办法是查 Codex 对应版本的配置文档逐项核对。我习惯把配置项分成确认支持和待验证两类待验证的先用最小配置测试确认生效后再加进去。5.3 多工具共存时的配置隔离策略Claude Code 和 Codex 如果都接同一个第三方 API很容易出现配置互相干扰。我的做法是按工具隔离配置Claude Code 的配置放在独立的 env 文件里启动时 sourceCodex 的配置放在~/.codex/config.toml不和其他工具共享本地模型的路由配置单独放一份用环境变量注入# ~/.openrig/env/claude.env export ANTHROPIC_BASE_URLhttp://localhost:1234/v1 export ANTHROPIC_API_KEYlocal-key # ~/.openrig/env/codex.env export OPENAI_BASE_URLhttp://localhost:1234/v1 export OPENAI_API_KEYlocal-key启动时按需 source 对应的文件避免全局环境变量污染。这样即使两个工具同时跑也不会因为环境变量冲突而报错。5.4 模型名称校验的绕过思路Codex 对模型名的白名单校验是很多人的拦路虎。当你用一个自定义模型名时它会直接拒绝。绕过思路有两个一是用 Codex 支持的模型名做别名映射在代理层把请求里的模型名替换成真实模型名二是用model_providers自定义 provider声明你自己的模型列表。第一种方案更通用因为它不依赖 Codex 的配置能力。你可以在本地起一个轻量代理收到 Codex 的请求后把model字段替换成实际模型名再转发给真正的推理服务。这样 Codex 以为自己在调官方模型实际调的是你的本地模型。6. 把 openrig 的思路落地成自己的工作流6.1 目录结构设计基于openrig的编排理念我建议这样组织你的工作目录~/.openrig/ ├── env/ # 各工具的环境变量文件 │ ├── claude.env │ └── codex.env ├── config/ # 工具配置文件 │ ├── codex-config.toml │ └── proxy-config.yaml ├── logs/ # 运行日志 ├── scripts/ # 启动、切换、监控脚本 │ ├── start-claude.sh │ ├── start-codex.sh │ └── switch-model.sh └── sessions/ # tmux 会话状态记录这个结构的好处是配置、日志、脚本分离出问题时能快速定位。切换模型时只改env/下的文件不影响其他部分。6.2 一键启动脚本#!/bin/bash # ~/.openrig/scripts/start-claude.sh # 加载环境变量 source ~/.openrig/env/claude.env # 检查 tmux 会话是否已存在 if tmux has-session -t claude-work 2/dev/null; then echo 会话已存在正在连接... tmux attach -t claude-work else echo 创建新会话... tmux new -s claude-work -d tmux send-keys -t claude-work claude C-m tmux attach -t claude-work fi这个脚本做了两件事检查会话是否存在存在就连接不存在就创建。这样你无论什么时候执行结果都是进入一个可用的 Claude Code 会话。6.3 模型切换的原子化操作切换模型最容易出问题的地方是改了一半。比如你改了环境变量但没重启进程或者改了配置文件但代理没重载。原子化操作的意思是要么全部生效要么全部不生效。#!/bin/bash # ~/.openrig/scripts/switch-model.sh MODEL$1 ENV_FILE~/.openrig/env/claude.env # 备份当前配置 cp $ENV_FILE ${ENV_FILE}.bak # 写入新配置 sed -i s|ANTHROPIC_BASE_URL.*|ANTHROPIC_BASE_URL\$MODEL\| $ENV_FILE # 验证新端点可达 if ! curl -s --max-time 5 $MODEL/health /dev/null; then echo 新端点不可达回滚配置 mv ${ENV_FILE}.bak $ENV_FILE exit 1 fi # 重启会话 tmux kill-session -t claude-work 2/dev/null source $ENV_FILE tmux new -s claude-work -d tmux send-keys -t claude-work claude C-m echo 切换完成已重启会话这个脚本的关键是先验证再切换端点不可达就回滚避免把环境搞坏。6.4 日志与可观测性AI 代理跑起来之后你需要知道它在干什么。我建议至少记录三类日志启动日志记录用了哪个配置、哪个模型、请求日志记录每次 API 调用的耗时和状态、错误日志记录所有非 200 响应。# 在启动脚本里加日志重定向 tmux send-keys -t claude-work claude 21 | tee -a ~/.openrig/logs/claude-$(date %Y%m%d).log C-m这样每个会话的输出都会同时显示在终端和写入日志文件。出问题时翻日志比凭记忆排查快得多。7. 我踩过的几个真实坑和对应的解法7.1 版本不匹配导致的装上了但跑不起来有一次我帮朋友配环境Node.js 装的是 24.xClaude Code 装上了但一启动就报原生模块加载失败。折腾了半天才发现是 Node.js 版本太新某个依赖还没适配。降到 20 LTS 之后立刻正常。这个教训是AI 工具链对 Node.js 版本敏感别盲目追新LTS 才是稳妥选择。7.2 环境变量污染导致的配置不生效我习惯在~/.bashrc里 export 一堆环境变量结果 Claude Code 和 Codex 同时读到了对方的配置行为变得诡异。后来改成按需 source 独立 env 文件问题消失。如果你也遇到明明配了却不生效先检查env | grep -i api看看有没有多余的环境变量在干扰。7.3 tmux 会话里的认证状态丢失tmux 会话保活很好用但有个坑如果你在会话里完成了 Claude Code 的登录然后系统重启tmux 会话没了重新创建会话后需要重新登录。认证 token 通常存在~/.claude/或类似目录下只要这个目录没被清理重新登录时可能自动恢复。但如果 token 过期了还是得手动重新认证。我的做法是把认证相关的目录加入备份避免重装系统后重新配置。7.4 本地模型接入时的协议不兼容前面提过Claude Code 要 Anthropic 格式LM Studio 给的是 OpenAI 格式。我试过直接用报了一堆格式错误。后来用一个轻量转换层把 OpenAI 格式转成 Anthropic 格式才跑通。如果你不想自己写转换层可以找现成的开源代理工具配置好映射规则即可。核心是要理解协议转换的关键是请求体和响应体的字段映射尤其是messages、model、max_tokens这几个字段。8. 关于 openrig 这类编排思路的延伸想法openrig目前还是个相对早期的概念但它的方向很明确随着 AI 编程代理越来越多Claude Code、Codex未来还会有更多开发者需要一个统一的编排层来管理它们。这个编排层要解决的核心问题包括配置统一、模型路由、会话保活、日志聚合、成本追踪。我自己在实际使用中的体会是与其等一个完美的工具出现不如先用手头的 tmux 脚本 环境变量隔离把工作流搭起来。这套土办法虽然不优雅但足够可靠而且你完全掌控每个环节。等openrig这类工具成熟了再迁移过去也不迟。最后分享一个小技巧给每个 AI 代理会话起一个有意义的名字比如claude-frontend、codex-backend、test-runner而不是默认的0、1、2。这样tmux ls的时候一眼就能看出哪个会话在干什么切换的时候也不用猜。这个习惯帮我省了不少时间尤其是在同时跑四五个会话的时候。