openrig 多 AI 编码工具编排：YAML 配置与 Node.js 实战

1. 从 openrig 说起一个被低估的 AI 编码工具编排层第一次看到openrig这个名字我下意识以为是某个开源硬件项目——毕竟 rig 在英文里常指机架装置。但结合它周围那一圈关键词Claude Code、Codex、YAML、Node.js我立刻反应过来这是一个把多个 AI 编码助手统一编排、统一配置的工具层。说白了它解决的是当下最让人头疼的一个问题——你手上有 Claude Code、有 Codex、可能还有本地跑的模型每个工具都有自己的配置方式、自己的启动参数、自己的模型映射规则切换一次就要改一堆文件烦得要命。openrig的核心价值就是把这些散落各处的配置收敛到一份 YAML 里用 Node.js 作为运行时把用哪个模型、走哪个端点、传什么参数这件事变成声明式的配置而不是每次手动敲命令。它面向的是那些已经在日常开发里重度使用 AI 编码助手的人——不是尝鲜玩一次就卸载的而是每天要跟 Claude Code 对话几十轮、偶尔切到 Codex 跑长任务、还想接本地模型省点额度的那批人。我写这篇东西不是要给你一份官方文档的翻译。官方文档通常只告诉你怎么配不告诉你为什么这么配配错了会怎样哪些坑我踩过。我打算按我自己实际折腾的顺序把 openrig 这套东西从设计思路到落地细节完整拆一遍包括 YAML 到底该怎么写、Node.js 环境怎么准备、多模型怎么映射、出问题怎么排查。看完你应该能直接抄作业也能明白每一步背后的道理。2. 为什么需要 openrig多 AI 编码工具的编排痛点2.1 单工具时代的配置还算能忍在只用 Claude Code 的时候配置其实不算复杂。装好 Node.js装好 Claude Code登录账号基本就能用了。偶尔要接本地模型或者第三方端点改一改环境变量也就过去了。这个阶段大多数人是能接受的因为只有一个工具心智负担低。但问题在于AI 编码这个领域变化太快了。今天 Claude Code 好用明天 Codex 某个版本在长上下文任务上更稳后天你又发现本地跑个量化模型做简单补全几乎零成本。于是你开始同时用两三个工具。这时候麻烦来了每个工具的配置格式不一样Claude Code 认环境变量Codex 认自己的配置文件本地模型又要单独起服务。你想让它们共享同一套模型定义几乎不可能只能各配各的。2.2 多工具并存的三个真实痛点我把实际使用中遇到的痛点归纳成三类这三类基本覆盖了 openrig 想解决的全部问题。第一类是模型映射的重复劳动。比如你有一个第三方端点提供了gpt-5.6-sol、deepseek-v4、qwen、glm这些模型。Claude Code 想用其中一个Codex 想用另一个本地 LM Studio 又跑着一个。每个工具都要单独写一遍模型名到端点的映射改一次要改三处非常容易漏。第二类是启动参数的碎片化。Claude Code 有它自己的启动参数Codex 有它自己的本地服务又有自己的。你想统一设置超时、重试次数、上下文长度结果发现每个工具的参数名都不一样根本没法统一。第三类是切换成本高。你正在用 Claude Code 写代码突然想切到 Codex 跑一个长任务得先退出、改配置、再启动。这个过程中断思路体验很差。理想情况下应该有一个统一的入口你告诉它这次用 Codex 跑它就自动把配置切过去。2.3 openrig 的定位配置层而非替代品这里必须说清楚一个容易误解的点openrig 不是要替代 Claude Code 或 Codex它是架在这些工具之上的一层配置编排。它不重新实现 AI 编码能力而是把怎么调用这些工具这件事标准化。这个定位决定了它的设计取向。它必须足够薄不能引入太多自己的逻辑否则就成了另一个需要学习的工具它又必须足够灵活能适配不同工具的差异。用 YAML 做配置格式是个很自然的选择——YAML 可读性好支持嵌套结构适合描述模型-端点-参数这种层级关系。用 Node.js 做运行时也很合理因为 Claude Code 本身就是 Node.js 生态的环境天然兼容。提示如果你还没装 Node.js先别急着装 openrig。Node.js 版本不对会导致一堆莫名其妙的报错后面我会专门讲版本选择。3. 环境准备Node.js 与 YAML 基础3.1 Node.js 版本选择与安装openrig 跑在 Node.js 上所以第一步是把 Node.js 装对。这里有个很常见的坑网上教程经常让你装最新版但最新版有时候是尚未正式发布的预览版装完各种报错。我见过有人报error installing 24.21.0: node.js v24.21.0 is not yet released or is not available就是版本号写错了或者源里还没有这个版本。我的建议是选 LTS长期支持版本不要追最新。截至我写这篇的时候Node.js 20.x 和 22.x 的 LTS 都比较稳。你可以去 Node.js 官网下载对应系统的安装包Windows 直接下.msimacOS 下.pkgLinux 用包管理器或者 nvm。装完之后验证一下node -v npm -v如果两条命令都能输出版本号说明装好了。如果提示command not found说明 PATH 没配好Windows 上重新装一遍并勾选Add to PATHmacOS/Linux 检查一下 shell 配置文件。注意如果你之前装过多个 Node.js 版本强烈建议用 nvmNode Version Manager来管理。它能让你在不同项目间切换 Node.js 版本避免版本冲突。装 nvm 之后nvm install 20然后nvm use 20就行。3.2 YAML 是什么为什么用它YAML 是一种配置文件格式全称是 YAML Aint Markup Language。它的特点是用缩进表示层级用冒号表示键值对可读性极强。举个例子同样描述一个模型配置JSON 要写成{ models: { claude: { endpoint: https://api.example.com, model: gpt-5.6-sol } } }YAML 写成models: claude: endpoint: https://api.example.com model: gpt-5.6-sol明显 YAML 更清爽没有一堆括号和引号。这就是 openrig 选 YAML 的原因——配置这东西人看得舒服比机器看得舒服更重要因为改配置的是人。YAML 有几个必须记住的规则缩进只能用空格不能用 Tab冒号后面要有一个空格字符串一般不用加引号除非包含特殊字符。这三条违反了任何一条YAML 解析就会报错而且报错信息往往很模糊让人抓狂。3.3 安装 openrig 与目录结构环境准备好之后安装 openrig。如果它发布在 npm 上直接npm install -g openrig装完之后通常会在用户目录下生成一个配置目录比如~/.openrig/或者~/.config/openrig/。里面会有默认的配置文件模板。你可以先看一眼模板了解它期望的结构再动手改。我建议的目录组织方式是~/.openrig/ ├── config.yaml # 主配置 ├── models/ # 模型定义按提供商拆分 │ ├── claude.yaml │ ├── codex.yaml │ └── local.yaml └── logs/ # 运行日志把模型定义拆成多个文件好处是改一个提供商不会影响其他也方便版本管理。openrig 一般支持在主配置里用include或类似机制引入子文件具体语法看它的文档。4. 核心配置用 YAML 编排多模型4.1 主配置文件的结构设计openrig 的主配置一般分三大块全局设置、模型定义、工具映射。全局设置管超时、日志级别这些模型定义描述每个模型怎么连工具映射说明哪个工具用哪个模型。一个典型的主配置长这样global: timeout: 120 retry: 3 log_level: info models: claude-sonnet: provider: anthropic endpoint: https://api.anthropic.com model: claude-sonnet-4 api_key_env: ANTHROPIC_API_KEY codex-gpt: provider: openai endpoint: https://api.openai.com/v1 model: gpt-5.6-sol api_key_env: OPENAI_API_KEY local-qwen: provider: openai-compatible endpoint: http://localhost:1234/v1 model: qwen2.5-coder api_key: not-needed tools: claude-code: default_model: claude-sonnet fallback: local-qwen codex: default_model: codex-gpt fallback: local-qwen这个结构的好处是模型和工具解耦。你可以定义十个模型然后让不同工具引用不同的模型改模型定义不影响工具配置改工具配置也不影响模型定义。4.2 模型定义的关键字段模型定义里有几个字段是必须理解的我逐个说。provider决定用哪套协议去调用。anthropic走 Anthropic 的协议openai走 OpenAI 的协议openai-compatible表示兼容 OpenAI 协议但不是官方本地模型和大多数第三方端点都属于这一类。选错 provider 会导致请求格式不对直接报错。endpoint是服务地址。官方服务填官方地址本地服务填http://localhost:端口/v1。注意很多 OpenAI 兼容端点要求路径带/v1漏了会 404。model是模型名。这个名字必须和端点实际提供的模型名一致。我见过有人把gpt-5.6-sol写成gpt-5.6结果报the gpt-5.6-sol model is not supported其实就是名字对不上。api_key_env表示从哪个环境变量读密钥。这样做比把密钥直接写在 YAML 里安全因为 YAML 可能被提交到版本库。设置环境变量的方式export ANTHROPIC_API_KEYyour-key-hereWindows 上用set或者系统设置里的环境变量界面。4.3 工具映射与回退策略tools这一块是 openrig 的精髓。它让你为每个工具指定默认模型和回退模型。回退策略的意义在于当默认模型不可用时比如额度用完、服务挂了自动切到备用模型不中断你的工作。比如你正在用 Claude Code 写代码突然 Anthropic 的额度用完了。如果没有回退你就得手动切到本地模型。有了回退openrig 自动帮你切过去你甚至感觉不到中断。配置回退的时候要注意回退模型的能力最好和主模型接近否则体验会断崖式下降。比如主模型是 Claude Sonnet回退到本地 7B 小模型那代码质量会差很多。更合理的做法是回退到另一个云端模型本地模型只作为最后兜底。4.4 环境变量与密钥管理密钥管理是个容易被忽视但很重要的问题。我总结几条经验永远不要把密钥写死在 YAML 里。用api_key_env引用环境变量。不同工具用不同的密钥变量名。避免混淆。本地模型不需要密钥但有些兼容端点会检查api_key字段是否存在填个占位符如not-needed即可。定期轮换密钥。尤其是第三方端点的密钥泄露风险更高。如果你在团队里共享配置可以把 YAML 提交到版本库但密钥部分用环境变量每个人在自己机器上设置。这样配置可共享密钥不泄露。5. 实操从零跑通一次多模型切换5.1 第一步验证 Node.js 与 openrig 安装先确认基础环境没问题node -v # 应输出 v20.x 或 v22.x npm -v # 应输出对应版本 openrig --version # 应输出版本号如果openrig命令找不到说明全局安装的 bin 目录不在 PATH 里。用npm config get prefix看一下全局目录把它加到 PATH。5.2 第二步写一份最小可用配置先别追求完整写一份最小配置跑通再说global: timeout: 60 log_level: debug models: local-test: provider: openai-compatible endpoint: http://localhost:1234/v1 model: qwen2.5-coder api_key: not-needed tools: claude-code: default_model: local-test这份配置只定义一个本地模型让 Claude Code 用它。跑通之后再逐步加云端模型。5.3 第三步启动本地模型服务如果你用 LM Studio打开它加载一个模型启动本地服务器默认端口通常是 1234。确认服务起来了curl http://localhost:1234/v1/models应该返回模型列表。如果连不上检查 LM Studio 的服务器是否启动、端口是否被占用。5.4 第四步用 openrig 启动 Claude Codeopenrig run claude-codeopenrig 会读取配置把local-test模型的信息注入到 Claude Code 的启动环境里然后启动它。这时候你在 Claude Code 里对话请求就会走本地模型。第一次跑通的时候我建议开debug日志级别这样能看到 openrig 到底注入了什么参数、请求发到了哪里。排查问题时这个日志非常有用。5.5 第五步加入云端模型并测试切换本地跑通后加入云端模型models: local-test: provider: openai-compatible endpoint: http://localhost:1234/v1 model: qwen2.5-coder api_key: not-needed cloud-main: provider: anthropic endpoint: https://api.anthropic.com model: claude-sonnet-4 api_key_env: ANTHROPIC_API_KEY tools: claude-code: default_model: cloud-main fallback: local-test设置好ANTHROPIC_API_KEY环境变量再跑一次。这次默认走云端云端不可用时自动回退到本地。你可以故意把ANTHROPIC_API_KEY设错观察回退是否生效。5.6 参数计算超时与重试怎么定超时和重试这两个参数看似简单其实有讲究。超时太短长任务会被打断超时太长卡住的时候你要等很久。我的经验值是普通对话 60 秒长代码生成 120 到 180 秒。本地模型因为算力有限超时要设得更长比如 300 秒。重试次数建议 2 到 3 次。重试太多会在服务真的挂了的时候浪费时间重试太少又扛不住偶发的网络抖动。配合指数退避第一次等 1 秒第二次等 2 秒第三次等 4 秒效果最好不过这个要看 openrig 是否支持配置退避策略。6. 常见问题与排查技巧实录6.1 模型不支持类报错最常见的报错之一是the xxx model is not supported。这个报错几乎总是因为模型名和端点实际提供的名字不一致。排查步骤用curl直接问端点有哪些模型curl endpoint/models对比返回的模型名和 YAML 里写的名字注意大小写、连字符、版本号后缀我踩过一次坑端点返回的是gpt-5.6-sol我 YAML 里写的是gpt-5.6-sol-2024多了个日期后缀结果就报不支持。去掉后缀就好了。6.2 端点连接失败类报错cc switch local proxy failed while handling codex endpoint /responses这类报错通常意味着本地代理层在转发请求时出了问题。可能的原因端点地址写错比如漏了/v1本地服务没启动端口被占用防火墙拦截排查顺序先curl端点确认服务活着再检查 YAML 里的地址最后看日志里实际请求的 URL 是什么。6.3 组织权限类报错your organization has disabled claude subscription access for claude code这个报错和 openrig 本身无关是账号层面的权限问题。如果你用的是组织账号管理员可能关闭了 Claude Code 的访问权限。这种情况只能联系管理员或者换个人账号。6.4 常见问题速查表报错关键词可能原因排查方向model is not supported模型名不匹配对比端点返回的模型列表local proxy failed端点地址或服务问题curl 端点、检查端口organization has disabled账号权限问题联系管理员或换账号node.js not yet releasedNode.js 版本号错误换 LTS 版本command not foundPATH 未配置检查全局 bin 目录6.5 独家避坑技巧几条我从实际折腾里总结的技巧文档里一般不会写第一改配置前先备份。YAML 缩进错一格就可能整个解析失败备份能让你快速回滚。第二用openrig validate之类的命令先校验配置。如果 openrig 提供校验命令改完配置先跑一遍别直接启动工具。第三日志级别平时设info排查时设debug。debug日志量大长期开着会拖慢速度。第四本地模型和云端模型分开测。先确保本地跑通再加云端出问题容易定位。第五环境变量在启动 openrig 的同一个终端里设置。如果你在 A 终端设了环境变量在 B 终端启动 openrig是读不到的。7. 进阶玩法把 openrig 用出花来7.1 多项目多配置如果你同时维护多个项目每个项目对模型的需求可能不同。比如项目 A 需要长上下文模型项目 B 需要快速补全模型。openrig 一般支持按目录加载不同配置你可以在项目根目录放一个.openrig.yaml启动时自动读取。这样每个项目的模型偏好就隔离了不会互相干扰。7.2 本地模型与云端模型的成本平衡本地模型几乎零成本但能力有限云端模型能力强但按量计费。合理的策略是简单任务走本地复杂任务走云端。openrig 的回退机制可以帮你实现这个——把本地设为主模型云端设为回退当本地搞不定时自动升级到云端。不过要注意回退是自动的你可能不知道什么时候切了。所以日志要开定期看看回退频率评估本地模型是否够用。7.3 配置的版本管理把 openrig 配置纳入 Git 管理是个好习惯。你可以追踪每次配置变更出问题时回滚到上一个可用版本。密钥部分用环境变量配置文件本身可以放心提交。我建议给配置写个简短的 README说明每个模型是干什么的、密钥怎么设、常见问题怎么处理。团队协作时这份 README 能省很多沟通成本。7.4 与其他工具的集成openrig 的配置层思路其实可以推广。比如你在 VS Code 里用 Claude Code 插件插件本身可能不支持多模型切换但你可以通过 openrig 在底层做映射让插件以为自己在用一个模型实际背后是 openrig 在调度。这种透明代理的思路是 openrig 这类工具最大的想象空间。它不改变上层工具的使用方式只在底层做编排对用户几乎无感。8. 我个人的几点体会折腾 openrig 这段时间最大的感受是AI 编码工具的编排层价值不在于功能多而在于把复杂度收敛。以前我要维护三份配置、记三套参数、切换时手动改文件现在一份 YAML 搞定。省下来的不是几分钟是每次切换时被打断的思路。另一个体会是YAML 配置的可读性真的重要。我试过用 JSON 写同样的配置改的时候要数括号眼睛都花了。YAML 用缩进表达层级一眼就能看出结构改起来顺手很多。这也是为什么我建议把模型定义拆成多个文件——单个文件太长再好的格式也会变得难读。最后分享一个小技巧给每个模型起个有意义的名字。别用model1、model2这种用claude-sonnet、local-qwen、codex-gpt这种一看就知道是什么的名字。配置是给人看的名字起好了半年后回来看还能秒懂。这套东西后续还能怎么扩展我想到两个方向一是把配置做成模板新项目直接复制二是写个脚本根据当前任务类型自动切换模型。不过这些都要看 openrig 后续支不支持更细粒度的钩子机制。目前这套配置层已经够我日常用了稳。