openrig 统一配置管理：Claude Code 与 Codex 多模型接入实战

1. openrig 到底是个什么东西

第一次看到 openrig 这个名字，很多人会以为是某个硬件外设或者开源机械臂项目。实际上，结合它周围出现的关键词——Claude Code、Codex、YAML、Node.js——可以判断，这是一个围绕 AI 编程助手做统一接入与配置管理的工具层项目。它的核心价值在于：把原本散落在各个 CLI 工具、配置文件、环境变量里的模型接入信息，收敛到一份可维护的 YAML 配置中，再通过 Node.js 运行时统一调度。

说白了，openrig 解决的是一个很具体的痛点。现在用 Claude Code 的人越来越多，同时用 Codex CLI 的人也不少，还有人两个都想接本地模型或者第三方 API。每个工具的配置方式都不一样：Claude Code 认环境变量和 settings 文件，Codex 认自己的 config 目录，切换模型要改的地方五花八门。openrig 想做的事情，就是让你只维护一份配置，剩下的交给它去分发。

这个项目适合谁？三类人最值得关注。第一类是同时使用多个 AI 编程工具的开发者，配置管理成本高；第二类是想把本地模型（比如通过 LM Studio 跑的模型）接进 Claude Code 或 Codex 的人；第三类是需要团队统一配置、避免每个人各自踩坑的工程团队。如果你只是偶尔用一下某个 CLI，那可能感受不到它的价值，但只要你的工具链超过两个，openrig 这种统一层的意义就出来了。

需要说明的是，openrig 目前并不是一个广为人知的主流项目，公开资料有限。下面涉及的具体实现细节，一部分是基于同类工具（配置管理类 CLI）的常见做法做的合理推演，我会明确标注哪些是推断、哪些是通用实践，你在实际使用时以项目仓库的实际文档为准。

2. 核心设计思路与方案选型拆解

2.1 为什么用 YAML 做配置载体

配置格式的选择看似小事，实际上决定了这个工具好不好用。openrig 选 YAML 而不是 JSON 或 TOML，有它的道理。

JSON 的问题是写起来太啰嗦，不能写注释，多行字符串处理起来很难受。你想想，一个模型接入配置里往往要写系统提示词、自定义请求头、路径映射，这些用 JSON 写会非常痛苦。TOML 虽然可读性好，但嵌套结构表达能力偏弱，遇到"多个 provider 下面挂多个 model，每个 model 又有自己的参数"这种三层结构时，TOML 会变得很别扭。

YAML 的优势正好补上这两点：支持注释（这对配置管理极其重要，你可以标注每个字段是干什么的）、嵌套结构清晰、多行字符串用|或>就能搞定。代价是 YAML 对缩进敏感，缩进错了会报一些莫名其妙的错，这也是后面排查问题时要重点注意的地方。

提示：YAML 里 tab 和空格不能混用，统一用两个空格缩进是最稳妥的做法。很多"配置不生效"的问题，根源就是某一行不小心用了 tab。

2.2 Node.js 作为运行时的考量

openrig 依赖 Node.js，这个选择在 AI 工具生态里非常自然。Claude Code 本身就是 npm 包分发，Codex CLI 也是 Node 生态，整个链条用同一套运行时，安装和调用都顺。而且 Node.js 的跨平台能力成熟，Windows、macOS、Linux 上行为基本一致，这对一个要管理多工具配置的项目来说很关键。

从版本角度，建议用 Node.js 的 LTS 版本。网上经常有人遇到error installing 24.21.0: node.js v24.21.0 is not yet released这类报错，本质是版本号写错了或者源里还没有这个版本。稳妥做法是去 Node.js 官网下载 LTS 版本，或者用 nvm 这类版本管理工具装。不要盲目追最新的大版本号，AI 工具链对 Node 版本比较敏感，太新的版本有时候会有兼容问题。

2.3 统一接入层的架构逻辑

openrig 的架构思路可以类比成"配置翻译官"。你写一份中立的 YAML，它负责翻译成 Claude Code 能懂的格式、Codex 能懂的格式、以及本地模型服务能懂的格式。

这样做的好处是解耦。以前你想换个模型，得去翻 Claude Code 的文档改环境变量，再去翻 Codex 的文档改它自己的配置，两边还可能冲突。现在你只改 YAML 里的一行，openrig 帮你同步到各个工具。坏处是引入了一层间接性，出问题的时候要多排查一层——到底是 YAML 写错了，还是 openrig 翻译错了，还是目标工具本身的问题。这个排查链路后面会专门讲。

