1. 从零认识 openrig它到底解决什么问题第一次看到 openrig 这个名字很多人会以为是某个硬件支架项目毕竟 rig 在英文里有“装配、支架”的意思。但如果你最近在折腾 Claude Code、Codex 这类命令行 AI 编程工具就会明白它出现的背景这些工具各自有独立的配置体系、模型接入方式、代理转发规则切换一次环境要改一堆文件稍不留神就报出cc switch local proxy failed while handling codex endpoint /responses这种让人头大的错误。openrig 要做的就是把这些散落各处的配置统一收拢到一套 YAML 描述里用一份声明式文件管理多个 AI 编程工具的运行环境。我最初接触它是因为手上同时跑着 Claude Code 和 Codex 两套 CLI一个走本地模型一个走远端接口每次换项目都要手动改环境变量、改 base_url、改模型名改完还得重启终端。后来用 openrig 把两套配置写成两个 profile一条命令切换世界清净了。这篇文章我会把 openrig 的定位、YAML 配置结构、npm 安装链路、常见报错排查以及和 Claude Code、Codex 的联动方式全部拆开讲清楚适合刚上手命令行 AI 工具的新手也适合已经被多环境配置折磨过的老手。需要先说明一点openrig 本身不是一个模型也不是一个代理服务它更像是一个“环境编排器”。它读取你写的 YAML把里面定义的模型端点、工具参数、启动命令翻译成对应 CLI 能识别的形式然后拉起进程。理解这个定位很关键因为后面所有的配置逻辑都围绕“声明式描述 运行时注入”展开。提示如果你只是偶尔用一次 Claude Code不涉及多环境切换其实不一定需要 openrig。它的价值在多工具、多模型、多项目并行时才真正体现出来。2. 核心设计思路与方案选型拆解2.1 为什么用 YAML 而不是 JSON 或 TOMLopenrig 选择 YAML 作为配置载体这个决定背后有很实际的考量。JSON 不支持注释而 AI 工具的配置里经常需要标注“这个 key 从哪申请的”“这个模型名对应哪个本地服务”没有注释会非常痛苦。TOML 虽然支持注释但嵌套结构表达起来比较啰嗦尤其是当你要描述多个 profile、每个 profile 下又有多个工具配置时TOML 的层级会显得很笨重。YAML 的缩进式结构天然适合表达“profile → tool → params”这种三层嵌套而且支持锚点和引用可以在多个 profile 之间复用公共配置。比如你有一个公共的本地模型端点多个 profile 都要用就可以用 YAML 锚点定义一次其他地方引用。这个特性在 JSON 里是做不到的TOML 也只能靠重复书写。我实测下来一个典型的多环境配置用 YAML 写大约 40 行换成 JSON 要 70 行以上而且可读性差很多。当然 YAML 也有坑缩进必须用空格不能用 Tab冒号后面必须跟空格这些细节后面会专门讲。2.2 声明式配置与命令式启动的分离openrig 的另一个核心设计是把“配置描述”和“进程启动”分开。你在 YAML 里只描述“我想要什么环境”不关心“怎么启动”。openrig 在运行时读取 YAML根据目标工具的类型生成对应的启动参数和环境变量再 exec 出去。这样做的好处是配置可以版本化管理。你可以把 openrig 的 YAML 提交到 git团队成员拉下来就能得到一致的环境不会出现“我这边能跑你那边报错”的情况。而且当 Claude Code 或 Codex 升级后改变了参数格式你只需要更新 openrig 的适配层不用改自己的 YAML。这种分离也带来一个注意点YAML 里写的模型名、端点地址必须是目标工具真正认识的。openrig 不会帮你做名称映射它只做透传。所以如果你在 YAML 里写了一个 Codex 不支持的模型标识启动后依然会报错只是错误发生在工具层而不是 openrig 层。2.3 与 Claude Code、Codex 的协作边界很多人会混淆 openrig 和 Claude Code、Codex 的关系。简单说Claude Code 和 Codex 是“执行者”它们负责实际调用模型、处理代码openrig 是“调度者”它负责在启动执行者之前把环境准备好。具体协作方式是这样的openrig 读取 YAML 中某个 profile 的配置提取出该工具需要的环境变量比如 API 端点、模型名、超时时间设置到当前进程环境然后调用对应的 CLI 入口。对于 Claude Code它可能还需要处理 VS Code 插件的配置同步对于 Codex它需要处理 endpoint 路径的拼接。这里有个容易踩的坑如果你同时在系统环境变量和 openrig YAML 里定义了同一个 keyopenrig 的优先级更高会覆盖系统变量。这个设计是为了保证 profile 切换的一致性但如果你忘了自己之前在系统里设过什么可能会出现“明明改了 YAML 却没生效”的错觉。排查时先用env | grep看一下当前实际生效的值。3. 环境准备与 npm 安装全流程3.1 Node.js 与 npm 的前置检查openrig 通过 npm 分发所以第一步是确认 Node.js 和 npm 可用。打开终端执行node -v npm -v如果这两条命令报错说明 Node.js 没装好或者 PATH 没配。Windows 上最常见的问题是 PowerShell 执行策略限制报错信息长这样npm : 无法加载文件 C:\Program Files\nodejs\npm.ps1因为在此系统上禁止运行脚本这不是 npm 坏了是 PowerShell 默认禁止运行 .ps1 脚本。解决办法是以管理员身份打开 PowerShell执行Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned然后输入 Y 确认。这个设置只影响当前用户不会降低系统整体安全性。改完之后重新打开终端npm 就能正常跑了。macOS 和 Linux 用户一般不会遇到这个问题但如果node -v提示 command not found检查一下 Node.js 是否通过 nvm 安装但没激活执行nvm use --lts即可。3.2 npm 镜像源配置与安装 openrig国内网络环境下npm 默认源拉包经常超时。建议先切到国内镜像npm config set registry https://registry.npmmirror.com设置完可以用npm config get registry确认。然后安装 openrignpm install -g openrig-g表示全局安装这样在任何目录都能调用 openrig 命令。安装完成后执行openrig --version验证。如果提示命令找不到说明 npm 的全局 bin 目录不在 PATH 里。用npm config get prefix查看全局目录然后把这个目录下的 bin 子目录加到 PATH。Windows 上全局目录通常是C:\Users\你的用户名\AppData\Roaming\npm把这个路径加到系统环境变量 Path 里重启终端即可。这个 PATH 配置问题在热词里出现频率很高本质上是 npm 全局包安装后命令不可见的通用原因。3.3 卸载与版本回退如果装完发现版本不对或者想重装先卸载npm uninstall -g openrig然后重新安装指定版本npm install -g openrig1.2.0版本号根据实际需要替换。有时候卸载后全局 bin 目录会残留软链接导致新版本装不上这时候手动删掉残留文件再装。我遇到过几次npm warn eresolve overriding peer dependency的警告这个警告本身不影响安装但如果伴随安装失败可以加--legacy-peer-deps参数绕过依赖冲突检查。注意不要用 sudo 安装全局 npm 包除非你清楚后果。sudo 安装会导致后续非 sudo 操作没有权限反而制造更多问题。正确做法是配置 npm 的 prefix 到用户目录。4. openrig 的 YAML 配置结构详解4.1 顶层结构与 profile 定义openrig 的配置文件默认叫openrig.yaml放在项目根目录或用户主目录。一个最小可用的结构如下version: 1 profiles: local-claude: tool: claude-code model: local-model endpoint: http://127.0.0.1:1234/v1 params: timeout: 120 remote-codex: tool: codex model: gpt-4-codex endpoint: https://api.example.com/v1 params: timeout: 60version是配置格式版本目前用 1 即可。profiles下面每个 key 是一个 profile 名你可以随便起比如local-claude、work-codex。每个 profile 必须包含tool字段告诉 openrig 这是给哪个工具用的目前支持claude-code和codex两个值。model和endpoint是最核心的两个字段。model是模型标识endpoint是 API 基础地址。注意 endpoint 要写到/v1这一层不要写到具体的/chat/completions因为不同工具的路径拼接规则不一样openrig 会帮你补全。4.2 参数覆盖与优先级规则params下面可以放任意键值对这些会作为环境变量或启动参数注入。优先级从高到低是命令行参数 profile 的 params 全局 defaults 系统环境变量。全局 defaults 可以这样定义defaults: timeout: 90 retry: 2 profiles: local-claude: tool: claude-code model: local-model endpoint: http://127.0.0.1:1234/v1 params: timeout: 180这个例子里local-claude的 timeout 是 180覆盖了 defaults 的 90retry 没有在 profile 里定义所以继承 defaults 的 2。这种层级覆盖机制让你可以把公共配置抽到 defaults只在 profile 里写差异部分。需要留意的是params 的 key 命名要符合目标工具的要求。比如 Claude Code 认的是ANTHROPIC_BASE_URL这类环境变量名而 openrig 的 params 用的是简化的endpoint中间有一层映射。如果你写的 key 不在映射表里openrig 会原样透传可能导致工具不识别。建议先查 openrig 文档里的映射表或者用openrig inspect profile命令查看实际生成的环境变量。4.3 多环境切换与锚点复用当你有多个 profile 共享部分配置时YAML 锚点能大幅减少重复common: common endpoint: http://127.0.0.1:1234/v1 params: timeout: 120 profiles: claude-local: : *common tool: claude-code model: local-model codex-local: : *common tool: codex model: local-codexcommon定义锚点*common引用锚点:表示合并。这样两个 profile 共享同一套 endpoint 和 timeout只在 tool 和 model 上有差异。改端点时只改一处两个 profile 同时生效。这个特性在多工具场景下特别有用。我自己的配置里有一个local-base锚点被四个 profile 引用切换本地模型端口时只改一行。不过要注意锚点合并是浅合并如果 params 里嵌套了多层内层不会自动合并需要手动处理。5. 实操从配置到启动的完整链路5.1 编写第一个可运行的 profile假设你本地跑了一个兼容 OpenAI 接口的模型服务监听在 1234 端口。先创建openrig.yamlversion: 1 profiles: my-claude: tool: claude-code model: qwen2.5-coder endpoint: http://127.0.0.1:1234/v1 params: timeout: 180 max_tokens: 8192保存后执行openrig run my-claudeopenrig 会读取配置设置环境变量然后启动 Claude Code。如果一切正常你会看到 Claude Code 的交互界面并且它使用的是你指定的本地模型。这里有个细节model字段的值必须是你的本地服务真正支持的模型名。如果你写了一个服务端不认识的模型名请求会返回 404 或 model not found。排查时先用 curl 直接测一下curl http://127.0.0.1:1234/v1/models看看返回的模型列表里有没有你写的那个名字。5.2 验证配置是否生效启动后怎么确认 openrig 的配置真的生效了有两个方法。第一在 Claude Code 里执行一个简单请求观察它是否连到了你指定的端点。第二用 openrig 的 inspect 命令openrig inspect my-claude这个命令会打印出该 profile 最终生成的环境变量和启动参数不实际启动进程。你可以对照检查 endpoint、model、timeout 是否符合预期。如果发现某个值不对顺着优先级规则往上找看是哪一层覆盖了。我习惯在改完配置后先 inspect 一遍再 run这样能提前发现拼写错误或层级问题省去启动后再排查的时间。特别是 endpoint 末尾多了或少了一个斜杠这种问题 inspect 时一眼就能看出来。5.3 与 Codex 的联动配置Codex 的配置和 Claude Code 略有不同主要是 endpoint 路径的处理。Codex 默认会在 endpoint 后面拼接/responses所以你的 endpoint 只需要写到/v1profiles: my-codex: tool: codex model: gpt-4-codex endpoint: https://api.example.com/v1 params: timeout: 60启动openrig run my-codex如果你遇到cc switch local proxy failed while handling codex endpoint /responses这类错误通常是因为 endpoint 配置重复拼接了路径或者代理层没有正确转发/responses请求。检查你的 endpoint 是否多写了/responsesopenrig 会自动补你写了就变成双份。另一个常见问题是 Codex 无法加载组织设置这多半是认证信息没传对。openrig 的 params 里可以放认证相关的 key但具体 key 名要参考 Codex 的文档。我一般把认证信息放在系统环境变量里openrig 只负责端点切换这样职责更清晰。6. 常见报错与排查技巧实录6.1 npm 相关报错速查报错信息原因解决方法npm.ps1 因为在此系统上禁止运行脚本PowerShell 执行策略限制设置 RemoteSigned 策略npm warn eresolve overriding peer dependency依赖版本冲突加--legacy-peer-deps或忽略command not found: openrig全局 bin 不在 PATH配置 npm prefix 到 PATH安装超时默认源网络问题切换国内镜像源PowerShell 策略问题在 Windows 上极其常见几乎每个第一次用 npm 的人都会遇到。除了改执行策略也可以改用 CMD 或 Git Bash 来执行 npm 命令绕开 PowerShell 的限制。但长期看还是改策略更省事。6.2 配置加载失败的排查顺序当 openrig 报配置错误时按这个顺序排查检查 YAML 缩进确认没有用 Tab。YAML 对缩进极其敏感一个 Tab 就能让整个文件解析失败。检查冒号后面是否有空格。model:xxx是错的必须model: xxx。检查 profile 名是否和 run 命令里的一致大小写敏感。用openrig validate命令做语法校验它会指出具体哪一行有问题。我踩过最坑的一次是复制粘贴配置时某一行末尾多了个不可见字符YAML 解析器报错但行号指向下一行找了半天才发现。后来养成习惯改完配置先跑 validate再 run。6.3 模型连接失败的定位方法配置语法没问题但启动后连不上模型按这个思路定位先确认本地模型服务是否在跑用 curl 测/v1/models接口。如果 curl 通但 openrig 不通说明是环境变量注入的问题用 inspect 看实际生成的 endpoint。如果 inspect 显示的 endpoint 正确但依然连不上检查是否有系统级代理干扰某些代理会拦截本地回环地址的请求。还有一种情况是模型名不匹配。有些本地服务对模型名大小写敏感Qwen2.5-Coder和qwen2.5-coder可能被当成两个不同的模型。统一用小写通常更安全。提示排查连接问题时把 timeout 临时调大比如 300 秒排除是超时导致的假失败。确认能连上后再调回正常值。7. 多工具并行与进阶用法7.1 同时管理 Claude Code 和 Codexopenrig 的真正威力在于同时管理多个工具。你可以定义一组 profile覆盖不同工具和不同模型的组合profiles: claude-local: tool: claude-code model: local-coder endpoint: http://127.0.0.1:1234/v1 claude-remote: tool: claude-code model: remote-model endpoint: https://api.example.com/v1 codex-local: tool: codex model: local-codex endpoint: http://127.0.0.1:1234/v1 codex-remote: tool: codex model: remote-codex endpoint: https://api.example.com/v1切换时只需openrig run claude-local或openrig run codex-remote。这种模式下你可以在同一个终端窗口里快速切换不同工具和模型不用手动改任何环境变量。我通常会给每个项目建一个独立的 openrig.yaml项目 A 用本地模型省钱项目 B 用远端模型保证质量互不干扰。openrig 支持通过--config参数指定配置文件路径所以可以在不同目录放不同的配置。7.2 在 VS Code 中集成如果你用 VS Code 的 Claude Code 插件openrig 也能配合。思路是让 VS Code 启动 Claude Code 时走 openrig 包装过的命令。在 VS Code 的设置里找到 Claude Code 的可执行文件路径配置改成 openrig 的包装脚本。具体做法是写一个 shell 脚本内容为openrig run claude-local $然后在 VS Code 设置里指向这个脚本。这样插件启动时就会经过 openrig自动加载你的 YAML 配置。Windows 上写 .bat 脚本macOS 和 Linux 写 .sh 脚本。这个集成方式的好处是插件和命令行共享同一套配置不会出现“命令行能跑插件不能跑”的割裂。缺点是每次改配置要重启 VS Code 才能生效因为插件启动时只读一次配置。7.3 配置的版本管理与团队共享openrig.yaml 是纯文本天然适合 git 管理。但要注意配置文件里可能包含认证信息不能直接提交到公开仓库。推荐做法是把敏感信息抽到环境变量YAML 里只写引用profiles: remote: tool: codex model: remote-model endpoint: ${CODEX_ENDPOINT} params: api_key: ${CODEX_API_KEY}openrig 支持${VAR}语法读取环境变量。团队成员各自在本地设置环境变量YAML 文件可以安全共享。这样既保证了配置一致性又不会泄露密钥。我自己的做法是提交一个openrig.example.yaml作为模板实际的openrig.yaml加到 .gitignore。新成员克隆仓库后复制模板填入自己的环境变量即可。这个模式在团队协作里非常实用避免了“配置靠口口相传”的混乱。8. 我踩过的坑与实操心得说几个文档里不会写、但实际用起来一定会遇到的细节。第一个是 YAML 的布尔值陷阱。YAML 里yes、no、on、off会被解析成布尔值如果你某个参数值恰好是这些词会被意外转换。比如模型名如果叫on就会被解析成 true。解决办法是给这类值加引号写成on。第二个是环境变量注入的时机。openrig 设置的环境变量只在它启动的子进程里有效不会影响当前 shell。所以你不能先openrig run再在同一个终端里手动执行 Claude Code 命令那样拿不到 openrig 的环境。要么用 openrig 启动要么用openrig env profile导出环境变量再 source。第三个是超时设置的经验值。本地模型首次加载比较慢timeout 建议设 180 秒以上远端 API 一般 60 秒够用。如果经常遇到超时先确认是模型加载慢还是网络慢前者调大 timeout后者检查网络链路。第四个是配置文件的查找顺序。openrig 默认从当前目录往上找 openrig.yaml找到第一个就用。如果你在子目录里执行命令可能加载的是父目录的配置。用openrig which可以查看当前实际加载的是哪个文件避免改错文件。最后分享一个小技巧给常用的 profile 起短名字比如cl代表 claude-localcr代表 codex-remote。每天敲几十遍的命令短一个字符都是效率提升。openrig 支持 profile 名别名在配置里加aliases: [cl]即可。这套配置我用了大半年从最初的手忙脚乱到现在一条命令切换最大的体会是工具的价值不在于功能多而在于把重复劳动压缩到最少。openrig 做的就是这件事把多环境配置的复杂度收进一个 YAML让开发者专注在真正重要的事情上。