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_KEYCodex 认OPENAI_BASE_URL和OPENAI_API_KEYopenrig负责在启动对应工具时把这些变量设好。你不需要记这些变量名改 YAML 就行。3.2 环境变量注入为什么不能把密钥写死在配置里我单独把这一点拎出来讲是因为它太重要了。热搜词里有一堆关于“第三方 API 使用技巧”的搜索说明很多人确实在接第三方模型。接第三方模型时密钥管理是第一个要过的关。把密钥写进 YAML 的直接风险是你一旦git push密钥就进了版本历史即使后面删掉历史里依然能翻出来。正确做法是 YAML 里只写环境变量名真实值放在 shell 的 profile 文件或者.env文件里并且把.env加进.gitignore。下面是我常用的.env结构# .env不要提交到仓库 DEEPSEEK_API_KEYsk-xxxxxxxxxxxxxxxx DEEPSEEK_BASE_URLhttps://api.deepseek.com/v1 LOCAL_API_KEYnot-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: nodeNode.js 未安装或不在 PATHwhich node检查 nvm/fnm 是否加载node.js v24.21.0 is not yet released指定了不存在的版本改用 LTS 版本如 22.xopenrig: command not found包未安装或全局 bin 不在 PATHnpm config get prefix检查 PATHYAML 解析失败缩进用了 Tab、全角符号yamllint openrig.yaml401 Unauthorized密钥未注入或错误检查环境变量是否exportecho $DEEPSEEK_API_KEY404 Not Foundbase_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 里这个投入的回报周期非常短。
