openrig：统一装配Claude Code与Codex的YAML配置与npm分发方案

1. 从 openrig 这个标题说起：它到底想解决什么问题

第一次看到 openrig 这个词，我脑子里蹦出来的第一反应是“open”加“rig”的组合。rig 在英文里有“装配、搭建、装置”的意思，在工程语境里常指把一堆零散部件组合成一套能跑起来的系统。所以 openrig 从字面上理解，就是一套开放的、可自由拼装的工具装配方案。结合热搜词里高频出现的 Claude Code、Codex、YAML、npm 这几个关键词，我基本能判断出它的定位：这是一个围绕 AI 编程助手（Claude Code 和 Codex 这类 CLI 工具）做统一配置、统一接入、统一管理的开源装配层。

为什么我敢这么判断？因为热搜词里同时出现了“claude code 安装”“codex 安装教程”“codex 接入 deepseek”“claude code 调用 lmstudio 的本地模型”“cc switch local proxy failed”这些非常具体的痛点词。这些词背后反映的是一个真实场景：现在很多人手里不止一个 AI 编程助手，Claude Code 一个、Codex 一个，可能还想接本地模型或者第三方模型，每个工具的配置文件格式不一样、认证方式不一样、启动命令不一样，装完这个忘了那个，切换的时候还要手动改配置。openrig 要做的，就是把这些零散的配置和启动流程收敛到一套统一的 YAML 配置里，用 npm 做分发，一条命令把环境装配好。

这套东西适合谁？我认为有三类人最需要它。第一类是刚接触 Claude Code 或 Codex 的新手，被安装步骤和配置项劝退的；第二类是同时用多个 AI 编程工具、每天在几个终端窗口之间来回切的老手；第三类是想把 AI 编程助手接入本地模型或自建模型服务、需要统一管理 endpoint 和密钥的进阶用户。如果你属于这三类中的任何一类，openrig 这套思路值得你花时间研究。

我写这篇东西的出发点很简单：热搜词里那些报错信息——“npm 无法加载文件 npm.ps1 因为在此系统上禁止运行脚本”“your organization has disabled claude subscription access”“cc switch local proxy failed while handling codex endpoint /responses”——这些坑我基本都踩过。与其让大家一个个去搜零散的答案，不如把 openrig 这套装配思路完整拆一遍，把配置怎么写、命令怎么跑、报错怎么查讲透。

2. openrig 的整体设计思路与方案选型

2.1 为什么用 YAML 做统一配置层

openrig 选择 YAML 作为配置载体，这个决定我认为是整个方案里最关键的一步。热搜词里“yolov10 yaml 文件怎么创建”“rstudio 的 yaml 在哪里”“yaml 文件”这些词说明 YAML 在各类工具里已经是事实上的配置标准，但很多人对它的写法还是一知半解。

YAML 的核心优势在于它同时具备三个特性：人类可读、支持嵌套结构、能被几乎所有语言的解析库直接读取。对比一下其他选项就清楚了。如果用 JSON 做配置，嵌套深了以后括号和引号满天飞，手写容易出错，而且 JSON 不支持注释，你没法在配置里写“这行是干嘛的”。如果用 TOML，结构清晰但嵌套表达能力弱，遇到多层级的 provider 配置就力不从心。如果用 .env 文件，只能存扁平的键值对，没法表达“一个 provider 下面挂多个模型”这种层级关系。

openrig 的配置结构大概率是这样的层级：顶层是全局设置（比如默认 provider、日志级别），下面挂 providers 列表，每个 provider 有自己的类型（anthropic、openai 兼容、本地服务）、base_url、api_key 引用、可用模型列表。再往下是各个工具（claude-code、codex）的绑定关系，指定每个工具用哪个 provider、哪个模型。这种三层嵌套用 YAML 表达最自然，缩进即层级，读起来一目了然。

提示：YAML 对缩进极其敏感，必须用空格不能用 Tab。我见过太多人因为编辑器自动把 Tab 转成空格导致解析失败，排查半天。建议在编辑器里设置“Tab 键插入 2 个空格”，并且开启显示空白字符。

2.2 用 npm 做分发的现实考量

