1. openrig 到底是个什么东西第一次看到 openrig 这个名字我下意识以为是某个硬件机架项目毕竟 rig 在英文里就是“装配、机架”的意思。但翻了一圈社区讨论和热词关联之后才反应过来这玩意儿跟物理设备没半点关系它是一个围绕 AI 编程助手做本地配置编排的工具思路。核心场景说白了就一句话把 Claude Code、Codex 这类命令行 AI 编程工具通过一份 YAML 配置文件统一管理起来让它们在本地跑得顺、切得快、不打架。你可能会问Claude Code 和 Codex 各自都有官方配置方式为什么还要多此一举搞个 openrig我举个自己踩过的例子。我本机同时装了 Claude Code 和 Codex CLI两个工具都要读环境变量、都要配 API 端点、都要指定模型。一开始我是手动改~/.zshrc改完 Claude 的再改 Codex 的结果有一次把两边的 base_url 搞混了Claude Code 去请求了 Codex 的端点报了一堆cc switch local proxy failed while handling codex endpoint /responses的错排查了快一个小时才发现是环境变量串了。openrig 这类工具的价值就在这儿——用一份声明式的 YAML 把每个工具的配置隔离清楚谁用哪套配置一目了然。所以这篇文章适合谁看如果你正在用或者打算用 Claude Code、Codex 这类 AI 编程 CLI本机又装了不止一个或者你需要在不同项目之间切换不同的模型后端比如这个项目用 DeepSeek那个项目用本地 LM Studio那 openrig 这套思路能帮你省掉大量重复劳动。哪怕你最后不用 openrig 本身它背后的 YAML 编排逻辑也值得学。下面我会从设计思路、YAML 结构、Node.js 环境准备、实操步骤到常见报错一层层拆开讲。2. 为什么用 YAML 来做配置编排2.1 声明式配置相比环境变量的优势环境变量这东西简单场景下确实方便export ANTHROPIC_API_KEYxxx一行搞定。但它的致命问题是没有结构。当你需要配置的东西超过五六个环境变量就变成了一锅粥命名靠约定、层级靠前缀、注释没法写、复用基本靠复制粘贴。我见过有人为了区分不同项目的配置把变量名写成PROJ_A_CLAUDE_KEY、PROJ_B_CLAUDE_KEY最后自己都记不清哪个是哪个。YAML 的好处是它天生就是树形结构。一个工具一套配置嵌套在它自己的节点下面互不干扰。而且 YAML 支持注释你可以把“这个 key 是从哪申请的”“这个模型什么时候换的”直接写在配置旁边三个月后回来看还能秒懂。openrig 选择 YAML 而不是 JSON 或 TOML我觉得主要是考虑可读性和注释支持——JSON 不能写注释TOML 虽然能写但嵌套深了之后表格语法很啰嗦YAML 在“人写”和“机器读”之间平衡得最好。2.2 openrig 的配置分层逻辑我理解 openrig 的配置应该分三层。最底层是全局默认比如 Node.js 的路径、通用的超时时间、日志级别。中间层是工具级配置Claude Code 一套、Codex 一套各自指定自己的可执行文件路径、默认模型、API 端点。最上层是项目级覆盖某个具体项目想用不同的模型或者不同的 key就在项目根目录放一个局部配置运行时覆盖全局。这种分层的好处是 DRYDont Repeat Yourself。全局改一次所有项目跟着变某个项目要特殊处理只写差异部分就行。我实测下来这种结构在同时维护五六个 AI 辅助项目的时候特别省心不用每个项目都复制一份完整配置。提示YAML 对缩进极其敏感统一用两个空格绝对不要用 Tab。我见过太多因为 Tab 和空格混用导致解析失败的案例报错信息还特别隐晦往往只告诉你“mapping values are not allowed here”根本不提缩进问题。2.3 与 Claude Code、Codex 原生配置的关系需要说清楚的是openrig 不是要取代 Claude Code 或 Codex 自己的配置机制而是在它们之上做一层编排。Claude Code 本身支持通过环境变量和配置文件来指定模型和端点Codex 也有自己的config.toml之类的配置。openrig 做的事情是读取你的 YAML然后生成或注入对应的环境变量和配置文件再启动目标工具。这就意味着即使 openrig 哪天不维护了你从 YAML 里推导出的环境变量依然能用不会出现“工具一挂全盘瘫痪”的情况。这种设计思路我个人非常认可——编排层应该是可替换的底层能力不应该被绑架。3. 环境准备Node.js 与工具链安装3.1 Node.js 版本选择与安装避坑openrig 本身大概率是个 Node.js 工具从热词里 Node.js 高频出现能推断出来所以第一步是把 Node.js 装好。这里有个坑我必须提前说不要盲目装最新版。热词里有一条error installing 24.21.0: node.js v24.21.0 is not yet released or is not ava这就是典型的版本号写错或者源里还没有这个版本导致的。Node.js 的版本号是偶数大版本为 LTS长期支持奇数大版本是 Current尝鲜生产环境一律选 LTS。截至我写这篇的时候稳妥的选择是 Node.js 20 LTS 或 22 LTS。安装方式看你系统Windows直接去 Node.js 官网下载 LTS 的.msi安装包双击一路下一步。装完在 PowerShell 里敲node -v和npm -v验证。macOS推荐用nvm管理版本brew install nvm之后nvm install 22这样以后切版本不用重装。Ubuntu/Debian用 NodeSource 的源比系统自带的 apt 版本新命令是curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -然后sudo apt install nodejs。装完之后验证一下node -v输出v22.x.x就对了。如果提示command not found八成是 PATH 没配好Windows 重启一下终端Linux/macOS 检查~/.bashrc或~/.zshrc里有没有把 nvm 的初始化脚本加进去。3.2 Claude Code 与 Codex 的安装顺序我建议先装 Claude Code再装 Codex最后装 openrig。原因是 openrig 在初始化的时候可能会去探测这两个工具的可执行文件路径如果它们还没装探测就会失败虽然不影响 openrig 本身安装但初始化配置时会缺默认值。Claude Code 的安装官方推荐用 npm 全局装npm install -g anthropic-ai/claude-code。装完敲claude应该能进交互界面。Codex 类似也是 npm 包具体包名以官方文档为准。这里注意如果你在公司网络环境下npm 可能需要配镜像源npm config set registry https://registry.npmmirror.com能解决大部分下载慢的问题。注意热词里有个your organization has disabled claude subscription access for claude code这是账号层面的限制跟安装无关。遇到这个提示说明你的账号所属组织关闭了 Claude Code 的订阅访问权限需要找管理员开通或者换个人账号。这不是技术问题折腾配置没用。3.3 验证工具链是否就绪装完三个东西之后跑一遍这个检查清单检查项命令预期结果Node.jsnode -vv20.x 或 v22.xnpmnpm -v10.x 以上Claude Codeclaude --version显示版本号Codexcodex --version显示版本号openrigopenrig --version显示版本号任何一项报command not found先别急着往下走把 PATH 问题解决了再说。我见过太多人跳过这步后面配置半天发现是工具根本没装上。4. openrig 的 YAML 配置结构详解4.1 一份完整的配置骨架基于我对这类工具的理解openrig 的配置文件大概长这样放在项目根目录或者用户主目录下的.openrig/config.yamlversion: 1 defaults: node_path: /usr/local/bin/node timeout: 120 log_level: info tools: claude: enabled: true command: claude model: claude-sonnet-4-20250514 env: ANTHROPIC_API_KEY: ${CLAUDE_KEY} ANTHROPIC_BASE_URL: https://api.anthropic.com codex: enabled: true command: codex model: gpt-5.6-sol env: OPENAI_API_KEY: ${CODEX_KEY} OPENAI_BASE_URL: https://api.openai.com/v1 projects: my-web-app: path: ~/projects/my-web-app tool: claude overrides: model: claude-opus-4-20250514这个骨架里defaults是全局默认tools定义每个工具怎么启动、用什么模型、注入什么环境变量projects做项目级覆盖。${CLAUDE_KEY}这种写法是引用系统环境变量这样密钥不会明文写在 YAML 里安全得多。4.2 关键字段逐个拆解version字段是配置格式版本方便以后格式升级时做兼容。defaults.node_path指定 Node.js 可执行文件路径多版本环境下这个很重要避免 openrig 用了系统自带的旧版本 Node。timeout是单次请求超时秒数AI 编程工具经常要等模型返回设太短会频繁超时我一般设 120 秒起步。tools下面的每个工具command是可执行文件名model是默认模型env是要注入的环境变量。这里有个细节不同工具的 API 端点环境变量名不一样Claude Code 用ANTHROPIC_BASE_URLCodex 用OPENAI_BASE_URL写错了工具就读不到会回退到默认端点表现出来就是“配置了但没生效”。projects下面的overrides是精髓所在。比如你全局用 Sonnet但某个复杂项目想用 Opus就在这里覆盖不用改全局配置。4.3 多环境配置的拆分策略实际用起来我建议把配置拆成三份config.base.yaml放通用配置config.local.yaml放本机特有的路径和密钥引用config.project.yaml放项目覆盖。openrig 启动时按顺序合并后面的覆盖前面的。这样做的好处是config.base.yaml可以提交到 Git 仓库团队共享config.local.yaml加到.gitignore里各人管各人的。密钥永远不进版本库这是铁律。提示YAML 合并的时候列表是替换不是追加。也就是说如果 base 里args: [--verbose]local 里args: [--quiet]合并结果是[--quiet]不是两个都有。这个行为跟很多人直觉相反配置列表参数时要特别注意。5. 实操从零跑通 openrig 编排流程5.1 初始化配置文件假设你已经装好了 Node.js、Claude Code、Codex 和 openrig。第一步是生成初始配置。大多数这类工具都有openrig init命令跑一下会在当前目录生成一份带注释的模板 YAML。如果没有 init 命令就手动创建.openrig/config.yaml把上面 4.1 的骨架抄进去改。改的时候重点改三处node_path换成你which node的输出env里的密钥引用换成你实际用的环境变量名projects下面加上你真实项目的路径。改完用openrig validate校验一下语法YAML 写错了这一步就能抓出来。5.2 配置密钥的安全注入方式密钥绝对不能明文写 YAML这是底线。正确做法是在 shell 的配置文件里 export然后 YAML 里用${VAR}引用。比如在~/.zshrc里加export CLAUDE_KEYsk-ant-xxxxxxxx export CODEX_KEYsk-xxxxxxxx然后source ~/.zshrc生效。openrig 启动工具时会把这些变量注入到子进程环境里。这样 YAML 文件可以随便分享密钥始终留在本机 shell 环境里。如果你用密钥管理工具比如 1Password CLI、系统钥匙串也可以在启动 openrig 前用它们的命令把密钥读出来 export进一步降低泄露风险。5.3 启动与切换工具的完整流程配置好之后日常使用流程是这样的cd到你的项目目录跑openrig run claude或openrig run codexopenrig 会读取配置、合并项目覆盖、注入环境变量、启动对应工具工具退出后环境变量自动清理不会污染当前 shell我实测下来这种“用完即走”的模式比手动 export 干净太多。以前我手动 export 之后忘了 unset下一个项目跑的时候用的还是上一个项目的 key排查半天。openrig 这种子进程隔离的方式从根上避免了这个问题。如果你要临时切模型不用改配置文件直接openrig run claude --model claude-opus-4-20250514命令行覆盖就行优先级最高。5.4 验证配置是否真正生效怎么确认 openrig 真的把配置注入了有个简单办法在工具里让它打印当前用的模型和端点。Claude Code 里可以问它“你现在用的是哪个模型”Codex 里类似。如果返回的模型跟你 YAML 里配的一致说明注入成功。另一个办法是看 openrig 的 debug 日志openrig run claude --log-level debug会把合并后的完整配置和环境变量打出来密钥会脱敏一眼就能看出哪层覆盖了哪层。6. 常见报错与排查技巧实录6.1 端点串台导致的 proxy failed热词里那条cc switch local proxy failed while handling codex endpoint /responses我太熟悉了。这个报错的本质是Claude Code 的请求被发到了 Codex 的端点或者反过来。常见原因有三个环境变量名写错、YAML 里工具配置块嵌套错了、shell 里有残留的旧 export。排查顺序先env | grep -i -E anthropic|openai看当前 shell 有没有残留变量有就 unset 掉再看 YAML 里tools.claude.env和tools.codex.env有没有写串最后用openrig run xxx --log-level debug确认注入的变量对不对。6.2 模型不支持报错的处理{detail:the gpt-5.6-sol model is not supported when using codex with a...}这类报错说明你配置的模型名在当前端点不存在或者不被支持。可能是模型名拼错了也可能是你的 API 套餐没有这个模型的权限。解决办法换成端点文档里明确列出的模型名或者降级到通用模型试试。模型名这东西更新很快配置里最好写注释标明“这个模型名是什么时候确认可用的”。6.3 组织权限与订阅限制your organization has disabled claude subscription access for claude code和codex无法加载组织设置这两类都是账号权限问题不是配置问题。前者是组织管理员关了 Claude Code 的访问后者是 Codex 读不到组织配置。这类问题自己折腾配置没用要么找管理员要么换账号。我一般建议个人开发者用个人账号避免组织策略的干扰。6.4 常见问题速查表报错关键词可能原因解决方向command not foundPATH 未配置检查 shell 配置文件重启终端mapping values not allowedYAML 缩进错误统一用两空格禁用 Tabproxy failed / endpoint环境变量串台清理残留 export检查 YAML 嵌套model is not supported模型名错误或无权限换端点支持的模型名organization disabled账号权限限制联系管理员或换账号node not yet released版本号写错改用 LTS 版本号6.5 我踩过的三个坑第一个坑是 YAML 里用了中文冒号。有次我从文档里复制配置冒号是全角的YAML 解析直接报错但报错信息指向的行号是下一行害我找了半天。后来养成习惯配置文件里所有标点都用英文半角。第二个坑是环境变量引用写成了$CLAUDE_KEY而不是${CLAUDE_KEY}。在 YAML 里$VAR这种写法某些解析器不认必须用花括号包起来。这个差异很隐蔽因为 shell 里两种写法都行但 YAML 解析器只认后者。第三个坑是项目路径用了~但没有展开。YAML 里的~不会自动展开成用户主目录得写绝对路径或者用${HOME}。我一开始写path: ~/projects/xxxopenrig 找不到目录报了个很模糊的错后来改成${HOME}/projects/xxx才正常。7. 进阶玩法与扩展思路7.1 接入本地模型与第三方端点openrig 的 YAML 编排能力最大的价值在于它能统一管理不同后端。比如你想让 Claude Code 调用 LM Studio 的本地模型只要在tools.claude.env里把ANTHROPIC_BASE_URL指向本地 LM Studio 的兼容端点就行。同理Codex 接入 DeepSeek 也是改OPENAI_BASE_URL和对应的 key。这种玩法下openrig 就成了一个“模型路由层”。你可以在 YAML 里定义多个 profile比如profile: local、profile: cloud启动时用--profile切换。本地模型跑简单任务省钱云端模型跑复杂任务保质量切换成本几乎为零。7.2 多项目多模型的批量管理当你手上有十几个项目每个项目用的模型和端点都不一样时手动管理会疯掉。openrig 的projects节点就是为这个场景设计的。你可以给每个项目指定默认工具和模型覆盖然后写个简单的 shell 脚本cd到项目目录自动openrig run连工具名都不用记。更进一步可以把项目配置也拆成独立的 YAML 文件放在各自项目仓库里openrig 启动时自动向上查找最近的配置文件。这样每个项目的配置跟着代码走团队协作时新人 clone 下来就能用。7.3 与 VS Code 的协同配置热词里vscode配置claude code、claude code for vs code出现频率很高说明很多人是在 VS Code 里用这些工具的。openrig 跟 VS Code 的协同点在于VS Code 的集成终端会继承 shell 环境所以只要 openrig 在终端里能跑通VS Code 终端里也能跑通。如果你用 VS Code 的 tasks 功能可以配一个 task 调用openrig run claude一键在集成终端里启动配置好的 Claude Code。这样既享受了 VS Code 的界面又用上了 openrig 的配置管理。提示VS Code 有时会缓存终端环境变量改了 shell 配置后需要完全重启 VS Code不是重载窗口才能生效。这个坑我踩过改了半天配置没反应重启 VS Code 就好了。7.4 配置版本化与团队共享最后说个团队协作的点。openrig 的 YAML 配置天然适合版本化。把config.base.yaml提交到仓库团队所有人共享同一套工具配置和模型选择新人入职 clone 下来配好自己的密钥就能干活不用挨个问“你 Claude Code 怎么配的”。密钥部分用${VAR}引用各人在自己 shell 里 export互不干扰。如果团队用统一的密钥管理服务还可以在 openrig 启动前加一个拉取密钥的钩子实现全自动注入。这套流程跑顺之后团队里换工具、换模型、加新项目都只是改几行 YAML 的事。我个人在实际操作中的体会是openrig 这类编排工具的价值不在于它本身多复杂而在于它把“配置”这件事从散落各处的环境变量和命令行参数收敛成了一份可读、可版本化、可共享的声明式文件。刚开始配的时候可能觉得多此一举但当你同时维护多个 AI 编程项目、频繁切换模型后端的时候这份 YAML 省下的时间远超配置它的成本。最后再分享一个小技巧把常用的openrig run命令做成 shell alias比如alias ccopenrig run claude、alias cxopenrig run codex日常使用几乎零负担。