openrig 统一配置 Claude Code 与 Codex：YAML 声明式管理 AI 编程助手

1. openrig 到底想解决什么问题

第一次看到 openrig 这个名字，很多人会以为是某个硬件项目，毕竟 rig 这个词在英文里常指“设备、装置、机架”。但结合它周边的关键词——Claude Code、Codex、YAML、Node.js——基本可以判断，这是一个围绕 AI 编程助手做统一配置与编排的工具层项目。它的核心诉求不是重新造一个模型，而是把散落在不同 CLI 工具、不同配置文件、不同模型供应商之间的“接线”工作收敛到一处。

我自己在同时使用 Claude Code 和 Codex 的那段时间，最头疼的就是配置漂移。Claude Code 有自己的 settings 体系，Codex 有自己的 config 体系，两边都要写模型名、endpoint、认证方式、超时参数。改了一个忘了另一个，结果就是某个工具突然报cc switch local proxy failed while handling codex endpoint /responses这类错误，排查半天发现只是配置文件里少了一行。openrig 这类项目的价值，就是把这些重复劳动抽象成一份可维护的 YAML，让“切换模型”“切换供应商”“切换工作目录”变成改一个字段的事。

从热搜词能看出目标用户画像非常清晰：正在折腾 Claude Code 安装、Codex 安装、Node.js 环境、YAML 配置的开发者。这些人往往卡在环境搭建阶段，被error installing 24.21.0: node.js v24.21.0 is not yet released这种版本问题劝退，或者被your organization has disabled claude subscription access这种权限提示搞得一头雾水。openrig 面向的就是这批人，它试图用一份声明式配置，把“装什么、连哪里、用哪个模型”讲清楚。

适合读这篇内容的人有三类。第一类是刚接触 AI 编程助手、还在纠结装 Claude Code 还是 Codex 的新手，需要一套不绕弯的落地路径。第二类是已经在用但配置混乱、经常遇到代理转发失败的中级用户，需要理解配置分层和排查方法。第三类是想把团队里多个人的开发环境统一起来的技术负责人，需要可复制、可版本管理的方案。下面我会按“设计思路—核心细节—实操落地—问题排查”的顺序，把 openrig 这类工具背后的逻辑拆开讲。

2. 整体设计思路与方案选型拆解

2.1 为什么是 YAML 而不是 JSON 或 TOML

openrig 选择 YAML 作为配置载体，这个决定值得单独说。JSON 的问题是没法写注释，而 AI 工具配置里恰恰有大量需要解释的地方，比如“这个模型名对应哪个供应商”“这个超时为什么设成 120 秒”。TOML 虽然可读性好，但嵌套结构表达起来比较啰嗦，尤其是当你要描述“多个供应商、每个供应商下多个模型、每个模型带不同参数”这种三层结构时，TOML 的[provider.model.param]写法会迅速变得难以维护。

YAML 的缩进式结构天然适合表达层级关系，而且支持锚点和引用，这一点在配置复用上非常关键。举个例子，如果你有三个模型都走同一个 endpoint，只是模型名不同，用 YAML 的锚点可以这样写：

defaults: &defaults endpoint: https://api.example.com/v1 timeout: 120 retry: 3 models: fast: <<: *defaults name: gpt-5.6-sol balanced: <<: *defaults name: claude-sonnet

这种写法在 JSON 里需要重复三遍 endpoint，改一次要改三处。YAML 的锚点机制让“公共配置只写一次”成为可能，这是 openrig 这类工具选择 YAML 的核心理由。当然 YAML 也有坑，缩进用空格不能用 Tab，冒号后面必须跟空格，这些细节后面会专门讲。

2.2 Node.js 在整条链路里扮演什么角色

热搜里node.js是干什么的、node.js安装、node.js lts下载出现频率极高，说明很多人对 Node.js 的定位是模糊的。在 openrig 这类工具链里，Node.js 不是可选项，而是运行时底座。Claude Code 的 CLI、Codex 的 CLI、以及大量周边工具都是用 JavaScript/TypeScript 写的，它们最终都跑在 Node.js 运行时上。

这里有个常见的认知误区：有人以为装了 Node.js 就等于装了 npm，其实 npm 是随 Node.js 一起分发的，但版本可能不匹配。更关键的是，Node.js 的版本管理直接影响工具能否启动。热搜里那条error installing 24.21.0: node.js v24.21.0 is not yet released or is not available就是典型的版本问题——某个工具在 package.json 里声明了engines: { node: ">=24.21.0" }，但该版本还没正式发布，安装直接失败。