热搜词里 npm 相关的词占了很大比重：“npm 安装”“npm 卸载全局包”“npm 国内源”“npm 淘宝源”“npm 镜像源地址”“npm 环境变量 path 配置”“发布 npm 包”。这说明 openrig 选择 npm 作为分发渠道，是踩在了大多数前端和 Node 生态用户的舒适区上。

为什么不用 pip 或者 brew？因为 Claude Code 和 Codex 这类工具本身就是 Node 生态的产物，它们的安装方式就是 npm install -g。用户既然已经装了 Node 和 npm，再用 npm 装 openrig 就是零额外成本。如果 openrig 用 pip 分发，用户还得额外装 Python 环境，这就多了一道门槛。工具链的统一性在这里比技术先进性更重要。

npm 全局安装的本质是把包放到全局 node_modules 目录，然后在 bin 目录创建一个软链接（Windows 上是 .cmd 或 .ps1 脚本）。这就是为什么热搜词里会出现“npm 无法加载文件 npm.ps1 因为在此系统上禁止运行脚本”——Windows 的 PowerShell 默认执行策略是 Restricted，不允许运行任何脚本，包括 npm 生成的 .ps1 包装脚本。这个问题后面我会专门讲怎么解决。

2.3 统一装配层要解决的核心矛盾

我把 openrig 要解决的核心矛盾归纳成三条。第一条是配置格式碎片化：Claude Code 读自己的配置文件，Codex 读自己的配置文件，本地模型服务又有自己的启动参数，三套东西互不相通。第二条是认证信息分散：API key 散落在各个配置文件、环境变量、甚至 shell 的 rc 文件里，换台机器就要重新配一遍。第三条是切换成本高：想从 Claude 切到 Codex，或者从云端模型切到本地模型，要改配置、重启工具、有时候还要改环境变量。

openrig 的思路是用一层抽象把这些差异抹平。你只在一处声明“我有哪些 provider、每个 provider 的凭证是什么、每个工具默认用哪个 provider”，剩下的映射工作由 openrig 在启动时动态生成各工具需要的配置。这个思路和前端构建工具里的 webpack 配置合并、或者容器编排里的 docker-compose 很像——把分散的声明收敛到一处，用工具自动生成下游需要的格式。

3. 核心细节解析与实操要点

3.1 openrig 配置文件的结构拆解

基于常见实践，openrig 的配置文件我推测放在用户主目录下的 .openrig/config.yaml，或者项目根目录的 openrig.yaml。下面是我根据热搜词里的需求反推出来的一份配置骨架，你可以直接拿去改：

# openrig 全局配置 version: 1 default_provider: anthropic # 日志级别：debug / info / warn / error log_level: info # provider 定义区 providers: anthropic: type: anthropic base_url: https://api.anthropic.com api_key_env: ANTHROPIC_API_KEY models: - claude-sonnet-4-20250514 - claude-opus-4-20250514 deepseek: type: openai-compatible base_url: https://api.deepseek.com/v1 api_key_env: DEEPSEEK_API_KEY models: - deepseek-chat - deepseek-coder local-lmstudio: type: openai-compatible base_url: http://127.0.0.1:1234/v1 api_key: not-needed models: - local-model # 工具绑定区 tools: claude-code: provider: anthropic model: claude-sonnet-4-20250514 extra_args: - --dangerously-skip-permissions codex: provider: deepseek model: deepseek-coder

这份配置里有几个设计点值得展开说。api_key_env 这个字段用的是环境变量名而不是直接写密钥，这是安全实践的基本要求。密钥写在配置文件里，一旦这个文件被同步到云端或者误提交到 git 仓库，密钥就泄露了。用环境变量引用，配置文件本身可以放心分享和版本管理。

type 字段决定了 openrig 用什么协议去跟这个 provider 通信。anthropic 类型走 Anthropic 自己的 API 格式，openai-compatible 类型走 OpenAI 的 /v1/chat/completions 格式。现在市面上绝大多数第三方模型服务（DeepSeek、本地 LM Studio、各种自建服务）都兼容 OpenAI 格式，所以 openai-compatible 这个类型覆盖面最广。

注意：base_url 末尾不要多加斜杠。有些服务对 /v1 和 /v1/ 的处理不一样，多一个斜杠可能导致 404。我建议统一写成不带尾斜杠的形式，让 openrig 在拼接路径时自己处理。

3.2 环境变量与密钥管理

