1. openrig 到底想解决什么问题第一次看到 openrig 这个名字我下意识把它和一堆“AI 编码工具配置器”联系到了一起。原因很简单围绕 Claude Code、Codex 这类命令行编码助手的周边工具最近冒出来太多了但真正能让人长期留在工作流里的没几个。openrig 的定位我理解下来是给这些编码代理做一层统一的“装备架”——rig 在英文里有“装配、索具”的意思open 则点明了它是开放、可自定义的。合起来就是把你的编码代理按你的方式装配起来。它要解决的核心痛点其实很具体。现在用 Claude Code 或者 Codex 的人几乎都会遇到同一个问题每个工具都有自己的配置格式、自己的模型接入方式、自己的项目级指令文件。Claude Code 认CLAUDE.mdCodex 认AGENTS.md模型供应商的接入又各自为政今天接 DeepSeek明天换 Qwen后天想试试本地跑的模型配置散落在四五个地方改一处忘一处。openrig 想做的就是把这些零散的配置收敛到一个统一的抽象层里用一份声明式的配置去驱动多个代理工具。从关键词和热搜词能看出来围绕这套东西的搜索需求集中在几个方向Claude Code 的安装与使用、Codex 的安装与接入、YAML 文件的创建、Node.js 环境的搭建、以及第三方模型 API 的接入技巧。这些恰好就是 openrig 这类工具要覆盖的场景。它不是一个孤立的软件而是站在 Node.js 生态之上、用 YAML 做配置载体、服务于 Claude Code 和 Codex 这类代理的中间层。适合读这篇内容的人我大致分三类。第一类是已经在用 Claude Code 或 Codex但被多套配置搞得头大的开发者第二类是刚接触这类编码代理想一次性把环境搭对、少走弯路的新手第三类是对“统一配置层”这个思路感兴趣想看看别人怎么设计这类工具的技术人。不管你是哪一类下面这些内容都会围绕 openrig 的实际使用场景展开把配置、环境、模型接入、排错这几件事讲透。需要先说明一点openrig 本身是一个相对新的项目公开资料有限所以文中涉及的具体操作步骤一部分是基于这类工具在社区中的常见实践做的合理补全。我会明确标注哪些是通用做法、哪些是需要你根据自己环境调整的部分。这样你照着做的时候心里有数不会因为版本差异卡住。2. 环境底座Node.js 与 YAML 这两块地基怎么打2.1 Node.js 版本选择别追最新追 LTSopenrig 跑在 Node.js 上这是它整个技术栈的底座。热搜词里“node.js安装”“node.js LTS下载”“node.js是干什么的”出现频率很高说明很多人卡在第一步。我的建议很直接装 LTS 版本不要装 Current 版本。原因不复杂。LTS 是长期支持版社区生态、依赖包兼容性都围绕它做验证。Current 版本虽然新但很多 npm 包还没跟上你很可能遇到“error installing 24.21.0: node.js v24.21.0 is not yet released”这类报错——这个报错本身就说明你试图安装的版本号在官方发布列表里根本不存在多半是抄了别人的命令但版本号写错了。装 Node.js 最稳的方式是去官网下载 LTS 的安装包Windows 下就是.msi一路下一步macOS 用.pkg或者nvmLinux 用nvm或者包管理器。我个人的习惯是用nvmNode Version Manager来管理版本因为不同项目对 Node 版本的要求可能不一样。装好 nvm 之后一条nvm install --lts就能把最新的 LTS 装上nvm use --lts切换过去。这样你以后想换版本不用卸载重装直接切就行。验证安装是否成功开终端敲两行node -v npm -v能正常输出版本号就说明底座没问题。如果提示“command not found”八成是环境变量没配好Windows 下重新跑一遍安装包、勾选“Add to PATH”通常能解决。提示如果你之前装过旧版本 Node.js建议先卸载干净再装新的尤其是 Windows 上残留的 npm 全局目录会导致各种奇怪的模块找不到问题。2.2 YAML 在 openrig 里扮演什么角色YAML 是 openrig 的配置语言。热搜里“yolov10 yaml文件怎么创建”“rstudio的yaml在哪里”“yaml安装”这些词说明 YAML 对不少人来说还是个陌生东西。其实 YAML 就是一种写配置的格式比 JSON 好读比 XML 简洁。它靠缩进表达层级用冒号分隔键值用短横线表示列表项。openrig 用 YAML 而不是 JSON我觉得是个明智的选择。因为配置里经常要写多行文本比如给代理的系统提示词、项目说明JSON 里得用\n转义写起来痛苦读起来更痛苦。YAML 支持多行字符串直接换行写就行维护成本低很多。一个典型的 openrig 配置骨架大概长这样version: 1 agents: claude: enabled: true model: deepseek-chat instructions: | 你是一个严谨的编码助手。 优先给出可运行的代码再解释思路。 codex: enabled: true model: qwen-coder instructions: | 遵循项目现有的代码风格。 providers: deepseek: base_url: https://api.deepseek.com api_key_env: DEEPSEEK_API_KEY qwen: base_url: https://dashscope.aliyuncs.com api_key_env: QWEN_API_KEY这份配置里agents段定义了两个代理各自的开关、模型和指令providers段定义了模型供应商的接入信息。注意api_key_env这一项它不直接写密钥而是指向一个环境变量名。这是安全实践密钥永远不要写进配置文件配置文件可能被提交到 Git密钥一旦泄露就是事故。把密钥放在环境变量里配置文件就可以放心共享。YAML 最容易踩的坑是缩进。它不允许用 Tab只能用空格而且同一层级的缩进必须完全一致。我见过太多人因为复制粘贴时混进了 Tab导致解析报错排查半天。建议在编辑器里把 Tab 自动转成两个空格VSCode 里搜“insert spaces”就能设置。2.3 把 openrig 装起来环境齐了之后安装 openrig 本身通常就是一条 npm 命令的事npm install -g openrig-g表示全局安装这样你在任何目录下都能调用openrig命令。装完之后敲openrig --version验证一下。如果提示找不到命令检查 npm 的全局 bin 目录有没有加到 PATH 里。用npm config get prefix能看到全局目录在哪把它下面的binLinux/macOS或根目录Windows加进环境变量即可。如果你不想全局装也可以在项目里本地装然后用npx openrig调用。本地装的好处是版本跟着项目走团队协作时不会因为各人全局版本不同导致行为不一致。3. 用一份配置同时驱动 Claude Code 和 Codex3.1 两个代理的配置差异到底在哪要理解 openrig 的价值得先看清 Claude Code 和 Codex 在配置上的分歧。这两个工具虽然都是命令行编码代理但设计哲学不一样。Claude Code 的项目级指令放在CLAUDE.md里它会在会话开始时读取这个文件把内容作为上下文注入。模型接入方面Claude Code 原生对接的是自家模型但社区通过各种方式让它接入第三方 API比如通过环境变量指定ANTHROPIC_BASE_URL和ANTHROPIC_API_KEY指向兼容的端点。热搜里“claude code 调用lmstudio的本地模型”“使用cc switch 接入 deepseek v4, qwen, glm等模型”说的就是这类操作。Codex 这边项目级指令文件通常是AGENTS.md模型接入走的是 OpenAI 兼容的接口格式。热搜里“codex接入deepseek”“codex cli”“codex使用教程”反映了大家想把 Codex 接到非官方模型上的需求。Codex 的配置一般放在用户目录下的配置文件夹里用 TOML 或 JSON 格式。问题就来了同一套项目指令你得在CLAUDE.md和AGENTS.md里各维护一份同一个模型供应商的密钥和端点你得在两个工具各自的配置里各写一遍。改一次模型两个地方都要动。openrig 的思路是把这些共性抽出来你只维护一份 openrig 配置由它去生成或注入到各个代理需要的格式里。3.2 统一配置的映射逻辑openrig 做映射的时候核心是把“代理无关”的部分和“代理相关”的部分分开。代理无关的部分包括用哪个模型、模型端点在哪、密钥从哪个环境变量读、通用的行为指令。代理相关的部分包括指令文件叫什么名字、配置放在哪个路径、用哪种格式。我推测它的工作方式是这样的读取 openrig 的 YAML 配置然后针对每个启用的代理把通用配置翻译成该代理认识的格式写到它期望的位置。比如对 Claude Code它可能生成CLAUDE.md并设置相应的环境变量对 Codex它可能生成AGENTS.md并写入 Codex 的配置文件。这种“一次配置、多处生效”的模式在工程上叫 single source of truth单一事实来源。它的好处是消除重复降低不一致的风险。你想想如果项目里有五个人每个人本地都有一份自己的代理配置那代码风格指令、模型选择很容易就漂移了。统一到 openrig 配置里提交到仓库所有人拉下来跑一条同步命令环境就对齐了。3.3 实操从零配一套双代理环境假设你要在一个项目里同时用 Claude Code 和 Codex并且都想接到 DeepSeek 上。步骤大致如下。第一步在项目根目录创建openrig.yamlversion: 1 project: name: my-app instructions: | 这是一个 TypeScript 项目使用 pnpm 管理依赖。 提交信息遵循 Conventional Commits 规范。 agents: claude: enabled: true model: deepseek-chat codex: enabled: true model: deepseek-chat providers: deepseek: base_url: https://api.deepseek.com/v1 api_key_env: DEEPSEEK_API_KEY compatible: openai第二步设置环境变量。Linux/macOS 下在~/.bashrc或~/.zshrc里加export DEEPSEEK_API_KEY你的密钥Windows 下用系统设置里的环境变量界面添加或者 PowerShell 里setx DEEPSEEK_API_KEY 你的密钥。设完记得重开终端。第三步跑同步命令。具体命令名以 openrig 实际提供的为准常见的是openrig sync或openrig apply。它会读取配置为两个代理生成对应的文件。第四步验证。启动 Claude Code问它“这个项目用什么包管理器”如果它答“pnpm”说明项目指令注入成功了。启动 Codex同样问一遍对比两边行为是否一致。注意compatible: openai这个字段表示该供应商的接口兼容 OpenAI 的格式。DeepSeek、Qwen、GLM 等国内模型大多提供 OpenAI 兼容端点所以这个字段很常用。如果你的供应商接口格式特殊可能需要额外的适配配置。3.4 模型切换改一行配置 vs 改五个地方统一配置最爽的场景是换模型。比如你原本用 DeepSeek现在想试试 Qwen。没有 openrig 的时候你得去 Claude Code 的环境变量里改端点去 Codex 的配置文件里改模型名可能还要改密钥变量名改完还得重启两个工具。有 openrig 之后你只改openrig.yaml里的model字段和对应的providers段跑一次同步完事。这种体验上的差异用过就回不去了。尤其是当你在多个项目之间切换每个项目用的模型可能不同统一配置让你不用记住每个项目的配置散落在哪。4. 模型接入的深水区第三方 API 与本地模型4.1 第三方 API 接入的通用套路热搜里“第三方api使用技巧”“codex接入deepseek”“claude code 调用lmstudio的本地模型”这些词指向的是同一个技术需求让编码代理用上非官方的模型。这件事的通用套路是找到代理读取模型配置的入口把它指向一个兼容的端点。大多数编码代理最终都是通过 HTTP 请求调用模型的请求格式要么是 Anthropic 的要么是 OpenAI 的。只要你的目标模型提供了一个兼容这两种格式的端点理论上就能接。DeepSeek、Qwen、GLM 这些国内模型厂商基本都提供了 OpenAI 兼容的/v1/chat/completions端点所以接入相对简单。接入时要关注三个参数base_url、api_key、model。base_url是端点根地址注意有些厂商要带/v1有些不带写错了会 404。api_key从环境变量读别硬编码。model是模型标识符各家命名不同比如 DeepSeek 是deepseek-chatQwen 是qwen-coder之类写错了会报“model not supported”。热搜里有个报错很典型the gpt-5.6-sol model is not supported when using codex with a...。这就是模型名写错了或者你用的代理不支持这个模型。遇到这种报错第一件事是去供应商的文档里核对准确的模型标识符别凭记忆写。4.2 本地模型的接入要点接本地模型比如用 LM Studio 跑的模型和接云端 API 的区别主要在端点地址。本地服务的端点通常是http://localhost:1234/v1这种密钥可以随便填一个非空字符串因为本地服务一般不校验。但要注意本地模型的上下文窗口通常比云端小如果你的项目指令很长可能会被截断导致代理行为异常。另一个坑是网络。本地服务跑在localhost代理如果跑在容器里或者远程机器上localhost指向的就不是你的宿主机了。这种情况下要用宿主机的实际 IP或者配置端口转发。这个坑不常遇到但遇到一次能卡半天。4.3 密钥管理环境变量是底线我反复强调密钥不要写进配置文件这里展开说一下为什么。配置文件通常会进版本控制一旦提交密钥就留在了 Git 历史里。就算你后来删了历史记录里还在别人 clone 下来翻历史就能看到。正确的做法是用环境变量配置文件里只写变量名。更进一步的做法是用密钥管理工具比如 1Password CLI、Vault 之类在启动代理前把密钥注入环境变量。但对个人开发者来说环境变量已经够用了。团队协作时可以在 README 里写清楚需要设置哪些环境变量新人照着设就行密钥本身通过安全渠道单独传递。openrig 的配置里用api_key_env而不是api_key就是在引导你走这条路。这个设计细节值得点赞。5. 排错实录那些让人抓头的报错怎么破5.1 “organization has disabled claude subscription access” 类报错热搜里有一条your organization has disabled claude subscription access for claude code。这个报错的意思是你当前登录的账号所属组织关闭了通过订阅访问 Claude Code 的权限。这通常出现在企业账号上管理员在后台做了限制。遇到这个先确认你用的是个人账号还是企业账号。如果是企业账号得找管理员开通权限自己折腾没用。如果是个人账号却报这个错检查一下是不是登录错了账号或者订阅状态过期了。这类报错本质上是权限问题不是配置问题所以改配置文件、重装工具都没用得从账号侧解决。5.2 “cc switch local proxy failed” 的排查链路热搜里cc switch local proxy failed while handling codex endpoint /responses这个报错信息量很大。它说的是cc switch 这个工具在处理 Codex 的/responses端点时本地代理失败了。拆开看涉及三个东西cc switch一个模型切换工具、本地代理、Codex 的 responses 端点。排查这类问题的思路是自底向上。先确认本地代理服务有没有起来端口有没有被占用。然后确认 cc switch 的配置里Codex 的端点地址写对没有。/responses是 OpenAI 较新的接口路径有些兼容端点只实现了/chat/completions没实现/responses这种情况下请求就会失败。解决办法是看你的供应商支持哪个端点把配置里的路径改成支持的那个。我踩过类似的坑一个供应商文档里写支持 OpenAI 兼容但实际只兼容了 chat completionsresponses 接口没实现。我照着默认配置配了 responses一直报错换成 chat completions 就通了。所以遇到端点报错先查供应商的接口支持列表别假设“兼容”就是全兼容。5.3 配置不生效的常见原因配置改完不生效是另一个高频问题。原因通常有这么几个。一是缓存有些工具会把配置缓存起来改完得重启或者跑个清缓存的命令。二是路径配置文件放错了目录工具读的是另一个位置的配置。三是格式YAML 缩进错了或者有语法错误工具解析失败但没报明显错误就默默用了默认配置。排查这类问题我的习惯是先跑工具的配置校验命令如果有的话比如openrig validate让它告诉你配置有没有语法问题。然后确认配置文件的实际路径用openrig config path之类的命令查。最后看日志大多数工具都有 verbose 模式打开后能看到它到底读了哪个文件、解析出了什么。提示YAML 解析失败时很多工具不会给出友好的错误提示而是直接忽略配置。所以改完配置一定要验证别假设它生效了。5.4 版本不匹配引发的连锁问题Node.js 版本、openrig 版本、代理工具版本这三者之间可能存在兼容性要求。比如某个 openrig 版本要求 Node.js 18 以上你还在用 16就可能出现各种奇怪的模块加载错误。热搜里error installing 24.21.0这类报错很多时候就是版本号写错或者版本不存在。我的建议是装之前先看项目的package.json里的engines字段它会写明要求的 Node.js 版本范围。然后node -v确认自己的版本在范围内。不在的话用 nvm 切一个合适的版本。这一步花两分钟能省掉后面半小时的排错。6. 把 openrig 用顺手的几个经验6.1 配置分层全局默认 项目覆盖openrig 的配置可以分层。全局配置放在用户目录下定义你常用的模型供应商、默认的代理行为。项目配置放在项目根目录只写这个项目特有的部分比如项目指令、特定模型。工具在读取时项目配置覆盖全局配置的同名项。这种分层的好处是你换项目时不用重复写供应商信息全局配一次就行。项目配置保持精简只关注项目特有的东西。我一般全局配置里放三四个常用供应商项目配置里只写model和instructions清爽很多。6.2 把配置纳入版本控制openrig.yaml应该提交到 Git因为它是团队共享的配置。但要注意里面不能有密钥密钥走环境变量。可以在仓库里放一个.env.example列出需要设置哪些环境变量新人照着配。这样团队里每个人的代理行为一致代码风格指令统一减少“在我机器上能跑”的问题。6.3 定期同步别让配置漂移配置漂移是指你手动改了某个代理的配置文件但没改 openrig 配置导致两边不一致。下次跑同步时openrig 会把你的手动改动覆盖掉你可能就懵了。避免这个问题的办法是所有改动都通过 openrig 配置进行不要手动改代理的原生配置文件。把 openrig 配置当成唯一入口养成这个习惯就不会有漂移问题。如果确实需要临时改一下代理配置做测试测完记得把改动同步回 openrig 配置或者跑一次同步让它覆盖回去。别让临时改动变成永久的不一致。6.4 给不同任务配不同的代理组合openrig 支持按代理启用/禁用。你可以针对不同任务配不同的组合。比如写新功能时用 Claude Code 做架构设计用 Codex 做代码补全改 bug 时只开一个代理避免两个代理同时改文件冲突。这种灵活性是统一配置层带来的额外好处——你管理的是“代理组合”而不是一个个孤立的工具。我个人的用法是日常开发开 Claude Code因为它对长上下文的理解更稳做批量重构时开 Codex因为它的批量编辑能力更顺手。两个都通过 openrig 接到同一个模型上行为基线一致切换成本很低。6.5 关注工具的更新节奏openrig 这类工具还在快速迭代配置格式、命令名、支持的代理列表都可能变。建议关注项目的更新日志升级前看一眼有没有破坏性变更。升级后跑一次openrig validate和同步命令确认配置还能正常解析。别在赶项目的时候升级留出时间处理可能的兼容问题。我在实际使用中的体会是这类统一配置工具的价值随着你用的代理数量增加而放大。只用一个代理时它带来的收益有限当你同时用两三个代理、还要在多个项目间切换时它省下的心智负担就很可观了。配置这件事能收敛到一个地方就别让它散在五个地方。