openrig 配置编排：用 YAML 统一接入 Claude Code 与 Codex

1. openrig 到底是个什么东西第一次看到 openrig 这个名字我下意识以为是某个硬件机架项目毕竟 rig 在英文里就是“装配、机架”的意思。但翻了一圈社区讨论和热词关联之后才反应过来这其实是一个围绕 AI 编程助手做统一接入与编排的开源工具层。简单说它想解决的问题是你手头同时有 Claude Code、Codex 这类命令行 AI 编程工具每个工具都有自己的配置格式、模型接入方式、端点协议切换一次就要改一堆东西openrig 就是把这些差异收敛到一套 YAML 配置里让你用同一份声明式文件去驱动不同的后端。它适合谁如果你只是偶尔用一下某个 AI 助手写两行代码那确实用不上。但如果你像我一样日常要在 Claude Code 和 Codex 之间来回切还要接本地模型、接第三方兼容端点那 openrig 这种“配置即接入”的思路就非常省事。它的核心价值不在于某个模型多强而在于把“工具切换成本”压到接近零。我先把结论放前面openrig 的本质是一个基于 Node.js 运行的配置编排层用 YAML 描述模型端点、工具行为和路由规则然后把这些配置翻译成 Claude Code、Codex 各自能读懂的运行时参数。理解这一点后面所有的安装、配置、排错都会顺很多。2. 为什么是 YAML 加 Node.js 这套组合2.1 YAML 承担的是“人写机器读”的中间层很多人第一次接触 YAML 是在写 CI 配置或者 Docker Compose 的时候觉得它不过是另一种 JSON。但在 openrig 这个场景里YAML 的选择是有明确理由的。Claude Code 和 Codex 各自的配置格式并不统一一个可能偏向 JSON 结构一个可能用环境变量加命令行参数。如果 openrig 直接用某一种工具的格式做基准那另一种工具接入时就要写转换逻辑维护成本会随着工具数量增加而爆炸。YAML 在这里扮演的是“中立描述层”。你只描述你想要什么——用哪个模型、走哪个端点、超时多少、要不要代理转发——至于这些描述最终怎么变成 Codex 的启动参数或者 Claude Code 的配置文件交给 openrig 内部去翻译。这种分层设计的好处是新增一个工具支持时只需要加一个翻译器而不是改动所有已有配置。提示YAML 对缩进极其敏感Tab 和空格混用是最常见的低级错误。我建议统一用两个空格缩进并且在编辑器里打开“显示空白字符”一眼就能看出问题。2.2 Node.js 是运行时底座不是随便选的热词里反复出现 node.js 安装、node.js 官网下载、node.js LTS 下载说明很多人卡在第一步。openrig 选 Node.js 作为运行时核心原因是 Claude Code 和 Codex 这两个工具本身就是 Node.js 生态的产物。Claude Code 通过 npm 分发Codex 的 CLI 也依赖 Node 环境。既然上下游都是 Nodeopenrig 用 Node 实现就能直接复用同一套模块解析、进程管理和网络请求能力不需要额外引入 Python 或 Go 的运行时。另一个现实原因是跨平台。Node.js 在 Windows、macOS、Ubuntu 上的行为一致性比较好openrig 作为编排层需要在这三个平台上都能稳定拉起子进程。如果你在 Ubuntu 上配置 Claude Code或者想在 Windows 桌面版上跑 CodexNode 提供的 child_process 和跨平台路径处理能省掉大量兼容代码。版本选择上我强烈建议用 LTS 版本。热词里有一条 “error installing 24.21.0: node.js v24.21.0 is not yet released” 就是典型的踩坑案例——有人照着某个教程写了版本号结果那个版本根本不存在或者还没发布。Node.js 的版本号不是随便编的偶数开头的是 LTS 线奇数开头的是当前特性线。生产环境用 LTS这是铁律。2.3 配置驱动的编排比硬编码强在哪我早期是自己写 shell 脚本在 Claude Code 和 Codex 之间切脚本里硬编码了端点地址和模型名。刚开始还行后来端点换了、模型升级了每个脚本都要改一遍改漏一个就出问题。openrig 这种配置驱动的做法把“变化的部分”集中到一个 YAML 文件里工具本身不动。这就是典型的关注点分离。而且 YAML 文件可以纳入版本管理。你改了哪次配置、什么时候改的、为什么改git log 里清清楚楚。相比之下环境变量散落在各个 shell 配置文件里排查问题时经常忘了自己什么时候 export 过什么。3. 环境准备Node.js 与包管理器的正确安装姿势3.1 Node.js 安装的三种路径与选择建议安装 Node.js 看起来简单但热词里 node.js 安装、安装 node.js、node.js下载 反复出现说明这一步的坑不少。我梳理了三种常见路径你可以根据自己的系统对号入座。第一种是官网下载安装包。node.js 官网下载页面会给你 LTS 和 Current 两个选项直接选 LTS。Windows 用户下载 .msimacOS 用户下载 .pkg双击一路下一步就行。这种方式最省心适合不熟悉命令行的朋友。缺点是版本切换麻烦想换版本要重新下载安装。第二种是用版本管理工具。macOS 和 Linux 上推荐 nvmWindows 上可以用 nvm-windows。装好之后一条命令就能切版本比如nvm install --lts装最新 LTSnvm use --lts切过去。我自己的习惯是每个项目目录放一个.nvmrc文件写明版本号进目录自动切换避免不同项目互相干扰。第三种是系统包管理器。Ubuntu 上apt install nodejs能装但仓库里的版本往往偏旧。如果你在 Ubuntu 配置 Claude Code用 apt 装的 Node 可能版本不够新导致某些依赖装不上。这种情况我建议还是走 nvm 或者 NodeSource 的源。# 用 nvm 安装并切换到最新 LTS nvm install --lts nvm use --lts node -v npm -v装完之后一定要验证node -v和npm -v都能正常输出版本号。如果node -v报 command not found说明 PATH 没配好这是新手最常见的问题。3.2 npm 镜像与网络问题的处理国内环境下 npm 装包慢是常态。热词里虽然没有直接提镜像但 codex 安装、claude code 安装这类操作都依赖 npm 拉包网络不通就会卡住。我的做法是配置一个国内镜像源能显著提升安装速度。npm config set registry https://registry.npmmirror.com npm config get registry改完之后再装包速度通常能从几分钟降到几十秒。如果你在公司内网可能还需要配置代理但这里要注意代理配置要符合你所在组织的网络规范不要随意使用来路不明的代理地址。注意有些教程会让你全局安装一堆包我建议尽量用npx临时执行或者装在项目本地。全局包多了之后版本冲突和 PATH 污染会让你怀疑人生。3.3 验证 Node 环境是否满足 openrig 要求openrig 对 Node 版本有最低要求通常需要 18 以上。你可以用下面这段命令快速检查node -e console.log(process.versions.node, process.platform, process.arch)输出会告诉你当前 Node 版本、操作系统和 CPU 架构。如果你的版本低于 18建议先升级。另外注意架构Apple Silicon 的 Mac 是 arm64老款 Intel Mac 是 x64下载安装包时别选错。4. openrig 的核心配置结构拆解4.1 一份最小可用的 YAML 长什么样openrig 的配置核心是一个 YAML 文件通常放在项目根目录或者用户配置目录下。我先给你一份最小可用的结构然后逐段解释每个字段为什么这么设计。version: 1 defaults: timeout: 30000 retries: 2 providers: local: type: openai-compatible baseUrl: http://127.0.0.1:1234/v1 model: local-model remote: type: anthropic-compatible baseUrl: https://api.example.com model: claude-sonnet routes: claude-code: provider: remote codex: provider: local这份配置里version是配置格式版本方便未来做向后兼容。defaults放全局默认值比如超时和重试次数。providers定义模型端点每个端点有类型、地址和模型名。routes把工具名映射到具体的 provider。为什么要把 provider 和 route 分开因为同一个 provider 可能被多个工具共用分开之后改端点地址只需要改一处。这就是配置设计里的“单一数据源”原则。4.2 provider 类型的选择逻辑provider 的type字段决定了 openrig 用什么协议去跟端点通信。常见的有openai-compatible和anthropic-compatible两类。前者对应大多数兼容 OpenAI 接口的服务后者对应 Claude 系列接口。热词里出现 “claude code 调用 lmstudio 的本地模型” 和 “codex 接入 deepseek”这两个场景其实都落在openai-compatible这一类上。因为 LM Studio 和 DeepSeek 都提供 OpenAI 兼容接口。你只需要把 baseUrl 指向它们的服务地址model 填对应的模型名就行。这里有个容易踩的坑baseUrl 到底要不要带/v1。不同服务的约定不一样有的要求带有的要求不带。我的经验是先看服务商文档文档没写就两种都试一下报 404 就换另一种。这个细节在热词里 “cc switch local proxy failed while handling codex endpoint /responses” 这类报错中经常出现本质就是路径拼接不对。4.3 路由规则与工具映射routes段是 openrig 的调度核心。它告诉 openrig当 Claude Code 发起请求时走哪个 provider当 Codex 发起请求时又走哪个 provider。这样你就能实现“Claude Code 用远程强模型Codex 用本地快模型”这种混合策略。路由的粒度还可以更细。比如你可以按任务类型分流代码补全走低延迟端点长文本分析走高上下文端点。这种细粒度控制在纯手工配置时代几乎做不到因为你要为每个工具单独维护一套逻辑。openrig 把它抽象成配置之后改一行 YAML 就能调整全局行为。提示路由名要和工具实际使用的标识一致。如果你写的是claude-code但工具内部标识是claude_code匹配就会失败。这种问题不会报明显错误只会表现为“配置没生效”排查起来很费时间。5. 实操从零跑通 openrig 的完整流程5.1 安装 openrig 本体假设你已经装好了 Node.js LTS接下来安装 openrig。如果它发布在 npm 上直接npm install -g openrig openrig --version如果是从源码安装流程通常是 clone 仓库、装依赖、build、linkgit clone repo-url openrig cd openrig npm install npm run build npm linknpm link的作用是把本地包链接到全局这样你就能在任意目录用openrig命令。开发阶段用 link 很方便改完代码重新 build 就生效不用反复安装。装完之后跑openrig --help看看子命令列表。通常会有init、run、validate这几个。init生成默认配置validate检查 YAML 语法run启动编排。5.2 生成并校验配置文件openrig init openrig validateinit会在当前目录生成一个openrig.yaml模板。你先别急着改先跑validate确认模板本身没问题。如果模板都报错那说明安装环节有问题先解决安装再往下走。校验通过之后按你的实际端点修改 provider 段。改完再 validate 一次。养成“改完就校验”的习惯能避免很多运行时才暴露的问题。5.3 接入 Claude Code 的配置要点Claude Code 的接入核心是让它知道请求该发往哪里。openrig 通常会通过环境变量或者生成临时配置文件的方式注入端点信息。你需要确认两件事一是 Claude Code 读的是哪个环境变量二是 openrig 有没有正确设置这个变量。热词里 “vscode 配置 claude code” 和 “ubuntu 配置 claude code” 说明很多人在编辑器集成这一步卡住。我的建议是先在纯终端里跑通确认 openrig 能正常拉起 Claude Code 并完成一次请求再去配 VS Code。终端排错信息更直接编辑器插件层会掩盖很多细节。如果遇到 “your organization has disabled claude subscription access” 这类提示那是账号权限层面的问题跟 openrig 配置无关。这种情况需要检查你的账号订阅状态不是改 YAML 能解决的。5.4 接入 Codex 的配置要点Codex 的接入逻辑类似但端点路径可能不同。热词里 “codex endpoint /responses” 提示我们Codex 可能走的是/responses这个路径而不是常见的/chat/completions。如果你的 provider 配置里 baseUrl 拼出来的完整路径不对就会报 “local proxy failed while handling codex endpoint” 这类错误。排查方法很直接用 curl 手动打一下你的端点看返回什么。curl -X POST http://127.0.0.1:1234/v1/responses \ -H Content-Type: application/json \ -d {model:local-model,input:hello}如果 curl 能通而 openrig 不通那问题在 openrig 的路径拼接或参数转换上。如果 curl 也不通那问题在端点服务本身先把服务跑起来再说。5.5 一次完整的端到端验证配置改完之后跑一次完整流程openrig run claude-code --prompt 写一个快速排序 openrig run codex --prompt 解释这段代码观察输出是否正常返回。如果返回了内容说明链路通了。如果报错看错误信息里提到的端点地址和状态码对照前面的排查思路逐层定位。我自己的习惯是准备一个smoke-test.sh脚本把几个关键命令串起来每次改完配置跑一遍。这样能快速发现“改 A 弄坏 B”的回归问题。6. 常见报错与排查速查表6.1 安装阶段的典型问题报错关键词可能原因处理方式node.js v24.21.0 is not yet released版本号写错或不存在改用--lts或查官网确认版本command not found: nodePATH 未配置检查安装路径并加入 PATHnpm install 卡住网络或镜像问题配置国内镜像源EACCES permission denied全局安装权限不足用 nvm 管理或调整目录权限安装阶段的问题大多有明确报错照着改就行。最怕的是那种“装完了但命令找不到”的静默失败本质都是 PATH 问题。6.2 配置校验阶段的典型问题YAML 语法错误是这一阶段的主力。缩进不对、冒号后面没空格、字符串里有特殊字符没加引号都会导致解析失败。openrig validate通常会告诉你第几行出错按行号去看基本能定位。另一个隐蔽问题是字段名拼写错误。比如把baseUrl写成baseURLYAML 解析不会报错但 openrig 读不到这个字段行为就变成用默认值。这种问题只能靠仔细核对文档解决。6.3 运行阶段的典型问题运行阶段的问题最复杂因为涉及网络、端点服务、协议转换多个环节。我整理了一个排查顺序按这个顺序走能覆盖大部分情况。第一步确认端点服务本身可用。用 curl 直接打端点排除服务问题。第二步确认 openrig 生成的请求地址正确。打开 debug 日志看它实际请求的 URL 是什么。第三步确认请求体和响应体格式匹配。有些端点对字段名有要求比如要input而不是messages。第四步确认超时设置合理。本地模型首次加载可能很慢30 秒超时不够就调到 120 秒。提示debug 日志是排查利器。openrig 通常支持--verbose或环境变量开启详细日志。别嫌日志多出问题时它就是你的地图。6.4 工具集成阶段的典型问题Claude Code 和 Codex 各自有自己的配置读取逻辑。openrig 注入的配置可能被工具自身的配置覆盖导致“改了没生效”。这种情况要检查工具的配置优先级确认 openrig 注入的配置在最高优先级。还有一种情况是工具版本不兼容。Claude Code 更新之后改了配置格式openrig 还在用旧格式注入就会失效。遇到这种问题先看 openrig 有没有新版本升级往往能解决。7. 我踩过的坑和几条实用经验第一个坑是过度配置。刚开始我恨不得把每个参数都写进 YAML结果配置文件几百行改一处要翻半天。后来我学会了只配置真正会变的部分其他用默认值。配置文件的目的是减少重复劳动不是展示你懂多少参数。第二个坑是忽略日志。有次排查一个请求失败我盯着 YAML 看了半小时最后开日志发现是端点地址少了个斜杠。日志里写得清清楚楚早看早解决。第三个坑是版本漂移。Node.js 升级、openrig 升级、工具升级任何一个环节版本变了都可能出问题。我的做法是锁定版本在项目里记录当前验证过的版本组合升级时一次性升完并重新跑 smoke test。第四个经验是配置分层。把公共配置放一份基础 YAML不同场景用覆盖文件叠加。这样既能复用又能针对特定场景微调。openrig 如果支持配置继承这个模式会非常高效。第五个经验是关于本地模型的。本地模型启动慢、显存占用高如果 openrig 并发拉起多个请求很容易把本地服务打爆。我的做法是在 provider 层面加并发限制或者干脆串行执行。远程端点没这个问题但本地端点一定要控制并发。8. 这套方案还能怎么扩展openrig 这种配置编排的思路其实不局限于 Claude Code 和 Codex。任何有“多后端、多工具、配置各异”特征的场景都可以套用类似模式。比如你同时用多个代码审查工具、多个文档生成工具只要它们有可配置的端点就能用一层 YAML 统一管理。再往深了想配置层还可以加策略。比如按时间段切换 provider白天用远程快模型晚上用本地模型跑批量任务。或者按 token 消耗做限流超过阈值自动降级到便宜端点。这些策略在纯手工配置时代很难实现但在配置编排层就是加几行规则的事。我目前的做法是把 openrig 的配置和项目代码放在同一个仓库用不同的 profile 区分开发、测试、生产。这样换环境只需要切 profile不用改任何代码。这个模式跑下来很稳推荐你也试试。最后分享一个小技巧给每个 provider 起一个有意义的名字别用provider1、provider2这种。名字本身就是文档三个月后回来看local-fast和remote-strong比p1、p2好懂得多。