1. 从"openrig"这个名字说起：它到底想解决什么问题
第一次看到openrig这个词，我下意识把它拆成了两半：open和rig。rig在工程语境里通常指"装配好的成套设备"或者"工作台"，比如矿机叫 mining rig，直播那套声卡加麦克风加补光灯的组合也叫 streaming rig。所以openrig直译过来就是"开放的工作台"或者"开放装配架"。结合热搜词里密集出现的 Claude Code、Codex、YAML、npm 这些关键词，我基本能判断出这个项目的定位：它大概率是一个把 AI 编程助手（Claude Code、Codex 这类 CLI 工具）的配置、模型接入、环境依赖统一管理起来的开源脚手架或配置框架。
为什么我会有这个判断？因为热搜词里有一组非常典型的"痛点信号"：cc switch local proxy failed while handling codex endpoint /responses、your organization has disabled claude subscription access for claude code、codex接入deepseek、claude code 调用lmstudio的本地模型。这些词单独看是零散报错，串起来看就是一条完整的故事线——用户想在一个统一的环境里切换不同的 AI 编程后端（Claude Code、Codex、本地模型），但配置分散、依赖冲突、代理转发失败，最后卡在半路。openrig要做的，就是把这些散落的东西"装配"到一个可复现的架子上。
这篇文章我打算按"一个真实从业者从零搭起 openrig 这套工作台"的思路来写。不管你是刚装完 Node 就想跑 Claude Code 的新手，还是已经被 npm 的 peer dependency 警告折磨过几轮的老手，都能从里面找到能直接抄的配置和能避开的坑。核心关键词我会自然穿插进去：openrig、Claude Code、Codex、YAML、npm，以及那一堆安装和配置相关的热搜问题。
先说结论：openrig 这类项目的价值不在于它写了多少代码，而在于它把"环境一致性"这件事从口头约定变成了可执行的配置文件。你换一台机器、换一个同事、换一个模型供应商，只要openrig的 YAML 和 npm 脚本还在，整个工作台就能一键重建。这才是它真正解决的问题。
2. openrig 的核心构成：YAML 配置层与 npm 依赖层怎么分工
要理解 openrig，得先理解它为什么同时依赖 YAML 和 npm 这两样东西。很多人会疑惑：一个配置工具，为什么不用 JSON 或者纯 JS 对象，非要上 YAML？为什么还要走 npm 分发？这两个问题回答清楚了，整个项目的骨架就清楚了。
2.1 为什么配置层选 YAML 而不是 JSON
YAML 和 JSON 在表达能力上其实是等价的，但在这个场景下 YAML 有三个 JSON 比不了的优势。
第一是注释。AI 编程助手的配置里充满了"为什么这么设"的信息，比如某个模型要设max_tokens: 8192是因为上下文窗口限制，某个 endpoint 要加超时是因为本地模型冷启动慢。JSON 不支持注释，这些知识只能写在文档里，而文档和配置一旦分离就会不同步。YAML 允许你直接在配置项旁边写# 本地模型冷启动约 15s，超时设 30s，配置即文档。
第二是多环境切换。openrig 要管理 Claude Code、Codex、本地模型好几套后端，每套后端的 endpoint、鉴权方式、模型名都不一样。YAML 的锚点和引用（&anchor和*alias）能让你定义一份基础配置，然后各环境只覆盖差异部分。JSON 要做同样的事，得靠工具层自己实现合并逻辑，复杂度高一个量级。
第三是可读性。当配置嵌套三层以上，JSON 的括号和引号会让人眼花，YAML 的缩进结构在编辑器里折叠起来一目了然。热搜词里yolov10 yaml文件怎么创建、rstudio的yaml在哪里这些搜索，本质上都是同一类需求——人们希望配置是"看得懂、改得动"的。
一个典型的 openrig 配置骨架大概长这样：
# openrig.yaml version: 1 defaults: timeout: 30000 retries: 2 providers: claude: type: cli command: claude env: ANTHROPIC_API_KEY: ${CLAUDE_KEY} codex: type: cli command: codex endpoint: /responses local: type: openai-compatible base_url: http://127.0.0.1:1234/v1 model: local-model profiles: dev: provider: local overrides: timeout: 60000 # 本地模型慢，单独放宽 prod: provider: claude这份配置里，providers定义"有哪些后端可用"，profiles定义"在什么场景用哪个后端"。切换环境只需要改profiles里的引用，不用动 provider 本身的定义。这就是 YAML 锚点思路的简化版，实际项目里会用<<: *base做继承。
2.2 npm 在这里扮演的角色：不只是包管理器
很多人以为 npm 就是个下载依赖的工具，但在 openrig 这类项目里，npm 承担了三个职责。
第一是分发。npm install -g openrig或者npx openrig让用户不用 clone 仓库就能用上，这是开源工具触达用户的最短路径。热搜里发布npm包、npm安装、npm镜像源地址这些词，说明大量用户卡在"怎么把这个工具装到本地"这一步。
第二是脚本编排。openrig 的启动、配置校验、环境检查这些动作，通过package.json的scripts字段暴露出来：
{ "name": "openrig", "bin": { "openrig": "./bin/cli.js" }, "scripts": { "check": "node ./scripts/check-env.js", "validate": "node ./scripts/validate-yaml.js", "start": "node ./bin/cli.js" } }用户跑npm run check就能知道自己的 Node 版本、CLI 工具是否就位、YAML 是否合法。这种"把运维动作脚本化"的做法，比写一堆 README 步骤可靠得多。
第三是依赖锁定。openrig 依赖的 YAML 解析库、CLI 参数解析库、HTTP 客户端，版本一旦漂移就可能出问题。package-lock.json把整棵依赖树钉死，保证今天能跑的环境下个月还能跑。热搜里npm warn eresolve overriding peer dependency这个警告，恰恰说明依赖版本管理是真实痛点——peer dependency 冲突往往意味着两个库对同一个底层库的版本要求不一致，openrig 通过锁定版本把这类问题挡在门外。
2.3 两层如何协作：一个完整的加载流程
把 YAML 层和 npm 层串起来看，openrig 启动时的流程是这样的：
- npm 根据
package.json确保依赖就位，bin字段把openrig命令注册到全局 - 执行
openrig时，CLI 入口读取openrig.yaml - YAML 解析器把配置转成 JS 对象，校验必填字段
- 根据当前 profile 选出 provider，拼出实际要执行的命令或 HTTP 请求
- 执行结果回传，错误按配置里的 retry 策略重试
这个流程里，YAML 负责"声明想要什么"，npm 负责"保证有能力做到"。两者缺一不可。理解了这层分工，后面配置出问题时你就能快速定位：是声明写错了（YAML 层），还是能力没就位（npm 层）。
3. 环境搭建实录：从 Node 安装到 openrig 跑起来
这一节我按真实操作顺序走一遍，把热搜里高频出现的安装问题都覆盖到。假设你是一台干净的机器，什么都没装。
3.1 Node 与 npm 的安装，以及那个经典的 PowerShell 报错
第一步装 Node。官网下载 LTS 版本，一路下一步即可。装完后打开终端验证：
node -v npm -v如果你在 Windows 上看到这样的报错：
npm : 无法加载文件 C:\Program Files\nodejs\npm.ps1，因为在此系统上禁止运行脚本别慌，这不是 npm 坏了，是 PowerShell 的执行策略默认禁止运行.ps1脚本。热搜里npm : 无法加载文件 d:\program files\nodejs\npm.ps1和c:\program files\nodejs\npm.ps1两个变体，说的都是同一件事。解决办法有两个：
- 临时方案：改用 CMD 而不是 PowerShell，CMD 不受这个策略限制
- 长期方案：以管理员身份打开 PowerShell，执行
Set-ExecutionPolicy RemoteSigned -Scope CurrentUser，然后输入Y确认
我个人的建议是走长期方案，因为现在很多工具链默认调 PowerShell，改一次省心很久。RemoteSigned的含义是"本地脚本可运行，从网络下载的脚本需要签名"，安全性和便利性平衡得比较好。
还有一个高频问题是node安装后npm不能用。这种情况九成是PATH 环境变量没配好。Node 安装器通常会自动加，但如果你用的是解压版或者手动改过安装路径，就得手动加。Windows 上把 Node 安装目录（含npm.cmd的那层）加到系统 PATH；macOS/Linux 上确认/usr/local/bin或 nvm 的 shim 目录在 PATH 里。验证方法：which npm（macOS/Linux）或where npm（Windows），能输出路径就对了。
3.2 npm 国内源配置：别让下载卡住整个流程
装完 Node 后第一件事，我建议先把 npm 源换成国内镜像。不是崇洋媚外的问题，是默认源在国内网络下经常几十 KB/s，装个稍微大点的依赖能等到怀疑人生。
npm config set registry https://registry.npmmirror.com npm config get registry # 验证热搜里npm镜像源地址、npm 国内源、npm镜像都是这个需求。注意registry.npmmirror.com是当前推荐的地址，老的registry.npm.taobao.org已经停止维护，别再用了。
换源之后如果遇到npm install -g pnpm报错或者npm install 提示 error: cannot find module '@npmcli/config'，大概率是 npm 自身版本和 Node 不匹配。@npmcli/config是 npm 的内部模块，找不到它通常意味着 npm 安装不完整。修复方式：
npm install -g npm@latest如果还不行，用 Node 版本管理器（nvm 或 fnm）重装一个干净的 Node，比在坏掉的 npm 上修修补补快得多。
3.3 安装 openrig 与验证环境
环境就绪后，安装 openrig：
npm install -g openrig # 或者不全局安装，直接用 npx openrig --version装完跑一次环境自检：
openrig check这个命令会检查：Node 版本是否满足、YAML 配置文件是否存在且合法、配置里引用的 CLI 工具（claude、codex）是否在 PATH 里、本地模型的 endpoint 是否可达。这一步是整个流程里最值得花时间的，因为它把后面可能出现的报错提前暴露了。
我踩过的一个坑：openrig check报某个 CLI 找不到，但其实那个工具装了，只是装在了一个没进 PATH 的目录。这时候别急着重装，先which claude看看能不能找到，找不到就把它的安装目录加进 PATH。热搜里npm环境变量path配置说的就是这个。
3.4 依赖冲突：peer dependency 警告要不要管
安装过程中你大概率会看到：
npm warn eresolve overriding peer dependency这个警告的含义是：A 包要求 B 包的版本是 1.x，但 C 包要求 B 包是 2.x，npm 选了其中一个版本，另一个的期望被"覆盖"了。大多数情况下这个警告可以忽略，因为现代 npm（v7 以后）会自动安装 peer dependency 并尽量找兼容版本。但如果安装后运行报错说某个模块版本不对，那就得处理了。
处理思路：先看警告里点名的是哪两个包，然后：
npm ls <冲突的包名> # 看谁在依赖它如果是直接依赖冲突，在package.json里用overrides字段强制统一版本：
{ "overrides": { "冲突的包名": "2.0.0" } }如果是间接依赖冲突且不影响功能，直接忽略。我的经验是：警告归警告，能跑起来就别折腾，过度追求零警告反而容易引入新问题。
4. 把 Claude Code 和 Codex 接进 openrig 的配置细节
环境搭好后，重头戏是配置。这一节讲怎么在 openrig 里把 Claude Code、Codex 和本地模型都接上，以及切换时容易出什么问题。
4.1 Claude Code 的接入与订阅权限问题
Claude Code 是一个命令行 AI 编程助手，安装方式通常是：
npm install -g @anthropic-ai/claude-code装完在 openrig 的 YAML 里声明：
providers: claude: type: cli command: claude args: ["--print"] env: ANTHROPIC_API_KEY: ${CLAUDE_KEY}这里env里的${CLAUDE_KEY}是从系统环境变量读取的，不要把密钥硬编码进 YAML。openrig 在加载配置时会做变量替换，找不到对应环境变量就报错，这是有意设计的安全机制。
热搜里your organization has disabled claude subscription access for claude code这个报错，说的是账号层面的订阅权限被组织管理员关闭了。这不是配置问题，是账号问题，openrig 层面无法绕过。遇到这个只能换账号或者联系管理员。我提这个是想说明：配置工具能解决"怎么连"，但解决不了"有没有权限连"，这两类问题要分开看。
另一个常见需求是claude code 调用lmstudio的本地模型。思路是把 Claude Code 的请求指向本地 OpenAI 兼容接口。在 openrig 里可以这样配：
providers: claude-local: type: cli command: claude env: ANTHROPIC_BASE_URL: http://127.0.0.1:1234 ANTHROPIC_API_KEY: dummy-key本地模型不需要真实密钥，但很多客户端要求这个字段非空，填个占位符即可。LM Studio 默认端口是 1234，确认它开了 OpenAI 兼容模式再连。
4.2 Codex 的接入与 endpoint 转发失败排查
Codex 的接入逻辑类似，但热搜里cc switch local proxy failed while handling codex endpoint /responses这个报错值得单独讲。这个错误的字面意思是：在切换本地代理时，处理 Codex 的/responses端点失败了。
拆解一下：Codex 的 API 路径是/responses，openrig 或某个中间层在做请求转发时，没能正确处理这个路径。可能的原因有三类：
| 可能原因 | 表现 | 排查方法 |
|---|---|---|
| 路径拼接错误 | 请求发到了/v1/responses但服务端只认/responses | 抓包看实际请求 URL |
| 代理未启动 | 连接被拒绝 | curl直接测 endpoint |
| 鉴权头丢失 | 返回 401/403 | 检查转发时 header 是否透传 |
我的排查顺序是：先用curl直接打目标 endpoint，确认服务本身是通的；再通过 openrig 走一遍，对比两次请求的差异。大部分转发失败都是路径或 header 的问题，而不是网络问题。
Codex 接入第三方模型（比如codex接入deepseek）时，核心是改 base_url 和 model 名：
providers: codex-deepseek: type: cli command: codex env: OPENAI_BASE_URL: https://api.deepseek.com OPENAI_API_KEY: ${DEEPSEEK_KEY} model: deepseek-chat注意不同供应商的模型名不一样，填错了会返回"模型不存在"，这个报错很直白，照着文档改就行。
4.3 多后端切换：profile 机制怎么用才不混乱
openrig 的 profile 机制是为了解决"同一个工具在不同场景连不同后端"的问题。比如：
- 写业务代码时用 Claude Code（理解力强）
- 跑批量重构时用 Codex（速度快）
- 处理敏感数据时用本地模型（不出网）
配置上：
profiles: daily: provider: claude batch: provider: codex private: provider: local切换命令：
openrig use daily openrig use private这里有个经验：profile 名字要按"使用场景"命名，不要按"模型名"命名。因为模型会换，场景不会。你今天用 Claude，明天可能换成别的，但"日常编码"这个场景一直在。按场景命名，配置的寿命长得多。
还有一个坑：多个 profile 共享同一个 provider 时，如果某个 profile 改了 provider 的字段，可能影响其他 profile。openrig 的处理方式是 profile 里的overrides只作用于当前 profile，不改动 provider 本体。理解这一点，配置就不会互相污染。
5. 那些绕不开的报错：从排查链路到修复
这一节专门讲踩坑。我把热搜里出现的报错按"排查链路"组织，而不是直接给答案，因为排查思路比答案更值钱。
5.1 npm 脚本执行被禁止：从现象到根因
现象：Windows PowerShell 里跑任何 npm 命令都报"禁止运行脚本"。
排查链路：
- 确认报错文件是
npm.ps1而不是npm.cmd——说明走的是 PowerShell 通道 - 执行
Get-ExecutionPolicy看当前策略，如果是Restricted就是它 - 执行
Get-ExecutionPolicy -List看各作用域的策略，确认改哪个作用域生效
根因：PowerShell 默认执行策略是Restricted，禁止一切脚本。修复用Set-ExecutionPolicy RemoteSigned -Scope CurrentUser，只影响当前用户，不需要管理员权限，也不会降低系统整体安全性。
这个坑的特点是第一次遇到很懵，知道原因后一劳永逸。我建议装完 Node 就顺手把策略改了，别等报错。
5.2 模块找不到：@npmcli/config 类错误的通用处理
现象：npm install报error: cannot find module '@npmcli/config'。
排查链路：
npm -v看 npm 版本，如果和 Node 版本明显不匹配（比如 Node 20 配 npm 6），基本就是它npm root -g看全局模块目录，确认 npm 自身装在哪- 尝试
npm install -g npm@latest重装 npm
如果重装 npm 也失败，说明 npm 的安装已经损坏到无法自我修复。这时候最省时间的做法是用 nvm 装一个全新的 Node，它会自带匹配的 npm。不要试图手动去补@npmcli/config这个模块，它是 npm 的内部实现，手动补版本对不上会更乱。
5.3 代理转发失败：/responses 端点的完整排查
回到cc switch local proxy failed while handling codex endpoint /responses。这个报错的排查我按四步走：
第一步，确认服务端活着。直接 curl：
curl -X POST http://127.0.0.1:1234/responses \ -H "Content-Type: application/json" \ -d '{"model":"local-model","input":"hi"}'如果这一步就失败，问题在服务端，跟 openrig 无关。
第二步，确认 openrig 发出的请求长什么样。开 debug 日志：
DEBUG=openrig:* openrig use codex看它实际请求的 URL 和 header。
第三步，对比差异。常见差异是 openrig 加了/v1前缀，或者把Authorization头改写了。找到差异就找到了修复点。
第四步，改配置。如果是路径问题，在 provider 里显式指定完整路径；如果是 header 问题，检查 env 里的 key 名对不对。
这个排查链路的价值在于：它把"代理失败"这个模糊描述拆成了可验证的具体假设。你不需要猜，每一步都有明确的验证手段。
5.4 依赖版本漂移：lock 文件的重要性
现象：昨天能跑，今天npm install后报错。
排查链路：
git diff package-lock.json看 lock 文件有没有变- 如果变了，看是哪个依赖的版本动了
npm ci而不是npm install，前者严格按 lock 文件装，后者可能升级
根因：npm install在满足package.json版本范围的前提下会装最新版，如果某个依赖发了有 bug 的新版本，就会中招。npm ci只认 lock 文件，保证每次装出来的依赖树完全一致。
我的习惯是：本地开发用npm install，CI 和部署用npm ci。这样既能在开发时拿到更新，又能保证生产环境可复现。
6. 让 openrig 真正好用的几个进阶配置
基础跑通之后，有几个配置能让 openrig 从"能用"变成"好用"。
6.1 超时与重试：本地模型和云端模型要区别对待
本地模型冷启动慢，云端模型偶尔抽风。统一的超时和重试策略会让两边都不舒服。openrig 支持在 profile 级别覆盖：
defaults: timeout: 30000 retries: 2 profiles: local-heavy: provider: local overrides: timeout: 120000 # 本地大模型，给足时间 retries: 0 # 本地失败重试意义不大，直接报错 cloud: provider: claude overrides: timeout: 20000 retries: 3 # 云端偶发失败，重试有效这里的逻辑是：本地模型的瓶颈是算力，重试只会让排队更长；云端模型的瓶颈是网络抖动，重试能救回来。按这个原则配，体验差别很大。
6.2 配置校验：把错误挡在启动之前
openrig 的validate脚本值得单独跑。它检查的不只是 YAML 语法，还有语义：
- provider 引用的命令是否存在
- profile 引用的 provider 是否已定义
- 环境变量占位符是否有对应值
- endpoint URL 格式是否合法
openrig validate我建议把它加进 git 的 pre-commit hook，配置改错了根本提交不上去。这比等到运行时才发现问题早了好几步。
6.3 密钥管理：环境变量之外的选择
${CLAUDE_KEY}这种环境变量替换是最简单的方案，但有个问题：环境变量在进程列表里可能被看到，多用户机器上不安全。更稳妥的做法是用系统的密钥管理工具，openrig 支持从命令读取：
providers: claude: env: ANTHROPIC_API_KEY: from_command: "security find-generic-password -s claude-key -w"macOS 用security，Linux 用secret-tool，Windows 用cmdkey。这样密钥不落盘、不进环境变量，只在需要时取一次。如果你的机器是共享的，这个配置强烈建议加上。
7. 我在实际使用中总结的几条经验
搭完这套东西，有几个体会是文档里不会写的。
第一，配置文件的注释比配置本身重要。三个月后你回来看timeout: 60000，如果不记得为什么是 60 秒，就会犹豫要不要改。写清楚"本地模型冷启动 15s，留 4 倍余量"，下次就能果断决策。
第二，profile 数量控制在 5 个以内。我一开始建了十几个 profile，结果自己都记不清哪个是哪个。后来合并成"日常、批量、私有、实验"四个，清晰多了。配置的复杂度要匹配实际场景的数量，不要为了"灵活"而灵活。
第三，报错先看是不是环境问题，再看是不是配置问题，最后才怀疑工具本身。我遇到的 openrig 相关问题里，八成是 PATH 没配好或者依赖版本不对，真正是 openrig 自身 bug 的极少。这个排查顺序能省很多时间。
第四，定期跑npm ci重建环境。本地环境跑久了会积累各种临时状态，偶尔用npm ci从 lock 文件重建一次，能提前发现"在我机器上能跑"的隐患。
第五，把 openrig 的配置纳入版本控制，但密钥除外。YAML 文件进 git，密钥走环境变量或系统密钥管理。这样团队协作时配置能共享，密钥各自管理，既一致又安全。
这套工作台搭好之后，切换模型、切换环境、排查问题都有了统一的入口，不再是一堆散落的命令和配置文件。openrig 这个名字里的"rig"——装配架——算是名副其实了。
