1. openrig 到底是个什么东西第一次看到 openrig 这个名字很多人会以为是某个硬件外设或者机械臂项目毕竟 “rig” 这个词在硬件圈里太常见了。但如果你最近在折腾 Claude Code、Codex 这类终端 AI 编程助手又恰好被各种配置文件的路径、格式、字段名搞得头大那你大概率已经和它打过照面了——openrig 本质上是一套围绕 AI 编程工具链的配置组织方案核心载体就是 YAML 文件通过 npm 分发用来把 Claude Code、Codex 这些工具的模型接入、端点配置、环境变量统一管理起来。我最初接触它是因为一个很实际的问题我在本地同时跑 Claude Code 和 Codex前者要接本地模型后者要接远端端点两边的配置文件格式不一样、字段名不一样、存放路径也不一样。每次切换工具都要手动改一堆东西改错一个字段就报错报错信息还特别含糊。openrig 解决的正是这个痛点——用一份结构化的 YAML 把多个工具的配置集中描述再通过命令行工具生成各工具认识的配置文件。它适合谁三类人最需要一是同时使用多个 AI 编程助手的开发者二是需要在团队内统一配置规范的技术负责人三是想把本地模型接入 Claude Code 或 Codex 的折腾党。如果你只是偶尔用一下某个工具手动改改配置也能凑合但一旦工具数量超过两个、环境超过两台机器openrig 这类方案的价值就体现出来了。需要说明的是openrig 目前并不是一个官方标准更像是社区里逐渐形成的一套实践约定。不同人手里的 openrig 目录结构可能略有差异但核心思路是一致的配置与工具解耦一份源文件生成多份目标配置。理解了这一点后面所有的操作你都能自己想明白为什么这么做。2. 核心设计思路与方案选型拆解2.1 为什么用 YAML 而不是 JSON 或 TOML这是被问得最多的一个问题。JSON 不支持注释而配置文件里最需要的就是注释——你得写清楚这个字段是干什么的、为什么这么填、换环境时哪里要改。TOML 虽然支持注释但嵌套结构表达起来比较啰嗦尤其是当你要描述多个工具、多个模型、多个端点的时候层级会变得很深。YAML 的优势在于支持注释、层级直观、缩进即结构。对于 openrig 这种需要描述 “工具 → 模型 → 端点 → 参数” 多层关系的场景YAML 的可读性明显更好。当然 YAML 也有坑最大的坑就是缩进必须用空格不能用 Tab以及某些特殊字符需要引号包裹。我踩过的坑后面会专门讲。2.2 为什么通过 npm 分发npm 是前端和 Node.js 生态里最成熟的包管理工具安装一条命令搞定版本管理、依赖解析、全局命令注册都是现成的。openrig 选择 npm 分发意味着你只要有 Node.js 环境就能用npm install -g把它装到全局然后在任何目录下调用。对于已经装了 Claude Code 或 Codex 的人来说Node.js 环境本来就是必备的所以这个选择几乎没有额外成本。但 npm 在国内的网络环境下有个老问题默认源速度慢有时候直接超时。所以安装前配置国内镜像源几乎是标配操作这个后面实操部分会详细说。2.3 配置解耦带来的实际收益传统做法是每个工具各自维护自己的配置文件Claude Code 有它的配置Codex 有它的配置两边字段名还不一样。这种模式下有三个问题一是重复劳动同一个模型端点要在多个文件里各写一遍二是容易不一致改了 A 忘了改 B三是迁移困难换台机器要把散落各处的配置一个个找出来。openrig 的思路是把这些配置抽象成一份源文件工具只负责读取生成后的目标文件。这样你只需要维护一份源配置生成动作交给命令行完成。收益很直接改一处、生成多处、全环境一致。对于需要频繁切换模型或端点的场景这个收益尤其明显。3. 环境准备与安装实操3.1 Node.js 与 npm 环境确认在装 openrig 之前先确认你的 Node.js 和 npm 是正常的。打开终端执行node -v npm -v正常的话会输出两个版本号。如果提示 “command not found” 或者 “不是内部或外部命令”说明 Node.js 没装或者没配好环境变量。Windows 用户特别注意装完 Node.js 后要确认 npm 的路径已经加到系统 PATH 里否则会出现那种 “npm 不是内部或外部命令” 的经典报错。3.2 Windows 下 PowerShell 脚本执行策略问题这是 Windows 用户遇到频率最高的坑没有之一。报错长这样npm : 无法加载文件 C:\Program Files\nodejs\npm.ps1因为在此系统上禁止运行脚本原因不是 npm 坏了而是 PowerShell 默认的执行策略禁止运行 .ps1 脚本。解决办法是以管理员身份打开 PowerShell执行Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser然后输入 Y 确认。这个命令只影响当前用户不会动系统级设置相对安全。改完之后关掉终端重新打开npm 就能正常用了。注意不要图省事直接设成 UnrestrictedRemoteSigned 已经够用而且更稳妥。改完策略后如果还是报错检查一下是不是有多个 Node.js 安装路径冲突。3.3 配置 npm 国内镜像源默认源在国内访问经常慢到怀疑人生换成国内镜像源能快很多npm config set registry https://registry.npmmirror.com设置完可以用npm config get registry确认一下。如果哪天想换回官方源把地址改成https://registry.npmjs.org即可。这个设置是全局的对所有 npm 安装都生效。3.4 安装 openrig环境没问题之后安装就一条命令npm install -g openrig-g表示全局安装装完之后 openrig 命令在任何目录都能调用。装完验证一下openrig --version能输出版本号就说明装好了。如果提示命令找不到八成是 npm 全局 bin 目录没加到 PATH 里。用npm config get prefix看看全局目录在哪然后把这个目录下的 bin 子目录加到系统 PATH。4. openrig 配置文件结构详解4.1 目录组织约定openrig 的配置通常放在项目根目录下的.openrig/文件夹里核心文件是openrig.yaml。一个典型的目录结构是这样的项目根目录/ ├── .openrig/ │ ├── openrig.yaml # 主配置文件 │ ├── models.yaml # 模型定义可选拆分出来更清晰 │ └── endpoints.yaml # 端点定义可选 ├── .claude/ # Claude Code 生成的目标配置 └── .codex/ # Codex 生成的目标配置把模型和端点拆分成独立文件不是必须的但当配置项多起来之后拆开维护会舒服很多。openrig 支持通过include字段引入其他 YAML 文件这个机制后面会讲。4.2 主配置文件字段说明一份最小可用的openrig.yaml大概长这样version: 1 models: local-qwen: provider: openai-compatible base_url: http://127.0.0.1:1234/v1 model_name: qwen2.5-coder-7b api_key: not-needed remote-deepseek: provider: openai-compatible base_url: https://api.deepseek.com/v1 model_name: deepseek-chat api_key: ${DEEPSEEK_API_KEY} targets: claude-code: model: local-qwen output: .claude/settings.json codex: model: remote-deepseek output: .codex/config.yaml逐字段解释一下。version是配置格式版本目前用 1 就行。models下面定义所有可用的模型每个模型有provider、base_url、model_name、api_key四个核心字段。provider目前主流是openai-compatible因为绝大多数本地模型服务和云端 API 都兼容 OpenAI 的接口格式。api_key这里用了${DEEPSEEK_API_KEY}这种写法表示从环境变量读取。这是强烈推荐的做法永远不要把真实密钥硬编码在配置文件里尤其是这个文件要提交到 Git 仓库的时候。环境变量在运行时注入配置文件里只留占位符。targets定义要生成哪些工具的配置每个 target 指定用哪个模型、输出到哪个路径。openrig 会根据 target 类型自动转换成对应工具认识的格式。4.3 环境变量与密钥管理密钥管理这块值得单独说。除了用${VAR}引用环境变量openrig 还支持.env文件。在.openrig/目录下放一个.envDEEPSEEK_API_KEYsk-xxxxxxxxxxxx然后在.gitignore里把.env排除掉。这样本地开发方便又不会把密钥提交上去。团队协作时每个人维护自己的.env配置文件本身可以共享。注意.env文件不要用引号包裹值除非值里真的有空格。很多人习惯性加引号结果引号被当成值的一部分传进去导致认证失败排查半天。5. 从配置到生成完整实操流程5.1 初始化一个 openrig 项目在项目根目录执行openrig init这个命令会创建.openrig/目录和一份带注释的示例openrig.yaml。示例文件里把常用字段都列出来了你只需要按需修改。如果目录已存在它会提示你是否覆盖选否就行。5.2 配置本地模型接入 Claude Code这是热词里出现频率很高的场景。假设你用 LM Studio 在本地跑了一个模型服务地址是http://127.0.0.1:1234/v1模型名是qwen2.5-coder-7b。在openrig.yaml里这样写models: lmstudio-local: provider: openai-compatible base_url: http://127.0.0.1:1234/v1 model_name: qwen2.5-coder-7b api_key: lm-studio targets: claude-code: model: lmstudio-local output: .claude/settings.json然后执行生成命令openrig generateopenrig 会读取配置把lmstudio-local转换成 Claude Code 认识的格式写到.claude/settings.json。生成之后启动 Claude Code它就会用这个本地模型。这里有个细节LM Studio 的 API key 随便填一个非空字符串就行它不校验。但有些工具会检查 key 是否存在所以不能留空。我一般填lm-studio或者local。5.3 配置 Codex 接入远端端点Codex 的配置格式和 Claude Code 不一样但 openrig 帮你做了转换。假设要接 DeepSeektargets: codex: model: remote-deepseek output: .codex/config.yaml生成之后.codex/config.yaml里就是 Codex 认识的格式。这里要注意Codex 对模型名的支持有白名单机制某些模型名它会拒绝。热词里那个 “the gpt-5.6-sol model is not supported” 的报错就是这类问题——模型名不在支持列表里。解决办法是查一下当前 Codex 版本支持的模型名列表用列表里的名字。5.4 多环境配置切换实际工作中经常需要在本地模型和远端模型之间切换。openrig 支持用 profile 机制profiles: local: claude-code: model: lmstudio-local remote: claude-code: model: remote-deepseek生成时指定 profileopenrig generate --profile local这样一份配置就能覆盖多种场景不用来回改文件。切换成本从 “改配置 重启工具” 降到 “一条命令 重启工具”。6. 常见报错与排查技巧实录6.1 npm 相关报错速查报错信息根本原因解决办法npm.ps1 禁止运行脚本PowerShell 执行策略限制Set-ExecutionPolicy RemoteSignednpm 不是内部或外部命令PATH 未配置把 npm 全局目录加入 PATHERESOLVE overriding peer dependency依赖版本冲突加 --legacy-peer-deps 或检查版本安装超时默认源网络慢换国内镜像源全局包卸载不干净缓存残留npm cache clean --force 后重装6.2 YAML 格式报错排查YAML 的报错信息通常很含糊只说 “解析失败” 不告诉你哪一行。我的排查顺序是先看缩进确认全部用空格且层级对齐再看特殊字符冒号后面如果有值要加空格值里如果有冒号要加引号最后看 Tab用编辑器显示不可见字符把所有 Tab 替换成空格。一个特别隐蔽的坑YAML 里yes、no、on、off会被解析成布尔值而不是字符串。如果你的某个字段值恰好是这些词必须加引号。我见过有人把模型名写成on结果被解析成true排查了半天。6.3 模型接入类报错“cc switch local proxy failed while handling codex endpoint /responses” 这类报错通常是端点路径不对。OpenAI 兼容接口的路径一般是/v1/chat/completions但有些工具会请求/responses这种不同的路径。检查你的base_url是否包含了正确的版本前缀以及工具本身请求的路径是什么。“your organization has disabled claude subscription access” 这类报错和配置无关是账号权限问题需要检查订阅状态不是 openrig 能解决的。6.4 生成后工具不生效生成完配置后工具没反应按这个顺序查一是确认生成的目标文件路径和工具实际读取的路径一致有些工具读的是用户目录下的全局配置而不是项目目录二是确认生成后重启了工具很多工具只在启动时读一次配置三是确认环境变量在工具的运行环境里可见IDE 里启动的终端可能不继承你 shell 里设的环境变量。提示排查配置问题时先用openrig generate --dry-run看看会生成什么内容不实际写文件。确认无误再去掉 dry-run。这个习惯能省很多来回折腾的时间。7. 我踩过的坑和几条实用建议第一个坑是路径问题。openrig 生成的目标路径默认相对于执行命令时的当前目录如果你在子目录里执行生成的文件就跑到子目录去了。我的做法是始终在项目根目录执行或者在配置里用绝对路径。第二个坑是环境变量加载顺序。.env文件里的变量和系统环境变量同名时谁覆盖谁取决于实现。我的经验是系统环境变量优先级更高所以调试时如果发现值不对先检查系统里是不是有同名变量。第三个坑是版本升级。openrig 这类工具迭代快配置格式可能变。升级前先备份openrig.yaml升级后跑一次openrig validate检查配置是否还兼容。如果报格式错误对照新版本的示例文件改。关于密钥再强调一次不要提交到仓库。我见过太多人图方便把 key 写在配置里然后 push 上去结果被扫描到只能紧急轮换。用环境变量或者.env.gitignore多花两分钟省一堆麻烦。最后分享一个提效技巧把openrig generate挂到 npm scripts 里比如在package.json里加一行rig: openrig generate以后npm run rig就能生成配置。再配合文件监听改完 YAML 自动重新生成整个流程就顺了。这套东西搭好之后切换模型和端点基本就是改一行配置的事比手动维护多个配置文件舒服太多。