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

1. openrig 到底是个什么东西第一次看到 openrig 这个名字我下意识以为是某个硬件外设或者开源机械臂项目毕竟 rig 这个词在工程圈里通常跟设备、装置挂钩。但翻了一圈社区讨论和仓库结构之后才明白它其实是一个围绕 AI 编程助手做统一接入与配置管理的工具层核心解决的是多个 AI 编码工具各自为政、配置散落一地的问题。说白了现在用 Claude Code、Codex 这类命令行 AI 编程助手的人越来越多但每个人手里往往不止一个工具。今天用 Claude Code 写业务逻辑明天用 Codex 跑重构后天又想接本地模型省钱。问题就来了每个工具的配置文件格式不一样认证方式不一样模型端点不一样切换一次要改一堆东西改错了还得排查半天。openrig 想干的事就是把这些工具的配置抽象成一套统一的 YAML 描述用一个入口管理所有 AI 编码助手的接入参数。它适合谁三类人最需要。第一类是同时使用多个 AI 编程工具的开发者尤其是那些在 Claude Code 和 Codex 之间来回切换的人。第二类是想把 AI 助手接入本地模型或第三方兼容端点的用户比如用 LM Studio 跑本地模型再让 Claude Code 调用。第三类是团队里负责统一开发环境的人需要把 AI 工具的配置标准化后分发给多个成员。如果你只是偶尔用一下某个工具那 openrig 对你来说可能有点重但只要你开始认真把 AI 助手当生产力工具用配置管理这件事迟早会变成刚需。openrig 这个名字本身也透露了设计意图open 强调开放、可扩展rig 在英文里有装配、搭建的意思合起来就是开放式的装配层。它不替代任何 AI 工具而是在工具之上做一层配置编排。这个定位很关键理解了这一点后面所有的设计取舍就都说得通了。2. 为什么需要一层配置编排2.1 多工具并用的真实痛点我先说说自己踩过的坑。最开始用 Claude Code 的时候配置文件放在用户目录下的一个隐藏文件夹里格式是 JSON。后来想试试 Codex发现它的配置又是另一套结构认证信息存在完全不同的位置。再后来想把某个工具指向本地跑的模型又得改端点地址、改模型名称、改认证方式。每次切换都要手动改文件改完还得重启终端有时候改错了连报错都看不懂。这种痛点在社区里非常普遍。你搜一下 cc switch local proxy failed while handling codex endpoint /responses 这类报错会发现大量用户卡在配置切换的环节上。问题的根源不在于工具本身不好用而在于每个工具都假设你是专一的只用一个工具、一套配置。但现实是开发者天然会同时用多个工具因为不同工具在不同任务上各有优势。openrig 的思路是把配置从各个工具里抽出来集中到一份 YAML 文件里描述。这份 YAML 定义了你有哪些工具、每个工具用什么模型、走什么端点、用什么认证方式。然后 openrig 负责把这些抽象配置翻译成各个工具能识别的具体格式写到正确的位置。你只需要维护一份 YAML切换工具或切换模型时改一个字段就行。2.2 为什么选 YAML 而不是 JSON 或 TOML这里有个设计选择值得展开说。openrig 用 YAML 作为配置格式而不是 JSON 或 TOML背后是有考量的。JSON 的问题是写起来太啰嗦不能写注释多行字符串处理起来很难受。AI 工具的配置里经常需要写系统提示词、端点路径、模型参数这些东西用 JSON 写会非常痛苦。TOML 虽然比 JSON 友好但嵌套结构表达力有限遇到复杂的多工具、多模型配置时会显得力不从心。YAML 的优势在于支持注释这对配置文件来说太重要了你可以直接在配置里标注这行是给本地模型用的这个端点需要特殊认证支持锚点和引用多个工具共享同一套模型配置时不用重复写缩进表达层级读起来直观。当然 YAML 也有坑缩进敏感、冒号后面必须空格、特殊字符要转义这些后面会专门讲。从社区热搜词也能看出来YAML 相关的搜索量很高比如 yolov10 yaml文件怎么创建rstudio的yaml在哪里yaml安装yaml文件说明大量用户对 YAML 的写法本身就不太熟。openrig 选择 YAML 作为配置格式实际上也把 YAML 的学习成本转嫁给了用户所以这篇文章会花不少篇幅讲 YAML 配置的实操细节。2.3 与直接改工具配置的对比有人可能会问我直接改每个工具的配置文件不就行了为什么要多一层 openrig直接改的问题在于不可维护。假设你有三个工具、每个工具有两套配置一套云端、一套本地那就是六份配置散落在六个地方。改一个模型名称要改六处漏一处就出问题。而且每个工具的配置格式还不一样你得记住六种写法。用 openrig 之后配置收敛成一份 YAML里面用不同的 profile 区分场景。切换时执行一条命令openrig 自动把对应 profile 展开成各个工具需要的格式并写入。配置的单一事实来源建立起来了维护成本从 O(n) 降到 O(1)。代价是引入了一个额外的工具层需要先安装 openrig、学习它的 YAML 语法、理解它的工作方式。对于只用单一工具的用户这层抽象是多余的。但对于多工具用户这层抽象带来的收益远大于成本。3. 环境准备与依赖安装3.1 Node.js 的正确安装方式openrig 本身是基于 Node.js 生态的工具所以第一步是把 Node.js 装好。这里有个高频坑很多人直接去 Node.js 官网下载最新版结果装了个奇数版本比如 v24.x 的某些非 LTS 版本然后遇到 error installing 24.21.0: node.js v24.21.0 is not yet released or is not available 这类报错。正确的做法是装 LTS 版本。LTS 是长期支持版稳定性和兼容性都有保障。截至我写这篇文章时Node.js 的 LTS 版本在 v20 或 v22 系列具体以官网标注为准。下载地址就是 Node.js 官网选那个标着 LTS 的按钮不要选 Current。Windows 用户下载 .msi 安装包一路下一步就行安装程序会自动把 node 和 npm 加到 PATH 里。macOS 用户可以用官网的 .pkg 安装包也可以用 Homebrew 装。Ubuntu 用户建议用 NodeSource 的源来装比系统自带的版本新命令大概是先添加源再 apt install具体命令官网有。装完之后验证一下node -v npm -v两条命令都能输出版本号说明装好了。如果 node 能输出但 npm 报错多半是 PATH 没配好重启终端或者手动检查环境变量。注意不要用 sudo 去装全局 npm 包容易把权限搞乱。如果遇到权限问题正确做法是配置 npm 的全局目录到用户目录下而不是加 sudo。3.2 安装 openrig 本体Node.js 就绪之后openrig 的安装通常通过 npm 全局安装npm install -g openrig装完验证openrig --version如果提示命令找不到检查 npm 全局 bin 目录是否在 PATH 里。用npm config get prefix可以看到全局目录位置把这个位置下的 bin 目录加到 PATH 即可。有些用户会问能不能用 pnpm 或 yarn 装。理论上可以但全局命令行工具的兼容性还是 npm 最稳建议就用 npm。另外如果你在国内网络环境下 npm 安装慢可以配置镜像源这个属于常规操作不展开。3.3 各 AI 工具的安装前置openrig 是配置管理层它本身不包含 Claude Code 或 Codex所以你得先把这些工具装好。Claude Code 的安装方式根据平台不同有差异Windows 用户注意它早期对 Windows 的支持是通过 WSL 或者特定终端实现的后来才有更原生的支持。Codex 的安装类似也有自己的安装包和 CLI 版本。这里要强调一个顺序问题先装好各个 AI 工具并确保它们能独立运行再用 openrig 接管配置。如果工具本身都没跑通直接上 openrig 只会让排查变复杂。我见过有人 Claude Code 还没装明白就去配 openrig结果报错都不知道是哪一层的问题。4. openrig 的 YAML 配置详解4.1 配置文件的位置与结构openrig 的配置文件通常放在用户目录下的一个约定位置比如~/.openrig/config.yaml具体路径以官方文档为准。首次运行 openrig 时它可能会引导你生成一份初始配置或者你可以手动创建。一份典型的 openrig 配置大概长这样version: 1 profiles: default: tools: claude-code: model: claude-sonnet endpoint: https://api.example.com auth: ${CLAUDE_API_KEY} codex: model: gpt-5 endpoint: https://api.example.com auth: ${CODEX_API_KEY} local: tools: claude-code: model: local-model endpoint: http://localhost:1234/v1 auth: none这个结构里profiles是核心概念。每个 profile 代表一套完整的工具配置组合。default走云端local走本地模型。切换时只要指定 profile 名称openrig 就会把对应配置展开写入各个工具。${CLAUDE_API_KEY}这种写法是环境变量引用意思是认证信息不写在配置文件里而是从环境变量读取。这样做的好处是配置文件可以安全地提交到版本控制密钥不会泄露。这是配置管理的基本素养强烈建议所有认证信息都走环境变量。4.2 模型端点的配置要点端点配置是最容易出问题的地方。不同工具的端点格式要求不一样有的要求带/v1有的要求不带有的要求完整路径。openrig 的作用之一就是帮你处理这些差异但你得在 YAML 里写对基础信息。以接入本地模型为例假设你用 LM Studio 在本地跑了一个模型它默认监听http://localhost:1234兼容 OpenAI 的接口格式。那么端点和模型名要这样配claude-code: model: your-local-model-name endpoint: http://localhost:1234/v1 auth: none注意model字段必须和 LM Studio 里加载的模型名称完全一致大小写敏感。很多人报 model not supported 就是因为模型名写错了。另外auth: none表示不需要认证本地模型通常不需要。如果你接的是第三方兼容端点端点地址和模型名要以服务商提供的为准。社区里常见的报错 the gpt-5.6-sol model is not supported when using codex with a... 就是模型名和端点不匹配导致的检查这两个字段基本能解决。4.3 认证信息的处理方式认证信息有三种处理方式按安全性从高到低排列第一种是环境变量引用就是前面说的${VAR_NAME}写法。密钥存在 shell 的环境变量里配置文件里只写引用。这是最推荐的方式。第二种是独立的密钥文件配置文件里写文件路径openrig 读取文件内容作为密钥。这种方式适合密钥比较长或者需要频繁轮换的场景。第三种是直接写在配置文件里。这种方式最方便但最不安全只建议在临时测试时用用完立刻改掉。如果配置文件要进版本控制绝对不能这么写。环境变量的设置方式根据系统不同Linux 和 macOS 在~/.bashrc或~/.zshrc里加export VAR_NAMEvalueWindows 在系统设置里加环境变量或者用set命令临时设置。设置完记得重启终端或者 source 一下配置文件。注意环境变量名不要用特殊字符全大写加下划线是最稳妥的命名方式。另外环境变量在子进程里的继承行为要注意有些终端配置会导致环境变量在特定场景下丢失。4.4 YAML 语法避坑指南YAML 看着简单坑其实不少。我整理了几个高频问题缩进必须用空格不能用 Tab。这是 YAML 最经典的坑混用 Tab 和空格会直接报解析错误。建议编辑器设置成Tab 转空格统一用两个空格缩进。冒号后面必须跟一个空格。model:claude是错的model: claude才对。这个错误很隐蔽因为有些解析器不报错但行为异常。字符串里的特殊字符要处理。如果值里包含冒号、井号、引号这些字符最好用引号包起来。比如endpoint: http://localhost:1234/v1比不加引号更安全。布尔值的坑。YAML 里yes、no、on、off、true、false都会被解析成布尔值。如果你想把no当字符串用必须加引号写成no。模型名里如果恰好有这些词就会出问题。多行字符串用|或。|保留换行把换行折叠成空格。写系统提示词的时候会用到。验证 YAML 语法是否正确可以用在线 YAML 校验工具或者用 Python 的yaml.safe_load快速测一下。养成写完就验证的习惯能省很多排查时间。5. 实操流程与核心环节5.1 从零到跑通的完整步骤我把整个流程拆成可复现的步骤你照着做基本能跑通。第一步确认 Node.js 是 LTS 版本node -v输出 v20 或 v22 系列。不是的话先升级。第二步全局安装 openrignpm install -g openrig然后openrig --version验证。第三步确认你要接管的 AI 工具已经独立安装并能正常运行。比如 Claude Code 能正常对话Codex 能正常执行。第四步创建 openrig 配置文件。如果 openrig 有初始化命令就用初始化命令没有就手动在约定位置创建config.yaml。第五步在配置文件里定义第一个 profile填入工具、模型、端点、认证信息。认证信息用环境变量引用。第六步设置好对应的环境变量重启终端。第七步执行 openrig 的应用命令让它把配置写入各个工具。命令形式通常是openrig apply profile-name或类似。第八步启动 AI 工具验证。如果工具能正常用你配置的模型对话说明整条链路通了。5.2 切换 profile 的实际操作配置好多个 profile 之后切换就是一条命令的事。比如从云端切到本地openrig apply localopenrig 会读取localprofile 的定义把 Claude Code 的配置改成指向本地端点把 Codex 的配置也相应调整。切换完可能需要重启 AI 工具才能生效因为很多工具在启动时读取配置运行中不会热加载。这里有个实操心得切换后先跑一个最简单的测试对话确认模型响应正常再去干正事。我吃过亏切了 profile 直接开始写代码结果发现模型没切过来白写半天。另外建议给常用的 profile 起短名字local、cloud、fast、cheap这种敲命令快。profile 名字里不要有空格和特殊字符。5.3 验证配置是否生效验证分三层。第一层是 openrig 层面看 apply 命令有没有报错有没有提示写入成功。第二层是工具配置文件层面去各个工具的实际配置位置看看内容是不是被改成了预期值。第三层是运行时层面启动工具发一条消息看返回的模型标识和响应特征是否符合预期。第三层最可靠。比如你切到本地模型本地模型的响应速度通常比云端快而且断网也能用。如果切到本地后响应还是很慢或者断网就报错说明配置没真正生效。有些工具会在启动时打印当前使用的模型和端点注意看启动日志。Claude Code 和 Codex 都有类似的启动信息输出这是最直接的验证依据。5.4 与 VS Code 的配合很多人是在 VS Code 里用这些 AI 工具的所以 openrig 的配置也要考虑 VS Code 场景。VS Code 有 Claude Code 的扩展也有 Codex 相关的集成。这些扩展读取配置的方式可能和命令行工具不完全一样。一般来说扩展会读取和命令行工具相同的配置文件所以 openrig 改完配置后VS Code 里的扩展也能生效。但 VS Code 有缓存机制可能需要重启窗口或者重新加载扩展。如果改了配置 VS Code 里没反应先试试CtrlShiftP执行 Reload Window。还有一种情况是扩展有自己的配置入口和命令行工具的配置分离。这种就需要单独处理openrig 可能覆盖不到。遇到这种情况要么手动同步要么看 openrig 是否支持该扩展的配置路径。6. 常见问题与排查技巧6.1 配置不生效的排查顺序配置不生效是最常见的问题排查要按顺序来不要跳步。先确认 openrig apply 命令真的执行成功了没有报错。再看目标工具的配置文件内容是否被修改。如果文件没变说明 openrig 没找到正确的配置路径检查 openrig 的配置里有没有指定工具配置路径或者工具的安装位置是否和 openrig 预期的一致。如果文件变了但工具行为没变说明工具没有重新读取配置。重启工具或者检查工具是否有配置缓存。有些工具会把配置缓存到内存或临时文件里需要清理缓存。如果工具重启后还是没变检查是不是有多个配置文件工具读的是另一个。比如系统级配置和用户级配置同时存在时优先级可能和你预期的不一样。6.2 端点连接失败的典型原因端点连不上报错五花八门但原因就那么几类。地址写错是最常见的。localhost和127.0.0.1在大多数情况下等价但在某些容器或网络环境下不等价。端口号写错也很常见本地模型默认端口各不相同LM Studio 是 1234其他工具可能是 8000、5000 等以实际为准。服务没启动是第二常见原因。本地模型服务需要先启动才能连接很多人配好了配置但忘了启动本地服务。先确认本地服务在跑用 curl 测一下端点是否可达curl http://localhost:1234/v1/models能返回模型列表说明服务正常。认证问题排第三。云端端点需要正确的 API KeyKey 过期、额度用完、权限不足都会导致连接失败。检查环境变量是否设置正确Key 是否有效。网络问题排第四。某些端点需要特定的网络环境才能访问这个不展开遇到的话检查网络连通性即可。6.3 模型名不匹配的处理model not supported 这类报错九成是模型名写错了。模型名必须和端点实际提供的模型标识完全一致包括大小写、连字符、版本号后缀。排查方法是先查端点支持哪些模型。OpenAI 兼容端点通常有/v1/models接口curl 一下就能看到完整列表。把列表里的模型名原样复制到配置里不要凭记忆写。有些端点对模型名做了映射你写的名字和实际调用的模型不是一回事。这种情况要看端点的文档确认映射关系。还有一种情况是模型名对了但端点不支持该模型的某些参数。比如某些模型不支持流式输出或者不支持特定的 temperature 范围。这种要看具体报错信息调整参数。6.4 常见问题速查表问题现象可能原因排查方法openrig 命令找不到npm 全局 bin 不在 PATH检查 npm prefix 并加入 PATHYAML 解析报错缩进用了 Tab 或冒号后缺空格用空格缩进冒号后加空格配置改了不生效工具未重启或读错配置文件重启工具确认配置文件路径端点连接失败地址错、服务未启动、认证失效curl 测端点检查环境变量模型不支持模型名写错或端点不提供该模型查端点模型列表原样复制名称切换 profile 后行为异常部分工具配置未同步检查所有工具的配置文件环境变量读不到终端未重启或变量名写错重启终端echo 验证变量本地模型响应慢模型太大或硬件不足换小模型或检查资源占用6.5 几个容易忽略的细节配置文件编码要用 UTF-8。有些 Windows 编辑器默认用 GBK写中文注释会乱码导致解析失败。路径分隔符在 Windows 和 Linux 上不同。配置文件里如果写路径尽量用正斜杠/Node.js 在 Windows 上也能识别正斜杠这样配置跨平台通用。配置文件备份。改配置之前先备份一份改坏了能快速回滚。我习惯用 git 管理配置文件每次改动都有记录出问题能 diff 出改了什么。版本兼容性。openrig 本身在迭代配置格式可能有版本变化。配置文件顶部的version字段要写对升级 openrig 后注意看有没有配置迁移提示。7. 我个人的一些使用体会用了一段时间 openrig 之后最大的感受是它把配置这件事从每个工具各自为政变成了统一管理。以前切换模型要改三四个文件现在改一个字段或者执行一条命令。这个体验提升是实打实的。但也要客观说openrig 不是银弹。它解决的是配置管理问题不解决工具本身的能力问题。如果你的痛点只是某个工具不好用那 openrig 帮不了你。它的价值在多工具、多环境的场景下才体现得明显。另外我建议新手不要一上来就搞复杂的多 profile 配置。先用一个 profile 把单个工具跑通理解 openrig 的工作方式再逐步加工具、加 profile。配置这东西简单的时候最稳复杂了问题就多。最后分享一个小技巧把常用的切换命令做成 shell 别名比如alias occopenrig apply cloud、alias oclopenrig apply local切换起来更快。这种小优化积累起来日常效率提升很明显。