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 或 TOML
openrig 选择 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 里定义了同一个 key，openrig 的优先级更高，会覆盖系统变量。这个设计是为了保证 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确认。然后安装 openrig：
npm 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 openrig@1.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 的 90；retry 没有在 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-codex&common定义锚点，*common引用锚点，<<:表示合并。这样两个 profile 共享同一套 endpoint 和 timeout，只在 tool 和 model 上有差异。改端点时只改一处，两个 profile 同时生效。
这个特性在多工具场景下特别有用。我自己的配置里有一个local-base锚点，被四个 profile 引用，切换本地模型端口时只改一行。不过要注意，锚点合并是浅合并，如果 params 里嵌套了多层，内层不会自动合并，需要手动处理。
5. 实操：从配置到启动的完整链路
5.1 编写第一个可运行的 profile
假设你本地跑了一个兼容 OpenAI 接口的模型服务，监听在 1234 端口。先创建openrig.yaml：
version: 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 只需要写到/v1：
profiles: 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 是否多写了/responses，openrig 会自动补，你写了就变成双份。
另一个常见问题是 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 和 Codex
openrig 的真正威力在于同时管理多个工具。你可以定义一组 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-local，cr代表 codex-remote。每天敲几十遍的命令，短一个字符都是效率提升。openrig 支持 profile 名别名，在配置里加aliases: [cl]即可。
这套配置我用了大半年，从最初的手忙脚乱到现在一条命令切换，最大的体会是：工具的价值不在于功能多，而在于把重复劳动压缩到最少。openrig 做的就是这件事，把多环境配置的复杂度收进一个 YAML，让开发者专注在真正重要的事情上。
