openrig：用YAML统一管理Claude Code与Codex的AI编程配置

1. openrig 到底想解决什么问题第一次看到 openrig 这个名字很多人会以为是某个硬件项目毕竟 rig 这个词在英文里常指“设备、装置”。但结合 Claude Code、Codex、YAML、Node.js 这一串关键词来看它其实是一个围绕 AI 编程助手做统一配置与编排的工具层。简单说openrig 想做的事情是把 Claude Code、Codex 这类命令行 AI 编程工具的管理方式抽象出来用一份 YAML 配置驱动让多个模型、多个端点、多个项目环境之间的切换不再靠手改环境变量和配置文件。我在实际折腾 Claude Code 和 Codex 的过程中最头疼的就是配置分散。Claude Code 有自己的配置目录Codex 有自己的登录态和模型设置切换不同模型供应商时还要改 base URL、API Key、模型名。每次换项目就像重新装一遍环境。openrig 这类工具的价值就在于把这些零散的配置收敛到一个入口用声明式的方式管理。它适合谁三类人最值得关注。第一类是同时使用 Claude Code 和 Codex 的开发者需要在两套工具之间频繁切换第二类是想接入第三方模型端点、但不想每次都手动改配置的人第三类是把 AI 编程助手纳入团队工作流、需要统一配置规范的工程团队。如果你只是偶尔用一次命令行 AI 工具那 openrig 可能有点重但只要你的日常开发已经离不开这些工具配置管理就会变成一个真实的痛点。需要说明的是openrig 目前并不是一个广为人知的标准项目网络上关于它的完整文档并不多。下面我基于 Claude Code、Codex、YAML 配置管理、Node.js 工具链这些已知信息结合一个合格从业者在搭建这类工具时最可能采用的方案做合理推演和补全。凡是我补充的部分都会明确标注是常见实践推断你可以根据自己拿到的实际版本做调整。2. 核心设计思路与方案选型拆解2.1 为什么用 YAML 做配置层YAML 在这类工具里几乎是默认选择原因很实际。JSON 写注释不方便多人协作时容易因为格式问题产生无意义的 diffTOML 表达嵌套结构时层级一多就变得啰嗦而 YAML 支持注释、缩进直观、嵌套结构清晰特别适合描述“多个模型 多个端点 多个项目”这种树状配置。一个典型的 openrig 配置大概会包含这几块内容模型供应商定义、每个供应商下的模型列表、端点地址、认证方式、以及不同项目或场景下默认使用哪个模型。用 YAML 写出来大概是这样providers: anthropic: type: claude api_key_env: ANTHROPIC_API_KEY models: - claude-sonnet - claude-opus openai_compatible: type: codex base_url: https://api.example.com/v1 api_key_env: CUSTOM_API_KEY models: - gpt-5.6-sol - deepseek-v4 profiles: default: provider: anthropic model: claude-sonnet local: provider: openai_compatible model: deepseek-v4这种结构的好处是切换模型只需要改 profile 字段不用动任何代码。YAML 的注释能力也让你可以在配置里写清楚每个端点的用途团队新人接手时不用猜。注意YAML 对缩进极其敏感Tab 和空格混用会直接报解析错误。建议在编辑器里统一设置为两个空格缩进并开启 YAML 语法校验。2.2 Node.js 在其中的角色openrig 选择 Node.js 作为运行时这个决策很符合当前 AI 编程工具的生态。Claude Code 本身就是基于 Node.js 分发的Codex CLI 也有 npm 安装方式。用 Node.js 做 openrig 的运行时意味着它可以复用同一套包管理生态安装时不需要额外装 Python 或 Go 环境。Node.js 在这里承担的工作包括读取 YAML 配置、解析成 JavaScript 对象、根据配置生成对应工具需要的环境变量或配置文件、以及可能存在的进程管理比如启动一个本地代理来转发请求。如果你之前没接触过 Node.js可以把它理解成一个“让 JavaScript 能在电脑上直接运行”的环境类似 Python 解释器之于 Python 脚本。安装 Node.js 时我建议直接用 LTS 版本不要追最新的 Current 版本。LTS 版本经过更长时间的测试和各类 CLI 工具的兼容性更稳。下载渠道优先选 Node.js 官网的 LTS 安装包Windows 用户下载 .msimacOS 用户可以用官方 pkg 或者通过包管理器安装Ubuntu 用户建议用 NodeSource 的源而不是系统自带的旧版本。# Ubuntu 下检查 Node.js 版本 node -v npm -v # 如果版本过低建议通过 nvm 管理多版本 curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash nvm install --lts nvm use --lts用 nvm 的好处是可以在不同项目间切换 Node.js 版本避免因为某个工具要求 Node 18 而另一个要求 Node 20 导致冲突。这个坑我在早期搭建环境时踩过系统里装了一个版本后来装 Claude Code 时提示版本不满足又不敢直接升级怕影响其他项目最后用 nvm 才解决。2.3 统一配置与多工具协同的逻辑openrig 的核心设计哲学是“配置与工具解耦”。Claude Code 和 Codex 各自有自己的配置格式和读取路径openrig 在中间做一层适配读取统一的 YAML然后分别生成或注入各工具需要的配置。这样做的好处有三个。第一新增一个模型供应商时只需要在 YAML 里加一段不用去翻每个工具的文档看怎么配。第二团队可以把 openrig 配置纳入版本控制新人 clone 下来就能用减少“在我机器上能跑”的问题。第三切换模型时不用改代码或环境变量降低误操作概率。从实现角度看openrig 可能会在启动时做这几件事解析 YAML、校验必填字段、根据 profile 生成环境变量、调用目标工具的 CLI 入口。如果涉及本地代理模式还可能在本地起一个 HTTP 服务把请求转发到配置的端点。这种设计在接入第三方 API 时特别有用因为有些工具对端点格式有特定要求中间加一层代理可以做格式转换。3. 环境搭建与核心配置实操3.1 Node.js 环境准备与版本选择搭建 openrig 的第一步是把 Node.js 环境弄干净。我见过太多人因为系统里存在多个 Node.js 版本、npm 全局包混乱而导致安装失败。建议按下面的顺序检查# 查看当前 node 和 npm 位置 which node which npm # 查看版本 node -v npm -v # 查看全局安装的包 npm list -g --depth0如果 which node 指向的是 /usr/bin/node 这种系统路径而你又用 nvm那很可能存在版本冲突。解决办法是确保 nvm 的初始化脚本在 shell 配置文件中正确加载并且 nvm 管理的版本优先级高于系统版本。Node.js 版本选择上openrig 这类工具通常要求 Node 18 以上。我实测 Node 20 LTS 兼容性最好Node 22 也可以但偶尔会遇到某些依赖还没跟上。如果你看到类似 “error installing 24.21.0: node.js v24.21.0 is not yet released” 这种报错说明你指定的版本号根本不存在去 Node.js 官网确认当前 LTS 的实际版本号再安装。提示不要盲目复制网上教程里的版本号Node.js 的版本更新很快半年前的教程里的版本号可能已经过时。以官网当前 LTS 为准。3.2 openrig 的安装与初始化假设 openrig 通过 npm 分发安装方式大概是全局安装npm install -g openrig安装完成后通常需要执行初始化命令来生成默认配置文件openrig init这个命令会在用户目录下创建一个配置目录比如 ~/.openrig/里面包含 config.yaml 和可能的 profiles 目录。如果 openrig 没有 init 命令那就手动创建配置目录和 YAML 文件具体路径参考项目文档。初始化之后第一件事是配置模型供应商。以接入一个兼容 OpenAI 格式的第三方端点为例providers: my_provider: type: openai_compatible base_url: https://your-endpoint.example.com/v1 api_key_env: MY_PROVIDER_KEY models: - model-a - model-b profiles: work: provider: my_provider model: model-a这里 api_key_env 的意思是“从环境变量读取密钥”而不是把密钥直接写在 YAML 里。这是安全实践的基本要求YAML 文件可能会被提交到版本库明文密钥一旦泄露后果严重。# 在 shell 配置文件中设置环境变量 export MY_PROVIDER_KEYyour-actual-key设置完记得 source 一下配置文件或者重开终端。3.3 Claude Code 与 Codex 的接入配置openrig 要管理 Claude Code 和 Codex就需要知道这两个工具的配置在哪里。Claude Code 通常读取用户目录下的配置Codex 也有自己的配置路径。openrig 的作用是在启动这些工具前把 YAML 里的 profile 转换成对应工具能识别的格式。以 Claude Code 为例如果 openrig 支持生成 Claude Code 的配置流程大概是# 激活某个 profile openrig use work # 然后正常启动 Claude Code claudeopenrig use 命令会修改 Claude Code 读取的配置文件或者设置当前 shell 的环境变量让 Claude Code 使用指定的模型和端点。对于 Codex逻辑类似。但 Codex 的配置可能涉及登录态和模型支持列表如果看到 “the ‘gpt-5.6-sol’ model is not supported when using codex with a...” 这类报错说明你配置的模型名不在 Codex 支持的列表里或者端点不兼容。这时候需要检查 YAML 里的模型名是否和端点实际提供的模型名一致。注意不同工具对模型名的写法要求可能不同。有的要求带供应商前缀有的要求用特定别名。配置时以工具文档为准不要想当然。3.4 本地代理模式与端点转发openrig 如果支持本地代理模式那它在处理第三方端点时会更有优势。本地代理的工作方式是openrig 在本地起一个 HTTP 服务监听某个端口然后把 Claude Code 或 Codex 的请求转发到真实端点。这样做的好处是可以在转发过程中做请求头修改、路径重写、格式转换。比如某些第三方端点不支持 Anthropic 的原生格式但支持 OpenAI 格式代理层就可以做转换。另外代理层还可以做日志记录方便排查请求失败的原因。配置本地代理大概需要在 YAML 里加一段proxy: enabled: true port: 8787 target_provider: my_provider然后启动代理openrig proxy start再把 Claude Code 或 Codex 的端点指向本地代理地址。这种模式下即使第三方端点有兼容性问题也有一个中间层可以调试。4. 常见问题排查与避坑经验4.1 安装阶段的典型报错安装 openrig 或相关工具时最常见的报错集中在 Node.js 版本和网络权限上。下面这张表整理了我遇到过和社区里高频出现的问题报错信息可能原因解决思路error installing 24.21.0: node.js v24.21.0 is not yet released版本号不存在或写错去官网确认当前 LTS 版本号npm ERR! code EACCES全局安装权限不足用 nvm 管理 Node避免 sudo npmyour organization has disabled claude subscription access组织策略限制检查账号权限或换用 API Key 方式cc switch local proxy failed while handling codex endpoint代理配置或端点不兼容检查 base_url 和模型名是否匹配codex 无法加载组织设置登录态或配置文件损坏重新登录或清理配置目录EACCES 这个错误特别常见。很多人第一次装全局 npm 包时用 sudo结果导致后续所有 npm 操作都需要 sudo权限越来越乱。正确做法是用 nvm 安装 Node.js这样全局包会装在用户目录下不需要 sudo。4.2 配置不生效的排查顺序配置写完但工具没按预期使用指定模型这种情况排查起来要有顺序。我的习惯是从下往上查先确认 YAML 文件语法正确可以用在线 YAML 校验工具或openrig config validate命令。确认环境变量已经设置echo $MY_PROVIDER_KEY看有没有输出。确认 profile 已经激活openrig current看当前用的是哪个 profile。确认目标工具读取的配置文件路径和 openrig 写入的路径一致。如果用了代理确认代理进程在运行端口没有被占用。这个顺序的逻辑是先排除最底层的语法和变量问题再往上查工具集成。很多“配置不生效”最后发现是环境变量没 source或者 YAML 里缩进错了。4.3 模型接入的兼容性坑接入第三方模型端点时兼容性问题主要集中在三个方面请求格式、认证方式、模型名映射。请求格式方面Claude Code 原生使用 Anthropic 的 API 格式Codex 使用 OpenAI 格式。如果你把 Claude Code 指向一个只支持 OpenAI 格式的端点就需要代理层做转换。openrig 如果内置了格式转换那配置时要注意指定正确的 type。认证方式方面有的端点用 Bearer Token有的用自定义 Header。YAML 里要能灵活配置认证头不能写死。模型名映射方面端点提供的模型名可能和工具默认期望的不一样。比如端点里叫 “deepseek-v4”但工具配置里写的是 “deepseek”就会报模型不支持。解决办法是在 YAML 里做映射models: - name: deepseek-v4 alias: deepseek这样工具用 alias 请求openrig 转发时替换成真实模型名。提示接入任何第三方端点前先用 curl 手动测试一下端点的 /models 接口确认模型名和认证方式再写进 YAML。这一步能省掉大量调试时间。4.4 多项目多配置的管理技巧当你同时维护多个项目每个项目用不同的模型配置时openrig 的 profile 机制就派上用场了。我的做法是按项目名建 profile然后在项目目录下放一个 .openrigrc 文件指定默认 profile。# 项目根目录下的 .openrigrc profile: project-a这样进入项目目录后openrig 自动读取当前目录的配置不用手动切换。如果 openrig 不支持目录级配置那就用 shell 函数封装# 在 .bashrc 或 .zshrc 里加 proj_a() { openrig use project-a cd ~/projects/project-a }这种小技巧看起来简单但每天省下几次手动切换的时间累积起来很可观。5. 把 openrig 用顺手的几个进阶思路5.1 配置版本化与团队共享openrig 的 YAML 配置天然适合纳入 Git 管理。团队可以建一个内部仓库存放共享的 provider 定义和 profile 模板每个人的本地配置只保留个人密钥和个性化部分。具体做法是把配置拆成两层基础层放共享的 provider 和模型定义个人层放 API Key 环境变量名和个人偏好的 profile。openrig 如果支持配置合并就可以按顺序加载多个 YAML 文件后面的覆盖前面的。# base.yaml - 团队共享 providers: team_endpoint: type: openai_compatible base_url: https://team-endpoint.example.com/v1 api_key_env: TEAM_KEY # personal.yaml - 个人配置 profiles: my_default: provider: team_endpoint model: model-a这种分层方式既保证了团队配置的一致性又保留了个人的灵活性。新人入职时只需要设置自己的 API Key 环境变量其他配置直接从仓库拉取。5.2 与编辑器工作流的结合Claude Code 和 Codex 都有 VS Code 扩展或终端集成方式。openrig 配置好之后可以进一步和编辑器工作流结合。比如在 VS Code 的 tasks.json 里定义一个任务启动前先执行 openrig use 切换配置再启动 Claude Code。{ version: 2.0.0, tasks: [ { label: Start Claude Code with work profile, type: shell, command: openrig use work claude, problemMatcher: [] } ] }这样在编辑器里一键就能用指定配置启动工具不用切到终端手动操作。对于需要频繁切换模型做对比测试的场景这个流程能省不少事。5.3 日志与调试信息的利用openrig 如果带日志功能一定要用起来。排查请求失败时日志里通常能看到完整的请求 URL、请求头、响应状态码和错误信息。这些信息比工具本身报的错要详细得多。建议在 YAML 里开启调试日志logging: level: debug file: ~/.openrig/logs/openrig.log遇到问题时先看日志大部分配置错误、认证失败、端点不可达都能从日志里直接定位。我排查 “cc switch local proxy failed” 这类问题时就是靠日志发现代理转发时请求头里的认证信息被覆盖了改了一下配置顺序就好了。5.4 后续可以扩展的方向openrig 这类工具如果继续演进有几个方向值得关注。一是支持更多 AI 编程工具不只是 Claude Code 和 Codex二是增加配置的加密存储避免 API Key 以明文环境变量形式存在三是提供 Web UI 做配置管理降低手动编辑 YAML 的门槛四是增加用量统计和成本追踪帮团队控制 API 开销。如果你现在就在用 openrig建议把配置纳入版本控制并且写一份简短的 README 说明每个 profile 的用途。这个习惯在团队协作时价值很大比任何文档都管用。我在实际使用中最大的体会是这类工具的价值不在于功能多强大而在于能不能让你少折腾配置、多写代码。openrig 如果能把 Claude Code 和 Codex 的配置统一管起来哪怕只省掉每天十分钟的切换时间长期来看也是值得的。配置这东西一次弄好后面就是纯收益。