1. 从 openrig 这个标题说起：它到底想解决什么问题
第一次看到 openrig 这个词，我脑子里蹦出来的第一反应是“开源 + rig（装置/工作台）”，直觉告诉我这大概率是一个围绕 AI 编程工具链做整合、编排或者配置管理的项目。结合热搜词里高频出现的 Claude Code、Codex、YAML、npm 这几个关键词，基本可以判断：openrig 面向的是那些同时使用多个 AI 编码助手（Claude Code、Codex 等）的开发者，试图用一套统一的配置层，把散落在各处的模型接入、端点路由、参数定义收敛到一个可维护的结构里。
为什么我这么判断？因为现在用 AI 写代码的人普遍面临一个很现实的痛点：Claude Code 有自己的一套配置，Codex 有自己的一套配置，本地模型（比如通过 LM Studio 跑的）又是另一套。你想切换模型、想给不同项目用不同的后端、想统一管理 API 端点，就得在好几个配置文件之间来回改。改错一个字段，工具直接报错，比如热搜里那个很典型的报错——“cc switch local proxy failed while handling codex endpoint /responses”，这就是典型的端点路由配置没对齐导致的。
openrig 要做的，我理解就是把这堆东西“rig”起来——像搭一个工作台一样，把模型、端点、参数、项目配置全部结构化地组织好。它大概率以 YAML 作为配置载体，通过 npm 分发，让用户用一条命令就能拉起一套可切换、可复用、可版本管理的 AI 编码环境。
这篇文章适合谁看？三类人：第一类是被 Claude Code 和 Codex 的配置折腾得够呛、想找个统一方案的开发者；第二类是想把本地模型接进主流编码工具、但卡在端点和参数上的折腾党；第三类是单纯想搞清楚 YAML 配置、npm 包管理这些基础环节怎么配合起来干活的新手。我会从设计思路、核心细节、实操流程、问题排查四个层面，把 openrig 这类项目该怎么做、怎么用讲透。
2. 整体设计思路：为什么是 YAML + npm 这套组合
2.1 用 YAML 做配置层的真实考量
很多人会问，为什么不用 JSON 或者 TOML，偏偏选 YAML？这个问题我在实际项目里反复权衡过。JSON 的问题是没法写注释，而 AI 工具的配置里，注释极其重要——你得标注“这个端点是给 Codex 用的”“这个模型名对应本地 LM Studio 的哪个实例”。TOML 虽然能写注释，但嵌套结构一深就变得很难读，尤其是当你要描述“多个 provider、每个 provider 下多个 model、每个 model 带一组参数”这种三层结构时，TOML 的[provider.model.params]写法会让人眼花。
YAML 的优势在于：缩进即层级，天然适合表达嵌套；支持注释；支持锚点和引用（&anchor和*alias），这意味着你可以定义一份基础配置，然后在不同项目里引用它、只覆盖差异部分。这一点对 openrig 这种“多工具共用一套底座”的场景太关键了。比如你定义了一个base_model_config锚点，Claude Code 和 Codex 的配置都可以引用它，改一处就全生效。
提示：YAML 对缩进极其敏感，Tab 和空格混用是新手最常见的翻车点。我建议统一用 2 个空格缩进，并且在编辑器里开启“显示空白字符”，一眼就能看出哪里混了 Tab。
2.2 npm 作为分发渠道的利与弊
选 npm 分发，逻辑很直接：目标用户是开发者，而开发者机器上大概率已经有 Node.js 和 npm。用npm install -g openrig或者npx openrig就能跑起来，门槛低。而且 npm 的版本管理、依赖解析、脚本钩子（preinstall、postinstall）都能复用，省得自己造一套更新机制。
但 npm 也有坑，热搜里那一堆报错就是证据。“npm : 无法加载文件 npm.ps1，因为在此系统上禁止运行脚本”——这是 Windows PowerShell 的执行策略问题，不是 npm 本身的错，但会拦住一大批 Windows 用户。“npm warn eresolve overriding peer dependency”——这是依赖树里有版本冲突，npm 强行覆盖了某个 peer 依赖，通常不致命但要看清楚覆盖的是什么。“node 安装后 npm 不能用”——多半是环境变量 PATH 没配好。
所以 openrig 这类项目在文档里必须把这几类环境问题写清楚，否则用户还没摸到配置层就被挡在门外了。我的经验是：安装文档里单独开一节“环境自检”，让用户先跑node -v、npm -v、npm config get registry三条命令确认基础环境，再往下走。
2.3 多工具统一编排的核心矛盾
openrig 最核心的设计难点，是 Claude Code 和 Codex 这两个工具的配置模型并不一致。Claude Code 偏向“订阅 + 端点”的模式，Codex 则更强调“模型名 + 参数”的显式声明。热搜里那个the 'gpt-5.6-sol' model is not supported when using codex with a...的报错，本质就是模型名和工具支持的清单对不上。
统一编排的思路，我倾向于“中间层抽象”：openrig 定义一套自己的中立配置 schema，然后针对每个工具写一个 adapter，把中立配置翻译成该工具认识的格式。这样用户只需要维护一份 openrig 配置，切换工具时由 adapter 负责转换。这个设计的代价是要维护 adapter 的兼容性，但收益是用户的心智负担大幅降低。
3. 核心细节解析：配置结构、端点路由与参数映射
3.1 一份可用的 openrig 配置长什么样
基于常见实践，我推测 openrig 的配置文件大概会长成下面这样。注意这是合理演绎，不是官方原文，但结构逻辑是这类项目通用的：
# openrig.yaml version: 1 # 定义可复用的模型底座 models: local_qwen: provider: lmstudio endpoint: http://127.0.0.1:1234/v1 model_name: qwen2.5-coder-7b context_window: 32768 params: temperature: 0.2 top_p: 0.9 remote_claude: provider: anthropic model_name: claude-sonnet context_window: 200000 params: temperature: 0.3 # 定义工具如何消费上面的模型 tools: claude_code: default_model: remote_claude fallback_model: local_qwen endpoint_style: anthropic codex: default_model: local_qwen endpoint_style: openai extra: stream: true这份配置里，models段是“资源池”，tools段是“消费方”。改模型参数只动models，改工具行为只动tools，职责清晰。这就是我前面说的“中间层抽象”落地后的样子。
3.2 端点路由：那个 /responses 报错的根源
热搜里cc switch local proxy failed while handling codex endpoint /responses这个报错，我拆解一下。Codex 走的是 OpenAI 风格的端点，路径通常是/v1/responses或/v1/chat/completions；而 Claude Code 走的是 Anthropic 风格，路径是/v1/messages。当你在一个代理层里做切换时，如果代理没根据目标工具改写路径，就会把 Codex 的请求打到 Anthropic 风格的端点上，或者反过来，于是报“failed while handling endpoint”。
openrig 的endpoint_style字段就是干这个的。它告诉 adapter：这个工具发出的请求应该被改写成哪种风格。anthropic风格走/v1/messages，openai风格走/v1/chat/completions。代理层拿到请求后，先看是哪个工具发来的，再按对应风格改写路径和请求体结构。
注意：本地模型服务（如 LM Studio）通常只实现了 OpenAI 兼容接口，不实现 Anthropic 的
/v1/messages。所以如果你把 Claude Code 直接指向本地模型，必须经过一层协议转换，把 Anthropic 格式转成 OpenAI 格式。openrig 的 adapter 如果做得好，这层转换应该是自动的。
3.3 参数映射：context_window 和 temperature 的坑
不同工具对参数的命名和取值范围要求不一样。比如context_window，Claude Code 可能叫max_tokens，Codex 可能叫max_output_tokens，本地模型服务可能压根不认这个字段。openrig 需要在 adapter 里做字段名映射，并且在值超出范围时给出警告而不是静默失败。
temperature相对统一，但要注意有些推理模型（reasoning model）不接受 temperature 参数，传了会报错。我的做法是在配置里加一个supports_temperature: false的标记，adapter 看到这个标记就跳过该参数的注入。
| 中立字段 | Claude Code 映射 | Codex 映射 | 本地模型映射 |
|---|---|---|---|
| context_window | max_tokens | max_output_tokens | 忽略或 n_ctx |
| temperature | temperature | temperature | temperature |
| top_p | top_p | top_p | top_p |
| stream | stream | stream | stream |
这张表是我在实际对接中总结出来的，不同版本可能有出入，但映射思路是一致的：中立字段做源，各工具字段做目标，adapter 负责翻译。
4. 实操过程：从零搭起一套 openrig 环境
4.1 环境准备与 npm 安装避坑
第一步永远是确认 Node.js 环境。跑这三条：
node -v npm -v npm config get registry如果npm -v报“无法加载文件 npm.ps1，因为在此系统上禁止运行脚本”，这是 Windows PowerShell 的执行策略拦的。解决办法是以管理员身份打开 PowerShell，执行Set-ExecutionPolicy RemoteSigned，然后输入 Y 确认。这个操作只影响当前用户的脚本执行策略，风险可控。
如果 npm 装包慢，换国内源：npm config set registry https://registry.npmmirror.com。换完再npm config get registry确认一下。热搜里“npm 淘宝源”“npm 国内源”“npm 镜像源地址”说的都是这件事。
装 openrig 本身，我建议先全局装：
npm install -g openrig openrig --version如果全局装遇到权限问题（Linux/macOS 上常见），可以改用 npx 免安装运行：npx openrig init。npx 的好处是每次拉最新版，坏处是启动稍慢。
提示：卸载全局包用
npm uninstall -g openrig。如果之前装过旧版想彻底清干净，先npm ls -g --depth=0看看装了哪些全局包，确认没有残留再重装。
4.2 初始化配置与目录结构
装完之后跑openrig init，它应该会在当前目录或用户主目录下生成一份openrig.yaml模板。我建议放在项目根目录，跟代码一起做版本管理，这样团队里每个人拉下来就是同一套配置。
目录结构我习惯这样组织：
project/ ├── openrig.yaml # 主配置 ├── .openrig/ │ ├── adapters/ # 自定义 adapter（可选） │ └── cache/ # 端点探测缓存 └── src/.openrig/目录建议加进.gitignore的只有cache/，adapters/如果团队共享就提交上去。
4.3 接入本地模型：以 LM Studio 为例
本地模型是很多人的刚需，热搜里“claude code 调用 lmstudio 的本地模型”就是典型场景。步骤是：
- 在 LM Studio 里加载模型，启动本地服务，记下端口（默认 1234）。
- 在 openrig.yaml 的
models段加一个local_xxx条目，endpoint填http://127.0.0.1:1234/v1。 - 在
tools段把目标工具的default_model指向这个条目。 - 跑
openrig apply让配置生效。
关键点在于endpoint_style。LM Studio 是 OpenAI 兼容的，所以endpoint_style: openai。如果你要让 Claude Code 用它，adapter 必须做 Anthropic 到 OpenAI 的协议转换，否则请求格式对不上，直接 400。
4.4 验证配置是否真的生效
配置写完别急着用，先跑openrig doctor（如果项目提供这个命令）或者手动发一个探测请求：
curl http://127.0.0.1:1234/v1/models确认本地服务活着，再跑openrig test --tool codex之类的命令，看它能不能成功握手。我踩过的坑是：配置里模型名写错一个字母，工具不报“模型名错”，而是报“端点无响应”，排查方向完全被带偏。所以验证时一定要先确认端点通、再确认模型名对、最后确认参数合法，三步分开查。
5. 常见问题与排查技巧实录
5.1 安装阶段的典型报错速查
| 报错信息 | 根本原因 | 解决方向 |
|---|---|---|
| npm.ps1 禁止运行脚本 | PowerShell 执行策略 | Set-ExecutionPolicy RemoteSigned |
| node 装完 npm 不能用 | PATH 未配置 | 把 Node 安装目录加进系统 PATH |
| eresolve overriding peer dependency | 依赖版本冲突 | 看警告里覆盖的是哪个包，必要时锁版本 |
| 全局包装不上 | 权限不足 | 用 npx 或配置 npm 全局目录到用户空间 |
这张表里的每一条我都在不同机器上遇到过。最烦的是 PATH 问题，因为报错信息往往不直接说“PATH 没配”，而是说“命令找不到”。判断方法很简单：where node（Windows）或which node（Linux/macOS），如果找不到，就是 PATH 的事。
5.2 运行阶段的端点与模型报错
cc switch local proxy failed while handling codex endpoint /responses这类报错，排查顺序是：
- 确认代理层是否在运行，端口是否被占用。
- 确认请求路径有没有被正确改写（Codex 的请求不该打到 Anthropic 风格端点上）。
- 确认目标端点是否支持该路径，本地模型服务通常只支持
/v1/chat/completions，不支持/v1/responses。
the 'gpt-5.6-sol' model is not supported when using codex with a...这类报错，就是模型名不在工具支持清单里。解决办法是在 openrig 配置里把model_name改成工具认识的名称，或者通过 adapter 做名称映射。
提示：遇到模型不支持的报错，先别改配置，先用工具自带的“列出可用模型”命令确认它到底认哪些名字。很多时候是名字大小写或者前缀的问题。
5.3 我踩过的三个真实坑
第一个坑：YAML 里用了 Tab 缩进，编辑器看着对齐，解析器直接报错。后来我养成了保存前跑一遍openrig validate的习惯，能在写配置阶段就发现问题，不用等到运行时。
第二个坑：本地模型服务的端口被别的进程占了，openrig 连不上却报“模型加载失败”，误导我以为模型有问题。后来学会先netstat -ano | findstr 1234确认端口占用情况。
第三个坑：切换工具时忘了openrig apply，改了配置但没生效，白白排查了半小时。现在我的流程固定成“改配置 → validate → apply → test”四步，一步不省。
6. 这套东西后续还能怎么扩展
openrig 这类项目的想象空间其实挺大。往小了说，它可以做成一个“配置模板市场”，大家把自己调好的模型参数、端点组合分享出来，别人openrig pull一下就能用。往大了说，它可以往 CI 方向走——在流水线里用 openrig 统一管理 AI 辅助编码的环境，保证本地和 CI 用的是同一套模型配置，避免“本地能跑 CI 挂掉”的经典问题。
我自己在实际操作中的体会是：配置层的东西，前期多花半小时把结构设计清楚，后期能省下几十次的来回改。openrig 的价值不在于它支持多少工具，而在于它把“工具怎么配”这件事从散落的文档和记忆里，收敛成了一份可读、可版本管理、可复现的 YAML。这一点，对任何同时用多个 AI 编码工具的人来说，都是实打实的减负。