我的建议是不要追最新版，用 LTS 版本。截至我写这篇内容时，Node.js 22 LTS 是相对稳妥的选择。安装方式上，Windows 用户直接去官网下载 LTS 安装包，macOS 用户可以用 Homebrew，Linux 用户建议用 nvm 管理多版本。用 nvm 的好处是，当某个工具要求特定 Node 版本时，你可以nvm use 22快速切换，而不是卸载重装。

2.3 Claude Code 与 Codex 的配置差异在哪

Claude Code 和 Codex 虽然都是 AI 编程助手，但配置哲学不同。Claude Code 更偏向“项目级配置”，它会在项目根目录找配置文件，支持 per-project 的模型选择和权限设置。Codex 则更偏向“全局配置 + 环境变量”，很多行为通过~/.codex/config或环境变量控制。

这种差异导致一个实际问题：当你想让两个工具用同一个模型供应商时，需要写两份配置。openrig 的思路是抽一层中间层，用统一的 YAML 描述“我要用什么模型、走什么 endpoint、带什么参数”，然后由 openrig 生成或注入到各个工具的原生配置里。这样你只需要维护一份 openrig 配置，切换供应商时改一处即可。

热搜里cc switch local proxy failed while handling codex endpoint /responses这个错误，本质就是中间层在转发请求时，Codex 的 endpoint 路径和 Claude Code 的路径不一致导致的。Claude Code 可能走/v1/messages，Codex 走/responses，如果代理层没有正确区分路径，就会转发失败。理解这一点，对后面排查问题很重要。

2.4 声明式配置相比命令式脚本的优势

有人会问，为什么不直接写个 shell 脚本，用export设置环境变量、用sed改配置文件？脚本当然能干活，但它是命令式的——你描述的是“怎么做”，而不是“要什么”。命令式脚本的问题是幂等性差，跑第二遍可能出错，而且难以回滚。

声明式配置描述的是“最终状态”，openrig 读取 YAML 后，自己决定怎么把当前状态调整到目标状态。这带来的好处是：配置可以进 Git 版本管理，可以 code review，可以回滚到任意历史版本。团队协作时，新人 clone 仓库、跑一条openrig apply，环境就对齐了，不需要口口相传“你先装这个再改那个”。

3. 核心细节解析与实操要点

3.1 openrig 配置文件的典型结构

虽然 openrig 的具体 schema 可能随版本变化，但这类工具的配置结构有共性。一份典型的配置通常包含四个顶层字段：providers、models、tools、defaults。providers定义供应商信息，包括 endpoint 和认证方式；models定义可用模型及其参数；tools定义 Claude Code、Codex 等工具如何消费这些模型；defaults定义全局默认值。

providers: main: endpoint: https://api.example.com/v1 auth: env:API_KEY protocol: openai models: coding: provider: main name: gpt-5.6-sol max_tokens: 8192 temperature: 0.2 tools: claude-code: model: coding extra_args: ["--dangerously-skip-permissions"] codex: model: coding endpoint_path: /responses defaults: timeout: 120 retry: 3

这里有几个细节值得展开。auth: env:API_KEY表示认证信息从环境变量API_KEY读取，而不是硬编码在配置里。这是安全实践的基本要求，配置文件可以进 Git，但密钥绝对不能进。protocol: openai表示该供应商兼容 OpenAI 的 API 格式，很多第三方供应商都兼容这个格式，所以这个字段能覆盖大部分场景。

tools下面的endpoint_path是解决前面提到的路径不一致问题的关键。Claude Code 和 Codex 对同一个供应商可能走不同路径，显式声明路径可以避免代理层猜错。extra_args用来传递工具特有的参数，比如 Claude Code 的权限跳过参数，这些参数不属于模型配置，但又是启动必需的。

3.2 环境变量与密钥管理

密钥管理是新手最容易踩坑的地方。我见过有人把 API Key 直接写在 YAML 里然后提交到公开仓库，结果密钥泄露被刷爆额度。正确的做法是：配置文件里只写env:API_KEY这样的引用，实际密钥放在.env文件或系统环境变量里，.env加入.gitignore。

在 Windows 上设置环境变量，可以用系统设置里的“环境变量”面板，也可以用 PowerShell 的$env:API_KEY="xxx"（仅当前会话有效）。在 macOS/Linux 上，推荐在~/.zshrc或~/.bashrc里写export API_KEY="xxx"，然后source一下。如果你用 openrig 这类工具，它通常会支持从.env文件自动加载，这样就不用手动 export 了。

