1. openrig 到底是个什么东西第一次看到 openrig 这个名字我下意识以为是某个硬件外设或者开源机械臂项目毕竟 rig 这个词在硬件圈太常见了。但翻了一圈社区讨论和仓库结构之后才明白它其实是一个围绕 AI 编程助手做配置编排与本地代理转发的工具层。简单说openrig 想解决的问题是当你同时用 Claude Code、Codex 这类命令行 AI 编程工具又想让它们统一走本地模型或者第三方兼容接口时中间那层翻译路由配置管理的活儿由它来干。这个定位其实非常务实。现在用 Claude Code 和 Codex 的人越来越多但每个人手里的资源不一样有人用官方订阅有人接 DeepSeek有人接 GLM有人本地跑 LM Studio还有人用 Qwen。每个工具的配置文件格式不同、环境变量不同、端点路径不同切换一次模型要改一堆东西改错了还报一堆看不懂的错。openrig 的核心价值就是把这些碎片化的配置收敛成一套 YAML 驱动的声明式方案让你改一个文件就能切换后端。它适合谁三类人最需要第一类是同时用 Claude Code 和 Codex 的开发者想统一管理两套配置第二类是习惯本地模型、经常在 LM Studio 和云端 API 之间来回切的人第三类是团队里要统一开发环境、不想每个人手动配一遍的 Tech Lead。如果你只是偶尔用一下某个 AI 编程工具那 openrig 可能有点重但只要你开始觉得配置管理这件事烦人了它就值得看。需要提前说明的是openrig 本身不是一个模型也不是一个 API 服务它更像是一个编排层。理解这一点很关键因为很多人第一次接触会误以为装完就能用实际上它依赖 Node.js 运行时依赖 YAML 配置文件还需要你至少有一个可用的模型后端。下面我会把整个链路拆开讲清楚。2. 核心设计思路与方案选型拆解2.1 为什么用 YAML 而不是 JSON 或 TOMLopenrig 选择 YAML 作为配置载体这个决定背后有很实际的考量。JSON 的问题是写注释不方便而 AI 工具的配置里经常需要标注这个 key 从哪来的这个端点什么时候换的注释很重要。TOML 虽然可读性好但嵌套结构表达起来比较啰嗦尤其是当你要描述多个 provider、多个 model、多个路由规则的时候TOML 的层级会变得很长。YAML 的优势在于它天然适合表达层级化的声明式配置。你可以这样理解一份 openrig 配置就像一张路由表顶层是 provider中间是 model底层是具体的参数覆盖。用 YAML 写出来缩进一眼就能看出层级关系改起来不容易改错。而且 YAML 支持锚点和引用多个 provider 共享同一段公共配置时不用复制粘贴这在管理多个模型后端时非常省事。提示YAML 对缩进极其敏感Tab 和空格混用是最常见的报错来源。建议统一用两个空格缩进并且在编辑器里开启显示空白字符。2.2 为什么依赖 Node.js 运行时openrig 跑在 Node.js 上这个选择跟它的目标用户群高度相关。Claude Code 和 Codex 的 CLI 本身就是 Node.js 生态的产物用户装这两个工具的时候大概率已经装过 Node.js 了。openrig 复用这个运行时等于零额外环境成本。另外 Node.js 在处理流式响应streaming和 HTTP 代理转发方面非常成熟AI 编程工具的响应基本都是流式的用 Node.js 做中间层转发背压处理和 chunk 透传都很自然。这里有个坑要提前说Node.js 版本不能太老。openrig 用到了一些较新的 API实测 Node.js 18 LTS 是底线20 LTS 更稳。如果你系统里是 16 甚至更早装依赖的时候就会报各种奇怪的错。网上搜 node.js v24.21.0 is not yet released 这类报错的人多半是版本管理工具比如 nvm的索引没更新或者 package.json 里锁了一个不存在的版本号跟 openrig 本身没关系但会卡住安装流程。2.3 本地代理转发的核心机制openrig 最关键的一环是本地代理转发。它的工作模式是在本地起一个 HTTP 服务监听某个端口然后把 Claude Code / Codex 发出的请求接住根据 YAML 里的路由规则转发到真正的后端本地 LM Studio、DeepSeek、GLM 等再把响应原路返回。为什么要多这一层因为不同工具对 API 的请求格式要求不一样。Claude Code 走的是 Anthropic 风格的端点Codex 走的是 OpenAI 风格的/responses端点。如果你直接让 Codex 去连一个只支持 OpenAI chat completions 格式的后端就会报 cc switch local proxy failed while handling codex endpoint /responses 这类错误。openrig 的代理层做的就是协议适配把进来的请求翻译成后端能懂的格式把后端的响应翻译回工具期望的格式。这个设计的好处是解耦。你的工具配置永远指向http://localhost:某端口后端怎么换都不用动工具本身。坏处是多了一层出问题的时候排查链路变长了所以后面我会专门讲排查方法。3. 环境准备与依赖安装实操3.1 Node.js 安装的正确姿势不管你用 Windows、macOS 还是 Ubuntu我都强烈建议用版本管理器而不是直接下安装包。Windows 上用 nvm-windowsmacOS 和 Linux 上用 nvm。原因很简单AI 工具生态更新快今天要 20 LTS明天某个工具可能要求 22用版本管理器一条命令就能切不用卸载重装。安装完先验证node -v npm -v如果node -v输出的是 v18 以下先升级。Ubuntu 上如果遇到权限问题不要用sudo npm install -g那样会把全局包装到 root 目录下后面普通用户跑的时候找不到。正确做法是配置 npm 的全局目录到用户目录mkdir -p ~/.npm-global npm config set prefix ~/.npm-global export PATH~/.npm-global/bin:$PATH最后那行要写进~/.bashrc或~/.zshrc否则新开终端就失效了。3.2 openrig 的获取与初始化拿到 openrig 之后第一步是装依赖npm install这一步如果卡住或者报网络错误先检查 npm 源。国内环境建议换成国内镜像源但注意有些企业内网会禁用外部源这种情况就得找内部镜像。装完之后通常会有一个初始化命令生成默认的 YAML 配置文件。这个文件是整个 openrig 的核心后面所有调整都在这里做。初始化之后目录结构大概是这样的一个主配置文件一个可选的本地覆盖文件还有日志目录。主配置文件进版本控制本地覆盖文件进.gitignore这样团队协作时公共配置统一个人密钥和本地路径各自管理。这个模式很实用建议一开始就这么分。3.3 配置文件的第一版怎么写新手最容易犯的错是一上来就写一大堆 provider结果一个都跑不通。我的建议是先跑通一条链路再扩展。第一版配置只写一个 provider指向你最容易验证的后端。如果你本地有 LM Studio就先连它因为不涉及网络和密钥排查最简单。一个最小可用的配置结构大致包含三块服务监听配置端口、host、provider 列表每个 provider 的 base URL 和密钥引用、路由规则哪个工具走哪个 provider。密钥不要直接写在主配置里用环境变量引用YAML 里写${ENV_NAME}这种形式运行时从环境读取。注意YAML 里引用环境变量时不同工具的语法不一样有的是${VAR}有的是$VAR还有的是{{VAR}}。写之前一定确认 openrig 用的是哪种写错了不会报语法错但会当成普通字符串传过去然后后端返回 401排查半天。4. 打通 Claude Code 与 Codex 的关键配置4.1 Claude Code 侧的接入要点Claude Code 接入 openrig 的核心是改它的 API 端点。默认情况下 Claude Code 连的是官方端点你要通过环境变量或者它自己的配置文件把它指向 openrig 的本地端口。常见做法是设置ANTHROPIC_BASE_URL之类的环境变量具体变量名以 Claude Code 当前版本的文档为准因为这类工具改配置项挺频繁的。这里有个高频问题很多人配完之后 Claude Code 报 your organization has disabled claude subscription access for claude code。这个报错通常不是 openrig 的问题而是 Claude Code 还在尝试用订阅身份去连说明你的端点覆盖没生效或者环境变量没被正确读取。排查顺序是先确认环境变量在当前 shell 里echo得出来再确认 Claude Code 启动时确实读到了这个变量有些工具只读特定配置文件不读 shell 环境变量。VSCode 里用 Claude Code 插件的话环境变量的传递又不一样。VSCode 从图形界面启动时不会继承你 shell 里的环境变量需要在 VSCode 的 settings 里配terminal.integrated.env.*或者干脆从终端里用code命令启动 VSCode。这个坑我踩过配了半小时以为 openrig 有问题结果是 VSCode 根本没拿到环境变量。4.2 Codex 侧的接入要点Codex 的接入比 Claude Code 稍微绕一点因为它走的是/responses端点格式跟传统的 chat completions 不同。openrig 的代理层要能把 Codex 发过来的请求正确翻译。如果你看到 cc switch local proxy failed while handling codex endpoint /responses 这个错误基本可以定位为代理层收到了 Codex 的请求但在转发或翻译环节失败了。可能的原因有三个一是后端根本不支持/responses这种语义需要 openrig 做格式转换但配置里没开启二是模型名对不上比如你配置里写的模型名后端不认识报 the gpt-5.6-sol model is not supported 这类错三是请求头里的认证信息没被正确透传。排查的时候先看 openrig 的日志日志里通常会打印出原始请求和转发请求对比一下就能看出是哪一步断的。Codex 还有一个常见问题是无法加载组织设置。这个多半跟认证态有关Codex 启动时会去拉组织级配置如果端点被改到了本地这个拉取就会失败。解决办法是在配置里关掉组织设置的拉取或者让 openrig 对这个特定请求返回一个空的有效响应。具体怎么配要看 openrig 版本思路是拦截并短路这类请求。4.3 多后端切换的配置组织方式当你同时配了 DeepSeek、GLM、Qwen、本地 LM Studio 之后配置文件的组织就很重要了。我的做法是按用途而不是按厂商来分组。比如分三组fast响应快、便宜日常补全用、strong能力强、贵复杂重构用、local本地、离线、隐私敏感场景用。每个工具的路由指向一个组名组内具体用哪个 provider 可以随时换工具侧完全无感。这样组织的好处是你切换模型的时候改的是组定义不是每个工具的配置。团队协作时每个人可以根据自己的资源覆盖组定义但工具配置保持一致减少我这能跑你那不能跑的扯皮。分组典型后端适用场景切换频率fast轻量云端模型日常补全、小改动低strong旗舰云端模型架构重构、复杂调试中local本地 LM Studio隐私代码、离线环境高5. 实操全流程与关键环节记录5.1 从零到跑通的完整步骤我把整个流程按顺序列一遍你可以照着走。第一步确认 Node.js 版本达标node -v输出 18 以上。第二步获取 openrig 代码并npm install这一步失败先解决网络和源的问题。第三步运行初始化命令生成默认配置。第四步编辑配置只保留一个 provider指向本地 LM Studio 或者一个你确定可用的云端端点。第五步启动 openrig观察日志有没有报错。第六步用 curl 直接打 openrig 的端口验证代理层本身是通的。第七步配置 Claude Code 指向 openrig跑一个最简单的对话验证。第八步配置 Codex同样验证。第九步逐步加入更多 provider 和路由规则。第六步特别重要很多人跳过它直接配工具结果工具报错时分不清是 openrig 的问题还是工具的问题。用 curl 验证代理层等于把变量隔离出来curl -X POST http://localhost:你的端口/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer 你的key \ -d {model:你的模型名,messages:[{role:user,content:hi}]}如果这个能返回正常响应说明 openrig 到后端这段是通的问题就在工具到 openrig 这段。反之就是后端配置的问题。5.2 参数选择与计算的实际考量配置里有几个参数值得单独说。第一个是超时时间。AI 编程工具的请求有时候很长比如让它读一个大文件再改超时设太短会中途断掉。我的经验是连接超时设 10 秒读取超时设 300 秒起步复杂任务多的话设到 600 秒。第二个是并发数。本地模型如果显存有限并发设太高会 OOM一般本地后端并发设 1 到 2云端可以设高一些。第三个是重试次数。云端 API 偶尔抽风设 2 到 3 次重试比较合理但要注意重试对非幂等请求可能有副作用AI 对话一般还好。端口选择也有讲究。别用 80、443、3000、8080 这些常被占用的端口选一个 10000 以上的高位端口冲突概率低。如果团队里多人共用一台开发机每个人用不同端口配置里写清楚。5.3 日志与可观测性openrig 的日志是你排查问题的眼睛。启动的时候把日志级别调到 debug能看到每个请求的进出。日志里重点看三样请求的路径、转发的目标 URL、响应状态码。路径对不上说明路由规则有问题目标 URL 不对说明 provider 配置有问题状态码 4xx 说明认证或参数有问题5xx 说明后端本身有问题。建议把日志输出到文件同时终端也能看。长时间跑的时候终端日志会刷屏文件日志方便回溯。日志文件要配轮转不然跑几天就占满磁盘。这个细节很多人不注意等到磁盘满了服务挂了才后悔。6. 常见问题排查与避坑经验6.1 高频报错速查表报错关键词可能原因排查方向local proxy failed /responses代理层翻译失败检查后端是否支持该端点格式看 debug 日志model is not supported模型名不匹配核对配置里的模型名与后端实际支持的名称organization has disabled端点覆盖未生效确认环境变量被工具读取VSCode 需单独配无法加载组织设置认证态拉取失败拦截该请求或关闭组织设置拉取node.js vXX not released版本号不存在检查 nvm 索引或 package.json 锁定的版本401 / 403密钥问题确认环境变量注入成功密钥未过期6.2 几个我踩过的坑第一个坑是 YAML 里的布尔值。YAML 会把yes、no、on、off解析成布尔值如果你某个字段本来想写字符串no结果被解析成false行为就完全不对了。涉及这类值的字段一律加引号。第二个坑是环境变量的加载时机。openrig 启动时读一次环境变量之后你在另一个终端export新变量正在跑的 openrig 是感知不到的。改完环境变量要重启 openrig。这个坑在调试密钥的时候特别容易遇到改了密钥发现没生效其实是没重启。第三个坑是本地模型的上下文长度。云端模型动辄 128K 上下文本地模型可能只有 8K 或 32K。Claude Code 和 Codex 默认会塞很长的上下文进去超过本地模型限制就会报错或者截断。解决办法是在 openrig 配置里对本地 provider 设置上下文上限让代理层提前截断而不是让后端报错。第四个坑是流式响应的缓冲。有些代理配置会默认缓冲整个响应再返回导致 AI 工具那边看起来卡住不动其实是响应被攒着没发。openrig 要确保流式透传是开启的配置里找stream相关的开关确认。6.3 性能与稳定性调优跑通之后如果觉得慢先分清是网络慢还是模型慢。在 openrig 日志里看请求发出到首字节返回的时间如果这个时间很长是后端慢如果首字节很快但整体很慢是模型生成慢。前者换后端或优化网络后者只能换更快的模型或者减少上下文。稳定性方面建议给 openrig 配一个进程守护崩了能自动拉起。开发机上用 pm2 或者 systemd 都行。另外定期检查日志里的错误率如果某个 provider 错误率明显偏高考虑把它从路由里摘掉或者降级。7. 一些延伸玩法与个人体会openrig 这套思路其实可以延伸出不少玩法。比如你可以给它加一层请求日志分析统计每个工具每天用了多少 token、花了多少钱做成一个简单的成本看板。再比如你可以根据时间段路由白天用云端快模型晚上跑批任务用本地模型省钱。还可以做 A/B 对比同一个请求同时发给两个后端对比输出质量帮你决定长期用哪个。我在实际使用中最大的体会是配置管理这件事越早规范化越省事。一开始图快把密钥硬编码在配置里把 provider 写死在工具配置里等到要换的时候就是一场灾难。openrig 这类工具的价值不在于它多高级而在于它逼你把配置结构化、把密钥外置、把路由抽象出来。这三件事做好了后面换什么模型、加什么工具都是改几行 YAML 的事。最后分享一个小技巧把 openrig 的配置文件和你的 dotfiles 一起管理换电脑的时候 clone 下来改一下本地路径和密钥引用就能用。团队里新人入职给他一份配置模板十分钟就能把开发环境搭起来比写一堆文档管用得多。