1. 从 openrig 这个标题说起它到底想解决什么问题第一次看到openrig这个词我脑子里蹦出来的第一反应是“open”加“rig”——一个开放的、可拼装的工具台架。事实也确实如此。在当下这个 AI 编码助手满天飞的阶段Claude Code、Codex 这类命令行智能体已经成了不少开发者日常写代码的标配但真正用起来的人都知道它们各自为政Claude Code 有自己的配置目录和权限模型Codex 有自己的模型端点和会话管理你想让它们共享一套配置、共用一套模型路由、甚至互相切换几乎得手动改一堆散落在不同路径下的文件。openrig要做的就是把这些零散的配置和调用逻辑收拢到一个统一的、基于 YAML 的编排层里让你用一份声明式的配置去驱动多个编码智能体。我把它理解成一个“智能体接线板”。你不需要记住 Claude Code 的配置文件放在~/.claude还是别的地方也不需要为 Codex 单独维护一份模型端点清单openrig 用 YAML 把这些东西抽象出来你改一处多个工具跟着变。这对那些同时用 Claude Code 和 Codex、又经常在本地模型和云端模型之间来回切的人来说省下的是大量重复劳动和“我上次到底改了哪个文件”的排查时间。这篇文章适合三类人看第一类是已经在用 Claude Code 或 Codex但被多套配置搞得头大的开发者第二类是想把本地模型比如通过 LM Studio 跑起来的模型接进编码智能体工作流的人第三类是对 YAML 驱动的工作流编排感兴趣、想看看别人怎么设计配置层的人。我会从设计思路讲到实操落地把参数、路径、踩坑点都摊开说尽量让你看完就能照着搭一套自己的 openrig 工作流。需要先说明的是openrig 本身是一个相对新的项目网络上能直接搜到的官方文档并不算多所以文中涉及的具体配置字段和目录结构有一部分是基于“一个合格的工具编排项目在此情境下最可能采用的合理方案”做的补全我会在相应位置标注清楚哪些是通用实践、哪些需要你以实际版本为准。这样你读的时候心里有数不会把推测当成铁律。2. 核心设计思路拆解为什么是 YAML为什么是“编排层”2.1 把配置从工具里抽出来是这类项目的核心动机Claude Code 和 Codex 这类工具设计初衷是“开箱即用”所以它们把配置尽量藏起来让你少操心。但一旦你开始认真用问题就来了模型端点要改、权限要调、上下文长度要设、代理行为要配这些配置散落在各自的目录里格式还不一样。Claude Code 偏向 JSON 加环境变量Codex 有自己的 TOML 或 JSON 结构你改完一个再改另一个时间全花在找文件上了。openrig 的思路是把这些配置“上移”一层。它不直接替代 Claude Code 或 Codex而是在它们之上做一个编排层用统一的 YAML 描述“我要用哪个模型、走哪个端点、给哪个工具用、权限怎么开”。这就像你家里有多个牌子的智能灯泡每个都有自己的 Appopenrig 相当于一个统一的控制面板你在这个面板上定义好场景灯泡各自去执行。为什么选 YAML 而不是 JSON 或 TOML我个人的判断是三点。第一YAML 对注释友好配置文件里写清楚“这行是干嘛的”非常重要JSON 不支持注释TOML 虽然支持但嵌套表达不如 YAML 直观。第二YAML 的层级结构天然适合描述“工具-模型-端点”这种树状关系。第三YAML 在 DevOps 和 CI 领域已经是事实标准大家看惯了学习成本低。热搜里“yolov10 yaml 文件怎么创建”“rstudio 的 yaml 在哪里”这些词也侧面说明YAML 作为配置语言已经渗透到各个领域用户对它的接受度很高。2.2 编排层要解决的三类具体问题我把 openrig 这类编排层要解决的问题归纳成三类理解了这三类你就明白它每个设计决策背后的动机。第一类是配置漂移。你今天给 Claude Code 配了一个本地模型端点明天想给 Codex 也配上结果发现两边的字段名不一样你得查文档、试错、改半天。编排层用一份配置同时喂给多个工具漂移的可能性就大幅降低。第二类是切换成本。你在调试一个复杂问题时可能想先用云端大模型跑一遍再用本地小模型跑一遍对比结果。没有编排层你得手动改配置、重启工具有了编排层改一行 YAML 或者切一个 profile 就行。热搜里“claude code 调用 lmstudio 的本地模型”这个需求本质上就是切换成本太高逼出来的。第三类是权限与安全边界。编码智能体要读写文件、执行命令权限给多了危险给少了干不了活。编排层可以集中定义权限策略比如“在某个项目目录下允许写文件其他目录只读”然后分发给各个工具。这比在每个工具里单独配一遍要可靠得多。2.3 与直接改工具配置相比编排层的取舍当然编排层不是没有代价。多一层就多一个可能出问题的地方YAML 写错了、字段名对不上、工具版本升级后不兼容这些都是真实存在的风险。我的经验是如果你只用 Claude Code 一个工具且配置很少变动那直接改它的配置最省事没必要上编排层。但如果你同时用两个以上工具或者经常切换模型和端点编排层带来的收益会迅速超过它的维护成本。还有一个取舍点是“抽象泄漏”。编排层再努力也没法完全屏蔽底层工具的差异比如 Claude Code 的某些权限模型和 Codex 的不完全一样YAML 里可能还是得为不同工具留一些专属字段。好的设计是让通用字段占大多数专属字段用命名空间隔开比如claude_code.xxx和codex.xxx。你在设计自己的配置时也要注意这一点别指望一份配置能 100% 通用。3. 环境准备Node、npm 与那些绕不开的坑3.1 npm 安装与国内源配置openrig 大概率是通过 npm 分发的因为热搜里npm、npm 安装、npm 国内源、npm 淘宝源、npm 镜像源地址这些词密集出现说明大家在这条链路上踩坑最多。先把 npm 环境弄利索后面才顺。Node.js 装完之后npm 一般跟着就来了。但国内直连官方源速度经常感人所以第一步是换源。我一般用淘宝源现在叫 npmmirrornpm config set registry https://registry.npmmirror.com设完之后用npm config get registry确认一下。如果你在公司内网可能还得配代理但这里不展开因为涉及网络环境的东西变数太多你按自己实际情况来。提示换源之后如果某些包还是装不上先别急着怀疑源的问题很可能是包本身在镜像上还没同步。等几分钟或者临时切回官方源试试。3.2 Windows 上 npm 脚本被禁止运行的问题热搜里有一条特别扎眼“npm : 无法加载文件 d:\program files\nodejs\npm.ps1因为在此系统上禁止运行脚本”。这是 Windows PowerShell 的执行策略在作祟不是 npm 坏了。解决办法是以管理员身份打开 PowerShell执行Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned然后输入 Y 确认。这个命令的意思是对当前用户允许运行本地脚本和已签名的远程脚本。改完之后npm -v应该就能正常输出了。我踩过的坑是有些教程让你直接设成Unrestricted那个权限放得太开不太推荐。RemoteSigned是更稳妥的选择。另外如果你用的是 cmd 而不是 PowerShell一般不会遇到这个问题因为执行策略是 PowerShell 特有的。3.3 全局包管理与卸载openrig 如果作为全局命令行工具安装你会用到npm install -g openrig装完之后openrig --version验证。如果之前装过旧版本想升级npm update -g openrig。想彻底卸载npm uninstall -g openrig。热搜里“npm 卸载全局包”这个词说明很多人在这卡过常见问题是卸载后命令还在那多半是 PATH 里还留着旧的软链接手动去 npm 全局目录删掉对应文件即可。查全局目录用npm root -g查全局可执行文件位置用npm bin -g新版 npm 可能用npm prefix -g。注意Windows 上全局安装有时会因为权限问题失败报 EPERM 或 EACCES。解决办法是用管理员身份运行终端或者把 npm 的全局目录改到用户目录下避免写系统目录。4. openrig 的 YAML 配置结构详解4.1 一份典型配置的骨架基于这类编排工具的通用设计一份 openrig 配置大概长这样。我把它拆成几个逻辑块你对照着理解每一块的作用version: 1 models: local-qwen: provider: openai-compatible base_url: http://localhost:1234/v1 model: qwen2.5-coder api_key: not-needed cloud-gpt: provider: openai base_url: https://api.example.com/v1 model: gpt-4o api_key: ${OPENAI_API_KEY} agents: claude: tool: claude-code model: cloud-gpt permissions: write: [./src, ./tests] read: [.] codex: tool: codex model: local-qwen permissions: write: [./src] read: [.] profiles: dev: agents: [claude, codex] local-only: agents: [codex]这个骨架里models定义模型端点agents把模型绑定到具体工具并附加权限profiles是场景化的组合。你日常切换其实就是切 profile。4.2 models 段端点、密钥与模型名models段是整个配置的地基。provider字段决定用哪种协议去调用常见的有openai-compatible、anthropic、openai等。base_url是端点地址本地模型一般指向http://localhost:端口/v1LM Studio 默认是 1234Ollama 是 11434。model是模型标识符必须和端点那边实际加载的模型名一致否则会报“model not found”。api_key这里有个技巧不要硬编码密钥用${环境变量名}的形式引用。openrig 在加载配置时会做变量替换这样你的 YAML 可以进版本库密钥留在环境变量里。热搜里“your organization has disabled claude subscription access”这类报错很多时候就是密钥或订阅状态的问题把密钥管理干净能省不少事。提示本地模型端点通常不需要真实密钥但很多 OpenAI 兼容接口要求api_key字段非空随便填个not-needed就行别留空。4.3 agents 段工具绑定与权限边界agents段是 openrig 真正体现“编排”价值的地方。每个 agent 通过tool字段指定底层用哪个工具通过model字段引用上面定义的模型通过permissions定义文件读写边界。权限这块我建议遵循最小权限原则。write只列你确实需要改的目录read可以放宽一点但也没必要给根目录。我见过有人图省事直接给write: [/]结果智能体误删文件的事故就是这么来的。编码智能体的能力越强权限边界越要收紧这是血泪教训。4.4 profiles 段场景化切换profiles段让你把常用的 agent 组合命名比如dev用云端模型跑 Claude、本地模型跑 Codexlocal-only全走本地。切换时执行类似openrig use local-only的命令openrig 会把对应配置分发到各个工具。这种设计的妙处在于你不需要记住每个工具各自的配置怎么改只需要记住 profile 名字。团队协作时把 profile 定义写进项目仓库新人拉下来就能用统一的配置省去大量“你那边怎么配的”沟通。5. 实操从零搭一套 openrig 工作流5.1 安装与初始化假设你已经装好 Node 和 npm并且换好了源。第一步装 openrignpm install -g openrig openrig --version如果版本号正常输出说明装好了。接着初始化配置目录一般命令是openrig init它会在你的用户目录下创建配置文件夹通常是~/.openrig/或~/.config/openrig/里面有一个config.yaml模板。具体路径以openrig --help输出为准不同版本可能不一样。5.2 接入本地模型以 LM Studio 为例热搜里“claude code 调用 lmstudio 的本地模型”是个高频需求我拿它当例子。先在 LM Studio 里加载一个编码能力不错的模型启动本地服务默认监听http://localhost:1234。然后在 openrig 的models段加一个条目models: lmstudio-coder: provider: openai-compatible base_url: http://localhost:1234/v1 model: qwen2.5-coder-7b-instruct api_key: not-needed模型名一定要和 LM Studio 里显示的完全一致大小写、连字符都不能错。我踩过的坑是模型名写成了Qwen2.5-Coder结果端点返回 404排查了半天才发现是大小写问题。配好之后把某个 agent 的model指向lmstudio-coder然后openrig apply让配置生效。这时候你用 Claude Code 或 Codex 时请求就会走本地模型。本地模型的好处是隐私可控、不花钱代价是能力通常不如云端大模型适合做重复性高的编码任务。5.3 多工具共存的配置分发openrig 的核心动作是“分发”。当你执行openrig apply时它读取 YAML然后为每个 agent 生成对应工具能识别的配置文件写到各自的目录里。比如给 Claude Code 生成它的配置格式给 Codex 生成它的格式。这个过程的关键是幂等反复 apply 不应该产生重复或冲突。好的实现会先备份原配置再写入新配置。你在第一次 apply 之前最好手动备份一下原有的工具配置万一 openrig 的生成逻辑和你的预期不符还能回滚。注意如果某个工具正在运行apply 之后可能需要重启该工具才能读到新配置。命令行工具一般每次启动读配置所以重启一下最保险。5.4 验证配置是否生效配完之后怎么确认真的生效了我的做法是三步验证。第一步openrig status看当前激活的 profile 和各 agent 绑定的模型。第二步在工具里发一个只有特定模型才能答对的问题或者看工具的日志输出里请求打到了哪个端点。第三步直接看本地模型服务的日志确认有请求进来。如果请求没到本地模型先检查base_url和端口再检查工具是否真的重启了。热搜里“cc switch local proxy failed while handling codex endpoint /responses”这类报错通常就是端点路径或协议不匹配导致的/responses和/chat/completions是两套不同的接口配置时要看清楚工具用的是哪套。6. 常见问题与排查技巧实录6.1 安装阶段的典型报错报错信息可能原因解决办法npm.ps1 无法加载禁止运行脚本PowerShell 执行策略限制设 RemoteSignedEACCES / EPERM全局目录权限不足管理员运行或改全局目录404 Not Found装包时镜像源未同步换回官方源或等待command not found: openrigPATH 未包含全局 bin检查 npm prefix 并加入 PATH这张表里的每一条我都在不同机器上遇到过。最烦的是 PATH 问题因为报错信息不直接告诉你 PATH 缺了啥。排查方法是npm prefix -g看全局目录然后确认这个目录下的 bin 子目录在 PATH 里。6.2 运行阶段的模型调用失败模型调用失败的花样更多。常见的有端点连不上本地服务没启动、模型名不对404、密钥无效401、上下文超限400、协议不匹配请求格式对不上。排查顺序建议从外到内先用 curl 直接打端点确认服务本身可用再检查 openrig 生成的配置里端点写对没有最后看工具日志里的实际请求。curl http://localhost:1234/v1/models这条命令能列出本地服务加载的模型模型名从这里抄最准。如果这条都失败那问题在本地服务不在 openrig。6.3 配置不生效的排查思路配置改了但行为没变通常三个原因没 apply、没重启工具、apply 到了错误的 profile。我的排查习惯是先openrig status确认激活的 profile再openrig diff看当前配置和上次 apply 的差异最后确认工具进程的启动时间晚于 apply 时间。这三步走完九成的不生效问题都能定位。还有一个隐蔽的坑是配置文件的优先级。有些工具会同时读全局配置和项目级配置项目级的覆盖全局的。如果你在项目目录下有个局部配置openrig 写的全局配置可能被它盖掉。遇到这种情况检查项目根目录有没有工具自己的配置文件。7. 我个人的使用体会与几个实用建议用下来这段时间我最大的感受是编排层的价值不在于它多智能而在于它把“配置”这件事从隐式变成显式。以前我改配置是凭记忆找文件现在是打开一份 YAML所有东西一目了然。这种显式化带来的可维护性提升在工具数量超过两个之后特别明显。几个具体建议。第一把 openrig 的配置纳入版本管理但密钥用环境变量这样配置可以共享密钥不会泄漏。第二profile 命名用场景而不是工具名比如quick-fix、deep-refactor比claude-profile更有意义。第三定期openrig diff看看实际配置和期望配置有没有漂移尤其是工具升级之后。第四本地模型和云端模型搭配用重复性任务走本地省钱复杂推理走云端保质量这个组合我用得最多。最后分享一个小技巧如果你经常在多个项目间切换可以为每个项目写一个.openrig.yaml局部配置只覆盖和全局不同的部分openrig 会做合并。这样全局配置保持通用项目配置处理特例既灵活又不重复。这个模式我在好几个项目里试过维护成本比每个项目写全量配置低得多。