1. openrig 到底是个什么东西第一次看到 openrig 这个名字我下意识以为是某个硬件机架项目毕竟 rig 这个词在矿机、测试台架、无线电设备里出现频率太高了。直到我在几个 Claude Code 和 Codex 的讨论串里反复看到它被提起才反应过来这是一套围绕 AI 编程助手做统一接入与编排的开源工具链。简单说openrig 想解决的问题是你手头同时有 Claude Code、Codex CLI 这类命令行编程助手每个都有自己的配置格式、模型来源、代理设置和调用习惯切换一次就要改一堆文件openrig 用一份 YAML 配置把这些东西统一管起来再通过 Node.js 跑一个本地服务层把请求分发到不同的模型端点上。它能做的事情很具体。你可以在一份配置文件里声明多个模型提供方比如本地跑的推理服务、云端 API、公司内网网关然后给每个编程助手指定默认走哪条线路。Claude Code 想调本地模型Codex 想接第三方兼容接口以前你得分别去翻两套文档、改两处环境变量现在集中在 openrig 的 YAML 里写清楚就行。它还顺带处理了端点路径重写、请求头注入、模型名映射这些琐碎但容易出错的环节。适合谁来参考三类人最对口。第一类是已经在用 Claude Code 或 Codex但被多套配置搞得头大的开发者第二类是想把本地模型接进编程助手工作流的人比如用 LM Studio 或类似方案跑量化模型再让 Claude Code 去调用第三类是做团队内部工具链统一的人需要给一批人分发一致的助手配置。如果你只是偶尔用一下网页版对话那 openrig 对你来说偏重了但如果你想把手头的 AI 编程助手真正工程化这套东西值得花时间研究。我写这篇的出发点很直接网上关于 openrig 的中文资料几乎是空白而 Claude Code、Codex 的安装配置问题却一大堆什么 cc switch local proxy failed、codex 无法加载组织设置、模型不支持之类的报错满天飞。这些问题的根子往往不在助手本身而在中间那层配置和转发没理顺。openrig 恰好就是冲着这层来的所以把它讲透能顺带解决一大片相关故障。2. 整体设计思路与方案选型拆解2.1 为什么用 YAML 做统一配置层openrig 把配置核心放在 YAML 上这个选择不是随便定的。Claude Code 和 Codex 各自的配置散落在 JSON、TOML、环境变量甚至命令行参数里格式不统一注释支持也参差不齐。YAML 的优势在于可读性强、支持注释、层级表达自然而且 Node.js 生态里解析 YAML 的库非常成熟js-yaml 几乎是标配。你写一份 openrig 的配置等于把原本分散在多处的模型端点、密钥引用、路径规则收敛到一个文件里。从工程角度看YAML 还有个隐性好处它天然适合做版本管理和代码评审。团队里谁改了模型映射、谁加了新端点git diff 一目了然。相比之下环境变量改了什么根本看不出来JSON 又没法写注释解释为什么这么配。我在实际项目里踩过的坑就是早期用一堆 .env 文件管模型配置三个月后没人记得某个变量是干嘛的迁移时删错一个直接全线报错。换成 YAML 加注释之后这种问题基本消失。当然 YAML 也有它的脾气。缩进必须用空格不能用 Tab冒号后面要留空格字符串里的特殊字符要引号包裹。这些规则新手很容易翻车后面我会专门讲排查方法。2.2 Node.js 作为运行时底座的理由openrig 选 Node.js 而不是 Python 或 Go核心考量是生态契合度。Claude Code 和 Codex 这类工具本身就是 npm 生态的产物安装方式基本是 npm install -g 或者通过 npx 调用。用 Node.js 做运行时意味着 openrig 可以无缝复用同一套包管理、同一套进程管理习惯用户不需要为了一个配置工具再装一个 Python 环境。这对 Windows 用户尤其友好Python 在 Windows 上的环境问题历来是重灾区。另一个原因是 Node.js 的异步 IO 模型特别适合做请求转发。openrig 本质上是个中间层要同时处理多个助手的并发请求把 HTTP 请求转发到不同后端再流式返回结果。Node.js 的事件循环在这种场景下表现稳定写起来也简洁。我实测下来用 Node.js 做这层转发单机扛住日常开发强度的并发完全没问题延迟增加基本可以忽略。版本选择上有个硬性提醒。网上有人报 error installing 24.21.0: node.js v24.21.0 is not yet released or is not available这类错误通常是因为指定了一个不存在的版本号或者镜像源还没同步。稳妥做法是用 LTS 版本去 Node.js 官网下载页选长期支持版别追最新的奇数版本。openrig 这类工具对 Node 版本的要求通常是 18 以上20 LTS 或 22 LTS 是最舒服的选择。2.3 端点重写与模型映射的设计意图openrig 最核心的能力其实是端点重写。Claude Code 默认会往某个固定路径发请求Codex 也有自己的端点约定比如 /responses 这种。当你把后端换成第三方兼容接口或本地模型时路径和请求格式往往对不上于是就有了 cc switch local proxy failed while handling codex endpoint /responses 这类报错。openrig 的做法是在配置里声明路径映射规则把助手发出的原始路径改写成后端能识别的路径同时按需调整请求体和请求头。模型映射解决的是另一个痛点。助手内部可能写死了模型名比如某个特定版本号但你的后端只认另一个名字。openrig 允许你配置别名表把助手请求的模型名翻译成后端实际支持的模型名。这样你就不用去改助手源码也不用担心它升级后覆盖你的修改。这个设计思路和反向代理里的 URL 重写是一个道理只是把重写对象从路径扩展到了模型标识。2.4 与直接改助手配置相比的优势有人会问我直接改 Claude Code 或 Codex 的配置文件不就行了为什么要多套一层短期看确实可以但有几个场景下直接改会很难受。第一是多助手共存你改了 Claude Code 的配置Codex 那边还得再改一遍两边格式还不一样。第二是频繁切换今天想用云端模型明天想用本地模型直接改配置意味着每次都要动原始文件容易改乱。第三是团队分发你没法保证每个人的本地环境一致但可以给大家发同一份 openrig 配置。多一层带来的代价是排查链路变长。请求出问题时你要判断是助手的问题、openrig 的问题还是后端的问题。这个后面在故障排查章节会详细讲。总体来说只要你同时用两个以上的助手或者需要频繁切换模型来源这层抽象就是划算的。3. 核心细节解析与实操要点3.1 配置文件的结构长什么样openrig 的配置通常分几个大块全局设置、提供方定义、助手绑定、映射规则。全局设置管端口、日志级别、超时时间这些。提供方定义是重点每个提供方要写清楚类型、基础地址、认证方式、支持的模型列表。助手绑定把 Claude Code、Codex 这些名字和具体的提供方关联起来。映射规则处理路径和模型名的转换。下面是一个结构示意具体字段名以你实际使用的版本为准这里重点看组织方式server: port: 8787 logLevel: info timeout: 120000 providers: local: type: openai-compatible baseUrl: http://127.0.0.1:1234/v1 apiKey: not-needed models: - qwen2.5-coder - deepseek-coder cloud: type: anthropic-compatible baseUrl: https://api.example.com apiKey: ${CLOUD_API_KEY} models: - claude-sonnet assistants: claude-code: provider: local modelMap: claude-3-5-sonnet: qwen2.5-coder codex: provider: cloud pathRewrite: /responses: /v1/responses这个结构的好处是一眼能看出谁走哪条线。apiKey 用 ${} 引用环境变量避免密钥硬编码进文件这是基本的安全习惯。3.2 路径重写的关键细节路径重写是 openrig 里最容易出问题的地方。Codex 的端点 /responses 是个典型例子很多第三方兼容接口并不认这个路径需要改写成 /v1/responses 或者别的形式。配置的时候要注意匹配规则是从头匹配还是包含匹配前缀要不要保留查询参数怎么处理。我的经验是先把助手的原始请求抓出来看。可以在 openrig 里把日志级别调到 debug它会打印每个进出的请求路径。看到原始路径之后再对照后端文档确认正确路径然后写重写规则。别凭猜猜错了就是 cc switch local proxy failed 那种报错而且报错信息往往不告诉你到底是路径错了还是别的问题。重写规则建议写得具体一点别用太宽泛的通配。比如 /responses 改成 /v1/responses 就明确写这两条不要写成把所有请求都加个 /v1 前缀那样可能把本来正确的路径也改坏。3.3 模型名映射的实操方法模型名映射看着简单实际有不少门道。助手请求的模型名可能带版本号、带日期后缀后端支持的模型名又是另一套命名。映射表要覆盖所有助手可能用到的名字漏一个就会在切换模型时报 the model is not supported 之类的错误。有个技巧是开启未匹配告警。openrig 一般支持配置当模型名没有命中映射表时的行为是直接透传还是报错。开发阶段建议设成报错并打日志这样你能快速发现漏配的名字。等映射表稳定了再考虑透传作为兜底。另外要注意大小写和连字符。有的后端对模型名大小写敏感claude-3-5-sonnet 和 Claude-3-5-Sonnet 可能被当成两个东西。映射表里的键值要和实际请求、实际后端严格对齐别想当然。3.4 认证信息的处理方式认证是另一个高频踩坑点。Claude Code 和 Codex 各自有自己的认证机制有的走 API Key有的走 OAuth 令牌有的还涉及组织设置。当你通过 openrig 转发时认证信息可能在多层之间传递容易乱。稳妥做法是让 openrig 统一持有后端认证助手侧用一套简单的本地认证或者干脆不认证仅限本机。这样助手不需要知道后端密钥密钥只在 openrig 的配置或环境变量里。团队场景下每个人本地跑 openrig密钥通过环境变量注入配置文件可以共享密钥不共享。如果遇到 codex 无法加载组织设置这类问题先确认是不是认证信息在转发过程中丢了或者格式不对。openrig 的日志里通常能看到请求头检查一下 Authorization 头有没有正确带上。3.5 本地模型接入的注意事项把本地模型接进 Claude Code 或 Codex 是 openrig 的典型用法。本地推理服务一般提供 OpenAI 兼容接口但兼容程度参差不齐。有的支持流式输出有的不支持有的对请求体字段挑剔多一个少一个都报错。接入前先单独测试本地服务。用 curl 直接打本地端点确认它能正常返回。确认没问题了再通过 openrig 接。这样出问题时能快速定位是本地服务的问题还是 openrig 的问题。我见过不少人一上来就全套接起来结果报错都不知道是哪一层白白浪费时间。还有上下文长度的问题。本地模型往往上下文窗口比云端小Claude Code 发过去的请求可能超出本地模型能接受的长度。这种情况要么换更大的本地模型要么在 openrig 里配置截断策略要么调整助手的使用习惯别一次性塞太多文件。4. 完整实操流程与关键环节4.1 环境准备Node.js 安装与版本确认第一步是把 Node.js 装好。去 Node.js 官网下载页选 LTS 版本。Windows 用户下载 msi 安装包一路下一步就行安装时记得勾选添加到 PATH。macOS 用户可以用官方 pkg 或者包管理器。Linux 用户建议用 NodeSource 的源或者版本管理工具。装完先确认版本node -v npm -v如果 node -v 报错说找不到命令说明 PATH 没配好。Windows 上重新跑一遍安装程序修复或者手动把 Node 安装目录加进环境变量。Linux 和 macOS 检查 shell 配置文件里有没有正确 export。版本方面18 以上都行20 LTS 最稳。如果 npm 装包时报 error installing 某个版本不存在多半是你指定了还没发布的版本号或者用的镜像源没同步。换成 LTS 版本号或者临时切回官方源再装。4.2 安装 openrig 与初始化配置Node.js 就绪后用 npm 全局安装 openrignpm install -g openrig如果权限报错Linux 和 macOS 上加 sudo或者更好的是配置 npm 的全局目录到用户目录下避免每次都要 sudo。Windows 上用管理员权限打开终端。装完跑一下初始化命令一般会生成一份默认配置文件openrig init生成的配置文件通常在用户目录下的 .openrig 或者当前目录。打开它按前面的结构填自己的提供方和助手绑定。第一次配建议只配一个提供方、一个助手跑通了再往上加。贪多嚼不烂一次配五个提供方出问题根本没法排查。4.3 配置 Claude Code 走 openrigClaude Code 侧需要告诉它把请求发到 openrig 的地址。这通常通过环境变量或者 Claude Code 自己的配置完成。常见做法是设置一个基础地址变量指向 openrig 监听的端口比如 http://127.0.0.1:8787。具体变量名以 Claude Code 当前版本的文档为准不同版本可能有差异。设置完之后启动 Claude Code随便问一个问题观察 openrig 的日志有没有收到请求。收到了说明链路通了没收到说明 Claude Code 那边没配对或者 openrig 没起来。这里有个细节Claude Code 可能对基础地址的格式有要求带不带 /v1 后缀结果不一样。先按文档来不行就两种都试试看日志里实际请求的路径是什么。4.4 配置 Codex 走 openrigCodex 的配置类似但端点约定不同。Codex 常用 /responses 这类路径需要在 openrig 里配好重写规则。配置 Codex 时特别注意它的认证方式Codex 可能要求特定的请求头或者令牌格式。如果遇到 codex 登录问题或者组织设置加载失败先确认 Codex 本身的登录状态是正常的。可以先用 Codex 直连官方端点确认能跑通再切到 openrig。这样能排除是 Codex 自身的问题还是转发的问题。Codex 的模型名映射也要单独配。它请求的模型名和 Claude Code 不一定一样映射表要分别覆盖。我建议给每个助手单独一段配置别混在一起清晰且好维护。4.5 启动服务与验证链路配置写完启动 openrigopenrig start前台运行方便看日志。确认没有报错监听端口正常。然后分别启动 Claude Code 和 Codex各发一个测试请求。验证的时候按层次来。第一层openrig 日志有没有收到请求。第二层openrig 有没有成功转发到后端。第三层后端有没有正常返回。第四层助手有没有正确显示结果。哪一层断了就查哪一层别跳步。我习惯用一个最简单的请求做验证比如让助手回答一个固定问题。这样输出可预期容易判断是不是真的通了。别一上来就让它分析整个代码库变量太多。4.6 参数调优与日志级别跑通之后可以调一些参数。超时时间根据后端响应速度设本地模型慢就设长一点云端快可以设短一点。日志级别开发阶段用 debug稳定后调成 info 减少噪音。并发相关的参数一般不用动默认值对个人开发够用。如果团队共用一台 openrig可能需要调大连接数限制但这种情况建议先评估是否该用更专业的网关方案。5. 常见问题与排查技巧实录5.1 请求发出去了但没响应这是最常见的一类问题。表现是助手卡住不动或者转圈很久最后超时。排查顺序是这样先看 openrig 日志有没有收到请求。没收到问题在助手到 openrig 这一段检查地址、端口、防火墙。收到了但没转发出去检查提供方配置的 baseUrl 能不能通用 curl 单独测。转发出去但后端没回问题在后端检查后端服务状态和日志。超时设置不合理也会造成假死。本地模型首次加载可能很慢如果 openrig 超时设得太短请求还没处理完就被掐断了。把超时调大试试。5.2 路径或模型不匹配报错cc switch local proxy failed while handling codex endpoint /responses 这类报错核心就是路径或模型对不上。先开 debug 日志看实际请求路径再对照后端文档。路径重写规则写错了、漏写了、匹配顺序不对都会导致这个问题。模型不匹配的报错信息通常更明确会告诉你哪个模型不支持。去映射表里补上对应的条目。如果映射表里明明有还是报错检查大小写和空格YAML 里多个空格少个空格结果完全不同。5.3 YAML 语法错误排查YAML 报错有时候很隐晦只说解析失败不告诉你哪一行。常见原因用了 Tab 缩进、冒号后没空格、字符串里有未转义的特殊字符、列表项缩进不一致。排查方法是逐段注释掉配置看哪段去掉之后能解析。定位到具体段落后再细看。也可以用在线的 YAML 校验工具先过一遍把语法问题提前排掉。我个人的习惯是写完配置先跑一次校验命令别等启动时报错才回头找。5.4 认证失败与密钥问题认证失败的表现是后端返回 401 或 403。检查 openrig 配置里的密钥是否正确环境变量有没有真的注入进去。有时候环境变量在终端里设了但启动 openrig 的那个终端没继承到就会读不到。团队场景下密钥通过环境变量分发要确认每个人的环境变量名一致。名字写错了读不到读不到就是空值空值就是认证失败。5.5 常见问题速查表现象可能原因排查动作助手无响应地址端口不对检查助手配置的基础地址确认 openrig 在监听转发后超时后端慢或超时太短curl 测后端调大 openrig 超时路径报错重写规则缺失或错误开 debug 日志看实际路径对照后端文档模型不支持映射表漏配补映射条目检查大小写认证失败密钥错误或未注入检查环境变量确认启动终端能读到YAML 解析失败缩进或语法问题逐段注释定位用校验工具组织设置加载失败认证信息转发丢失检查请求头确认 Authorization 正确传递5.6 几个容易忽略的坑第一个坑是端口冲突。openrig 默认端口可能和你机器上别的服务撞了启动时报地址被占用。换个端口就行但记得助手侧也要同步改。第二个坑是代理环境变量干扰。有些机器上设了全局的 HTTP 代理环境变量openrig 转发本地请求时可能被这些变量带偏把本该走本地的请求发到代理去了。检查一下 no_proxy 有没有包含本地地址。第三个坑是配置文件路径。openrig 可能从多个位置找配置当前目录、用户目录、系统目录优先级不同。你以为改的是生效的那份其实改的是被覆盖的那份。启动时看日志里加载的是哪个路径确认改对了文件。第四个坑是版本升级后配置格式变化。openrig 升级可能改了字段名或结构旧配置直接报错。升级前先看变更说明备份旧配置升级后对照新格式调整。6. 我个人的一些实操体会折腾 openrig 这套东西有段时间了最大的感受是中间层的价值在助手数量超过一个之后才真正体现。只用一个助手的时候直接改助手配置确实更省事。但当你 Claude Code 和 Codex 都要用还要在本地模型和云端之间来回切openrig 这种统一配置层的优势就出来了改一处全局生效不用记两套配置格式。另一个体会是日志的重要性。openrig 的 debug 日志基本能覆盖大部分排查场景请求路径、请求头、转发目标、响应状态都在里面。遇到问题第一件事就是开 debug别靠猜。我早期图省事不开日志一个路径问题查了半小时开了日志两分钟就定位了。还有一点是关于配置的渐进式搭建。别想着一次配全先配一个提供方一个助手跑通再加第二个助手再加第二个提供方。每加一步验证一次出问题范围小好定位。一口气配完再调等于给自己挖坑。最后分享一个小技巧把常用的配置片段存成模板。比如本地模型的提供方配置、云端兼容接口的配置各存一份。新环境搭建时直接复制改改比从头写快得多也不容易漏字段。这个习惯在团队里推广开之后新人上手时间能缩短不少。