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

1. openrig 到底是个什么东西第一次看到 openrig 这个名字我下意识以为是某个硬件测试架或者开源机械臂项目毕竟 rig 这个词在工程圈里通常指代装置、台架。但把标题和那串热搜词放在一起看——Claude Code、Codex、YAML、npm——方向就很清楚了这是一个围绕 AI 编程助手做配置编排、环境管理或者代理转发的工具类项目。简单说openrig 想解决的是当你同时用好几个 AI 编码工具时怎么把它们统一管起来这件事。我先把结论摆出来openrig 的核心价值在于把 Claude Code、Codex 这类命令行 AI 助手的配置、模型接入、端点转发、环境切换这些琐碎活儿收敛成一套可维护的 YAML 配置加 npm 分发的方案。它适合谁适合那些已经在用或者准备用 Claude Code、Codex 做日常开发但被每个工具一套配置、换个模型就要改半天、本地模型接不进去、代理端点老是报错这些问题折磨过的开发者。如果你只是偶尔用网页版问两个问题那这个项目对你意义不大但如果你把 AI 助手当成主力生产力工具天天在终端里跑那 openrig 这类东西能省下你大量重复劳动。为什么我这么判断你看热搜词里反复出现几个信号cc switch local proxy failed while handling codex endpoint /responses说明有人在折腾 Claude Code 和 Codex 之间的端点转发claude code 调用 lmstudio 的本地模型说明大家想把本地模型接进这套体系codex 接入 deepseek说明模型来源要多样化yaml 文件怎么创建、npm 安装、npm 国内源说明这个项目的分发和配置方式就是 npm YAML。这些线索拼在一起openrig 的画像就立体了——它是一个AI 编码工具的统一配置层。我个人的判断是这类工具的出现是必然的。因为 Claude Code 和 Codex 各自有各自的配置文件格式、各自的端点协议、各自的认证方式你想让它们共用一套模型后端或者想在它们之间快速切换手工维护成本极高。openrig 本质上是在做配置的抽象层把差异吃掉对上暴露统一的接口。这个思路和当年 Docker Compose 统一多容器编排是一个道理——不是发明新东西而是把已有的东西管好。2. 核心设计思路与方案选型拆解2.1 为什么是 YAML 而不是 JSON 或 TOMLopenrig 选择 YAML 作为配置格式这个决定值得说道说道。JSON 的问题是写起来太啰嗦一个简单的模型配置要写一堆引号和花括号而且不支持注释——你没法在配置里写这行是给本地 LM Studio 用的这种说明。TOML 虽然支持注释但嵌套结构表达起来比较别扭尤其是当你要描述多个工具、每个工具有多个模型端点这种层级关系时TOML 的[table.subtable]语法会让人头晕。YAML 的优势在于支持注释、缩进表达层级、天然适合描述列表和映射。你看热搜里yolov10 yaml 文件怎么创建、rstudio 的 yaml 在哪里这些词说明 YAML 已经是配置领域的事实标准了大家对这个格式有认知基础。openrig 用 YAML等于降低了用户的学习成本——你不需要学新格式只要会缩进就行。但 YAML 也有坑最大的坑就是缩进敏感。我见过太多人因为多打了一个空格导致配置解析失败然后对着报错信息一脸懵。所以 openrig 这类项目通常会在文档里强调用空格不用 Tab并且最好配一个 schema 校验。这一点后面讲实操的时候我会展开。2.2 npm 分发背后的考量用 npm 分发一个配置管理工具这个选择很聪明。原因有三第一目标用户群体——用 Claude Code 和 Codex 的人——大概率已经装了 Node.js因为这两个工具本身就是 npm 包或者依赖 Node 环境。第二npm 的全局安装机制npm install -g能让 openrig 的命令直接进 PATH用户敲openrig就能用体验流畅。第三npm 生态有成熟的版本管理和依赖解析省去了自己造轮子的麻烦。但 npm 在国内的痛点也很明显热搜里npm 国内源、npm 淘宝源、npm 镜像源地址、npm 安装这些词高频出现说明网络问题是个普遍障碍。还有npm : 无法加载文件 d:\program files\nodejs\npm.ps1因为在此系统上禁止运行脚本这种 PowerShell 执行策略问题以及node 安装后 npm 不能用、npm 环境变量 path 配置这些环境配置问题。这些都不是 openrig 本身的 bug而是 npm 生态在国内的通用门槛。所以我在实操部分会专门讲怎么把 npm 环境理顺。2.3 端点转发openrig 最核心也最容易出问题的部分热搜里那条cc switch local proxy failed while handling codex endpoint /responses是整个项目技术含量最高的地方。这句话翻译过来就是在 Claude Code 和 Codex 之间做本地代理切换时处理 Codex 的/responses端点失败了。这说明 openrig 很可能内置了一个本地代理服务负责把不同工具的请求转发到不同的模型后端。为什么要做代理转发因为 Claude Code 和 Codex 的 API 协议不一样。Claude Code 走的是 Anthropic 的 messages 格式Codex 走的是 OpenAI 的 responses 格式。如果你想用同一个模型后端比如本地 LM Studio 或者 DeepSeek同时服务这两个工具就必须有一个中间层做协议转换。openrig 的代理就是干这个的。这个设计的难点在于不同模型的响应格式、流式输出的分块方式、错误码的定义都不一样。/responses端点处理失败通常是因为请求体格式不匹配、认证头缺失、或者流式响应的 chunk 解析出错。我在实操部分会给出排查这类问题的具体思路。3. 环境准备与 npm 安装实操3.1 Node.js 环境的一次性理顺在装 openrig 之前先把 Node.js 和 npm 的环境搞干净这一步能帮你避开后面 80% 的玄学问题。我推荐用 nvmNode Version Manager来管理 Node 版本而不是直接去官网下安装包。原因很简单不同项目对 Node 版本要求不一样nvm 能让你一条命令切换版本不用卸载重装。Windows 用户可以用 nvm-windowsMac 和 Linux 用户用 nvm。装完之后验证一下node -v npm -v如果node -v能输出版本号但npm -v报错那基本就是 PATH 没配好。热搜里npm 环境变量 path 配置说的就是这个。npm 的可执行文件通常在 Node 安装目录下的node_modules/npm/bin里你需要把这个路径加到系统 PATH 中。还有一个高频坑Windows PowerShell 默认禁止运行脚本导致npm命令报无法加载文件 npm.ps1因为在此系统上禁止运行脚本。解决办法是以管理员身份打开 PowerShell执行Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser然后输入Y确认。这个操作只影响当前用户不会降低系统整体安全性可以放心执行。3.2 配置国内镜像源加速安装npm 默认源在国外国内下载包经常超时。换成国内镜像源能显著提速。临时用的话npm install openrig --registryhttps://registry.npmmirror.com想永久生效就改配置npm config set registry https://registry.npmmirror.com改完用npm config get registry验证一下。如果哪天想换回官方源把地址改成https://registry.npmjs.org就行。注意有些公司内网有自己的私有源如果你在公司环境里操作先问清楚 IT 部门该用哪个源别自己乱改导致依赖拉不下来。3.3 安装 openrig 并验证环境理顺之后安装就一行命令npm install -g openrig-g表示全局安装这样在任何目录下都能调用。装完验证openrig --version如果提示command not found说明全局 bin 目录没进 PATH。用npm config get prefix看看全局安装路径在哪然后把这个路径下的bin目录加到 PATH 里。我踩过的一个坑是之前用sudo npm install -g装包结果权限混乱后来改用 nvm 管理 Node 就再没出现过。所以强烈建议不要用 sudo 装全局包用 nvm 把 Node 装在用户目录下干净又省心。4. openrig 配置文件详解与实操4.1 YAML 配置文件的基本结构openrig 的配置文件通常放在用户主目录下的.openrig/config.yaml或者项目根目录下的openrig.yaml。具体位置取决于项目设计但 YAML 的结构逻辑是相通的。一个典型的配置大概长这样version: 1 tools: claude-code: enabled: true endpoint: http://localhost:8080/v1/messages model: claude-sonnet codex: enabled: true endpoint: http://localhost:8080/v1/responses model: gpt-4 providers: local-lmstudio: base_url: http://localhost:1234/v1 api_key: not-needed deepseek: base_url: https://api.deepseek.com/v1 api_key: ${DEEPSEEK_API_KEY} proxy: port: 8080 log_level: info这个结构分三层tools定义你要用哪些 AI 编码工具providers定义模型后端proxy定义本地代理的行为。${DEEPSEEK_API_KEY}这种写法是环境变量引用避免把密钥硬编码在配置文件里——这是个好习惯一定要养成。4.2 缩进、注释与常见语法错误YAML 用缩进表示层级必须用空格绝对不能用 Tab。我建议在编辑器里设置Tab 键插入 2 个空格VSCode 里搜editor.insertSpaces和editor.tabSize就能改。缩进不一致是 YAML 报错的头号原因而且报错信息往往指向一个莫名其妙的位置让人抓狂。注释用## 这是给本地 LM Studio 用的配置 local-lmstudio: base_url: http://localhost:1234/v1 # 端口要和 LM Studio 里设置的一致字符串一般不用加引号但如果值里包含特殊字符比如:、#、{就得用引号包起来。比如model: gpt-4:latest这种带冒号的不加引号会被解析成映射。4.3 把本地模型接进 openrig热搜里claude code 调用 lmstudio 的本地模型是个高频需求。思路是这样的LM Studio 启动后会暴露一个兼容 OpenAI 格式的 API默认在http://localhost:1234/v1。你在 openrig 的providers里把它注册进去然后在tools里把 Claude Code 的 endpoint 指向 openrig 的代理端口代理再转发到 LM Studio。关键点在于协议转换。Claude Code 发的是 Anthropic 格式的请求LM Studio 只认 OpenAI 格式openrig 的代理要在中间做翻译。如果这一步报错先检查三件事LM Studio 的 server 有没有启动、端口对不对、模型有没有加载。我见过有人 LM Studio 界面开着但 server 没开然后对着报错查了半天。4.4 端点转发失败的排查思路回到那条cc switch local proxy failed while handling codex endpoint /responses。这类错误我总结了一个排查顺序排查项检查方法常见问题代理是否启动curl http://localhost:8080/health端口被占用、进程没起来端点路径对比配置和实际请求/responses写成/response请求格式看代理日志的请求体字段名不匹配、缺 model 字段认证头检查 Authorization 头密钥没传、格式不是 Bearer流式响应看是否卡在第一个 chunkSSE 解析错误、超时设置太短我的经验是先看日志。openrig 的log_level设成debug能看到完整的请求和响应体比瞎猜快得多。如果日志里请求发出去了但没响应那大概率是后端模型服务的问题如果请求根本没发出去那就是代理配置的问题。5. 多工具协同与模型切换实战5.1 Claude Code 与 Codex 的共存配置很多人是 Claude Code 和 Codex 一起用的前者擅长长上下文理解后者在某些代码生成任务上更顺手。openrig 的价值就在于让你不用为每个工具单独配一套环境。你只需要在tools里把两个都启用各自指向代理的不同端点代理再根据端点路径把请求路由到对应的模型后端。这里有个细节Claude Code 和 Codex 的配置文件位置不一样。Claude Code 通常读~/.claude/settings.json或者环境变量Codex 读~/.codex/config之类。openrig 要做的是帮你生成或者修改这些文件让它们都指向本地代理。如果你手动改记得改之前备份原文件不然改乱了很难恢复。5.2 模型切换的几种姿势切换模型有三种粒度全局切换、按工具切换、按会话切换。全局切换就是改providers里的默认项所有工具都跟着变按工具切换是在tools下面单独指定按会话切换最灵活但需要工具本身支持运行时指定模型。我个人的习惯是日常用本地 LM Studio 跑小模型做快速补全遇到复杂重构任务再切到 DeepSeek 或者云端模型。这样既省 token 又保证质量。openrig 如果支持 profile 机制类似openrig use local/openrig use cloud那切换就是一条命令的事。5.3 环境变量与密钥管理密钥千万别写死在 YAML 里。用环境变量引用然后在 shell 的配置文件.bashrc、.zshrc或 Windows 的环境变量设置里定义。这样配置文件可以放心提交到 git不怕泄露。export DEEPSEEK_API_KEYyour-key-hereWindows 上用setx DEEPSEEK_API_KEY your-key-here然后重开终端生效。如果你用.env文件记得把它加进.gitignore。6. 常见问题与避坑经验实录6.1 安装阶段的典型问题npm warn eresolve overriding peer dependency这个警告很常见通常是依赖树里有版本冲突。大多数情况下不影响使用可以忽略。但如果安装直接失败试试npm install -g openrig --legacy-peer-deps这个参数会让 npm 用旧版的依赖解析策略绕过 peer dependency 的严格检查。npm 卸载全局包的命令是npm uninstall -g openrig。如果卸载后命令还在可能是缓存问题npm cache clean --force清一下。6.2 运行阶段的典型问题代理启动后工具连不上先确认代理监听的地址。有些代理默认只监听127.0.0.1如果你在容器或者虚拟机里跑工具就连不上。改成0.0.0.0能解决但要注意安全别暴露到公网。流式输出卡顿或者中断多半是超时设置太短。在代理配置里把timeout调大比如timeout: 300单位秒。本地模型首次加载比较慢超时给足很重要。6.3 我的独家避坑清单配置文件改完先跑openrig validate之类的校验命令如果有别直接启动省得报错信息看不懂。代理日志一定要开debug级别虽然吵但排查问题时是救命的。本地模型和云端模型的 API 格式差异比想象中大别假设它们能无缝互换该做适配就做适配。版本升级前备份配置YAML 的 schema 可能变旧配置不一定兼容新版本。遇到organization has disabled claude subscription access这类提示那是账号权限问题不是 openrig 的锅别在工具上浪费时间。6.4 性能与稳定性调优如果你同时跑多个工具代理的并发处理能力要注意。Node.js 单线程高并发下可能成为瓶颈。可以在配置里限制并发数或者把代理跑在性能更好的机器上。另外日志文件要定期清理debug级别的日志增长很快磁盘满了会导致各种诡异问题。我在实际使用中发现把代理和模型服务放在同一台机器上延迟最低。如果模型在远程网络抖动会直接影响体验。所以本地模型优先本地跑云端模型选延迟低的区域。7. 从 openrig 看 AI 编码工具的管理趋势折腾完这一圈我最大的感受是AI 编码工具已经从能用就行进入要管得好的阶段了。早期大家装个 Claude Code 就觉得很新鲜现在手里同时有三四个工具每个都要配模型、配端点、配密钥管理成本直线上升。openrig 这类项目的出现本质上是在回应这种管理需求。它的设计思路——YAML 配置、npm 分发、本地代理转发——都是成熟技术的组合没有炫技但每一块都踩在了实际痛点上。YAML 让配置可读可维护npm 让安装和升级简单代理让多工具多模型能协同。这套组合拳打下来确实能省不少事。当然它也不是银弹。协议转换的复杂度摆在那里不同模型的兼容性需要持续维护配置出错时的排查门槛也不低。但相比手工维护一堆散落的配置文件这已经是明显的进步了。我的建议是如果你只用一两个工具、一个模型那没必要上 openrig但如果你工具多、模型杂、还经常切换那花点时间把它配起来长期看是划算的。最后分享一个小技巧把常用的配置组合存成不同的 profile 文件比如local.yaml、cloud.yaml、hybrid.yaml切换的时候直接软链接或者复制覆盖比每次手改快得多。这个习惯我用了很久实测下来很稳。