3. 核心配置细节与实操要点

3.1 一份典型配置的结构长什么样

虽然 openrig 的确切 schema 要以官方为准，但同类工具的配置结构大同小异。一份能覆盖多工具、多模型的配置，通常会分成几个层次：全局设置、provider 定义、model 定义、工具映射。

# 全局设置 version: 1 default_provider: local # provider 定义：模型服务的来源 providers: local: type: openai-compatible base_url: http://localhost:1234/v1 api_key: not-needed remote: type: openai-compatible base_url: https://api.example.com/v1 api_key: ${REMOTE_API_KEY} # model 定义：具体用哪个模型 models: fast: provider: local name: qwen2.5-coder context_window: 32768 strong: provider: remote name: gpt-5.6-sol context_window: 128000 # 工具映射：哪个工具用哪个模型 tools: claude-code: model: strong codex: model: fast

这个结构的关键在于分层。provider 管"从哪来"，model 管"用哪个"，tools 管"谁用"。这样当你换一个本地模型服务地址时，只改 provider 一处；当你想让 Codex 用更强的模型时，只改 tools 里的一行。

3.2 环境变量与密钥处理

配置里最敏感的是 API key。直接把密钥写进 YAML 再提交到 git，是新手最容易犯的错。正确做法是用环境变量引用，像上面例子里的${REMOTE_API_KEY}。openrig 这类工具通常支持在读取配置时做变量替换。

具体操作上，Linux 和 macOS 可以在 shell 配置文件里 export，Windows 用系统环境变量或者.env文件。如果你用.env，记得把它加进.gitignore。我见过太多人因为把密钥提交上去，第二天收到账单才发现被人盗用。

注意：不同工具对密钥的环境变量名要求不一样。Claude Code 和 Codex 各自认的变量名不同，openrig 的价值之一就是帮你做这层映射，但你要确认它确实把密钥传到了正确的位置，而不是只改了模型名没改密钥。

3.3 本地模型接入的关键参数

把本地模型（比如 LM Studio 里跑的）接进 Claude Code 或 Codex，是很多人用 openrig 的主要场景。这里有几个参数必须配对。

base_url要指向本地服务的 OpenAI 兼容端点，通常是http://localhost:1234/v1这种形式。注意结尾的/v1不能少，少了会 404。api_key本地服务一般不校验，但很多客户端要求这个字段非空，随便填个字符串就行。model name必须和本地服务里加载的模型标识完全一致，大小写都不能错，否则会报模型不存在。

还有一个容易忽略的点是context_window。本地模型的上下文窗口往往比云端小，如果你在配置里写了 128000 但本地模型只支持 32768，长对话到一半就会崩。这个值要按实际模型填。

4. 完整实操流程与关键环节

4.1 环境准备：Node.js 与包管理器

第一步是把 Node.js 装好。去 Node.js 官网下载 LTS 版本，安装时勾选"添加到 PATH"。装完在终端里跑node -v和npm -v，能输出版本号就说明成功了。

如果你需要管理多个 Node 版本，用 nvm 更灵活。Windows 上用 nvm-windows，macOS 和 Linux 上用 nvm。装好之后nvm install --lts装最新 LTS，nvm use --lts切换过去。

# 检查环境 node -v npm -v # 如果用 nvm nvm install --lts nvm use --lts

这一步踩坑最多的地方是权限。Linux 和 macOS 上如果全局装包报权限错误，不要用 sudo 硬来，正确做法是配置 npm 的全局目录到用户目录下，或者用 nvm 管理。sudo 装全局包会导致后续权限混乱，后患无穷。

4.2 安装 openrig 与初始化配置

环境就绪后，通过 npm 安装 openrig（具体包名以官方为准）。安装完成后，一般会有一个 init 命令来生成初始配置文件。

# 安装（包名以官方为准） npm install -g openrig # 初始化配置 openrig init

init 会在你的用户目录下生成一份默认 YAML。这时候不要急着改，先把它读一遍，理解每个字段的含义。然后按你的实际情况填 provider 和 model。

4.3 配置 Claude Code 与 Codex 的映射

这是 openrig 的核心环节。你需要告诉它，Claude Code 用哪个模型，Codex 用哪个模型。