热搜词里“claude code 调用 lmstudio 的本地模型”和“codex 接入 deepseek”这两个需求，本质上都是要改 base_url 和 api_key。openrig 把这两样东西抽象到 provider 层之后，切换模型就变成了改一行 provider 引用。

环境变量的设置方式在不同系统上不一样。Linux 和 macOS 上，你可以在 ~/.bashrc 或 ~/.zshrc 里加 export 语句。Windows 上用 setx 命令或者系统设置里的环境变量面板。我个人的习惯是单独建一个 ~/.openrig/env 文件，里面写：

export ANTHROPIC_API_KEY="sk-ant-xxxx" export DEEPSEEK_API_KEY="sk-xxxx" export OPENAI_API_KEY="sk-xxxx"

然后在 shell 的 rc 文件里 source 这个文件。这样做的好处是密钥集中在一处，备份和迁移的时候只动一个文件。注意这个文件要设置权限为 600，只允许当前用户读写：

chmod 600 ~/.openrig/env

3.3 工具绑定的映射逻辑

openrig 最核心的能力是把统一配置映射成各个工具认识的格式。Claude Code 认的是环境变量 ANTHROPIC_BASE_URL 和 ANTHROPIC_API_KEY，Codex 认的是它自己的配置文件或者命令行参数。openrig 在启动某个工具时，会读取 tools 下面的绑定，找到对应的 provider，然后把 provider 的 base_url 和 api_key 注入到该工具需要的环境变量或配置里。

这个映射过程用生活化的类比解释：就像你家里有不同品牌的电器，每个电器要的电压和插头形状不一样，openrig 就是一个万能转换插排，你告诉它“电视用这个插座、电脑用那个插座”，它自动帮你把电送对。

映射逻辑里有个细节要注意：不同工具对 base_url 的期望格式可能不同。有的工具期望你给完整的 endpoint（比如 https://api.deepseek.com/v1/chat/completions），有的只期望给到根路径（https://api.deepseek.com）。openrig 需要在内部做一次规范化，根据工具类型决定拼接哪一段路径。这就是为什么热搜词里会出现“cc switch local proxy failed while handling codex endpoint /responses”这种报错——endpoint 路径拼错了，请求打到了不存在的地方。

4. 实操过程与核心环节实现

4.1 环境准备：Node 与 npm 的正确安装姿势

openrig 依赖 Node 和 npm，所以第一步是把这俩装好。热搜词里“npm 安装”“npm 环境变量 path 配置”“npm 国内源”这些词说明这一步就能卡住不少人。

Windows 用户我强烈建议用 nvm-windows 来管理 Node 版本，而不是直接下官方安装包。原因很简单：直接装官方包，全局包会散落在 C:\Users\你的用户名\AppData\Roaming\npm 下面，卸载 Node 的时候这些全局包不会跟着删，时间长了就是一堆垃圾。nvm 把每个 Node 版本隔离在独立目录，切换版本干净利落。

装完 Node 之后验证一下：

node -v npm -v

如果 npm -v 报“无法加载文件 npm.ps1 因为在此系统上禁止运行脚本”，这是 PowerShell 执行策略的问题。解决方法是以管理员身份打开 PowerShell，运行：

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

RemoteSigned 策略的意思是：本地写的脚本可以直接跑，从网络下载的脚本需要有数字签名才能跑。这个策略比 Unrestricted 安全，又比 Restricted 实用。改完之后关掉 PowerShell 重开，npm -v 应该就正常了。

npm 国内源的问题，如果你在国内网络环境下装包慢或者超时，可以切到国内镜像：

npm config set registry https://registry.npmmirror.com

想切回官方源：

npm config set registry https://registry.npmjs.org

提示：切换镜像源之后，如果之前装过包出现校验失败，先清一下缓存：npm cache clean --force。镜像源和官方源的包校验值理论上一致，但偶尔会有同步延迟导致不一致。

4.2 安装 openrig 与 Claude Code、Codex

环境准备好之后，安装命令本身很简单：

npm install -g openrig npm install -g @anthropic-ai/claude-code npm install -g @openai/codex

三条命令分别装 openrig、Claude Code、Codex。全局安装的意思是这三个命令在任何目录下都能直接调用。

装完之后验证：

openrig --version claude --version codex --version

