1. 从“openrig”这个名字说起：它到底想解决什么问题
第一次看到“openrig”这个词，我脑子里蹦出来的第一反应是“open”加“rig”——一个开放的、可拼装的装置或框架。结合热搜词里高频出现的 Claude Code、Codex、YAML、Node.js 这一串关键词，基本可以判断：openrig 是一个围绕 AI 编程助手（尤其是命令行形态的 Claude Code 和 Codex）做统一配置、统一接入、统一管理的开源工具或配置框架。它的核心价值，是把原本散落在各个工具、各个配置文件、各个环境变量里的东西，收敛成一套可复用、可版本控制、可跨机器迁移的“装备架”。
为什么我敢这么判断？因为过去大半年，我身边几乎所有重度使用 AI 编程助手的开发者都遇到了同一个痛点：Claude Code 装一遍、Codex 装一遍、VS Code 插件再配一遍，每换一台机器、每换一个模型供应商，就要把 API 地址、密钥、模型名、代理设置、权限开关重新折腾一遍。更麻烦的是，Claude Code 和 Codex 的配置格式还不一样，一个偏 JSON，一个偏 YAML，环境变量命名也各玩各的。openrig 要做的，就是把这些“各玩各的”统一到一个 rig（装备架）上，让你像换镜头一样切换模型和工具。
这篇文章我打算按一个真实从业者的视角，把 openrig 这类工具背后的设计逻辑、核心配置细节、完整落地流程、以及我踩过的坑，全部摊开讲清楚。不管你是刚听说 Claude Code 想上手的新人，还是已经在 Codex 和 Claude Code 之间来回横跳的老手，都能从里面找到能直接抄作业的部分。尤其是那些被 “cc switch local proxy failed while handling codex endpoint /responses” 这类报错折磨过的朋友，这篇大概率能帮你省下几个晚上的时间。
2. 整体设计思路：为什么是 YAML + Node.js 这套组合
2.1 用 YAML 做统一配置层的合理性
openrig 选择 YAML 作为核心配置格式，这个决定我认为非常务实。Claude Code 本身大量使用 JSON 做配置，Codex 的很多项目脚手架（比如模型训练相关的 YOLOv10 那类 yaml 文件）也习惯用 YAML，而 YAML 相比 JSON 有几个对“人”更友好的特性：支持注释、支持多行字符串、缩进即层级、不用满屏引号和逗号。当你需要在一个文件里同时描述“用哪个模型供应商”“走哪个端点”“给 Claude Code 和 Codex 分别传什么参数”时，YAML 的可读性优势就出来了。
更重要的是，YAML 天然适合做“环境分层”。你可以写一个openrig.base.yaml放公共配置，再写openrig.local.yaml放本机覆盖项，最后合并。这种模式在团队协作里特别香——公共部分进 Git，个人密钥和本机路径走本地覆盖，既不会泄露密钥，也不会因为某个人改了配置把别人搞崩。我实测下来，这套分层比直接在 Claude Code 的 settings.json 里硬编码要稳得多。
2.2 Node.js 作为运行时底座的原因
热搜词里 “node.js 是干什么的”“安装 node.js”“node.js lts 下载” 出现频率极高，说明大量用户是在配置 Claude Code / Codex 的过程中第一次接触 Node.js。openrig 这类工具用 Node.js 做运行时，原因很直接：Claude Code 本身就是基于 Node.js 生态分发的（npm 全局安装），Codex CLI 也大量依赖 Node 工具链。用 Node.js 写 openrig，意味着它可以直接复用 npm 的包管理、可以直接读取和写入 Claude Code 的配置文件、可以在 Windows / macOS / Ubuntu 上用同一套代码跑起来。
这里有个很多人忽略的点：Node.js 的版本选择。热搜里那条 “error installing 24.21.0: node.js v24.21.0 is not yet released or is not available” 就是典型的版本踩坑。我的建议是永远优先装 LTS 版本，而不是追最新的 Current 版本。LTS 版本经过长时间验证，npm 生态兼容性最好，Claude Code 和 Codex 的安装脚本对 LTS 的支持也最稳。你如果装了奇数版本或者刚发布的偶数版本，很容易遇到某个依赖编译不过去的情况。
2.3 统一接入层要解决的核心矛盾
openrig 真正要啃的硬骨头，是 Claude Code 和 Codex 在“模型接入”这件事上的差异。Claude Code 默认走 Anthropic 官方端点，但社区大量需求是接第三方模型（DeepSeek、Qwen、GLM 等），于是就有了 cc switch 这类切换工具。Codex 这边则经常出现 “the ‘gpt-5.6-sol’ model is not supported when using codex with a...” 这种模型名不匹配的报错。openrig 的思路是：在本地起一个轻量的转发层，把两个工具发出的请求统一成一种内部格式，再根据配置路由到真正的模型端点。
这个设计的好处是，Claude Code 和 Codex 都以为自己连的是“官方端点”，实际上请求被 openrig 接管并重新分发。坏处是，一旦转发层配置错了，就会出现 “cc switch local proxy failed while handling codex endpoint /responses” 这种让人抓狂的报错。所以理解 openrig 的配置结构，本质上就是理解它的路由规则。
3. 核心配置细节拆解：一份能跑的 openrig.yaml 长什么样
3.1 顶层结构设计
一份典型的 openrig 配置，我习惯分成四大块：runtime（运行时）、providers（模型供应商）、tools（Claude Code / Codex 等工具）、routing（路由规则）。这样分的好处是，当你新增一个模型供应商时，只需要动providers和routing，不用碰工具本身的配置。
runtime: node_version: "20.x" config_dir: "~/.openrig" log_level: "info" providers: deepseek: base_url: "https://api.deepseek.com/v1" api_key_env: "DEEPSEEK_API_KEY" models: - "deepseek-chat" - "deepseek-coder" qwen: base_url: "https://dashscope.aliyuncs.com/compatible-mode/v1" api_key_env: "QWEN_API_KEY" models: - "qwen-max" - "qwen-coder-plus" tools: claude_code: enabled: true default_provider: "deepseek" default_model: "deepseek-coder" codex: enabled: true default_provider: "qwen" default_model: "qwen-coder-plus" routing: - match: "claude_code" provider: "deepseek" - match: "codex" provider: "qwen"上面这份配置是我实际用过的简化版。注意api_key_env这个设计——它不直接写密钥，而是引用环境变量名。这是安全底线，密钥永远不要进配置文件，更不要进 Git。你在.bashrc或.zshrc里 export 对应的环境变量就行。
3.2 供应商配置里的关键参数
base_url是最容易出错的地方。很多第三方模型服务提供的是 OpenAI 兼容接口，路径通常是/v1，但有些服务商要求/v1/chat/completions完整路径，有些则只认根路径。我的经验是，先看服务商文档给的示例，然后用 curl 手动测一次，确认能通再写进配置。热搜里 “codex 接入 deepseek” 这类需求，十有八九卡在 base_url 写错。
models列表也要注意，模型名必须和服务商文档完全一致，大小写都不能错。Codex 报 “model is not supported” 很多时候不是模型真的不支持，而是名字写错了，或者路由没匹配上。我一般会在配置里把常用模型名都列出来，切换时只改default_model一行。
3.3 工具侧的配置映射
Claude Code 和 Codex 各自有自己的配置文件位置和格式。openrig 的作用是“生成”或“注入”这些配置，而不是让用户手动去改。以 Claude Code 为例，它读取的是用户目录下的 settings 文件，openrig 会根据tools.claude_code这一段，把 base_url、model、api_key 等字段写进去。Codex 类似，但字段名不同。
这里有个实操心得：先让 openrig 生成配置，再手动检查一遍生成结果。我遇到过 openrig 生成的配置里，某个字段名和工具实际期望的不一致，导致工具启动后一直报认证失败。检查一遍能省掉大量排查时间。生成后的文件通常在~/.openrig/generated/下面，直接打开对比官方文档即可。
4. 完整落地流程：从零到能跑通 Claude Code 和 Codex
4.1 环境准备：Node.js 与包管理器
第一步永远是 Node.js。去官网下载 LTS 版本，Windows 用户直接下.msi安装包，macOS 用户可以用官方.pkg或者nvm，Ubuntu 用户我强烈建议用nvm而不是apt，因为apt里的 Node 版本往往偏旧，而且升级麻烦。
# Ubuntu 下用 nvm 安装 Node.js LTS curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash source ~/.bashrc nvm install --lts nvm use --lts node -v npm -v装完之后node -v应该输出类似v20.x.x。如果输出的是v24.x.x这种非 LTS，建议切回 LTS。热搜里那个 “node.js v24.21.0 is not yet released” 的报错，本质就是版本号对不上，nvm 能帮你规避这类问题。
4.2 安装 Claude Code 与 Codex
Claude Code 通过 npm 全局安装：
npm install -g @anthropic-ai/claude-code claude --versionCodex 的安装方式取决于你用的是哪个发行版，常见的是 npm 包或者官方安装脚本。安装完成后用codex --version验证。如果安装过程中卡在某个 native 依赖编译，八成是 Node 版本或者系统缺少 build tools，Ubuntu 下装build-essential和python3通常能解决。
注意：安装 Claude Code 时如果遇到 “your organization has disabled claude subscription access for claude code” 这类提示，说明你的账号权限被组织策略限制了，这种情况需要联系组织管理员，不是本地配置能绕过的。
4.3 初始化 openrig 配置
在项目目录或者用户目录下创建openrig.yaml，把第 3 节那份配置填进去，然后 export 环境变量：
export DEEPSEEK_API_KEY="你的密钥" export QWEN_API_KEY="你的密钥"接着运行 openrig 的初始化命令（具体命令名以工具实际为准，通常是openrig init或openrig apply）。它会读取 yaml，生成 Claude Code 和 Codex 各自的配置文件，并可选地启动本地转发层。
4.4 验证链路是否打通
验证分三步。第一步，单独测供应商端点：
curl -X POST "https://api.deepseek.com/v1/chat/completions" \ -H "Authorization: Bearer $DEEPSEEK_API_KEY" \ -H "Content-Type: application/json" \ -d '{"model":"deepseek-chat","messages":[{"role":"user","content":"ping"}]}'能返回内容说明密钥和端点没问题。第二步，启动 openrig 转发层，看日志有没有报错。第三步，分别启动 Claude Code 和 Codex，发一句简单指令，比如“列出当前目录文件”，看是否正常响应。
如果 Claude Code 通了但 Codex 报 “cc switch local proxy failed while handling codex endpoint /responses”，重点检查 routing 里 codex 的匹配规则，以及 Codex 期望的端点路径是不是/responses而不是/chat/completions。这两个工具的 API 形态不同，路由层必须分别处理。
5. 常见问题与排查技巧实录
5.1 报错速查表
| 报错信息 | 可能原因 | 排查方向 |
|---|---|---|
| cc switch local proxy failed while handling codex endpoint /responses | 路由层未正确处理 Codex 的 responses 端点 | 检查 routing 中 codex 的路径映射，确认转发层支持 /responses |
| the ‘gpt-5.6-sol’ model is not supported | 模型名错误或供应商不支持该模型 | 核对供应商文档中的模型名，检查 default_model |
| your organization has disabled claude subscription access | 账号权限被组织策略限制 | 联系组织管理员，本地无法绕过 |
| error installing node.js v24.21.0 is not yet released | Node 版本号不存在或非 LTS | 用 nvm 切换到 LTS 版本 |
| codex 无法加载组织设置 | 配置文件路径或格式错误 | 检查 openrig 生成的 Codex 配置是否在正确位置 |
5.2 三个我踩过的坑
第一个坑是环境变量没生效。我在.zshrc里 export 了密钥，但 openrig 是在另一个 shell 会话里启动的，读不到。解决办法是把 export 写进 shell 的启动文件后，重新 source 或者新开终端。更稳的做法是用.env文件配合 dotenv 加载，openrig 一般支持指定 env 文件路径。
第二个坑是YAML 缩进错误。YAML 对缩进极其敏感，多一个空格少一个空格都会导致解析失败，而且报错信息往往指向一个看起来没问题的行。我的习惯是用 VS Code 装 YAML 插件，实时校验缩进和语法，能提前发现 90% 的低级错误。
第三个坑是转发层端口冲突。openrig 默认监听的端口如果被其他程序占用，启动会失败或者静默降级。启动前用lsof -i :端口号检查一下，或者直接在配置里换一个不常用的端口。
5.3 独家避坑技巧
我强烈建议在 openrig 配置里加一个dry_run开关。开启后，openrig 只生成配置、只打印将要执行的命令，但不真正启动转发层、不真正修改工具配置。这样你可以在正式应用前，先看一眼它到底要干什么。这个习惯帮我避免了好几次“配置被改乱、工具起不来”的事故。
另外，把~/.openrig整个目录纳入版本控制（密钥走环境变量，不进目录），这样换机器时直接 clone 下来，改一下环境变量就能恢复整套环境。这比每次重新配一遍要省太多时间。
6. 进阶玩法：多模型切换与团队协作
6.1 按项目切换模型
openrig 的配置支持按目录覆盖。你可以在项目根目录放一个openrig.local.yaml，里面只写tools.claude_code.default_model: "qwen-coder-plus"，这样进入这个项目时自动用 Qwen，离开就回到全局默认。这个机制对同时维护多个技术栈的开发者特别实用——写 Python 项目用 DeepSeek Coder，写前端用 Qwen，互不干扰。
6.2 团队共享配置模板
团队协作时，把openrig.base.yaml放进仓库，每个人本地用openrig.local.yaml覆盖密钥和个性化设置。新人入职只需要 clone 仓库、装 Node.js、export 密钥、跑一次openrig apply，五分钟就能把 Claude Code 和 Codex 全部配好。这比写一份几十页的“环境配置文档”要靠谱得多，因为文档会过时，配置模板不会。
6.3 与 VS Code 的集成
VS Code 里装 Claude Code 插件后，插件默认读的是全局配置。如果你用 openrig 管理配置，需要确认插件读的是 openrig 生成的那份文件。有些插件支持指定配置文件路径，有些不支持，不支持的情况下可以用软链接把 openrig 生成的文件链到插件期望的位置。这个细节在官方文档里往往不写，但实际用起来很关键。
7. 我对 openrig 这类工具的真实看法
用了几个月下来，我最大的体会是：openrig 的价值不在于它有多“智能”，而在于它把“配置”这件事从一次性劳动变成了可维护的资产。以前每换一个模型、每换一台机器，我都要重新翻文档、重新试错；现在改一行 YAML、跑一条命令就完事。这种确定性的提升，对天天和 AI 编程助手打交道的人来说，是实打实的效率。
当然它也不是银弹。转发层会引入额外的故障点，配置抽象层会增加理解成本，遇到工具本身升级导致配置格式变化时，openrig 也需要跟着更新。我的建议是：如果你只用 Claude Code 一个工具、只连一个模型，那手动配就够了，没必要上 openrig；但如果你同时用 Claude Code 和 Codex、经常在多个模型之间切换、或者需要给团队统一环境，那 openrig 这类工具能帮你省下的时间，远超学习它的成本。
最后分享一个小技巧：把 openrig 的日志级别调到debug，在排查转发问题时能看到完整的请求和响应路径。平时用info就行，别一直开着 debug，日志文件会涨得很快。