配置完成后，通常需要跑一个 apply 或者 sync 命令，让 openrig 把配置写入各个工具的实际配置文件里。

# 应用配置 openrig apply # 或者查看当前生效的配置 openrig status

apply 之后，去检查一下 Claude Code 和 Codex 各自的配置文件有没有被正确更新。这一步很重要，因为如果 openrig 的路径推断错了，它可能写到了一个工具根本不读的位置，你以为配好了，实际没生效。

4.4 验证接入是否成功

配置完必须验证。最直接的办法是启动 Claude Code 或 Codex，问一个简单问题，看它是否正常响应。如果用的是本地模型，观察本地服务的日志，看有没有收到请求。

# 启动 claude code 测试 claude # 启动 codex 测试 codex

如果请求发出去了但报错，看错误信息。常见的几类：模型名不对、base_url 不对、密钥没传过去、上下文超限。对照错误信息逐个排查。

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

5.1 配置不生效的排查顺序

配置改了但工具行为没变，这是最高频的问题。排查要按顺序来，不要乱试。

先确认 openrig 的 apply 有没有真的执行成功，看它的输出有没有报错。再确认目标工具的配置文件路径对不对，手动打开那个文件看内容有没有被更新。然后确认工具启动时读的是不是那个文件——有些工具支持多个配置位置，优先级不同。最后确认环境变量有没有覆盖配置文件，环境变量优先级通常更高。

这个顺序的逻辑是：从 openrig 到文件，从文件到工具，从工具到运行时，一层层缩小范围。跳过任何一层都可能白忙活。

5.2 模型报错与端点问题

the 'gpt-5.6-sol' model is not supported when using codex这类报错，说明模型名和工具支持的列表对不上。要么是模型名拼错了，要么是这个工具根本不支持这个模型。解决办法是换成工具明确支持的模型名，或者确认你的 provider 确实提供了这个模型。

cc switch local proxy failed while handling codex endpoint /responses这种错误，通常出现在用中间层代理转发请求的场景。问题往往出在端点路径映射上——Codex 请求的是/responses，但你的代理只处理了/chat/completions，路径对不上就失败了。这时候要检查 openrig 或代理层的路径重写规则。

5.3 常见问题速查表

5.4 几个我踩过的坑

第一个坑是 YAML 的布尔值。YAML 里yes、no、on、off会被解析成布尔值，如果你某个字段的值恰好是这些词，会得到意料之外的结果。字符串该加引号就加引号。

第二个坑是路径里的波浪号。~/.config/xxx这种写法在 shell 里能展开，但在某些配置解析器里不会，会被当成字面量。稳妥做法是写绝对路径，或者确认工具支持波浪号展开。

第三个坑是版本漂移。Claude Code 和 Codex 更新很频繁，配置格式偶尔会变。openrig 如果没跟上，就会出现"昨天还好好的今天不行了"。遇到这种情况先看工具的更新日志，再看 openrig 有没有新版本。

6. 进阶用法与扩展思路

6.1 多环境配置切换

如果你在公司和个人设备上用不同的模型服务，可以准备多份 YAML，用环境变量或者命令行参数指定用哪份。比如openrig apply --config work.yaml和openrig apply --config personal.yaml。这样切换环境不用手动改配置。

6.2 团队协作中的配置管理

团队场景下，可以把不含密钥的配置模板提交到仓库，密钥通过 CI 或者本地环境变量注入。新人入职拉下仓库，配好环境变量，跑一次 apply 就能用，省去大量沟通成本。这是 openrig 这类工具在团队里最大的价值。

6.3 与编辑器集成

Claude Code 有 VS Code 扩展，Codex 也有对应的编辑器集成。openrig 配好的模型信息，理论上可以被这些集成复用。不过要注意，编辑器扩展有时候读的是自己的配置，不一定走 CLI 的那套。如果发现编辑器里用的模型和 CLI 不一致，去检查扩展自己的设置。

我在实际使用中最大的体会是，这类统一配置工具的价值不在于省那几行配置，而在于把"配置"这件事从散落各处的隐式知识，变成了显式的、可版本管理的文件。以前换个模型要翻半天文档，现在打开 YAML 改一行。这个转变对个人是效率，对团队是规范。至于 openrig 本身，建议你先拿它管一个工具试试，跑通了再往上加，别一上来就把所有工具都接进去，出问题不好定位。