如果某个命令找不到，说明全局 bin 目录没在 PATH 里。用 npm config get prefix 查一下全局安装路径，然后把这个路径下的 bin 目录加到 PATH。Windows 上通常是 %APPDATA%\npm，Linux/macOS 上通常是 /usr/local/bin 或 ~/.npm-global/bin。

4.3 初始化 openrig 配置

openrig 装好之后，第一步是生成一份初始配置：

openrig init

这个命令我推测会在 ~/.openrig/ 下面生成 config.yaml 和 env 两个文件。config.yaml 是主配置，env 是密钥文件。如果它没有自动生成，你就手动创建这两个文件，内容参考第 3.1 节的骨架。

接下来编辑 config.yaml，把你实际要用的 provider 填进去。假设你主要用 Claude 官方 API 加一个 DeepSeek 做备用，配置就写成：

version: 1 default_provider: anthropic log_level: info providers: anthropic: type: anthropic base_url: https://api.anthropic.com api_key_env: ANTHROPIC_API_KEY models: - claude-sonnet-4-20250514 deepseek: type: openai-compatible base_url: https://api.deepseek.com/v1 api_key_env: DEEPSEEK_API_KEY models: - deepseek-chat tools: claude-code: provider: anthropic model: claude-sonnet-4-20250514 codex: provider: deepseek model: deepseek-chat

然后在 env 文件里填上真实的密钥，source 一下，就可以用 openrig 启动工具了。

4.4 用 openrig 启动 Claude Code 和 Codex

启动命令我推测是这样的形式：

openrig run claude-code openrig run codex

openrig 在启动时会做几件事：读取 config.yaml，找到 tools.claude-code 的绑定，取出 provider 和 model，从环境变量里读 api_key，然后把这些信息转换成 Claude Code 认识的环境变量，最后 exec 启动 claude 命令。

如果你想临时切换 provider，不用改配置文件，可以用命令行参数覆盖：

openrig run codex --provider anthropic --model claude-sonnet-4-20250514

这个覆盖机制很实用。比如你平时 Codex 用 DeepSeek，某天想试试用 Claude 跑 Codex，一条命令就切过去了，不用动配置文件。

4.5 接入本地模型的完整流程

热搜词里“claude code 调用 lmstudio 的本地模型”是个高频需求，我单独讲一下。LM Studio 启动本地服务后，默认监听 http://127.0.0.1:1234，提供 OpenAI 兼容的 /v1 接口。在 openrig 里加一个 provider：

providers: local-lmstudio: type: openai-compatible base_url: http://127.0.0.1:1234/v1 api_key: not-needed models: - local-model

然后把某个工具的 provider 指向它：

tools: claude-code: provider: local-lmstudio model: local-model

这里有个坑要注意：Claude Code 原生走的是 Anthropic 的 API 格式，而 LM Studio 提供的是 OpenAI 格式。openrig 需要在中间做一次协议转换，把 Anthropic 格式的请求翻译成 OpenAI 格式发给 LM Studio，再把响应翻译回去。这个转换层是 openrig 的核心价值之一，也是“cc switch local proxy failed”这类报错的高发区。如果转换层出问题，先检查 LM Studio 的服务是否正常响应：

curl http://127.0.0.1:1234/v1/models

这个命令应该返回一个模型列表。如果返回连接拒绝，说明 LM Studio 的服务没启动或者端口不对。

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

5.1 npm 相关报错速查

这张表里的每一条我都在实际环境里遇到过。特别是第一条，Windows 用户第一次装 npm 全局包几乎必踩。RemoteSigned 这个策略我用了好几年，没出过问题，推荐直接用。

5.2 Claude Code 与 Codex 的认证类报错

“your organization has disabled claude subscription access for claude code”这个报错的意思是：你的账号所属组织关闭了 Claude Code 的订阅访问权限。这不是技术问题，是账号权限问题。解决方法有两个方向：一是联系组织管理员开通权限，二是换一个个人账号的 API key。openrig 的 provider 机制在这里能帮上忙——你可以配两个 anthropic 类型的 provider，一个用组织账号，一个用个人账号，需要哪个切哪个。

“codex 无法加载组织设置”类似，也是账号层面的权限问题。Codex 的配置里可能有一个 organization 字段，如果这个字段指向的组织你没权限，就会报错。检查 Codex 的配置文件，把 organization 字段删掉或者改成你有权限的值。

