openrig 配置编排工具：统一管理 Claude Code 与 Codex 的 YAML 实践

1. openrig 到底是个什么东西第一次看到 openrig 这个名字我下意识以为是某个硬件外设或者开源机械臂项目毕竟 rig 这个词在硬件圈里太常见了。但翻了一圈社区讨论和仓库结构之后才反应过来它其实是围绕 AI 编程助手生态做的一套配置编排工具核心解决的是 Claude Code、Codex 这类命令行 AI 助手在本地环境里配置散、切换烦、复用难的问题。说白了openrig 干的事情就是把你散落在各个角落的 AI 助手配置——模型接入点、API 端点、代理规则、工具权限、项目级指令文件——统一收拢到一套 YAML 驱动的结构里然后用一条命令完成切换和加载。它本身不训练模型也不替代 Claude Code 或 Codex而是站在它们之上做一层配置管理层。这个定位为什么有价值你只要真正在本地跑过 Claude Code 或者 Codex CLI 就明白了。这两个工具各自有自己的配置文件格式、环境变量约定、认证方式。Claude Code 走的是~/.claude/目录下的 settings 体系Codex 走的是~/.codex/下的 config 体系两边互不相通。你想让它们共用同一个本地模型端点或者在同一台机器上为不同项目切换不同的模型后端就得手动改配置、改环境变量改完还容易忘。openrig 就是冲着这个痛点来的。适合谁看这篇内容三类人一是已经在用 Claude Code 或 Codex但每次换项目都要手动折腾配置的开发者二是想在自己机器上同时管理多个 AI 助手、多个模型端点的重度用户三是团队里需要统一 AI 助手配置规范、想让新人一条命令就能拉起环境的工程负责人。如果你只是偶尔用一下网页版那这篇可能对你帮助有限。2. 核心设计思路与方案选型拆解2.1 为什么选 YAML 作为配置载体openrig 用 YAML 而不是 JSON 或 TOML 来做配置这个选择不是随便定的。JSON 不支持注释而 AI 助手配置里有大量需要标注的地方——比如这个端点对应的是本地 LM Studio、这个模型名是 DeepSeek 的映射——没有注释的配置文件维护起来非常痛苦。TOML 虽然支持注释但嵌套结构表达起来比较啰嗦尤其是当你要描述多个助手 × 多个模型 × 多个项目这种三维关系时TOML 的表格语法会变得很难读。YAML 的优势在于支持注释、支持锚点和引用可以复用配置片段、嵌套结构直观、对多行字符串友好。最后一点特别关键因为 Claude Code 和 Codex 都支持项目级的指令文件类似CLAUDE.md或AGENTS.md这些文件内容往往是多行的提示词用 YAML 的|块标量写起来很自然。提示YAML 对缩进极其敏感Tab 和空格混用是最常见的报错来源。建议在编辑器里设置Tab 转 2 空格并且开启 YAML 语法校验插件。2.2 配置分层的逻辑openrig 的配置结构大致分三层全局层、助手层、项目层。全局层定义通用的模型端点、认证信息、代理规则助手层针对 Claude Code 和 Codex 分别定义各自的启动参数和行为偏好项目层则覆盖具体项目需要的模型选择、指令文件路径、工具权限。这种分层的好处是改一处、生效一片。比如你把本地模型的端点地址在全局层改一次所有引用这个端点的助手和项目都会跟着变。反过来如果某个项目需要特殊处理在项目层覆盖就行不会污染全局配置。我实测下来这种分层设计最实用的场景是白天用云端模型跑正式项目晚上切到本地模型跑实验性代码。以前要改两三个配置文件加环境变量现在只要在项目层把模型引用换一下一条命令重新加载就完事。2.3 与 Claude Code、Codex 原生配置的关系这里要说清楚一个容易混淆的点openrig 不是要取代 Claude Code 和 Codex 的原生配置而是在它们之上做编排。它最终还是要生成或写入这两个工具能识别的配置格式。所以你在 openrig 里写的 YAML本质上是一个源配置openrig 负责把它翻译成 Claude Code 和 Codex 各自认识的格式。这个设计的好处是解耦。Claude Code 和 Codex 的配置格式将来如果变了你只需要等 openrig 更新适配层自己的 YAML 源配置不用动。坏处是多了一层间接性出问题的时候排查链路变长了——你得先确认 YAML 写对了再确认 openrig 翻译对了最后才怀疑工具本身。3. 环境准备与安装实操3.1 Node.js 与 npm 环境确认openrig 通过 npm 分发所以第一步是确认 Node.js 和 npm 环境正常。打开终端执行node -v npm -v如果这两条命令有一条报错先解决 Node.js 安装问题。Windows 用户特别注意一个高频坑在 PowerShell 里执行 npm 命令时报无法加载文件 npm.ps1因为在此系统上禁止运行脚本。这不是 npm 没装好而是 PowerShell 的执行策略限制。解决办法有两种。第一种是临时放开当前会话的执行策略Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass第二种是改用 CMD 或者 Git Bash 来执行 npm 命令绕开 PowerShell 的脚本限制。我个人推荐第二种因为改执行策略有时候会被组策略覆盖重启后又失效。3.2 npm 镜像源配置国内网络环境下npm 默认源拉包速度可能很慢。建议先切到国内镜像源npm config set registry https://registry.npmmirror.com设置完可以用npm config get registry确认。如果之后要发布自己的包或者需要访问某些只在官方源上的包再切回去npm config set registry https://registry.npmjs.org注意切换镜像源之后之前装的全局包不会自动更新。如果遇到某个包行为异常先确认它是不是从镜像源拉的旧版本。3.3 安装 openrig环境确认无误后全局安装 openrignpm install -g openrig安装完成后验证openrig --version如果提示命令找不到说明 npm 的全局 bin 目录没有加到 PATH 里。用npm config get prefix查看全局安装路径然后把这个路径下的 bin 目录加到系统环境变量 PATH 中。Windows 上通常是%APPDATA%\npmmacOS 和 Linux 上通常是/usr/local/bin或~/.npm-global/bin。3.4 初始化配置目录openrig 首次运行需要初始化配置目录openrig init这条命令会在用户主目录下创建~/.openrig/目录并生成一份示例配置文件。目录结构大致如下~/.openrig/ ├── config.yaml # 全局配置 ├── assistants/ # 助手层配置 │ ├── claude.yaml │ └── codex.yaml └── projects/ # 项目层配置 └── example.yaml初始化完成后建议先打开config.yaml看一眼默认内容了解各个字段的含义再根据自己的实际情况修改。4. 配置文件详解与核心参数4.1 全局配置 config.yaml全局配置主要定义模型端点和通用行为。一个典型的配置长这样version: 1 defaults: timeout: 120 retry: 2 log_level: info endpoints: local-lmstudio: base_url: http://127.0.0.1:1234/v1 api_key: not-needed models: - qwen2.5-coder-7b - deepseek-coder-v2 cloud-primary: base_url: https://api.example.com/v1 api_key: ${CLOUD_API_KEY} models: - gpt-4o - claude-sonnet-4这里有几个关键点。base_url是模型服务的接入地址本地模型通常指向 LM Studio 或类似工具的本地端口。api_key支持环境变量引用语法${VAR_NAME}这样敏感信息不用明文写在配置文件里。models列表定义了这个端点下可用的模型名称openrig 在切换模型时会从这里读取候选列表。4.2 助手层配置助手层配置针对 Claude Code 和 Codex 分别定义。以 Claude Code 为例assistant: claude-code endpoint: local-lmstudio model: qwen2.5-coder-7b env: ANTHROPIC_BASE_URL: ${endpoint.base_url} ANTHROPIC_API_KEY: ${endpoint.api_key} settings: auto_approve: false max_tokens: 8192 temperature: 0.2Codex 的配置结构类似但环境变量名和设置项不同assistant: codex endpoint: cloud-primary model: gpt-4o env: OPENAI_BASE_URL: ${endpoint.base_url} OPENAI_API_KEY: ${endpoint.api_key} settings: approval_mode: suggest sandbox: true提示Claude Code 和 Codex 对环境变量的读取时机不同。Claude Code 在启动时读取Codex 在每次请求时读取。所以如果你在 openrig 里改了端点Claude Code 需要重启才生效Codex 则可能立即生效。4.3 项目层配置与覆盖规则项目层配置放在项目根目录下的.openrig.yaml文件里或者放在~/.openrig/projects/下按项目名索引。项目层配置的优先级最高会覆盖全局层和助手层的同名配置。project: my-web-app extends: claude-code model: deepseek-coder-v2 instructions: ./CLAUDE.md tools: allowed: - read_file - write_file - run_tests denied: - deployextends字段指定继承哪个助手层配置instructions指定项目级指令文件路径tools定义工具权限的白名单和黑名单。这个权限控制在实际使用中很有价值——你可以让 AI 助手在开发项目里自由读写文件但禁止它执行部署命令。4.4 配置校验与加载写完配置后先校验再加载openrig validate openrig applyvalidate会检查 YAML 语法、字段类型、引用完整性。apply会把配置翻译成 Claude Code 和 Codex 能识别的格式并写入对应位置。如果校验报错根据错误信息逐条修复不要跳过校验直接 apply否则可能写入半截配置导致工具启动失败。5. 多助手切换与实战场景5.1 场景一本地模型与云端模型快速切换这是最常见的需求。假设你配置了两个端点local-lmstudio和cloud-primary。切换命令openrig switch claude-code --endpoint local-lmstudio --model qwen2.5-coder-7b这条命令会更新 Claude Code 的配置把端点指向本地 LM Studio。切回云端openrig switch claude-code --endpoint cloud-primary --model claude-sonnet-4实测下来切换过程大约 1 到 2 秒比手动改配置文件快得多而且不会漏改环境变量。5.2 场景二同一项目下 Claude Code 与 Codex 协同有些团队会同时用 Claude Code 和 Codex让它们各司其职。比如 Claude Code 负责代码审查和重构建议Codex 负责生成测试用例。openrig 可以让两个助手共享同一套端点定义但各自使用不同的模型和参数。openrig apply --project my-web-app这条命令会根据项目配置同时更新 Claude Code 和 Codex 的配置。两个助手读同一个项目指令文件但模型和工具权限可以不同。5.3 场景三团队配置标准化团队里每个人机器上的 AI 助手配置往往五花八门。openrig 支持把配置模板提交到仓库新人克隆项目后执行openrig init --from-template ./team-config openrig apply就能拉起一套和团队一致的配置。这比写一份配置指南文档靠谱得多因为文档会过时配置模板不会。5.4 切换后的验证方法切换完成后不要假设一定生效。用以下方法验证openrig status这条命令会输出当前生效的端点、模型、助手列表。另外直接在 Claude Code 或 Codex 里发一条测试消息确认返回正常。如果返回报错先看 openrig 的日志openrig logs --tail 50日志里会记录配置加载过程和请求转发情况大部分问题看日志就能定位。6. 常见问题与排查技巧实录6.1 配置加载失败排查表现象可能原因排查方法validate 报 YAML 语法错误缩进用了 Tab、冒号后缺空格用编辑器显示不可见字符统一转空格apply 后工具启动报错环境变量未展开、端点地址错误检查${}引用是否对应存在的字段切换后模型没变工具缓存了旧配置重启 Claude CodeCodex 检查是否热加载本地模型连接超时LM Studio 未启动、端口不对用 curl 直接测端点连通性权限被拒绝tools 白名单未包含所需工具检查项目层 tools.allowed 列表6.2 环境变量不生效的排查思路环境变量问题是最高频的。openrig 支持${VAR}语法引用环境变量但引用的解析时机和工具读取时机可能不一致。排查步骤确认环境变量在当前 shell 里存在echo $CLOUD_API_KEY确认 openrig 能读到openrig env check确认写入的配置文件里变量已展开openrig show --resolved如果第三步显示的还是${CLOUD_API_KEY}原文说明展开失败了。常见原因是变量名拼写错误或者变量定义在.bashrc里但当前 shell 没 source。6.3 npm 全局包冲突处理有时候 openrig 安装后命令行为异常可能是全局包版本冲突。先看依赖树npm ls -g --depth0如果发现有多个版本的 openrig 或者相关依赖先卸载再重装npm uninstall -g openrig npm cache clean --force npm install -g openrig注意npm cache clean --force会清空整个 npm 缓存之后第一次安装包会慢一些但能解决大部分缓存导致的诡异问题。6.4 实操避坑心得踩过的坑里有三个值得单独说。第一YAML 里的布尔值true和false不要加引号加了引号就变成字符串openrig 解析时可能报类型错误。第二端点地址结尾不要多加斜杠http://127.0.0.1:1234/v1和http://127.0.0.1:1234/v1/在某些工具里行为不同。第三项目层配置文件名必须是.openrig.yaml写成openrig.yaml或者.openrig.yml都不会被识别。另外分享一个提效技巧把常用的切换命令写成 shell 别名。比如alias oc-localopenrig switch claude-code --endpoint local-lmstudio --model qwen2.5-coder-7b alias oc-cloudopenrig switch claude-code --endpoint cloud-primary --model claude-sonnet-4这样切换模型就是敲一个短命令的事比每次输完整参数快得多。6.5 日志分析与问题定位openrig 的日志默认写在~/.openrig/logs/下按日期分文件。日志级别可以在全局配置里调整排查问题时临时调到debugdefaults: log_level: debugdebug 级别会记录每次配置加载的完整过程包括读取了哪些文件、展开了哪些变量、写入了哪些目标路径。问题定位完之后记得调回info否则日志文件增长很快。我在实际使用中发现大部分配置不生效的问题根源都在于对配置优先级理解有误。记住这个顺序项目层 助手层 全局层。同名配置项层级高的覆盖层级低的。如果你在全局层改了端点但项目层也定义了端点那全局层的修改不会生效。这个规则看起来简单但在配置项多的时候很容易搞混。