1. 从 openrig 说起一个被低估的 AI 编码工具链编排层第一次看到openrig这个名字我下意识以为是某个开源硬件项目——毕竟 rig 在英文里常指机架装置。直到我在几个 AI 编码工具的讨论串里反复撞见它才意识到这是一个跟Claude Code、Codex这类命令行 AI 编码代理强绑定的配置编排工具。简单说它解决的是一个非常具体的痛点当你同时用多个 AI 编码代理比如白天用 Claude Code 写业务逻辑晚上用 Codex 跑重构每个工具都有自己的配置文件、模型端点、权限策略散落在~/.claude、~/.codex、项目根目录的 YAML 里改一处忘一处最后自己都搞不清哪个模型在哪个项目里生效。openrig的核心价值就是把这些零散的配置收敛成一套可版本化、可切换、可复用的YAML 驱动配置层。它本身不训练模型、不代理请求而是站在 Node.js 运行时之上帮你把 Claude Code、Codex 这些 CLI 工具的启动参数、模型映射、项目级覆盖规则统一管理起来。适合谁三类人一是同时维护多个 AI 编码工作流的独立开发者二是团队里需要统一 AI 工具配置规范的 Tech Lead三是喜欢折腾本地模型比如把 Claude Code 接到 LM Studio 或 DeepSeek的玩家。我写这篇东西的出发点很直接网上关于openrig的中文资料几乎是空白而热词里那一堆claude code 安装、codex 安装教程、yaml 文件怎么创建、node.js 安装教程说明大量人卡在环境准备这一步。所以下面我会从设计思路讲到实操落地把踩过的坑一并摊开。2. 整体设计思路为什么是 YAML Node.js 这套组合2.1 配置即代码把 AI 工具链当成基础设施管传统做法是每个工具各自为政。Claude Code 读它自己的配置Codex 读它自己的你想让两个工具在同一个项目里用同一套模型策略只能手动同步。这种模式在单工具场景下没问题一旦工具数量超过两个维护成本就指数上升。openrig的思路是把配置抽象成环境profile的概念。一个 profile 就是一份 YAML里面声明了这个环境下所有 AI 编码工具该怎么启动、用哪个模型端点、哪些目录有写权限、哪些命令需要二次确认。切换环境就是切换一份 YAML而不是去改五六个隐藏文件。这个设计借鉴了基础设施即代码IaC的思路——配置应该是声明式的、可 diff 的、可提交到 Git 的。为什么选 YAML 而不是 JSON 或 TOML我的判断是三点第一YAML 支持注释这对需要写为什么这么配的团队场景至关重要JSON 没法写注释是硬伤第二YAML 的层级表达比 TOML 更适合嵌套的工具配置结构第三Claude Code 和 Codex 生态本身就在大量使用 YAML比如模型定义、工作流定义保持一致降低认知负担。热词里yolov10 yaml文件怎么创建、rstudio的yaml在哪里这些搜索也侧面说明 YAML 已经是跨领域的通用配置语言。2.2 Node.js 作为运行时的必然性openrig依赖 Node.js 不是随便选的。Claude Code 本身就是 Node.js 生态的产物Codex 的 CLI 工具链也大量依赖 npm 分发。用 Node.js 做编排层意味着可以直接复用这些工具的 npm 包、共享同一套模块解析逻辑不需要在系统里再引入 Python 或 Go 的运行时。这里有个新手常踩的坑热词里error installing 24.21.0: node.js v24.21.0 is not yet released or is not ava这条报错本质是版本号写错了或者镜像源还没同步。Node.js 的版本发布有严格的节奏偶数版本是 LTS长期支持奇数版本是 Current尝鲜。生产环境我强烈建议锁 LTS比如 20.x 或 22.x别追最新的奇数版。如何查看有没有安装node.js这个问题一条node -v就够了如果报 command not found那就是没装或者没进 PATH。2.3 方案选型对比为什么不自己写脚本有人会问我用 bash 脚本 环境变量不也能实现配置切换吗能但有几个绕不过去的问题。bash 脚本跨平台差Windows 上得再写一套 PowerShell环境变量没法表达嵌套结构工具配置一复杂就变成一堆CLAUDE_MODEL_ENDPOINT_OVERRIDE_FOR_PROJECT_X这种反人类命名最关键的是脚本没有 schema 校验配错了要到运行时才炸。openrig用 YAML schema 校验的方式在加载配置阶段就能告诉你这个字段类型不对这个模型名不在允许列表里。这种 fail-fast 的体验在调试cc switch local proxy failed while handling codex endpoint /responses这类问题时能省下大量时间——至少你能确定问题不在配置格式上。方案跨平台结构表达校验能力可版本化推荐场景bash 脚本差弱无一般单人单工具环境变量好弱无差简单开关JSON 配置好强需额外工具好无注释需求YAML openrig好强内置好多工具多环境3. 核心细节解析openrig 配置结构拆解3.1 顶层结构profile、tools、defaults 三段式一份典型的openrig配置我习惯拆成三块来理解。第一块是profiles定义不同的使用场景比如work、personal、local-model第二块是tools声明每个 AI 编码工具的具体参数第三块是defaults放那些所有 profile 共享的兜底配置。version: 1 defaults: log_level: info confirm_dangerous: true profiles: work: tools: claude-code: model: claude-sonnet endpoint: https://api.example.com codex: model: gpt-5 sandbox: true local-model: tools: claude-code: model: local-qwen endpoint: http://127.0.0.1:1234这个结构的好处是defaults里的东西不用在每个 profile 里重复写。confirm_dangerous: true意味着任何可能修改文件系统的操作都要二次确认这在接本地模型时尤其重要——本地小模型的指令遵循能力参差不齐不加确认很容易把项目改乱。3.2 模型端点映射本地模型接入的关键热词里claude code 调用lmstudio的本地模型、codex接入deepseek这类需求非常集中。openrig处理这件事的方式是在 tool 配置里显式声明endpoint和model。这里有个细节Claude Code 和 Codex 对模型名的解析逻辑不同Claude Code 倾向于用别名如claude-sonnetCodex 更依赖具体的模型标识。openrig在中间做了一层映射你可以在配置里写人类可读的别名由它转换成各工具认识的格式。注意接本地模型时endpoint 一定要写完整的协议和端口比如http://127.0.0.1:1234/v1少写/v1是最高频的报错来源。另外本地模型的上下文窗口通常比云端小配置里最好显式限制max_tokens避免请求超长被截断。3.3 权限与沙箱别让 AI 代理裸奔codex的sandbox: true和 Claude Code 的权限策略是两套不同的机制。Codex 的沙箱更偏向进程级隔离Claude Code 则是在工具调用层面做审批。openrig没法统一这两套底层机制但它能在配置层做策略对齐——比如你声明write_scope: [./src, ./tests]它会分别翻译成两个工具各自认识的权限配置。我实测下来这个对齐功能在团队协作里价值最大。新人入职拉下仓库openrig apply work一条命令他的 Claude Code 和 Codex 就都按团队规范配好了不会出现为什么我的 AI 能改 node_modules 而你的不能这种扯皮。3.4 环境变量注入与密钥管理API 密钥绝对不能写进 YAML 提交到 Git。openrig的做法是配置里只写占位符比如${ANTHROPIC_API_KEY}实际值从环境变量或系统的密钥管理工具读取。这个设计跟十二要素应用12-Factor App的原则一致。tools: claude-code: api_key: ${ANTHROPIC_API_KEY} model: claude-sonnet提示如果你在 Windows 上环境变量的设置方式和 Linux/macOS 不同用setx而不是export。设置完要重开终端才生效这个坑我踩过不止一次。4. 实操过程从零搭起 openrig 工作流4.1 环境准备Node.js 安装与验证第一步永远是 Node.js。去官网下载 LTS 版本别用热词里那个报错的 24.21.0——那个版本号本身就有问题。安装完成后验证三件事node -v # 应输出 v20.x 或 v22.x npm -v # 应输出对应版本 which node # 确认路径正确避免多版本冲突如果which node指向的是 nvm 或 fnm 管理的路径那说明你用了版本管理器这是好事切换版本方便。但要注意某些 AI 编码工具的 CLI 在子进程里调用 node 时可能不走版本管理器导致版本不一致。我的经验是如果遇到诡异的模块找不到错误先检查echo $PATH里 node 的路径顺序。4.2 安装 openrig 与初始化配置假设你已经有了 npm 环境安装openrig本身通常是一条命令的事。安装完成后在项目根目录执行初始化它会生成一份带注释的模板 YAML。这份模板别急着改先跑一遍openrig validate确认环境没问题。npm install -g openrig cd your-project openrig init openrig validatevalidate这一步会检查 YAML 语法、schema 合规性、以及引用的环境变量是否存在。我强烈建议把这一步加进 CI防止有人提交了坏配置。4.3 配置 Claude Code 与 Codex 双工具这是核心环节。假设你的需求是工作日用云端 Claude 写业务代码周末用本地模型跑实验性重构。配置大概长这样version: 1 profiles: daily: tools: claude-code: model: claude-sonnet api_key: ${ANTHROPIC_API_KEY} write_scope: [./src] codex: model: gpt-5 sandbox: true weekend: tools: claude-code: model: local-qwen endpoint: http://127.0.0.1:1234/v1 max_tokens: 8192 write_scope: [./experiments]切换用openrig use daily或openrig use weekend。切换后两个工具的配置会同步更新。这里有个细节Claude Code 的配置生效通常需要重启会话而 Codex 支持热加载。所以切换后如果发现 Claude Code 没反应先退出重进。4.4 参数计算max_tokens 与上下文预算接本地模型时max_tokens的设置需要算一笔账。假设你的本地模型上下文窗口是 32K系统提示词占了 2K你希望留出 4K 给模型输出那么输入内容的预算就是 32 - 2 - 4 26K。但实际使用中AI 编码工具会塞入大量文件内容很容易超。我的做法是把max_tokens设成窗口的 1/4留足余量宁可让模型少输出一点也别因为超长导致整个请求失败。模型窗口系统提示建议 max_tokens输入预算8K1K2K5K32K2K8K22K128K4K32K92K4.5 与 VS Code 集成热词里vscode配置claude code、vscode接入claude code出现频率很高。openrig本身不直接管 VS Code 插件但它生成的配置能被插件读取。关键是把openrig的工作目录和 VS Code 打开的项目目录对齐。如果 VS Code 打开的是子目录而openrig配置在父目录插件可能找不到配置。我的做法是在项目根目录放一个.openrig标记文件让工具链能向上查找。5. 常见问题与排查技巧实录5.1 端点连接类问题cc switch local proxy failed while handling codex endpoint /responses这类报错九成是端点配置问题。排查顺序先curl一下端点看通不通再检查路径是否完整最后看模型名是否被服务端接受。本地模型服务如 LM Studio有时候只监听127.0.0.1如果你在容器或远程环境里跑得改成0.0.0.0并注意防火墙。5.2 模型不支持类问题the gpt-5.6-sol model is not supported when using codex with a...这种报错本质是模型名写错了或者该模型不在你的账户权限内。openrig的 schema 校验能拦住一部分拼写错误但拦不住权限问题。遇到这种先去服务商的控制台确认模型可用性再回来改配置。5.3 权限与订阅类问题your organization has disabled claude subscription access for claude code这条说明是组织层面的策略限制不是配置能解决的。这种情况要么找管理员开权限要么换用 API 密钥模式而非订阅模式。openrig支持在配置里切换认证方式但前提是你得有对应的凭证。5.4 常见问题速查表报错关键词大概率原因排查动作endpoint /responses failed端点路径或端口错curl 测试端点连通性model is not supported模型名错或权限不足控制台确认模型可用性subscription access disabled组织策略限制联系管理员或换认证方式node.js not yet released版本号错误改用 LTS 版本yaml parse error缩进或语法错用 validate 命令定位行号5.5 独家避坑技巧第一个技巧YAML 的缩进只能用空格不能用 Tab。这个坑每年都要坑一批人而且报错信息往往指向错误的行号让人抓狂。建议编辑器设置Tab 转空格。第二个技巧配置里的路径尽量用相对路径绝对路径在不同机器上会失效。openrig解析相对路径时是相对于配置文件所在目录不是当前工作目录这点要记牢。第三个技巧切换 profile 后如果工具行为没变化检查是否有环境变量覆盖了配置。环境变量的优先级通常高于配置文件这是设计使然但容易让人困惑。第四个技巧把openrig配置和项目代码一起提交但把包含密钥的本地覆盖文件加进.gitignore。openrig支持openrig.local.yaml这种本地覆盖机制团队共享基础配置个人放私有配置。6. 进阶玩法把 openrig 用出花来6.1 多项目配置继承openrig支持配置继承你可以定义一个baseprofile然后让其他 profile 继承它并覆盖部分字段。这在管理多个相似项目时特别有用。比如公司所有项目共享一套权限策略但每个项目的模型选择不同。profiles: base: tools: claude-code: confirm_dangerous: true project-a: extends: base tools: claude-code: model: claude-sonnet6.2 与 CI/CD 结合在 CI 里跑 AI 辅助的代码审查时可以用openrig动态生成配置。比如根据分支名决定用哪个模型PR 分支用便宜的模型跑初筛主分支用强模型跑终审。这个玩法我用了半年成本控制效果明显。6.3 本地模型实验场把openrig当成本地模型的实验场是个被低估的用法。你可以快速切换不同的本地模型端点对比它们在同一个编码任务上的表现。配置切换的成本几乎为零比手动改各个工具的配置文件高效太多。我在实际使用中发现openrig最大的价值不在于它做了什么惊天动地的事而在于它把配置管理这件琐事从你的心智负担里拿掉了。当你不用再记Claude Code 的配置在哪个隐藏目录Codex 的模型名该怎么写这些细节时你才能真正把注意力放在编码本身。最后分享一个小技巧定期跑openrig doctor它会检查你的环境是否有版本冲突、配置是否有漂移相当于给工具链做个体检。这个习惯帮我提前发现过好几次 Node.js 版本不一致的问题。