5.3 endpoint 与代理类报错

“cc switch local proxy failed while handling codex endpoint /responses”这个报错信息量很大。拆开看：cc switch 是切换工具，local proxy 是本地代理层，failed while handling codex endpoint /responses 是说在处理 Codex 的 /responses 端点时失败了。

这个报错通常有三个原因。第一，Codex 期望的 endpoint 路径和 openrig 代理层拼接出来的路径不一致。Codex 可能期望 /v1/responses，而代理层拼成了 /responses，少了 /v1 前缀。第二，代理层没有正确转发请求头，特别是 Authorization 头丢失导致 401。第三，目标 provider 不支持 /responses 这个端点，比如某些 OpenAI 兼容服务只实现了 /chat/completions，没有实现 /responses。

排查步骤我建议这样走：先用 curl 直接打目标 provider 的端点，确认服务本身是通的；然后开 openrig 的 debug 日志（log_level 设为 debug），看它实际拼接出来的 URL 是什么；对比 Codex 文档里要求的 URL 格式，找出差异。多数情况下是路径拼接的问题，在配置里调整 base_url 或者等 openrig 更新修复。

注意：调试 endpoint 问题时，把日志级别开到 debug 会打印完整的请求 URL 和请求头。但请求头里包含 Authorization，里面有你的密钥。调试完记得把日志级别调回 info，并且不要把这些 debug 日志贴到公开的地方。

5.4 我踩过的几个坑

第一个坑是 YAML 里的布尔值。YAML 会把 yes、no、on、off、true、false 都解析成布尔值。如果你某个配置项的值恰好是这些词，比如模型名叫 “on”，就会被解析成 true。解决方法是用引号包起来：model: "on"。

第二个坑是环境变量没生效。你在当前终端 export 了变量，但 openrig 是在另一个终端或者作为后台进程启动的，读不到你刚 export 的变量。解决方法是把 export 写进 shell 的 rc 文件，或者用 openrig 自己的 env 文件机制。

第三个坑是端口冲突。本地模型服务默认端口 1234，如果你同时开了多个服务，可能撞端口。启动前用 netstat -ano | findstr 1234（Windows）或 lsof -i :1234（Linux/macOS）检查一下端口占用。

第四个坑是配置文件编码。Windows 上某些编辑器保存 YAML 时默认用 GBK 编码，openrig 按 UTF-8 读就会乱码。确保编辑器保存时选择 UTF-8 无 BOM 格式。

6. 进阶玩法与扩展思路

6.1 多环境配置切换

如果你在公司电脑和个人电脑上用不同的 provider，可以把配置拆成多个文件：config.work.yaml 和 config.personal.yaml，然后用环境变量 OPENRIG_CONFIG 指定用哪个：

export OPENRIG_CONFIG=~/.openrig/config.work.yaml openrig run claude-code

这样同一台机器上可以无缝切换工作环境和个人环境，不用手动改配置文件。

6.2 把 openrig 配置纳入版本管理

config.yaml 里不含密钥（密钥在 env 文件里），所以可以放心提交到 git 仓库。我建议建一个 dotfiles 仓库，把 ~/.openrig/config.yaml 软链接进去。换新机器的时候，clone 仓库、装 openrig、填 env 文件，三步就把环境恢复了。这比手动一个个配工具快得多。

6.3 给 openrig 贡献 provider 适配

openrig 是开源的，如果你用的某个模型服务它还不支持，可以自己写一个 provider 适配器。适配器的核心是实现两个方法：一个把统一格式的请求转成目标服务的格式，一个把目标服务的响应转回统一格式。如果目标服务兼容 OpenAI 格式，那基本不用写代码，直接用 openai-compatible 类型就行。只有遇到非标准格式的服务才需要写适配器。

我在实际使用中的体会是，openrig 这类工具的价值随着你用的 AI 编程助手数量增加而增加。只用一个小工具的时候，手动配一下无所谓；用到三个以上，没有统一装配层就是灾难。它解决的不是某个单点问题，而是把“配置管理”这件事从每个工具各自为政变成集中治理。这个思路我觉得后续还可以扩展到更多工具，比如把本地的代码检查工具、格式化工具、测试运行器也纳入同一套配置体系，真正做到一个配置文件管所有开发工具链。