1. 从标题说起：openrig 到底想解决什么问题
第一次看到openrig这个名字，我下意识把它拆成了两半：open和rig。rig在工程语境里通常指“装配、搭台子、把一堆零件拼成能跑的系统”，比如我们常说的 test rig、rig up。所以openrig给我的第一直觉，就是一套开源的、用来把 AI 编码工具“装配”起来的脚手架或者配置框架。结合热搜词里高频出现的 Claude Code、Codex、YAML、Node.js，这个判断基本能坐实——它大概率是一个围绕命令行 AI 编码助手做统一配置、统一接入、统一管理的开源项目。
为什么我这么在意“统一”这两个字？因为只要你同时用过 Claude Code 和 Codex，就会明白一个非常现实的痛点：这两个工具各自有各自的配置文件、各自的模型接入方式、各自的认证逻辑。Claude Code 走的是它自己的一套订阅和本地配置，Codex 又是另一套 CLI 和 endpoint 体系。你想让它们共用一套模型供应商、共用一套代理规则、共用一套项目级配置，几乎得手动维护两三份互不相干的文件。openrig想干的，就是把这堆散落的配置收拢到一个 YAML 里，用 Node.js 作为运行时，把不同工具的接入层抽象出来。
这篇文章我打算按一个真实从业者的视角，把openrig这类项目背后的核心逻辑、YAML 配置怎么写、Node.js 环境怎么搭、Claude Code 和 Codex 怎么接进来、以及踩过的坑，全部摊开讲一遍。不管你是刚听说 Claude Code 想上手的新人，还是已经在用 Codex CLI 但被配置折磨过的老手，都能从里面抄到能直接用的东西。我不会只讲概念，重点放在“为什么这么设计”和“具体怎么落地”上，因为这类工具的价值全在细节里。
先给一个整体判断：openrig这类项目的核心价值不在于它自己实现了多牛的模型调用，而在于它把“配置”这件事从各个工具的私有格式里解放出来，变成一个可版本管理、可复用、可切换的中间层。你项目根目录放一个 YAML，团队里所有人拉下来就能用同一套模型、同一套规则，这才是它真正解决的问题。
2. 核心设计思路拆解：为什么要用 YAML + Node.js 这套组合
2.1 配置层与执行层分离，是这类工具的第一性原则
我见过太多人把 AI 编码工具的配置直接写死在 shell 的 alias 里，或者散落在~/.zshrc、~/.bash_profile里。这种做法的短期成本极低，但一旦你要换模型、换供应商、或者在不同项目里用不同配置，就会立刻崩溃。openrig这类项目的第一性原则，就是把配置层和执行层彻底分开。
配置层负责描述“我要用什么模型、走哪个 endpoint、带哪些参数、哪些项目用哪套规则”，执行层负责“把这些配置翻译成 Claude Code 或 Codex 能听懂的命令行参数和环境变量”。YAML 天然适合做配置层，因为它支持嵌套、支持注释、可读性好，而且几乎所有语言都能解析。Node.js 天然适合做执行层，因为 Claude Code 和 Codex 的 CLI 本身就是 Node 生态里的东西，用同一套运行时去调度它们，能省掉大量跨语言的胶水代码。
这个分离带来的直接好处是：你的配置可以进 Git，可以 code review，可以按环境（开发、测试、生产）分文件。团队成员不需要知道底层命令怎么拼，只要改 YAML 就行。这一点在多人协作里价值巨大，因为“配置即文档”比任何口头交接都可靠。
2.2 为什么是 YAML，而不是 JSON 或 TOML
有人会问，JSON 也能做配置，为什么非得 YAML？我的实测经验是，JSON 不支持注释这一点在配置场景里是致命的。你写一个模型接入配置，往往需要标注“这个 endpoint 是给内网用的”“这个 key 从环境变量读”，JSON 里你只能另开一个字段叫_comment，非常别扭。TOML 虽然支持注释，但嵌套结构一深就变得难读，尤其是数组里套对象再套数组的时候。
YAML 的优势在于它对“层级”的表达非常自然。比如你要描述多个模型供应商，每个供应商下面有多个模型，每个模型又有自己的参数，YAML 用缩进就能表达清楚，不需要一堆括号。而且 YAML 支持锚点和引用，你可以定义一个基础配置模板，其他配置继承它，这在多环境场景里能省掉大量重复。热搜词里有人问“yolov10 yaml 文件怎么创建”“rstudio 的 yaml 在哪里”，其实反映的是同一个需求：大家越来越习惯用 YAML 做统一配置入口，openrig选 YAML 是顺应这个趋势的。
不过 YAML 也有坑，最大的坑就是缩进。它用空格缩进表示层级，Tab 和空格混用会直接报错，而且报错信息往往很模糊。我在实际项目里踩过好几次，最后养成的习惯是：编辑器统一设置成“Tab 转 2 空格”，并且提交前用yamllint过一遍。这个习惯能帮你省掉大量排查时间。
2.3 Node.js 作为运行时，是顺理成章还是被迫选择
Claude Code 和 Codex 的 CLI 都是基于 Node.js 分发的，这意味着你机器上本来就得有 Node.js 环境。openrig用 Node.js 做运行时，等于复用了这个已有依赖，不需要用户再装 Python 或 Go。这是很务实的工程决策。
但 Node.js 版本管理本身是个大坑。热搜词里有一条特别典型：“error installing 24.21.0: node.js v24.21.0 is not yet released or is not available”。这说明很多人在装 Node.js 的时候，直接指定了一个还不存在的版本号，或者用了某个镜像源但镜像没同步。我的建议是，永远优先用 LTS 版本，不要追最新的奇数版本。截至我写这篇内容的时候，Node.js 的 LTS 线是 20.x 和 22.x，这两个版本对 Claude Code 和 Codex 的兼容性最稳。
安装方式上，我不推荐直接用系统包管理器（比如apt install nodejs），因为版本往往太旧。更稳的做法是用nvm或者fnm这类版本管理器，它们能让你在同一台机器上切换多个 Node 版本，而且安装过程不污染系统目录。下面这段是我常用的fnm安装流程，Ubuntu 和 macOS 都适用：
# 安装 fnm（以官方脚本为例，具体以官网最新说明为准） curl -fsSL https://fnm.vercel.app/install | bash # 重新加载 shell 配置 source ~/.bashrc # 安装并切换到 Node.js 22 LTS fnm install 22 fnm use 22 fnm default 22 # 验证 node -v npm -v装完之后node -v应该输出v22.x.x。如果输出的是v24.x.x而你并没有主动装过，那大概率是系统里还有另一个 Node 在 PATH 里抢先了，用which node查一下路径就能定位。
3. 核心细节解析：openrig 的配置结构与关键字段
3.1 一份典型的 openrig YAML 长什么样
因为openrig是一个开源项目，具体字段名可能随版本变化，但这类工具的配置结构有很强的共性。我按最常见的实践，给出一份结构完整、可以直接参考改造的 YAML。你在实际使用时，以项目官方文档的字段名为准，这里重点讲的是“每个字段为什么存在”。
# openrig.yaml version: 1 # 全局默认设置，所有工具共享 defaults: provider: deepseek timeout: 120 retry: 2 # 模型供应商定义 providers: deepseek: base_url: "https://api.deepseek.com/v1" api_key_env: "DEEPSEEK_API_KEY" models: - name: "deepseek-chat" context_window: 64000 - name: "deepseek-coder" context_window: 64000 local: base_url: "http://127.0.0.1:1234/v1" api_key_env: "LOCAL_API_KEY" models: - name: "local-model" context_window: 32000 # 工具级配置，分别对应 Claude Code 和 Codex tools: claude-code: provider: deepseek model: "deepseek-chat" env: ANTHROPIC_BASE_URL: "${DEEPSEEK_BASE_URL}" ANTHROPIC_API_KEY: "${DEEPSEEK_API_KEY}" codex: provider: deepseek model: "deepseek-coder" env: OPENAI_BASE_URL: "${DEEPSEEK_BASE_URL}" OPENAI_API_KEY: "${DEEPSEEK_API_KEY}" # 项目级覆盖 projects: my-web-app: tools: codex: model: "deepseek-chat"这份配置里，providers是核心。它把“供应商”抽象成一个独立实体，每个供应商有自己的base_url、api_key_env和模型列表。api_key_env这个设计很关键——它不把密钥明文写进 YAML，而是指向一个环境变量名。这样你的 YAML 可以安全地提交到仓库，密钥通过环境变量注入。这是配置管理的基本功，但很多人图省事直接把 key 写进文件，一旦仓库权限没管好就是事故。
tools段是openrig真正发挥价值的地方。它把 Claude Code 和 Codex 各自需要的环境变量映射出来。比如 Claude Code 认ANTHROPIC_BASE_URL和ANTHROPIC_API_KEY，Codex 认OPENAI_BASE_URL和OPENAI_API_KEY，openrig负责在启动对应工具时把这些变量设好。你不需要记这些变量名，改 YAML 就行。
3.2 环境变量注入：为什么不能把密钥写死在配置里
我单独把这一点拎出来讲，是因为它太重要了。热搜词里有一堆关于“第三方 API 使用技巧”的搜索，说明很多人确实在接第三方模型。接第三方模型时，密钥管理是第一个要过的关。
把密钥写进 YAML 的直接风险是：你一旦git push，密钥就进了版本历史，即使后面删掉，历史里依然能翻出来。正确做法是 YAML 里只写环境变量名，真实值放在 shell 的 profile 文件或者.env文件里，并且把.env加进.gitignore。下面是我常用的.env结构：
# .env（不要提交到仓库） DEEPSEEK_API_KEY=sk-xxxxxxxxxxxxxxxx DEEPSEEK_BASE_URL=https://api.deepseek.com/v1 LOCAL_API_KEY=not-needed-for-local然后在 shell 里加载：
# 在 ~/.bashrc 或 ~/.zshrc 里 set -a source ~/projects/my-app/.env set +aset -a的作用是让source进来的变量自动导出为环境变量，set +a恢复。这个技巧比手动export每一行要省事得多，而且不容易漏。
注意：
.env文件一定要放进.gitignore，并且养成提交前git status扫一眼的习惯。我见过不止一次因为.env被误提交而紧急轮换密钥的情况。
3.3 模型切换的粒度：全局、工具级、项目级三层覆盖
openrig这类工具设计得好的地方，在于它支持多层级的配置覆盖。全局defaults定义默认行为，tools定义每个工具的默认，projects定义具体项目的覆盖。这个三层结构解决了一个很实际的问题：你可能平时用便宜的模型做日常问答，但在某个对代码质量要求高的项目里想换成更强的模型。
覆盖逻辑通常是“就近优先”：项目级 > 工具级 > 全局默认。理解这个优先级很重要，因为当你发现配置没生效时，第一件事就是检查是不是被更高优先级的层覆盖了。我建议在 YAML 里给每个覆盖项加注释，写清楚为什么这个项目要特殊处理，否则半年后你自己都忘了。
4. 实操过程：从零把 openrig 跑起来
4.1 环境准备：Node.js、包管理器与目录结构
在动手之前，先把环境理清楚。你需要的是：一个 LTS 版本的 Node.js、一个包管理器（npm 或 pnpm）、以及一个干净的配置目录。我强烈建议不要在你的业务项目根目录里直接折腾，先建一个独立的配置仓库，跑通之后再往业务项目里引。
# 建一个独立的配置目录 mkdir -p ~/openrig-config cd ~/openrig-config # 初始化（如果 openrig 是通过 npm 分发的） npm init -y # 安装 openrig（以实际包名为准，这里演示流程） npm install openrig # 验证安装 npx openrig --version如果npx openrig --version报“command not found”，大概率是 npm 的全局 bin 目录没在 PATH 里。用npm config get prefix看一下前缀路径，然后确认那个路径下的bin目录在 PATH 中。这是 Node.js 新手最常见的坑之一。
4.2 编写第一份可用的 openrig.yaml
环境好了之后，写配置。我建议从最小可用配置开始，先只接一个供应商、一个工具，跑通再加。下面这份是我给新手准备的最小配置：
version: 1 providers: deepseek: base_url: "https://api.deepseek.com/v1" api_key_env: "DEEPSEEK_API_KEY" models: - name: "deepseek-chat" tools: claude-code: provider: deepseek model: "deepseek-chat" env: ANTHROPIC_BASE_URL: "${DEEPSEEK_BASE_URL}" ANTHROPIC_API_KEY: "${DEEPSEEK_API_KEY}"写完先别急着跑，用yamllint检查一遍语法：
# 安装 yamllint（如果还没装） pip install yamllint # 检查 yamllint openrig.yamlyamllint会告诉你缩进有没有问题、有没有重复键、有没有非法字符。这一步能挡掉 80% 的低级错误。我踩过的坑是：YAML 里用了中文全角冒号，肉眼几乎看不出来，但解析直接失败。yamllint能帮你揪出来。
4.3 启动 Claude Code 并验证接入
配置检查通过后，用openrig启动 Claude Code。具体命令以项目文档为准，通常是类似openrig run claude-code或者openrig claude的形式。启动后，Claude Code 会读取openrig注入的环境变量，把请求发到你配置的base_url。
验证是否接入成功，最直接的方法是问一个只有目标模型才知道的问题，或者看请求日志。如果openrig支持--verbose之类的调试开关，打开它，观察实际发出的请求地址。如果地址还是默认的官方地址，说明环境变量没注入成功，回去检查tools.claude-code.env段。
这里有个细节：Claude Code 对ANTHROPIC_BASE_URL的格式比较敏感，末尾带不带/v1可能影响结果。我的经验是，先按供应商文档给的完整地址填，如果报 404，再试着去掉或加上/v1。这个没有统一答案，取决于供应商的网关实现。
4.4 启动 Codex 并处理 endpoint 差异
Codex 的接入和 Claude Code 类似，但环境变量名不同，走的是OPENAI_BASE_URL和OPENAI_API_KEY。热搜词里有一条“cc switch local proxy failed while handling codex endpoint /responses”，这其实反映了一个很典型的问题：Codex 的请求路径和 Claude Code 不一样，Codex 走的是/responses这类 endpoint，而有些代理或网关只实现了/chat/completions，于是转发失败。
遇到这种问题，排查顺序是这样的：先确认你的供应商是否支持 Codex 需要的 endpoint 格式；如果不支持，要么换供应商，要么在中间加一层做协议转换。openrig如果内置了协议适配层，就能屏蔽这个差异；如果没有，你就得自己处理。这也是为什么我在选型时特别看重工具是否支持多协议适配——它决定了你能接多少种后端。
tools: codex: provider: deepseek model: "deepseek-coder" env: OPENAI_BASE_URL: "${DEEPSEEK_BASE_URL}" OPENAI_API_KEY: "${DEEPSEEK_API_KEY}" # 如果供应商不支持 /responses，可能需要指定兼容模式 options: api_mode: "chat_completions"上面这个api_mode是我基于常见实践补的字段，具体名称以openrig文档为准。核心思路是：当默认 endpoint 不通时，显式告诉工具走兼容模式。
5. 常见问题与排查技巧实录
5.1 环境类问题速查表
这类工具报错，八成是环境问题。我把最常见的几类整理成表，方便你对照排查。
| 报错现象 | 可能原因 | 排查动作 |
|---|---|---|
command not found: node | Node.js 未安装或不在 PATH | which node，检查 nvm/fnm 是否加载 |
node.js v24.21.0 is not yet released | 指定了不存在的版本 | 改用 LTS 版本，如 22.x |
openrig: command not found | 包未安装或全局 bin 不在 PATH | npm config get prefix，检查 PATH |
| YAML 解析失败 | 缩进用了 Tab、全角符号 | yamllint openrig.yaml |
| 401 Unauthorized | 密钥未注入或错误 | 检查环境变量是否export，echo $DEEPSEEK_API_KEY |
| 404 Not Found | base_url 路径不对 | 尝试加/去/v1，查供应商文档 |
| 请求超时 | 网络或 endpoint 不可达 | curl直接测 base_url |
这张表里的每一条，我都在实际项目里遇到过至少一次。尤其是 401 和 404，占了报错的大头。401 通常是环境变量没生效，注意source .env之后要确认变量真的导出了，用env | grep DEEPSEEK看一眼最稳。404 则多半是路径拼接问题，供应商给的 base_url 和你实际要请求的完整路径之间，可能差一个/v1或者/api。
5.2 配置不生效的三层排查法
当你改了 YAML 但行为没变，按这个顺序查：
- 确认文件被读取：
openrig默认读哪个路径的 YAML？是当前目录还是~/.config/openrig/？用--config显式指定路径，排除读错文件的可能。 - 确认层级覆盖：项目级配置是否覆盖了你的工具级配置？把项目级那段临时注释掉，看行为是否变化。
- 确认环境变量优先级：有些工具的环境变量优先级高于配置文件。如果你 shell 里已经
export了一个旧值，它会盖过 YAML 里的新值。用env | grep -i anthropic检查。
这个三层排查法能解决绝大多数“配置不生效”的问题。我自己的习惯是，每次改配置后先跑一个最小验证命令，确认改动生效了再继续，而不是攒一堆改动一起测。这样出问题时定位范围小得多。
5.3 本地模型接入的额外注意事项
热搜词里有“claude code 调用 lmstudio 的本地模型”，说明不少人想接本地模型。本地模型的好处是数据不出本机、没有调用成本，但坑也不少。
第一，本地模型的 endpoint 通常是http://127.0.0.1:1234/v1这种，注意127.0.0.1和localhost在某些环境下解析行为不同，建议统一用127.0.0.1。第二，本地模型的 context window 往往比云端小，配置里要如实填写，否则工具按大窗口发请求会直接失败。第三，本地模型的响应格式可能和标准接口有细微差异，如果工具报解析错误，先确认本地服务是否开启了兼容模式。
providers: local: base_url: "http://127.0.0.1:1234/v1" api_key_env: "LOCAL_API_KEY" models: - name: "local-model" context_window: 32000 # 本地模型通常不需要真实密钥，但字段不能空提示：本地模型的
api_key很多实现不校验，但工具可能要求该字段非空。随便填一个占位符即可，比如local。
5.4 团队协作时的配置管理心得
一个人用和团队用，配置管理的复杂度完全不是一个量级。团队场景下，我的建议是：
- 把
openrig.yaml提交到仓库，作为团队共享配置。 - 把
.env加进.gitignore，每个人维护自己的密钥。 - 在 README 里写清楚“新人三步走”：装 Node LTS、复制
.env.example为.env填密钥、跑openrig验证。 - 对项目级特殊配置加注释，说明为什么这个项目要用不同模型。
这样新人上手时间能从半天压缩到十分钟。我经历过没有这套规范的团队，每个人机器上的配置都不一样，出了问题根本没法复现，最后只能靠“在我机器上是好的”来搪塞。有了统一配置层之后，这类扯皮基本消失了。
6. 我对这类工具后续演进的一点判断
openrig这类项目的想象空间，其实不在“支持多少个模型”，而在“能不能成为 AI 编码工具的统一入口”。现在 Claude Code、Codex 各占一块，未来还会有更多同类工具出现。如果每次出新工具都要重新学一套配置，那成本太高。一个稳定的中间层，能让用户只学一次配置语法，就能接入所有工具，这个价值会随着工具数量增加而放大。
从技术上看，我觉得接下来值得关注的方向是配置的“可组合性”。比如把供应商配置、工具配置、项目配置拆成独立文件，用引用组合起来，这样团队可以维护一个共享的供应商库，各项目按需引用。YAML 的锚点和引用已经能部分实现这个，但更结构化的方案可能更好用。
另外就是密钥管理的进一步抽象。现在靠环境变量，已经比明文好很多，但团队场景下密钥分发依然是个麻烦事。未来如果能和系统级的密钥管理工具打通，配置里只写一个引用 ID，那就更省心了。
我在实际使用中的体会是：这类工具真正的门槛不在技术，而在习惯。你得先接受“配置应该集中管理”这个理念，才会觉得它有价值。一旦习惯了，再回到手动改 shell alias 的日子，会觉得非常难受。如果你现在还在用零散的 alias 管理 AI 编码工具，我建议你花一个下午把配置收拢到一份 YAML 里，这个投入的回报周期非常短。
