openrig：用YAML声明式编排Claude Code与Codex多智能体配置

1. openrig 到底想解决什么问题第一次看到 openrig 这个名字很多人会以为是又一个“AI 命令行工具合集”但真正用过 Claude Code、Codex 这类终端智能体的人会立刻明白它想解决的是多智能体协作时的配置漂移问题。你手头可能同时装着 Claude Code、Codex CLI甚至还有几个本地模型接入脚本每个工具都有自己的配置文件、环境变量、模型别名和端点定义。时间一长~/.claude/settings.json、~/.codex/config.yaml、项目根目录下的openrig.yaml就开始互相打架——同一个模型在 A 工具里叫gpt-5.6-sol在 B 工具里叫sol-2026端点路径一个写/responses另一个写/v1/responses最后排查半天发现是 YAML 缩进多了一个空格。openrig 的核心定位就是把这些散落在各处的智能体运行配置收拢到一份可版本控制、可复用、可校验的 YAML 清单里。它不替代 Claude Code 或 Codex而是站在它们之上做一层“配置编排层”。你可以把它理解成 Docker Compose 之于 Docker单个容器能跑但多个容器之间的网络、卷、依赖关系需要一份声明式文件来管理。openrig 对 Claude Code、Codex 以及后续可能接入的其他终端智能体做的就是类似的事情。适合读这篇内容的人有三类。第一类是已经在用 Claude Code 或 Codex但每次换项目都要手动改配置、经常遇到“本地代理处理 Codex 端点 /responses 失败”这类报错的开发者。第二类是团队里需要统一 AI 编码工具配置的技术负责人希望新人 clone 仓库后一条命令就能对齐环境。第三类是对 YAML 驱动的工作流感兴趣想看看声明式配置怎么落到 AI 工具链上的工程师。如果你只是偶尔用网页版对话那 openrig 暂时帮不到你但只要你的日常工作流里出现了终端智能体这份配置编排的思路就值得花时间理解。2. 核心设计思路与方案选型拆解2.1 为什么是 YAML 而不是 JSON 或 TOMLopenrig 选择 YAML 作为配置载体这个决定背后有很实际的考量。JSON 不支持注释而智能体配置里大量需要标注“这个模型别名对应哪个实际端点”“这个参数为什么设成 0.2 而不是默认值”。TOML 虽然支持注释但嵌套结构表达起来比较啰嗦尤其是当你要描述多个智能体、多个模型、多个端点之间的交叉引用时TOML 的[table.subtable]语法会迅速变得难以阅读。YAML 的优势在于层级直观、支持锚点和引用、注释自由。比如你可以定义一个基础模型配置作为锚点然后在 Claude Code 和 Codex 两个智能体下分别引用并覆盖差异部分。这种“继承加覆盖”的模式在管理多工具配置时非常省心。当然 YAML 也有它的坑缩进敏感、布尔值歧义yes/no/on/off在某些解析器里会被当成布尔这些后面会专门讲怎么规避。2.2 声明式编排与命令式脚本的取舍很多人第一反应是写个 shell 脚本用sed和jq去改各个工具的配置文件。这种做法在工具数量少、配置项稳定的时候能用但一旦 Claude Code 升级改了配置格式或者 Codex 新增了一个必填字段脚本就会静默失败——它可能把配置改坏了但不报错你直到运行时才发现问题。openrig 走的是声明式路线你只描述“最终状态应该是什么样”由 openrig 去计算差异并应用。这带来的好处是幂等性——无论你运行多少次openrig apply结果都一样。而且声明式配置天然适合放进 Git每次变更都有 diff 可查回滚就是git revert。代价是初次上手需要理解它的 schema不能像写脚本那样随心所欲。但对于需要长期维护的团队配置来说这个学习成本是值得的。2.3 与 npm 生态的集成逻辑openrig 通过 npm 分发这个选择很务实。目标用户群体——用 Claude Code、Codex 的开发者——大概率已经装了 Node.js 和 npm。npm install -g openrig一条命令就能装好不需要额外配置包管理器或编译工具链。而且 npm 的全局包管理机制天然支持版本锁定和升级提示对于需要跟随 Claude Code、Codex 快速迭代的编排工具来说分发效率很重要。不过 npm 在国内网络环境下有个经典问题默认源速度慢全局安装容易超时。后面实操部分会讲怎么配置国内镜像源以及遇到npm.ps1 无法加载文件这类 PowerShell 执行策略问题怎么处理。这些都是实际部署时绕不开的环节。3. 核心配置细节与实操要点3.1 openrig.yaml 的骨架结构一份典型的 openrig 配置从顶层开始通常包含四个部分version、agents、models、endpoints。version用于声明配置 schema 版本方便 openrig 在升级时做兼容性迁移。agents定义你要编排的智能体比如 claude-code 和 codex。models定义模型别名到实际模型 ID 的映射。endpoints定义 API 端点地址和认证方式。version: 1 endpoints: default: base_url: https://api.example.com/v1 api_key_env: OPENRIG_API_KEY models: fast: id: gpt-5.6-sol endpoint: default temperature: 0.2 agents: claude-code: model: fast config_path: ~/.claude/settings.json codex: model: fast config_path: ~/.codex/config.yaml这个骨架的关键在于引用关系清晰。agents下的model: fast指向models里的fastmodels里的endpoint: default指向endpoints里的default。当你要换端点时只改endpoints.default.base_url一处所有引用它的模型和智能体都会跟着变。这就是声明式编排相对于手动改配置的核心优势。3.2 模型别名的命名策略模型别名不要用model1、model2这种无意义的名字也不要用gpt-5.6-sol这种直接暴露实际 ID 的名字。推荐按用途加能力来命名比如fast、reasoning、local、cheap。这样当底层模型从gpt-5.6-sol升级到gpt-5.7-sol时你只需要改models.fast.id一处所有智能体的引用都不用动。注意别名一旦被多个智能体引用重命名成本很高。建议在项目初期就定好命名规范比如全部小写、用连字符分隔、不超过三个单词。3.3 端点配置与认证隔离端点配置里最容易被忽视的是认证信息的处理。绝对不要把 API Key 明文写在 openrig.yaml 里哪怕这个文件只在内网使用。正确做法是通过api_key_env字段引用环境变量openrig 在应用配置时会从环境变量读取实际值写入各智能体的配置时再做一次转换。endpoints: default: base_url: https://api.example.com/v1 api_key_env: OPENRIG_API_KEY timeout: 30 retry: 2timeout和retry这两个参数值得单独说。终端智能体在生成长代码时单次请求可能持续几十秒timeout 设太短会导致请求被中断设太长又会在端点不可用时卡住。根据实际经验30 秒是个比较稳妥的起点如果经常处理大文件可以调到 60。retry 设 2 意味着失败后重试两次对于偶发的网络抖动足够设太多反而会在端点真正故障时浪费时间。3.4 配置校验与 dry-run 机制openrig 在应用配置前应该先做校验这是避免“改坏配置”的关键防线。校验至少覆盖三层YAML 语法是否正确、引用关系是否完整比如agents.claude-code.model指向的别名是否在models里存在、必填字段是否缺失。建议在正式 apply 之前先跑一次 dry-run把将要发生的变更打印出来。openrig validate openrig apply --dry-run openrig applyvalidate只检查不修改apply --dry-run展示差异但不落盘确认无误后再执行apply。这个三步走流程在团队协作场景下尤其重要因为你的配置变更可能会影响其他人的环境。4. 完整实操流程与关键环节实现4.1 环境准备Node.js 与 npm 的安装确认openrig 依赖 Node.js 运行环境建议使用 Node.js 18 LTS 或更高版本。安装完成后先确认 npm 可用node -v npm -v如果npm -v报错无法加载文件 npm.ps1因为在此系统上禁止运行脚本这是 Windows PowerShell 的执行策略限制。解决方法是以管理员身份打开 PowerShell执行Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned然后重新打开终端。这个问题的根源是 PowerShell 默认禁止运行未签名的脚本而 npm 在 Windows 上是通过.ps1脚本调用的。改成RemoteSigned后本地脚本可以运行从网络下载的脚本仍需签名安全性和可用性平衡得比较好。4.2 配置国内镜像源加速安装npm 默认源在国内访问速度不稳定全局安装 openrig 时容易超时。建议切换到国内镜像源npm config set registry https://registry.npmmirror.com npm config get registry确认输出是镜像地址后再执行安装npm install -g openrig openrig --version如果之前装过旧版本先卸载再装npm uninstall -g openrig npm install -g openrig提示切换镜像源后如果遇到某个包找不到可能是镜像同步延迟。可以临时切回官方源安装该包装完再切回来。不要同时设置多个源npm 只会用最后一个生效的。4.3 初始化项目配置在项目根目录执行初始化命令openrig 会生成一份带注释的openrig.yaml模板cd your-project openrig init生成的模板里会包含version、endpoints、models、agents四个顶层字段的示例。不要直接删掉注释那些注释解释了每个字段的用途和可选值。根据你的实际情况修改把endpoints.default.base_url改成你实际使用的端点地址把endpoints.default.api_key_env改成你环境变量里实际设置的名称把models.fast.id改成你实际要调用的模型 ID确认agents.claude-code.config_path和agents.codex.config_path指向正确的配置文件位置4.4 应用配置并验证结果配置改好后按 validate、dry-run、apply 三步走openrig validate openrig apply --dry-run openrig applyapply执行后openrig 会把你声明的配置写入各智能体的实际配置文件。以 Claude Code 为例它会更新~/.claude/settings.json里的模型和端点相关字段。以 Codex 为例它会更新~/.codex/config.yaml。写入前 openrig 会自动备份原文件备份文件带时间戳方便回滚。验证是否生效可以分别启动 Claude Code 和 Codex看它们加载的模型和端点是否与 openrig.yaml 里声明的一致。如果 Claude Code 启动时报your organization has disabled claude subscription access说明认证方式或订阅状态有问题需要检查 API Key 环境变量是否正确设置。4.5 团队协作场景下的配置分发团队使用时把openrig.yaml提交到 Git 仓库但不要提交任何包含密钥的文件。新成员 clone 仓库后只需要三步安装 openrignpm install -g openrig设置环境变量export OPENRIG_API_KEYyour-key应用配置openrig apply这样就能保证所有人的智能体配置完全一致避免“我这里能跑你那里报错”的经典问题。如果团队使用不同的端点比如有人用云端、有人用本地可以在openrig.yaml里定义多个 endpoint然后通过环境变量或命令行参数选择激活哪个。openrig apply --endpoint local5. 常见问题与排查技巧实录5.1 YAML 解析报错怎么快速定位YAML 对缩进极其敏感一个多余的空格就可能导致解析失败。openrig 在 validate 阶段会报出具体的行号和列号但错误信息有时不够直观。我的经验是先看报错行号的上一行因为 YAML 解析器往往在遇到下一个 token 时才发现上一行的缩进有问题。另一个高频问题是布尔值歧义。YAML 1.1 规范里yes、no、on、off、y、n都会被解析成布尔值。如果你某个字段的值恰好是这些字符串需要加引号# 错误会被解析成布尔值 true value: yes # 正确明确是字符串 value: yes5.2 端点连接失败的分层排查遇到端点连接失败不要一上来就改配置按层次排查效率更高排查层检查内容常用命令网络层端点地址是否可达curl -I https://api.example.com/v1认证层API Key 是否有效echo $OPENRIG_API_KEY确认非空配置层openrig.yaml 引用是否正确openrig validate应用层智能体实际加载的配置查看各工具配置文件内容特别要注意cc switch local proxy failed while handling codex endpoint /responses这类报错。它通常意味着本地代理在转发 Codex 的/responses请求时失败了。排查方向是确认端点地址是否包含正确的路径前缀确认代理配置是否与 openrig 声明的端点一致确认模型 ID 是否被端点支持。如果端点不支持某个模型会返回明确的错误信息不要盲目重试。5.3 全局包安装后的 PATH 问题npm install -g安装的包其可执行文件会被放到 npm 的全局 bin 目录。如果这个目录不在系统 PATH 里就会出现“装好了但命令找不到”的情况。查看 npm 全局 bin 目录npm config get prefix在 Linux/macOS 上输出通常是/usr/local可执行文件在/usr/local/bin。在 Windows 上输出通常是%APPDATA%\npm。确认这个路径在 PATH 环境变量里。如果不在手动添加后重启终端。5.4 配置回滚的正确姿势openrig 在 apply 时会自动备份原配置文件备份文件命名格式类似settings.json.bak.20260101T120000。回滚时不要直接覆盖先用 diff 对比diff ~/.claude/settings.json ~/.claude/settings.json.bak.20260101T120000确认差异符合预期后再覆盖。如果 openrig 的 apply 过程本身出了问题导致配置损坏最快的恢复方式是找到最近一次备份文件复制回原位置然后检查 openrig.yaml 里哪项配置导致了问题。5.5 多版本 Node.js 环境下的兼容性如果你用 nvm 或 fnm 管理多个 Node.js 版本全局安装的 openrig 只对当前激活的 Node.js 版本可见。切换 Node.js 版本后如果openrig命令找不到需要在新版本下重新安装nvm use 20 npm install -g openrig这不是 openrig 的问题而是所有 npm 全局包在多版本环境下的通用行为。建议在项目里用.nvmrc固定 Node.js 版本避免团队成员之间因为版本差异导致的行为不一致。6. 进阶用法与配置扩展思路6.1 用锚点和引用减少重复配置当你有多个智能体共享大部分配置、只有少量差异时YAML 锚点能显著减少重复models: base: base_model endpoint: default temperature: 0.2 timeout: 30 fast: : *base_model id: gpt-5.6-sol reasoning: : *base_model id: gpt-5.7-reasoning temperature: 0.1base_model定义锚点*base_model引用锚点:表示合并。这样fast和reasoning都继承了base_model的endpoint、temperature、timeout只需要覆盖id和需要调整的字段。修改基础配置时只改一处所有引用它的模型都会跟着变。6.2 环境变量覆盖机制openrig 支持通过环境变量覆盖配置里的值这在 CI/CD 场景下很有用。约定是OPENRIG_前缀加上配置路径的大写下划线形式。比如要覆盖endpoints.default.base_urlexport OPENRIG_ENDPOINTS_DEFAULT_BASE_URLhttps://staging.example.com/v1 openrig apply这个机制让同一份 openrig.yaml 可以在不同环境开发、测试、生产下应用不同的端点而不需要维护多份配置文件。注意环境变量覆盖的优先级高于文件里的值排查配置不生效时先检查有没有意外的环境变量。6.3 与本地模型接入的配合如果你通过 LM Studio 或其他方式在本地运行模型openrig 同样可以编排。把本地端点定义为一个 endpoint模型 ID 填本地服务暴露的模型名endpoints: local: base_url: http://localhost:1234/v1 api_key_env: OPENRIG_LOCAL_KEY models: local-model: id: local-model-name endpoint: local然后在需要本地模型的智能体下引用local-model。这样切换云端和本地只需要改agents下的model字段不需要动其他配置。本地端点的api_key_env如果本地服务不校验密钥可以设一个占位值但不要留空某些客户端会因为没有密钥而拒绝请求。6.4 配置版本迁移的处理openrig 的version字段用于 schema 迁移。当你升级 openrig 到新版本如果新版本引入了不兼容的 schema 变更validate会提示你需要迁移。迁移命令通常是openrig migrate --from 1 --to 2迁移前务必备份 openrig.yaml。迁移工具会尽量保留你的配置语义但涉及字段重命名或结构调整时建议迁移后人工检查一遍关键字段。如果迁移失败不要强行 apply先回滚 openrig.yaml 再排查。7. 我在实际使用中踩过的坑第一个坑是在 openrig.yaml 里直接写了 API Key。当时图省事觉得反正是内部项目结果有一次不小心把文件推到了公开仓库虽然及时发现并撤销了提交但密钥已经暴露了几分钟。从那以后我强制自己只用api_key_env并且在.gitignore里加上*.local.yaml作为额外防线。第二个坑是忽略了 YAML 的缩进一致性。我习惯用 Tab 缩进但 YAML 规范禁止 Tab必须用空格。编辑器里看起来一样解析时直接报错。后来统一配置编辑器YAML 文件强制用两个空格缩进问题再没出现过。第三个坑是在团队里没有统一 Node.js 版本。有同事用 Node.js 16openrig 的某个依赖在 16 下行为不一致导致 apply 出来的配置有细微差异。后来在项目根目录加了.nvmrc并在 README 里明确写了推荐版本这类问题才消失。最后一个体会是openrig 的价值不在于它本身多复杂而在于它把“配置一致性”这件事从口头约定变成了可执行、可验证的流程。以前团队里说“记得把模型改成 fast”总有人忘现在只需要openrig apply配置就对齐了。这个转变带来的效率提升比任何单个工具的功能都更实在。