注意：不要把密钥写在项目级的.env里然后提交。项目级.env应该只放非敏感的默认值，敏感密钥放在用户级配置或系统环境变量里。

3.3 Node.js 版本与包管理器的选择

前面提到 Node.js 版本问题，这里展开讲。openrig 本身如果是 npm 包，安装时会检查 Node 版本。如果你的 Node 版本太低，会报engine相关错误；如果太高但该版本还没正式发布，会报not yet released。所以第一步是确认版本：

node -v npm -v

如果版本不对，用 nvm 切换：

nvm install 22 nvm use 22 nvm alias default 22

包管理器方面，npm 是默认的，但 pnpm 和 yarn 在依赖解析上更快、更省磁盘。openrig 这类工具如果依赖较多，用 pnpm 安装会明显快一些。不过要注意，有些工具的 postinstall 脚本对 pnpm 的严格依赖隔离不友好，遇到问题时可以退回 npm。

3.4 Claude Code 与 Codex 的安装路径差异

Claude Code 的安装方式在不同平台不一样。macOS/Linux 上通常用 npm 全局安装，Windows 上除了 npm 还有桌面版。热搜里claude code桌面版、claude code windows说明很多人在 Windows 上折腾。我的经验是，Windows 上优先用 WSL2，因为很多 CLI 工具在原生 Windows 上的路径处理和权限模型跟 Unix 差异大，容易出玄学问题。

Codex 的安装类似，codex安装包、codex安装 windows桌面版这些搜索词说明安装过程对新手不友好。Codex 的 CLI 通常也是 npm 包，安装后需要codex login或配置 API Key。热搜里codex登录、codex无法加载组织设置说明认证环节是卡点。如果遇到组织设置加载失败，通常是账号权限或网络策略问题，不是配置写错了。

3.5 YAML 语法的高频错误清单

YAML 看起来简单，但新手错误率极高。我整理了几个最常见的：

这些错误在解析时会报yaml.scanner.ScannerError或类似提示，但错误信息往往指向行号，不告诉你具体原因。我的习惯是写完 YAML 后用在线校验器过一遍，或者用python -c "import yaml; yaml.safe_load(open('config.yaml'))"快速验证。

4. 实操过程与核心环节实现

4.1 从零搭建 openrig 工作环境

假设你是一台全新的机器，下面是完整的搭建流程。第一步，安装 Node.js LTS。去 Node.js 官网下载对应平台的 LTS 安装包，或者用 nvm。安装完验证：

node -v # 应输出 v22.x.x 或类似 npm -v # 应输出 10.x.x 或类似

第二步，安装 openrig。如果它是 npm 包：

npm install -g openrig openrig --version

如果安装过程中报error installing 24.21.0，说明某个依赖要求了未发布的 Node 版本。这时候检查 openrig 的engines字段，或者用npm install -g openrig --ignore-engines跳过检查（不推荐长期这样，但应急可以）。

第三步，创建配置目录。openrig 通常会在~/.openrig/或当前目录找配置。我习惯在项目根目录放一份openrig.yaml，用户级配置放~/.openrig/config.yaml。项目级配置覆盖用户级，这样团队可以共享项目配置，个人偏好放用户级。

第四步，写第一份配置。从最小可用开始，不要一上来就写全量：

providers: default: endpoint: https://api.example.com/v1 auth: env:OPENRIG_API_KEY models: main: provider: default name: gpt-5.6-sol tools: claude-code: model: main codex: model: main

第五步，设置环境变量并应用：

export OPENRIG_API_KEY="your-key-here" openrig apply

apply命令会把配置注入到 Claude Code 和 Codex 的原生配置里。具体注入到哪里，取决于 openrig 的实现，可能是~/.claude/settings.json和~/.codex/config。应用后启动工具验证。

4.2 配置 Claude Code 走本地模型

热搜里claude code 调用lmstudio的本地模型是个高频需求。本地模型的好处是数据不出本机、无网络延迟、无额度限制。用 openrig 配置本地模型的思路是：把 provider 的 endpoint 指向本地服务，比如 LM Studio 默认的http://localhost:1234/v1。

providers: local: endpoint: http://localhost:1234/v1 auth: none protocol: openai models: local-coder: provider: local name: qwen2.5-coder-7b max_tokens: 4096 tools: claude-code: model: local-coder

这里的关键是auth: none，本地服务通常不需要密钥。protocol: openai表示 LM Studio 的 API 兼容 OpenAI 格式。模型名要跟 LM Studio 里加载的模型标识一致，否则会报模型不存在。

