1. 从“openrig”这个名字说起它到底想解决什么问题第一次看到openrig这个词我脑子里蹦出来的第一反应是“open”加“rig”——一个开放的、可拼装的“装备架”。后来翻了一圈社区里的讨论结合Claude Code、Codex、YAML、Node.js这几个高频关联词基本能确认它的定位一个把多种 AI 编码代理coding agent统一编排、统一配置、统一调度的开源脚手架。你可以把它理解成给Claude Code、Codex这类命令行 AI 工具做的一层“总控台”用一份 YAML 描述清楚“我要用哪个模型、走哪个端点、挂哪些工具、跑什么流程”然后由 Node.js 侧的执行器把整条链路拉起来。为什么这类东西会突然火起来因为过去大半年AI 编码工具的生态碎得厉害。Claude Code有自己的安装方式、自己的配置目录、自己的权限模型Codex又是另一套 CLI、另一套登录逻辑、另一套模型命名规则。你想在同一个项目里既用 A 又用 B还得让它们共享同一套提示词、同一套工具白名单手工维护的成本高得离谱。openrig想干的事就是把这堆碎片收拢到一个配置文件里让“换模型”“换代理”“换执行环境”变成改几行 YAML 的事。这篇文章适合谁看三类人。第一类是被Claude Code和Codex的安装、配置、模型报错折腾过想找个统一入口的开发者第二类是想把 AI 编码能力接进自己 CI/CD 或本地工作流需要可复现配置的工程同学第三类是对YAML驱动、Node.js工具链感兴趣想照着搭一套自己“装备架”的折腾党。下面我会把设计思路、核心细节、实操流程、踩坑记录全部摊开讲尽量让你看完就能动手。2. 整体设计思路为什么是 YAML Node.js 这套组合2.1 用 YAML 做“单一事实来源”的取舍openrig把配置收敛到 YAML这个选择不是拍脑袋。AI 编码代理的配置项天然是层级化 多环境 需要注释的模型名、端点地址、超时、重试、工具权限、环境变量注入这些东西用 JSON 写会痛不欲生不能写注释、尾逗号报错用 TOML 写嵌套又别扭用纯代码写则失去了“非程序员也能改”的友好度。YAML 刚好卡在中间结构清晰、支持注释、支持锚点和引用还能被绝大多数语言直接解析。但 YAML 有个众所周知的坑——缩进敏感 类型推断诡异。比如model: 5.6会被解析成浮点数endpoint: yes会被解析成布尔值。openrig在解析层做了强制字符串化的处理这点后面实操部分会细讲。选 YAML 的另一个理由是它和Claude Code、Codex生态里大量已有的配置文件比如各种*.yaml工作流定义能无缝对接迁移成本低。2.2 Node.js 作为执行层的现实考量为什么执行层选 Node.js 而不是 Python 或 Go我个人的判断有三点。第一Claude Code和Codex的 CLI 本身就是 Node 生态分发为主用 Node 做编排能直接复用它们的进程管理、stdio 管道、信号处理逻辑少一层跨语言胶水。第二Node 的异步 IO 模型天然适合“同时拉起多个代理进程、并发收集输出”这种场景。第三npx这种零安装分发方式对“脚手架”类工具太友好了用户不用先配虚拟环境。代价也有Node 的版本兼容是个老大难。热词里那条error installing 24.21.0: node.js v24.21.0 is not yet released就是典型——很多人照着教程装了个不存在的版本号直接卡在第一步。所以openrig这类工具通常会在package.json里用engines字段锁死一个 LTS 区间比如20.0.0 23.0.0避免用户踩到奇数版本或未发布版本的坑。2.3 统一编排要解决的三类冲突多代理共存本质上要调和三类冲突。第一是模型命名冲突Claude Code认的模型名和Codex认的模型名不是一套体系热词里那个the gpt-5.6-sol model is not supported when using codex就是模型名对不上导致的。第二是端点冲突一个走官方端点一个走本地推理服务比如 LM Studio端口、协议、鉴权头都不一样。第三是权限冲突Claude Code默认对终端命令有确认机制Codex的沙箱策略又是另一套混用时很容易出现“A 能跑 B 不能跑”的割裂感。openrig的思路是抽象出一层“适配器”每个代理对应一个 adapteradapter 负责把统一的 YAML 配置翻译成各自认识的参数。这样上层配置只写一次底层差异被 adapter 吃掉。这个设计模式在工程上叫“防腐层”好处是新增一个代理只需要写一个新 adapter不用动核心逻辑。3. 核心细节解析配置结构、适配器与执行链路3.1 一份典型 openrig 配置的字段拆解先看结构再讲每个字段为什么这么设计。一份精简的配置大概长这样version: 1 defaults: timeout: 120 retries: 2 log_level: info providers: claude: adapter: claude-code model: claude-sonnet-4 endpoint: https://api.example.com env: ANTHROPIC_API_KEY: ${CLAUDE_KEY} codex: adapter: codex-cli model: gpt-5-codex endpoint: http://127.0.0.1:1234/v1 env: OPENAI_API_KEY: ${LOCAL_KEY} rigs: review: provider: claude tools: [read, grep, diff] prompt_file: ./prompts/review.md refactor: provider: codex tools: [read, write, exec] prompt_file: ./prompts/refactor.mdversion字段是给未来做迁移用的配置格式一旦破坏性变更靠它做兼容分支。defaults放全局默认值避免每个 provider 重复写超时和重试。providers是核心每个条目绑定一个 adapter 和一套连接参数。rigs是我最喜欢的设计——它把“用哪个模型”和“干什么活”解耦了同一个 provider 可以挂多个 rig每个 rig 有自己的工具白名单和提示词文件。提示env里的${VAR}语法是运行时插值不要把密钥明文写进 YAML。openrig在加载时会先做一次环境变量替换替换失败的变量会直接报错退出而不是静默传空字符串——这个“快速失败”策略能帮你早发现配置漏项。3.2 适配器层到底做了什么翻译工作以claude-codeadapter 为例它要干的活包括把统一的model字段映射到 CLI 的--model参数把tools列表翻译成对应的权限开关把endpoint注入到环境变量里因为Claude Code读的是环境变量而不是命令行参数还要处理登录态——热词里your organization has disabled claude subscription access这类报错adapter 需要在启动前做一次轻量的凭证探测提前给出人话提示而不是让用户对着原始报错发呆。codex-cliadapter 的翻译逻辑又不一样。Codex的模型支持列表是硬编码在它自己内部的你传一个它不认的模型名比如那个gpt-5.6-sol它会直接抛model is not supported。所以 adapter 里通常会维护一张“已知可用模型”的映射表配置里写逻辑名adapter 负责转成实际名。这张表需要跟着上游更新这也是这类工具维护成本的主要来源。3.3 执行链路从一条命令到多个进程当你敲下openrig run review时内部大致经历这几个阶段加载并校验 YAMLschema 校验 环境变量插值→ 解析出目标 rig → 找到对应 provider → 实例化 adapter → adapter 拼装出真实的命令行 → 用child_process.spawn拉起子进程 → 把 stdio 接到当前终端或日志文件 → 监听退出码并做重试。这里有个细节值得说为什么用 spawn 而不是 exec。exec会把输出缓冲到内存再一次性返回AI 代理的输出动辄几万 token缓冲会爆内存而且你没法实时看到流式输出。spawn是流式的配合stdio: inherit能让子进程直接接管终端交互体验和原生 CLI 一致。重试逻辑则要小心——如果子进程已经产生了副作用比如改了文件盲目重试可能造成重复修改所以openrig一般只在“启动阶段失败”时重试运行中途失败不自动重试。4. 实操过程从零把 openrig 跑起来4.1 环境准备Node.js 版本这道坎第一步永远是 Node.js。别去官网随便下最新版直接认准 LTS。截至我写这篇时的稳定选择是 Node 20 或 22 的 LTS 线。装之前先确认node -v npm -v如果版本低于 18或者落在 23、24 这种奇数/未正式发布的线上先换掉。热词里那个node.js v24.21.0 is not yet released的报错就是因为有人照着过时教程写了个不存在的版本号。用nvm管理版本最省心nvm install 22 nvm use 22 nvm alias default 22Windows 用户如果不想折腾 nvm直接去 Node.js 官网下载 LTS 的.msi安装包安装时勾选“Add to PATH”。装完重开一个终端再验证别在旧终端里测环境变量不刷新会误判。4.2 安装 openrig 与初始化配置假设openrig已经发布到 npm标准安装方式是npm install -g openrig openrig --version如果不想全局装用npx openrig也能跑。初始化一个项目mkdir my-rig cd my-rig openrig initinit会生成一份带注释的openrig.yaml模板和prompts/目录。我建议先别急着改配置先跑一次openrig doctor。这个诊断命令会检查 Node 版本、配置文件语法、环境变量是否齐全、各 provider 的 CLI 是否在 PATH 里。它输出的报告比你自己一个个试要快得多。4.3 接入本地模型以 LM Studio 为例很多人想用本地推理服务省钱热词里claude code 调用 lmstudio 的本地模型就是这个需求。思路是让openrig的 provider 指向本地端点。LM Studio 默认在http://127.0.0.1:1234/v1提供 OpenAI 兼容接口配置里这样写providers: local: adapter: codex-cli model: local-model endpoint: http://127.0.0.1:1234/v1 env: OPENAI_API_KEY: not-needed OPENAI_BASE_URL: http://127.0.0.1:1234/v1注意两个点。第一本地服务通常不校验 key但很多 CLI 强制要求这个环境变量存在所以随便填个占位值。第二model字段要填 LM Studio 里实际加载的模型标识填错了会报模型不存在。启动本地服务后先用curl探一下curl http://127.0.0.1:1234/v1/models能列出模型列表说明端点通了再去跑openrig。4.4 在 VS Code 里串起来openrig本身是 CLI 工具但你可以把它接进 VS Code 的任务系统。在.vscode/tasks.json里加一条{ version: 2.0.0, tasks: [ { label: openrig: review, type: shell, command: openrig run review, problemMatcher: [] } ] }这样按CtrlShiftB就能触发。如果你用的是Claude Code for VS Code这类插件注意插件和 CLI 可能读不同的配置源别以为改了openrig.yaml插件就自动生效——它们大概率是两套独立配置需要分别维护。5. 常见问题与排查技巧实录5.1 模型报错从“not supported”到“disabled access”模型相关的报错占了日常问题的一大半。我整理了一张速查表报错关键词根因处理方式model is not supported模型名不在该 CLI 的允许列表换成 adapter 映射表里的逻辑名或查上游文档确认可用名organization has disabled ... access账号/组织策略限制换用个人凭证或改用本地/第三方端点proxy failed while handling endpoint端点地址或协议不匹配核对endpoint是否带/v1协议是 http 还是 httpsmodel not found本地本地服务未加载该模型在 LM Studio 里先加载模型再curl /v1/models验证排查顺序建议是先openrig doctor看静态配置再单独用原生 CLI 跑一次绕开 openrig如果原生也报错那就是上游问题跟 openrig 无关。这个“二分法”能帮你快速定位问题出在哪一层。5.2 YAML 缩进与类型陷阱YAML 最坑的两类问题缩进用了 TabYAML 只认空格以及值被错误推断类型。比如timeout: 120 # 数字OK model: 5.6 # 被解析成浮点数可能出错 endpoint: yes # 被解析成布尔 true规避办法是给容易歧义的值加引号model: 5.6、endpoint: yes。另外openrig加载配置时如果报“schema validation failed”八成是某个必填字段漏了或类型不对报错信息里一般会带字段路径照着改就行。5.3 进程挂起与超时有时候openrig跑着跑着就不动了。常见原因是子进程在等标准输入而父进程没把 stdin 接过去。解决办法是在 spawn 时显式设置stdio: [inherit, inherit, inherit]让三个流都直通终端。另一个原因是网络请求卡住这时候timeout字段就派上用场了设一个合理值比如 120 秒超时后 adapter 会杀掉子进程并报错而不是无限等待。注意超时值别设太短。AI 代理处理大文件或长上下文时单次响应超过 60 秒很常见设成 30 秒会导致大量误杀。我的经验值是本地模型 180 秒、云端模型 120 秒起步。5.4 凭证与登录态的那些坑Codex和Claude Code的登录态存储位置不同前者可能在用户目录下的某个隐藏文件后者可能走系统钥匙串。混用多个账号时最容易出现“A 工具登录了B 工具还是旧凭证”的情况。我的做法是给每个 provider 显式指定独立的凭证环境变量不依赖全局登录态。这样切换账号只需要改环境变量不用去翻隐藏目录。热词里codex无法加载组织设置这类问题很多时候就是凭证指向了错误的组织清掉旧凭证重新登录即可。6. 我踩过的坑和几条实在建议折腾openrig这类编排工具最大的体会是配置的复杂度不会消失只会转移。你省下了记多个 CLI 参数的心力但换来的是要理解 YAML schema 和 adapter 映射。所以别指望它“零学习成本”它的价值在于把复杂度集中到一处、可版本化、可复现。几条具体建议。第一把openrig.yaml纳入 git 管理但密钥走环境变量这样团队协作时配置能共享密钥不泄露。第二给每个 rig 写清楚用途注释过两周你自己都忘了review和refactor的区别。第三升级 Node 或上游 CLI 前先跑doctor很多兼容性问题在启动阶段就能暴露。第四本地模型和云端模型别混在同一个 rig 里它们的超时、重试、输出格式差异太大混用只会让排查变难。这个方向后续还能怎么扩展我比较看好的是把openrig接进 CI让 PR 自动跑一轮 AI review配置就用仓库里那份 YAML保证本地和 CI 行为一致。另外就是多代理协作——一个 rig 负责读代码另一个负责改通过文件系统或消息队列串起来。这些玩法等我把当前这套跑稳了再折腾到时候有新心得再写一篇。