1. openrig 到底想解决什么问题第一次看到openrig这个词是在几个折腾 Claude Code 和 Codex 的群里。有人丢出一句openrig 把配置全接管了底下立刻有人追问是不是又一个套壳工具。我当时的反应也差不多——市面上围绕 Claude Code、Codex 的辅助工具已经多到看不过来从模型切换到本地代理从 YAML 配置到 Node.js 环境几乎每个环节都有人做轮子。但真正把 openrig 拉下来跑通之后我发现它的定位和那些一键切换工具不太一样它更像是一套面向 AI 编码代理的运行时编排层把 Claude Code、Codex 这类 CLI 代理的启动参数、模型端点、YAML 配置、Node.js 运行环境统一收拢到一个可复现的工程结构里。说白了你平时用 Claude Code 或 Codex最烦的不是模型本身而是每次换机器、换项目、换模型供应商时那一堆散落的配置。~/.claude/settings.json、~/.codex/config.yaml、环境变量里的 API Key、Node.js 版本、代理地址……这些东西一旦多起来就会出现在我机器上能跑换台机器就报cc switch local proxy failed while handling codex endpoint /responses这种经典问题。openrig 的核心价值就是把这些碎片化的配置抽象成一份声明式的 rig 描述让代理怎么起、模型怎么接、环境怎么隔离变成可版本控制、可复现的东西。这篇文章适合三类人看一是已经在用 Claude Code 或 Codex但被多环境配置折磨过的开发者二是想搞清楚 YAML 配置、Node.js 运行时、模型端点之间关系的技术爱好者三是准备把 AI 编码代理引入团队工作流需要一套可复制方案的人。我会从 openrig 的设计思路讲起拆解它涉及的 YAML 结构、Node.js 环境管理、模型端点对接再给出一套可以照着抄的实操流程最后分享几个我在实际配置中踩过的坑。全文基于公开的 Claude Code、Codex、YAML、Node.js 生态常识做合理推演具体字段以你本地实际版本为准。2. 为什么需要一层rig来管 AI 编码代理2.1 从能跑就行到换台机器就崩的配置债大多数人第一次装 Claude Code 或 Codex 的时候都是照着教程一路npm install -g然后填个 API Key 就完事。这个阶段确实不需要什么 rig因为只有一套配置、一个模型、一台机器。问题出在第二个阶段你开始尝试不同的模型供应商比如把 Codex 接到 DeepSeek或者用 Claude Code 调用本地 LM Studio 的模型。这时候配置文件开始分叉环境变量开始打架Node.js 版本也可能因为不同工具的依赖要求而冲突。我见过最典型的情况是一台机器上同时装了 Claude Code 和 Codex两者都依赖 Node.js但一个要求 LTS 20.x另一个在新版 24.x 上才正常。你手动切来切去最后自己也记不清哪个终端用的是哪个版本。更麻烦的是 YAML 配置文件——Codex 的config.yaml里模型名、端点、超时参数混在一起改一个字段可能影响另一个功能。这种配置债在单机单人时还能忍一旦要同步到第二台机器或者交给同事就会变成灾难。openrig 这类工具的出现本质上是对这种配置债的回应。它不解决模型能力问题也不做代理转发它解决的是配置的可复现性和环境的一致性。你可以把它理解成 Docker Compose 之于容器不是必须的但当你的服务超过一个手动管理就开始不划算了。2.2 rig 描述文件与 YAML 的分工openrig 里最核心的概念是rig 描述。一个 rig 描述通常是一份 YAML 文件里面声明了这个 rig 需要哪些组件、每个组件用什么版本、模型端点指向哪里、环境变量怎么注入。这里要区分两个层次rig 描述本身是 YAML而它管理的组件比如 Codex自己也有 YAML 配置。很多人第一次接触会混淆这两者以为改一个文件就够了。我的理解是rig 描述是元配置它不直接参与运行时而是负责生成或挂载各个组件的实际配置。比如你在 rig 里声明codex.model: deepseek-chatopenrig 在启动时会把这个值写进 Codex 实际读取的config.yaml或者通过环境变量传给 Codex 进程。这样做的好处是你只需要维护一份 rig 描述不同组件的配置文件由工具自动生成避免了手动同步导致的字段不一致。YAML 在这里的角色很关键。相比 JSONYAML 支持注释、锚点引用、多行字符串写配置的时候可读性高很多。但 YAML 也有坑最著名的就是缩进敏感和类型推断——yes会被解析成布尔值1.0可能变成字符串。我在配置 Codex 端点时就遇到过因为缩进多了一个空格导致整个model_providers块被解析成字符串而不是映射报错信息还特别隐晦。所以用 YAML 管配置格式校验这一步绝对不能省。2.3 Node.js 运行时为什么成了绕不开的依赖Claude Code 和 Codex 的 CLI 版本基本都是 Node.js 写的这意味着你的机器上必须有一个可用的 Node.js 运行时。听起来简单但实际操作中 Node.js 版本管理是新手最容易卡住的地方。热词里出现的error installing 24.21.0: node.js v24.21.0 is not yet released就是典型——有人照着某个教程指定了一个还不存在的版本号安装直接失败。openrig 如果要做环境隔离通常有两种思路一是依赖系统全局的 Node.js通过版本检查确保满足要求二是内置或调用版本管理器如 nvm、fnm、volta来按 rig 切换 Node.js 版本。前者简单但不够隔离后者更彻底但增加了复杂度。从工程实践看如果你的机器上只跑一两个 AI 编码代理全局 Node.js 加版本检查就够了如果你要同时维护多个 rig每个 rig 对 Node.js 版本要求不同那就值得引入版本管理器。这里有个经验Node.js 的 LTS 版本和 Current 版本在 AI 工具生态里的兼容性差异比想象中大。很多 CLI 工具在 LTS 上跑得好好的换到 Current 就可能因为某个原生模块没编译好而报错。所以我在 rig 描述里会明确锁定 Node.js 的主版本号而不是写latest。锁定版本虽然不够新但换来的是一致性这在多人协作场景下比追新重要得多。3. 拆解 openrig 的配置骨架3.1 rig 描述文件的典型字段虽然没有官方文档可以逐字对照但根据 Claude Code、Codex 这类工具的配置惯例一个 rig 描述文件通常会包含以下几类字段。我按自己的理解整理成表格方便你对照自己手上的版本做调整。字段类别典型字段作用常见取值示例元信息name、version标识 rig 名称和版本my-codex-rig、1.0.0运行时runtime.node指定 Node.js 版本要求20.x、22.x组件components[].type声明要启动的代理类型claude-code、codex模型model.provider、model.name模型供应商和模型名deepseek、deepseek-chat端点endpoint.base_url模型 API 的基础地址由你的供应商提供环境env.KEY注入的环境变量API Key、超时设置挂载mount.config组件配置文件的生成路径~/.codex/config.yaml这张表不是标准答案而是帮你建立一个 rig 描述应该覆盖哪些维度的认知。实际字段名可能因版本而异但逻辑是相通的元信息定位、运行时约束、组件声明、模型绑定、端点指定、环境注入、配置挂载。你拿到任何一个 rig 工具都可以用这七个维度去套看它覆盖了哪些、漏了哪些。我特别想强调mount.config这一类字段。很多工具只做到启动时传参但 AI 编码代理往往需要读取磁盘上的配置文件而不是只认命令行参数。如果 rig 工具不能把配置写到正确的位置代理启动后还是会读旧的配置导致你改了 rig 描述却不生效。这个坑我在早期版本里踩过排查了半天才发现是配置文件路径没对上。3.2 模型端点与供应商的映射关系把 Codex 接到 DeepSeek、把 Claude Code 接到本地 LM Studio这类需求在热词里反复出现。核心难点不在技术而在端点格式的差异。不同供应商的 API 路径、认证头、请求体结构都不一样而 Codex 和 Claude Code 各自期望的端点格式也有区别。openrig 如果要做统一编排就必须处理这层映射。以 Codex 为例它通常期望一个兼容 OpenAI 风格的/responses或/chat/completions端点。热词里那个cc switch local proxy failed while handling codex endpoint /responses的报错本质上是本地代理在处理 Codex 的/responses请求时出了问题——可能是路径没匹配上也可能是请求体格式不对。这类问题的排查思路是先用 curl 直接打你的模型端点确认端点本身可用再检查代理层是否正确转发了路径和请求体最后看 Codex 的配置里base_url是否指向了代理而不是模型本身。在 rig 描述里模型端点通常写成供应商 模型名的组合由 openrig 负责拼出完整 URL。这样做的好处是切换供应商时只改一个字段不用手动拼 URL。但前提是 openrig 内置了常见供应商的端点模板。如果它没有内置你用的供应商你就需要手动指定完整base_url这时候要特别注意路径末尾有没有斜杠、版本号对不对。3.3 环境变量注入的时机与优先级环境变量是配置里最容易被忽视、又最容易出问题的一环。API Key、代理地址、超时时间、日志级别这些通常都通过环境变量传给代理进程。openrig 在注入环境变量时面临一个优先级问题系统环境变量、rig 描述里的 env、组件自身的配置文件三者谁覆盖谁我的建议是明确一个原则rig 描述 系统环境变量 组件默认值。也就是说rig 描述里显式声明的变量优先级最高这样你才能通过改 rig 文件来覆盖系统里的旧配置。如果反过来让系统环境变量优先那你在 rig 里写的配置可能被一个忘记取消的旧变量悄悄覆盖排查起来非常痛苦。还有一个时机问题环境变量是在启动代理进程时注入还是在生成配置文件时写入两者效果不同。启动时注入的好处是灵活改 rig 描述后重启即可生效写入配置文件的好处是持久代理自己读取时也能拿到。openrig 如果两者都做就要注意不要产生冲突——比如环境变量里写了API_KEYA配置文件里写了API_KEYB代理到底用哪个取决于它的读取顺序。这种冲突最好在 rig 层面就避免只选一种注入方式。4. 从零搭一个可复现的 openrig 环境4.1 Node.js 环境的准备与版本锁定动手之前先把 Node.js 这块理清楚。不管你用 openrig 还是手动配置Node.js 都是地基。我的做法是用版本管理器装 Node.js而不是从官网下载安装包。原因很简单版本管理器可以让你在同一台机器上并存多个 Node.js 版本按项目切换而官网安装包是全局覆盖的装完新版旧版就没了。如果你用 nvm流程大概是这样的# 安装 nvm具体命令以你系统为准 # 安装并切换到 LTS 版本 nvm install 20 nvm use 20 node -v npm -v如果你用 fnm 或 volta命令不同但逻辑一样。关键是在 rig 描述里锁定主版本号比如20.x然后在启动脚本里用版本管理器切到对应版本。这样即使系统默认是 22.xrig 启动时也会切到 20.x保证一致性。这里有个细节nvm use只在当前 shell 生效如果你在脚本里调用要确保脚本用的是同一个 shell 环境。我见过有人在 CI 里写nvm use 20 npm start结果因为 CI 的 shell 不是交互式的nvm命令根本没加载直接报 command not found。解决办法是在脚本开头 source 一下 nvm 的初始化脚本或者用nvm exec 20 npm start这种形式。提示不要盲目追新 Node.js 版本。热词里那个24.21.0 is not yet released的报错就是因为有人指定了一个不存在的版本。锁定 LTS 主版本比追最新版稳得多。4.2 编写第一份 rig 描述文件假设我们要搭一个把 Codex 接到 DeepSeek 的 rig。先建一个目录比如~/rigs/codex-deepseek在里面创建rig.yaml。内容结构大致如下字段名请以你实际使用的 openrig 版本为准name: codex-deepseek version: 1.0.0 runtime: node: 20.x components: - type: codex config: model: provider: deepseek name: deepseek-chat endpoint: base_url: https://api.deepseek.com/v1 env: API_KEY: ${DEEPSEEK_API_KEY} TIMEOUT: 60这份描述做了几件事声明 Node.js 用 20.x声明启动一个 Codex 组件指定模型供应商和模型名指定端点地址注入 API Key 和超时。注意API_KEY用了${DEEPSEEK_API_KEY}这种引用形式意思是从系统环境变量里读而不是把密钥明文写在 rig 文件里。这一点很重要rig 文件通常要进版本控制明文密钥绝对不能提交。写完 rig 描述后先做 YAML 语法校验。可以用 Python 的yaml模块快速检查import yaml with open(rig.yaml) as f: data yaml.safe_load(f) print(data)如果解析报错多半是缩进或特殊字符的问题。YAML 对缩进极其敏感建议统一用两个空格不要用 Tab。另外字符串里如果有冒号最好用引号包起来避免被解析成映射。4.3 启动、验证与配置落盘rig 描述写好后用 openrig 的启动命令拉起环境。具体命令取决于工具实现可能是openrig up、openrig start之类。启动后要做三件事验证第一确认 Node.js 版本正确。在代理进程的环境里执行node -v看是不是 rig 描述里锁定的版本。如果不对说明版本切换没生效。第二确认配置文件落盘到了正确位置。Codex 通常读~/.codex/config.yamlClaude Code 读自己的 settings 文件。检查这些文件里的模型名、端点是否和 rig 描述一致。如果不一致说明 openrig 的挂载逻辑没生效或者路径写错了。第三发一个最小请求验证端点连通。可以用 curl 直接打模型端点确认 API Key 和网络都没问题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}]}如果 curl 通了但 Codex 还是报错问题就在代理层或配置映射上而不是模型端点本身。这个分层排查的思路能帮你快速定位问题出在哪一层。5. 那些让我卡了半天的坑5.1 YAML 缩进引发的配置不生效前面提过 YAML 缩进敏感但真正踩进去才知道有多坑。我有一次在 rig 描述里写模型配置model下面缩进了两个空格provider和name又各缩进了两个空格看起来没问题。但endpoint那一块我不小心多缩进了一个空格结果整个endpoint被解析成了model的子字段而不是和model平级。openrig 读取时找不到顶层endpoint就用了默认值导致请求打到了一个错误的地址。这种问题的隐蔽性在于YAML 解析器不会报错它只是按缩进理解你的意图。你以为写的是 A它理解的是 B。排查方法是把解析后的数据结构打印出来逐层看字段挂在哪里。我现在的习惯是写完 rig 描述先跑一遍解析把结构 dump 出来确认层级再启动。注意YAML 里yes、no、on、off会被解析成布尔值1.0可能被解析成浮点数。如果你的某个字段值恰好是这些记得加引号。5.2 端点路径末尾斜杠导致的 404模型端点的base_url末尾有没有斜杠看起来是小事实际影响很大。有些代理在拼接路径时是简单字符串相加base_url末尾有斜杠就变成//responses没有就变成/responses。不同的服务器对双斜杠的处理不一样有的能容忍有的直接 404。我遇到过一次cc switch local proxy failed while handling codex endpoint /responses排查到最后发现是base_url末尾多了个斜杠代理转发时路径变成了//responses上游服务器不认。去掉斜杠就好了。这个坑的教训是端点地址要么严格按文档写要么用 curl 验证拼接后的完整 URL不要凭感觉。5.3 环境变量没传进子进程openrig 启动代理时通常是 fork 一个子进程。如果你在 rig 描述里声明了环境变量但启动逻辑没有把这些变量传给子进程代理就读不到。表现是 API Key 为空、超时用默认值报错信息可能是 401 或者连接超时。排查方法是在代理启动后想办法打印它的环境变量。有些工具支持--verbose或 debug 模式能看到实际注入的环境。如果没有可以在 rig 的启动脚本里加一行env | grep API_KEY之类的调试输出。确认变量传进去了再去看代理是否正确读取。这里还有个优先级问题如果系统里已经有一个同名的旧环境变量而 rig 注入的新值没有覆盖它代理可能读到旧值。所以我在启动脚本里会显式 unset 掉可能冲突的变量再注入 rig 里的值确保干净。5.4 多组件共存时的端口与配置冲突如果你在一个 rig 里同时启动 Claude Code 和 Codex要注意它们可能都依赖某些共享资源比如本地代理端口、配置目录、缓存路径。两个组件如果抢同一个端口后启动的会失败如果写同一个配置文件后写的会覆盖先写的。我的做法是给每个组件分配独立的配置目录和端口。比如 Codex 用~/.codexClaude Code 用~/.claude本地代理端口一个用 8080一个用 8081。在 rig 描述里显式声明这些隔离参数而不是依赖默认值。默认值在单组件时没问题多组件时就是冲突的来源。6. 把 openrig 用顺手的几个实践6.1 rig 描述的版本控制与密钥管理rig 描述文件应该进 Git这样换机器时 clone 下来就能用。但密钥不能进 Git。我的做法是rig 描述里只写${VAR_NAME}这种引用真实密钥放在一个不进版本控制的.env文件里启动时 source 进来。.env文件加到.gitignore同时提供一个.env.example说明需要哪些变量。这样做的另一个好处是团队协作时每个人用自己的密钥但共享同一份 rig 描述。新人入职只需要拿到.env.example填上自己的密钥就能复现出和团队一致的环境。这比在群里发配置文件截图靠谱得多。6.2 用 rig 描述做环境快照openrig 的 rig 描述本质上是一份环境快照。当你调通了一个可用的配置把它 commit 下来就相当于给这个可用状态打了个标签。以后升级 Node.js、换模型供应商、改端点都可以基于这个快照做分支出问题能快速回滚。我习惯在 rig 描述里加一个notes字段记录这次配置变更的原因和验证结果。比如2024-xx-xx 切换到 DeepSeek验证通过延迟约 xx ms。这些备注在几个月后回看时特别有用能帮你回忆起当时为什么这么配。6.3 从单机到多机的迁移检查清单把 rig 从一台机器迁到另一台最容易漏的是那些机器特有的东西Node.js 版本、全局安装的 CLI、系统环境变量、本地代理端口占用情况。我整理了一个迁移检查清单每次换机器照着过一遍检查项检查方法常见问题Node.js 版本node -v版本不符需用版本管理器切换CLI 是否安装which codex、which claude未全局安装需npm install -g环境变量envgrep API_KEY端口占用lsof -i :8080端口被其他进程占用配置目录权限ls -la ~/.codex权限不足配置写不进去网络连通curl打端点网络不通或端点地址错误这份清单看起来基础但每次迁移至少能帮我省下半小时的盲目排查。尤其是端口占用和权限问题报错信息往往不直接指向根因有清单对照能快很多。6.4 什么时候不该用 openrig说了这么多 openrig 的好处也得说说什么情况下不需要它。如果你只在一台机器上用一个 AI 编码代理配置一次就不动了那手动配完全够用引入 openrig 反而多一层抽象出问题时还多一个排查对象。openrig 的价值在多的场景下才体现多机器、多模型、多组件、多人协作。单机单代理的场景手动配置的简单直接反而是优势。另外如果你的团队对工具链有严格的安全审查要求引入任何第三方编排工具都需要评估。openrig 作为配置管理层本身不接触模型请求内容但它会读写配置文件和环境变量这些环节需要确认符合你们的安全规范。这一点在团队落地时值得提前沟通。7. 关于模型切换与本地模型接入的补充热词里claude code 调用 lmstudio 的本地模型和codex 接入 deepseek出现频率很高说明大家最关心的还是怎么把代理接到自己想用的模型上。这里补充几个实操要点。本地模型比如 LM Studio的端点通常是http://localhost:1234/v1这种形式兼容 OpenAI 风格。接入时的关键是把base_url指向本地地址模型名填 LM Studio 里加载的模型标识。注意本地模型不需要 API Key但有些代理会强制要求这个字段随便填一个非空值即可。另外本地模型的响应速度取决于你的硬件超时时间要设得比云端模型长一些否则容易在生成中途超时断开。云端模型比如 DeepSeek的接入要点是认证头和端点路径。DeepSeek 兼容 OpenAI 格式认证用Authorization: Bearer端点是/v1/chat/completions。在 rig 描述里把这些固定下来切换模型时只改model.name和base_url两个字段其他不动。这样能把切换成本降到最低。还有一个容易被忽视的点不同模型对请求体里某些字段的支持程度不一样。比如有的模型不支持temperature的某些取值有的对max_tokens有上限要求。切换模型后如果报参数错误先检查请求体里有没有该模型不支持的字段逐个去掉验证。这类问题在 rig 层面不好统一处理只能靠实际测试积累经验。8. 我个人的几点体会折腾 openrig 这类工具最大的收获不是省了多少配置时间而是被迫把AI 编码代理到底怎么跑起来这件事想清楚了。以前用 Claude Code 就是装完用报错就搜搜不到就换工具。现在会去分层看Node.js 运行时对不对、配置文件落盘没有、环境变量传进去没有、端点通不通、代理层转发对不对。这套分层排查的思路比任何一个具体工具都值钱。另外一点是配置这东西一定要可复现。我现在的原则是任何一次调通了的状态都要能通过一份文件加几条命令复现出来。做不到复现的配置等于没配。openrig 的 rig 描述正好满足这个原则所以即使它本身还有些粗糙的地方我也愿意继续用下去。最后提醒一句工具生态变化很快今天能用的字段明天可能就改了。保持 rig 描述简洁、只依赖必要字段能让你的配置在工具升级时少受冲击。那些花哨的高级特性等真正需要时再加也不迟。