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_KEYsk-ant-xxxx export DEEPSEEK_API_KEYsk-xxxx export OPENAI_API_KEYsk-xxxx然后在 shell 的 rc 文件里 source 这个文件。这样做的好处是密钥集中在一处备份和迁移的时候只动一个文件。注意这个文件要设置权限为 600只允许当前用户读写chmod 600 ~/.openrig/env3.3 工具绑定的映射逻辑openrig 最核心的能力是把统一配置映射成各个工具认识的格式。Claude Code 认的是环境变量 ANTHROPIC_BASE_URL 和 ANTHROPIC_API_KEYCodex 认的是它自己的配置文件或者命令行参数。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 CurrentUserRemoteSigned 策略的意思是本地写的脚本可以直接跑从网络下载的脚本需要有数字签名才能跑。这个策略比 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%\npmLinux/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 codexopenrig 在启动时会做几件事读取 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 里加一个 providerproviders: 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 相关报错速查报错信息根本原因解决方法npm 无法加载文件 npm.ps1因为在此系统上禁止运行脚本PowerShell 执行策略为 RestrictedSet-ExecutionPolicy RemoteSigned -Scope CurrentUsernpm warn eresolve overriding peer dependency依赖树里有版本冲突多数情况可忽略严重时用 npm install --legacy-peer-depsnpm 安装超时或卡住默认源网络不通切换国内镜像源全局命令找不到全局 bin 目录不在 PATH把 npm config get prefix 下的 bin 加入 PATHnpm 卸载全局包失败权限不足或包被占用Linux/macOS 加 sudoWindows 用管理员终端这张表里的每一条我都在实际环境里遇到过。特别是第一条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 1234Windows或 lsof -i :1234Linux/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 编程助手数量增加而增加。只用一个小工具的时候手动配一下无所谓用到三个以上没有统一装配层就是灾难。它解决的不是某个单点问题而是把“配置管理”这件事从每个工具各自为政变成集中治理。这个思路我觉得后续还可以扩展到更多工具比如把本地的代码检查工具、格式化工具、测试运行器也纳入同一套配置体系真正做到一个配置文件管所有开发工具链。
