1. openrig 到底是什么从一堆热词里还原真实项目轮廓第一次看到 openrig 这个名字加上旁边跟着的 Claude Code、Codex、YAML、Node.js 这一串关键词我脑子里第一反应是这大概率是一个围绕 AI 编程助手做“统一接入层”的开源工具。后来把相关热词捋了一遍基本印证了这个判断——openrig 要解决的核心问题是把 Claude Code、Codex 这类命令行 AI 编程工具以及它们背后五花八门的模型服务收敛到一套统一的配置和调用方式里。说白了现在用 AI 写代码的人都会遇到一个很现实的麻烦Claude Code 有自己的一套配置Codex 有自己的一套配置你想换个模型、换个服务端点就得改环境变量、改配置文件、重启终端甚至有时候改完还不生效报一堆看不懂的错。openrig 这类工具的价值就是把这些碎片化的配置统一成一份 YAML让你在一个地方管好所有模型接入剩下的交给它去分发。它适合谁三类人最需要。第一类是同时用 Claude Code 和 Codex 的开发者来回切换配置切到崩溃的第二类是想把本地模型、第三方模型接进这些 CLI 工具的人比如用 LM Studio 跑本地模型再喂给 Claude Code第三类是团队里要统一管理 AI 编程工具配置的人一个人配好其他人直接抄 YAML 就行。我先把话说在前面openrig 本身不是一个模型也不是一个 IDE 插件它更像是一个“配置中枢 请求转发层”。理解这一点后面所有的操作逻辑就顺了。它的技术底座是 Node.js配置载体是 YAML服务对象是 Claude Code、Codex 这类 CLI 工具。这三个关键词贯穿全文缺一个都玩不转。2. 为什么需要 openrig多工具多模型的配置地狱2.1 单工具时代的配置还算能忍早两年大家用 AI 编程助手基本就是认准一个工具用到底。Claude Code 装好环境变量里塞一个 API Key配置文件里写个模型名就能跑起来。Codex 也是类似的路子装完 CLI登录选模型开干。这个阶段配置虽然也有点烦但至少是线性的一个工具一套配置互不干扰。问题出在你开始“脚踏两条船”的时候。比如白天用 Claude Code 写业务代码晚上用 Codex 跑一些批量重构任务两个工具各自维护一套配置。这时候你会发现同一个模型服务你得在两个地方分别填一遍地址和密钥想换个模型试试效果两个工具都得改更坑的是有些工具的环境变量名还不一样改错一个字母就静默失败连报错都不给你。2.2 多工具多模型时代的真实痛点我把实际踩过的坑列一下你看看中了几条配置分散Claude Code 的配置在~/.claude下Codex 的配置在~/.codex下两边格式还不一样一个是 JSON一个是 TOML 或者 YAML改起来得记两套语法。模型切换成本高想从云端模型切到本地 LM Studio 模型得改 base URL、改模型名、改密钥占位符改完还要重启工具一套流程下来五分钟没了。团队协作难同步你配好了一套能用的配置想分享给同事结果发现里面混着你的个人密钥得手动脱敏脱敏完同事还不一定能跑通因为路径不一样。报错信息不友好像cc switch local proxy failed while handling codex endpoint /responses这种报错第一次看到根本不知道从哪查起其实是代理层转发请求时端点对不上。版本兼容问题Node.js 版本不对装依赖直接失败报error installing 24.21.0: node.js v24.21.0 is not yet released这种让人一脸问号的错。这些痛点的本质是配置和工具耦合太紧。每个工具都假设你只用它一个没考虑你会在多个工具之间横跳。openrig 的思路就是把配置从工具里抽出来做成一份中立的 YAML工具通过 openrig 来读配置这样你只需要维护一份文件。2.3 openrig 的解法一份 YAML 管所有openrig 的核心设计哲学可以用一句话概括配置与工具解耦模型与服务解耦。具体来说它做了三件事统一配置格式不管你后面接的是 Claude Code 还是 Codex前面配的都是同一份 YAML。YAML 的好处是结构清晰、可读性强、支持注释比 JSON 友好太多比 TOML 又更通用。统一模型抽象不管你接的是云端模型、本地 LM Studio 模型还是第三方兼容接口在 openrig 里都抽象成“一个 provider 一个 model”配置结构一致切换只改几行。统一转发层openrig 在本地起一个轻量服务Claude Code 和 Codex 都指向这个本地服务由它去决定请求最终发给谁。这样工具端完全不用关心后端是谁换模型对工具透明。这个设计的好处是显而易见的。你换模型只改 YAML你加新工具只改工具端指向你分享配置把 YAML 里的密钥换成占位符就行。配置地狱一下子变成了配置天堂。提示openrig 这类工具的本质是“本地代理 配置管理”理解了这个定位后面遇到任何报错先想“是配置问题还是转发问题”排查效率会高很多。3. 环境准备Node.js 与 YAML 的正确打开方式3.1 Node.js 安装别踩版本坑openrig 跑在 Node.js 上所以第一步是把 Node.js 装对。这里有个高频坑很多人直接去官网下载最新版结果装了个还没正式发布的版本跑起来各种报错。热词里那个error installing 24.21.0: node.js v24.21.0 is not yet released or is not available就是典型症状——你拿到的版本号在官方发布列表里根本不存在多半是某个镜像源同步出了问题或者你手动指定了一个不存在的版本。正确的做法是认准 LTS 版本。LTS 是长期支持版稳定、兼容性好社区踩坑最多、解决方案最全。截至我写这篇的时候Node.js 20.x 和 22.x 都是稳妥选择。安装方式分平台Windows去 Node.js 官网下载 LTS 的.msi安装包一路下一步。装完打开 PowerShell 敲node -v和npm -v能出版本号就成。macOS推荐用nvm管理版本别直接装 pkg。命令是curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash然后nvm install --lts再nvm use --lts。Ubuntu / Linux同样推荐 nvm或者用 NodeSource 的源装 LTS。别用apt install nodejs那个版本往往太老。装完验证一下node -v # 期望输出类似 v20.11.0 或 v22.x.x npm -v # 期望输出 10.x 或更高如果node -v报“command not found”说明 PATH 没配好Windows 重启终端Linux/macOS 检查~/.bashrc或~/.zshrc里有没有 nvm 的初始化脚本。注意如果你之前装过旧版 Node.js建议先卸载干净再装 LTS避免多版本打架。Windows 上尤其容易残留去“应用和功能”里把 Node.js 相关项全卸了再重装。3.2 YAML 基础写对缩进就成功了一半openrig 的配置文件是 YAML很多人第一次写 YAML 就栽在缩进上。YAML 用缩进表示层级不能用 Tab只能用空格而且同一层级缩进必须一致。这是硬规则违反了直接解析失败。一个典型的 openrig 配置大概长这样providers: - name: local-lmstudio type: openai-compatible base_url: http://127.0.0.1:1234/v1 api_key: not-needed models: - name: qwen2.5-coder-7b alias: local-coder - name: cloud-service type: anthropic-compatible base_url: https://api.example.com api_key: ${CLOUD_API_KEY} models: - name: claude-sonnet alias: cloud-sonnet defaults: provider: local-lmstudio model: local-coder几个关键点解释一下providers是个列表每一项是一个模型服务来源。type决定 openrig 用什么协议去跟这个服务通信常见的有openai-compatible和anthropic-compatible。base_url是服务地址本地模型就填127.0.0.1加端口。api_key支持环境变量引用写成${VAR_NAME}这样密钥不用明文写在文件里安全又方便分享。defaults指定默认用哪个 provider 和 model工具端不指定时就走这个。YAML 里还有个小技巧字符串如果包含特殊字符比如冒号、井号最好用引号包起来避免解析歧义。比如base_url: http://127.0.0.1:1234/v1加引号更保险。3.3 目录结构规划别把配置扔得到处都是我建议在用户目录下建一个统一的工作目录比如~/openrig-workspace里面放openrig-workspace/ ├── config/ │ └── openrig.yaml # 主配置 ├── logs/ │ └── openrig.log # 运行日志 └── scripts/ └── start.sh # 启动脚本这样做的好处是配置、日志、脚本集中管理出问题好排查迁移也好打包。别把 YAML 随手扔在桌面或者项目根目录时间一长你自己都找不到。4. 核心配置实操把 Claude Code 和 Codex 接进来4.1 openrig 安装与初始化假设你已经装好了 Node.js LTS接下来装 openrig。如果它是 npm 包命令大概是npm install -g openrig装完验证openrig --version如果报“command not found”检查 npm 全局 bin 目录有没有在 PATH 里。Linux/macOS 下通常是~/.npm-global/bin或/usr/local/binWindows 下是%APPDATA%\npm。初始化配置openrig init这个命令一般会在当前目录或用户目录下生成一份示例 YAML你基于它改就行。如果它没生成手动建一个openrig.yaml把上一节的模板抄进去。4.2 接入本地 LM Studio 模型本地模型的好处是免费、隐私好、不怕断网。LM Studio 跑起来后默认会在127.0.0.1:1234提供一个 OpenAI 兼容接口。配置里这样写providers: - name: local-lmstudio type: openai-compatible base_url: http://127.0.0.1:1234/v1 api_key: lm-studio models: - name: qwen2.5-coder-7b-instruct alias: local-coder注意api_key这里 LM Studio 不校验随便填一个非空字符串就行但不能留空有些客户端留空会报错。name要跟 LM Studio 里加载的模型名完全一致大小写都不能错否则会报“model not found”。配好后启动 openrigopenrig serve然后用 curl 测一下转发是否通curl http://127.0.0.1:8080/v1/models如果返回模型列表说明 openrig 到 LM Studio 这条链路是通的。4.3 让 Claude Code 走 openrigClaude Code 默认会读环境变量里的 API 地址和密钥。你要做的是把它的 base URL 指向 openrig 的本地端口密钥填 openrig 约定的占位符。以常见的环境变量为例export ANTHROPIC_BASE_URLhttp://127.0.0.1:8080 export ANTHROPIC_API_KEYopenrig-localWindows PowerShell 下$env:ANTHROPIC_BASE_URLhttp://127.0.0.1:8080 $env:ANTHROPIC_API_KEYopenrig-local设完重启 Claude Code它就会把请求发给 openrigopenrig 再根据 YAML 里的defaults决定转发给谁。这样你换模型只改 YAMLClaude Code 那边完全不用动。提示环境变量是会话级的关掉终端就没了。想持久化Linux/macOS 写进~/.bashrc或~/.zshrcWindows 用setx命令或者系统环境变量面板。4.4 让 Codex 走 openrigCodex 的配置方式跟 Claude Code 不太一样它通常有一个配置文件比如~/.codex/config.yaml或~/.codex/config.toml。你需要把里面的服务地址指向 openrig。以 YAML 格式为例model_provider: openrig providers: openrig: base_url: http://127.0.0.1:8080/v1 api_key: openrig-local wire_api: responses这里wire_api是个关键参数。Codex 支持不同的 API 协议responses和chat是两种常见模式。如果你接的后端是 OpenAI 兼容的 chat 接口就填chat如果后端支持 responses 协议就填responses。填错了会报类似cc switch local proxy failed while handling codex endpoint /responses的错本质是端点对不上。配好后跑一下 Codex看它能不能正常出结果。如果报 404多半是base_url后面少了或多了/v1这个要跟 openrig 实际暴露的路径对齐。4.5 多模型切换的配置技巧openrig 最爽的地方是多模型切换。你可以在 YAML 里配好几个 provider然后通过改defaults或者用命令行参数临时切换。比如defaults: provider: local-lmstudio model: local-coder想临时用云端模型启动时加参数openrig serve --provider cloud-service --model cloud-sonnet或者更优雅的做法是配多个 profileprofiles: fast: provider: local-lmstudio model: local-coder smart: provider: cloud-service model: cloud-sonnet启动时openrig serve --profile smart就切过去了。这个设计特别适合“日常用本地模型省钱复杂任务切云端模型”的工作流。5. 常见报错与排查那些让人头大的错误信息5.1 报错速查表我把实际遇到的和热词里出现的高频报错整理成表方便你对号入座报错信息可能原因排查方向cc switch local proxy failed while handling codex endpoint /responsesCodex 的 wire_api 与后端不匹配检查wire_api是responses还是chat与后端协议对齐error installing 24.21.0: node.js v24.21.0 is not yet releasedNode.js 版本号不存在或镜像源异常改用 LTS 版本清理 npm 缓存后重装your organization has disabled claude subscription access账号权限或订阅问题检查账号状态或改用 API Key 方式接入the gpt-5.6-sol model is not supported when using codex模型名不被 Codex 支持换成 Codex 支持的模型名或在 openrig 里做别名映射model not found模型名与后端不一致核对 YAML 里的 name 与后端实际模型名ECONNREFUSED 127.0.0.1:1234本地模型服务没启动确认 LM Studio 已加载模型并开启服务401 Unauthorized密钥错误或缺失检查 api_key 配置确认环境变量已生效404 Not Foundbase_url 路径不对检查是否漏了或多写了/v15.2 排查思路从链路两端往中间查遇到报错别慌按这个顺序查先确认后端服务活着直接 curl 后端地址比如curl http://127.0.0.1:1234/v1/models能返回就说明后端没问题。再确认 openrig 活着curl http://127.0.0.1:8080/v1/models能返回说明 openrig 转发正常。最后确认工具端配置检查环境变量或配置文件里的地址、密钥、模型名。看日志openrig 的日志会记录每个请求转发到哪、返回什么状态码这是最直接的线索。这个“两端往中间查”的方法能帮你快速定位问题出在哪一段而不是盲目改配置。5.3 几个容易忽略的细节端口冲突openrig 默认端口如果被占用会启动失败。换个端口或者把占用端口的进程干掉。防火墙Windows 上本地回环一般不受防火墙影响但如果你把服务暴露到局域网记得放行端口。编码问题YAML 文件保存成 UTF-8别用 GBK否则中文注释会乱码严重时解析失败。缓存问题改完配置记得重启 openrig有些实现不会热加载配置不重启不生效。注意排查时养成“改一个变量、测一次”的习惯别一次改一堆否则出了问题不知道是哪个改动导致的。6. 进阶玩法与个人经验6.1 用别名做模型映射不同工具对模型名的要求不一样Claude Code 可能认claude-sonnetCodex 可能认gpt-4但你后端只有一个本地模型。这时候用 openrig 的别名功能做映射models: - name: qwen2.5-coder-7b-instruct alias: claude-sonnet - name: qwen2.5-coder-7b-instruct alias: gpt-4同一个模型挂多个别名工具端要哪个名字都给后端统一指向同一个模型。这个技巧在多工具共存时特别有用。6.2 密钥管理别把密钥写进 YAMLYAML 里永远只写${ENV_VAR}真实密钥放环境变量。团队分享配置时把 YAML 发出去就行密钥各自配。这是基本的安全习惯也是配置能复用的前提。6.3 我踩过的几个坑第一个坑是 Node.js 版本。我一开始图省事用了某个非 LTS 版本结果 openrig 的某个依赖编译不过折腾半天换回 LTS 才好。第二个坑是 YAML 缩进我用编辑器自动格式化把 Tab 和空格混用了解析直接报错找了半小时才发现是缩进问题。第三个坑是 Codex 的wire_api我一开始填的chat但后端只支持responses报了一堆端点错误改成responses立马通了。这些坑的共同点是报错信息不直接指向根因。所以排查时要有耐心从链路两端往中间查别被表面报错带偏。6.4 后续可以怎么扩展openrig 这套配置思路其实可以扩展到更多场景。比如你可以给它加一个简单的 Web 界面可视化切换 profile或者加一个配置校验命令启动前先检查 YAML 合法性再或者把配置存到团队共享的仓库里用 CI 做配置校验。这些扩展都不难核心还是那份 YAML 和那个转发层。我个人在实际操作中的体会是配置管理这件事越早统一越省事。一开始多花半小时把 openrig 配好后面每天省下的切换和排查时间早就赚回来了。尤其是同时用多个 AI 编程工具的人这套方案基本是刚需。