提示：本地模型的上下文窗口通常比云端小，max_tokens不要设太大，否则可能触发截断或报错。7B 模型建议设 4096，14B 以上可以设 8192。

4.3 用 openrig 统一管理多供应商切换

实际工作中，我可能上午用云端模型处理复杂重构，下午用本地模型做简单补全。手动改配置太麻烦，openrig 的 profile 机制可以解决。在配置里定义多个 profile：

profiles: cloud: model: coding local: model: local-coder models: coding: provider: main name: gpt-5.6-sol local-coder: provider: local name: qwen2.5-coder-7b

切换时执行openrig use cloud或openrig use local，openrig 会更新各工具的原生配置。这比手动改文件可靠得多，因为手动改容易漏掉某个工具。

4.4 验证配置是否生效

配置写完不等于生效。验证分三步。第一步，检查 openrig 自己的解析结果：

openrig config show

这会打印合并后的最终配置，确认没有字段被覆盖错。第二步，检查工具的原生配置是否被正确注入。比如 Claude Code 的配置文件里应该能看到模型名和 endpoint。第三步，实际发一个请求测试：

claude "写一个 hello world"

如果返回正常，说明链路通了。如果报cc switch local proxy failed while handling codex endpoint /responses，说明代理层路径配置有问题，检查endpoint_path字段。

4.5 把配置纳入版本管理

openrig 配置的最大价值之一是能进 Git。我的做法是：项目根目录放openrig.yaml，里面只写非敏感信息，密钥用env:引用。.env.example列出需要的环境变量名，.env加入.gitignore。新人 clone 后，复制.env.example为.env，填入自己的密钥，跑openrig apply即可。

这样做的另一个好处是 code review。配置变更可以像代码一样 review，比如有人把temperature从 0.2 改成 0.8，review 时能看出来并讨论是否合理。命令式脚本做不到这一点，因为脚本的执行结果是隐式的。

5. 常见问题与排查技巧实录

5.1 代理转发失败的排查路径

cc switch local proxy failed while handling codex endpoint /responses这个错误我在不同场景下遇到过三次，原因各不相同。第一次是 endpoint 路径写错，Codex 需要/responses但配置里写的是/v1/responses。第二次是认证头格式不对，某个供应商要求Authorization: Bearer xxx但代理发的是x-api-key: xxx。第三次是超时太短，复杂请求还没返回就断了。

排查顺序建议是：先看 openrig 的日志（通常有--verbose或--debug参数），确认请求发到了哪个 URL、带了什么头。然后用 curl 手动发同样的请求，排除是工具层还是网络层的问题。最后检查供应商文档，确认路径和认证格式。

5.2 Node.js 版本冲突的解决

error installing 24.21.0: node.js v24.21.0 is not yet released or is not available这个错误的根源是依赖声明了不存在的版本。解决方法有三种：降级依赖版本、用--ignore-engines跳过检查、或者用 nvm 安装一个满足条件的版本。我通常选第一种，因为跳过检查可能导致运行时行为不一致。

如果多个工具要求不同 Node 版本，nvm 是唯一优雅的解法。在项目目录放一个.nvmrc文件，内容写22，进入目录时nvm use自动切换。这样不同项目可以用不同 Node 版本，互不干扰。

5.3 组织权限问题的应对

your organization has disabled claude subscription access for claude code这个提示说明账号所在组织禁用了该工具的订阅访问。这不是配置能解决的，需要联系组织管理员。如果是个人账号遇到类似提示，检查是否误用了企业邮箱注册。这类问题的排查优先级最低，因为通常不是技术问题。

5.4 YAML 解析错误的快速定位

YAML 报错信息通常只给行号，不给原因。我的快速定位方法是：把报错行附近的配置单独摘出来，用最小化配置测试。比如报错在第 15 行，就把 1 到 15 行复制到一个新文件，逐步删减，直到找到触发错误的那个字段。常见触发点包括：冒号后没空格、缩进混用 Tab、字符串里有未转义的特殊字符。

提示：VS Code 装 YAML 插件后，能实时高亮语法错误，比事后排查省事得多。插件还能做 schema 校验，如果 openrig 提供了 schema，配置写错会直接标红。

5.5 工具间配置不同步的处理

有时候 openrig apply 成功了，但 Claude Code 生效了、Codex 没生效。这通常是因为 Codex 的配置缓存或需要重启。Codex 的 CLI 可能在启动时读取配置，运行中改配置不生效。解决方法是完全退出 Codex 再启动。如果还不行，检查 Codex 是否有独立的配置覆盖机制，比如环境变量优先级高于配置文件。

另一个可能是权限问题。如果 openrig 没有写入~/.codex/的权限，apply 会静默失败或报权限错误。检查目录权限，必要时用sudo（不推荐）或修改目录所有者。

5.6 本地模型连接失败的排查

本地模型连不上，先确认服务在跑：

curl http://localhost:1234/v1/models

如果这条命令返回模型列表，说明服务正常，问题在 openrig 配置。如果不返回，说明 LM Studio 没启动或端口不对。LM Studio 默认端口是 1234，但可以在设置里改。确认端口后，检查 openrig 配置里的 endpoint 是否一致。

还有一个坑是防火墙。某些系统会阻止本地回环以外的连接，如果 LM Studio 绑定的是0.0.0.0而 openrig 连的是127.0.0.1，一般没问题；但如果绑定的是特定网卡地址，可能连不上。统一用localhost或127.0.0.1最稳妥。

6. 进阶用法与团队协作实践

6.1 用 profile 实现环境隔离

团队里通常有开发、测试、生产多套环境，每套环境的模型供应商可能不同。用 openrig 的 profile 可以做到环境隔离：

profiles: dev: model: local-coder provider: local staging: model: coding provider: staging prod: model: coding provider: prod

每个开发者本地用devprofile，CI 环境用staging，生产部署用prod。切换只需openrig use dev。这样避免了“在我机器上能跑”的经典问题，因为配置是显式声明的。

6.2 配置模板与继承

大型团队可能有几十个项目，每个项目都要写配置太累。openrig 如果支持配置继承，可以定义一个基础模板，项目配置只写差异部分。比如基础模板定义好 provider 和认证方式，项目配置只覆盖模型名和参数。这样改 provider 时只改一处，所有项目生效。

实现方式通常是在项目配置里写extends: ../base.yaml，openrig 加载时先读 base 再合并项目配置。合并规则一般是深度合并，项目配置覆盖 base 的同名字段。理解合并规则很重要，否则可能出现“我改了但没生效”的情况，实际是被 base 覆盖了。

6.3 与 CI/CD 集成

在 CI 里跑 AI 辅助的代码检查或生成，需要非交互式配置。openrig 支持从环境变量读取所有配置，这样 CI 的 secret 管理可以直接注入。比如：

OPENRIG_PROVIDER_ENDPOINT=${{ secrets.API_ENDPOINT }} \ OPENRIG_API_KEY=${{ secrets.API_KEY }} \ openrig apply --non-interactive

--non-interactive跳过所有确认提示，适合自动化环境。CI 里还要注意超时设置，云端模型可能比本地慢，timeout 要留足。

6.4 配置变更的回滚

配置改错了导致工具不能用，需要快速回滚。如果配置在 Git 里，git checkout旧版本再openrig apply即可。如果没进 Git，openrig 通常会保留上一次的配置备份，可以用openrig rollback恢复。我的习惯是每次大改前先openrig config show > backup.yaml，出问题直接openrig apply backup.yaml。

7. 我踩过的坑与实操心得

第一个坑是过度配置。刚开始用 openrig 时，我把所有能配的字段都配了一遍，结果某个字段跟工具默认行为冲突，导致启动失败。后来学乖了，从最小配置开始，需要什么加什么。配置不是越多越好，每多一个字段就多一个出错点。

第二个坑是忽略日志。openrig 的--verbose输出很详细，但我一开始不看，遇到问题就瞎猜。后来养成习惯，任何异常先看日志，日志里通常直接写了原因，比如“endpoint unreachable”或“invalid yaml at line 23”。看日志比搜索快得多。

第三个坑是密钥硬编码。早期图省事把密钥写在 YAML 里，后来意识到风险才改成环境变量。改的时候发现有些工具不支持环境变量引用，只能写文件，这时候至少把文件权限设成 600，并且确保不进 Git。

第四个坑是版本追新。有次看到 Node.js 新版本发布就升级，结果 openrig 的某个依赖不兼容，折腾了一下午。现在我固定用 LTS，并且用.nvmrc锁定版本，团队统一。

第五个坑是忽略工具差异。以为 Claude Code 和 Codex 配置一样，结果 Codex 需要额外的路径配置。后来在 openrig 配置里给每个工具单独写tools段，差异显式声明，不再假设它们行为一致。

最后分享一个小技巧：openrig 配置写完后，用openrig validate先校验再 apply。validate 只检查语法和字段合法性，不实际写入，能在早期发现大部分低级错误。这个命令我每次改配置都会跑，省了很多回滚时间。