1. openrig 到底是个什么东西第一次看到 openrig 这个名字我下意识以为是某个硬件外设的开源项目毕竟“rig”这个词在矿机、直播设备、测试台架这些圈子里太常见了。但把标题和那串热搜词放在一起看——Claude Code、Codex、YAML、Node.js——方向就很清楚了这是一个围绕 AI 编程助手做编排、配置和本地化接入的工具类项目。说白了openrig 想解决的是“我手头有好几个 AI 编程工具怎么把它们统一管起来、按需切换、还能本地跑”的问题。我接触这类工具的时间不算短从最早手动改配置文件到后来用脚本批量切换再到现在这种带 YAML 配置的编排方案踩过的坑能写满一个笔记本。openrig 吸引我的点在于它把配置这件事从“散落在各个工具目录里的 JSON”收敛成了“一份 YAML 说了算”而且明确绑定了 Node.js 生态。这意味着你不需要为了用它再去学一门新语言前端、后端、运维的同学都能快速上手。它适合谁三类人最值得看一是同时用 Claude Code 和 Codex 的开发者想省掉来回切换的麻烦二是需要在本地模型和云端模型之间做路由的人比如把简单补全丢给本地、复杂重构丢给云端三是团队里负责统一开发环境的人需要一份可版本管理的配置文件来约束所有人的工具行为。如果你只是偶尔用一下某个 AI 助手那 openrig 可能有点重但只要你开始认真把 AI 编程工具当生产力它就有价值。2. 核心设计思路与方案选型拆解2.1 为什么是 YAML 而不是 JSON 或 TOMLopenrig 选 YAML 作为配置载体这个决定背后有很实际的考量。JSON 的问题是写注释不方便而 AI 工具的配置里恰恰有大量需要解释的地方比如“这个模型走本地是因为延迟低”“这个端点只在特定网络环境下启用”。TOML 虽然支持注释但嵌套结构一深就变得很难读尤其是涉及多工具、多模型、多路由规则的时候。YAML 的优势在于它对层级和列表的表达非常自然。你可以这样描述一个路由规则当请求来自 Claude Code 且模型名包含“local”时转发到本地端点否则走云端。这种带条件的逻辑用 YAML 写出来几乎就是自然语言的映射。而且 YAML 在 DevOps 圈子里已经是事实标准Kubernetes、Ansible、GitHub Actions 都在用学习成本几乎为零。注意YAML 对缩进极其敏感Tab 和空格混用是新手最常见的翻车点。openrig 的配置文件建议统一用两个空格缩进并且在编辑器里开启“显示空白字符”一眼就能看出问题。2.2 Node.js 作为运行时的取舍选 Node.js 而不是 Python 或 Go我认为 openrig 的意图很明确贴近前端和全栈开发者的日常环境。Claude Code 和 Codex 的很多用户本身就是写 JavaScript/TypeScript 的机器上大概率已经装了 Node.js。用 Node.js 写编排层意味着安装成本几乎为零不需要额外配 Python 虚拟环境或者编译 Go 二进制。另一个原因是 Node.js 的异步 I/O 模型非常适合做代理和转发。openrig 的核心工作之一就是在本地起一个轻量服务接收来自各个 AI 工具的请求根据 YAML 里的规则决定转发到哪个上游。这种场景下Node.js 的事件循环机制比同步阻塞的模型更合适而且生态里有大量成熟的 HTTP 客户端和流处理库可以直接用。不过 Node.js 也有它的坑最典型的就是版本问题。热搜词里那条“error installing 24.21.0: node.js v24.21.0 is not yet released”就是活生生的例子——有人照着某个教程去装一个根本不存在的版本。openrig 对 Node.js 版本有要求但不会要求你装什么奇怪的非 LTS 版本老老实实用 LTS 就行。2.3 多工具接入的架构逻辑openrig 要同时伺候 Claude Code 和 Codex这两个工具虽然都是 AI 编程助手但它们的接口形态、认证方式、请求格式并不完全一样。Claude Code 有自己的订阅体系和端点规范Codex 则是另一套。openrig 的做法是在中间加一层适配把不同工具的请求归一化成内部格式再根据配置分发出去。这个设计的好处是解耦。今天你用的是 Claude Code 和 Codex明天想加一个新工具只需要写一个适配器不用动核心逻辑。对用户来说你只需要在 YAML 里声明“我要接入哪些工具、每个工具走哪个端点”剩下的脏活累活 openrig 帮你干了。3. 环境准备与安装实操3.1 Node.js 的正确安装方式不管你用 Windows、macOS 还是 Ubuntu装 Node.js 的第一原则是去官网下 LTS 版本别去第三方站点下什么“优化版”“绿色版”。Node.js 官网的下载页面很直白LTS 那一栏就是给你用的。截至我写这篇内容的时候Node.js 的 LTS 版本号是 20.x 和 22.x 这两个大版本openrig 在这两个版本上都跑得很稳。Windows 用户直接下 .msi 安装包一路下一步就行安装程序会自动把 node 和 npm 加到 PATH 里。macOS 用户如果装了 Homebrew一句brew install node22就搞定。Ubuntu 用户我建议用 NodeSource 的源比系统自带的版本新命令大概是先加源再 apt install具体版本号去 NodeSource 官网查最新的。# Ubuntu 下用 NodeSource 安装 Node.js 22 LTS 的示例 curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash - sudo apt-get install -y nodejs装完之后验证一下node -v npm -v两个命令都能输出版本号说明环境没问题。如果 node 能跑但 npm 报错大概率是 PATH 没配好检查一下安装路径有没有加到环境变量里。提示如果你之前装过其他版本的 Node.js建议先用 nvm 或者系统包管理器清理干净避免多个版本打架。我见过有人机器上同时存在三个 node 可执行文件最后自己都搞不清在用哪个。3.2 openrig 的获取与初始化openrig 的获取方式取决于它的发布形态。如果是 npm 包直接npm install -g openrig就行如果是源码仓库就 clone 下来再npm install。我建议优先看官方仓库的 README里面会写清楚推荐的安装方式。初始化通常分两步先生成一份默认配置再根据你的实际情况改。默认配置里一般会包含几个占位符比如端点地址、API Key 的引用方式、默认路由规则。不要急着把所有东西都填满先让最小配置跑起来再逐步加东西。# 假设 openrig 提供了 init 命令 openrig init # 这会在当前目录生成 openrig.yaml 或者 ~/.openrig/config.yaml生成之后先别改直接尝试启动一次看看能不能正常加载配置。如果启动就报错说明环境还有问题先解决环境再谈配置。3.3 目录结构与配置文件位置openrig 的配置文件位置通常有两个选择项目级和用户级。项目级的放在项目根目录只对当前项目生效用户级的放在 home 目录下对所有项目生效。我的习惯是把通用规则放用户级把项目特有的路由放项目级这样既不会污染全局也不用每个项目都重复写一遍。典型的目录结构大概长这样~/.openrig/ config.yaml # 全局配置 adapters/ # 自定义适配器 logs/ # 运行日志 项目目录/ openrig.yaml # 项目级配置会覆盖全局的同名配置项日志目录很重要出问题的时候第一件事就是看日志。openrig 的日志一般会记录每个请求的来源、目标端点、响应状态排查路由问题时非常有用。4. YAML 配置文件的编写要点4.1 配置文件的基本骨架一份能跑的 openrig 配置至少需要三个部分端点定义、工具定义、路由规则。端点定义告诉 openrig 有哪些上游可以转发工具定义说明要接入哪些 AI 编程工具路由规则决定什么请求走什么端点。endpoints: local: base_url: http://127.0.0.1:1234/v1 api_key: not-needed cloud: base_url: https://api.example.com/v1 api_key: ${CLOUD_API_KEY} tools: claude-code: enabled: true default_endpoint: cloud codex: enabled: true default_endpoint: local routes: - match: tool: claude-code model_contains: local target: local - match: tool: codex target: cloud这个骨架里${CLOUD_API_KEY}是环境变量引用不要把密钥明文写在 YAML 里。openrig 支持这种引用方式启动时会从环境变量里读。4.2 端点配置的细节与陷阱端点配置里最容易出问题的是 base_url 的格式。有些工具要求 URL 以/v1结尾有些要求不带还有些要求带完整的路径。openrig 一般会在适配器里处理这些差异但如果你自己写适配器就要特别注意。另一个坑是超时设置。本地模型端点如果没启动请求会一直挂着默认超时可能长达几十秒。建议在端点配置里显式设置超时endpoints: local: base_url: http://127.0.0.1:1234/v1 timeout_ms: 5000 retries: 1timeout_ms设成 5000 意味着 5 秒没响应就放弃retries设成 1 表示失败后重试一次。这两个参数要根据你的本地模型启动速度来调模型加载慢的话超时给大一点但别超过 30 秒否则用户体验很差。4.3 路由规则的匹配逻辑路由规则是 openrig 最灵活也最容易写错的部分。匹配条件通常支持按工具名、模型名、请求路径、甚至请求头来匹配。多个条件之间是“与”的关系多个规则之间是“从上到下先匹配先赢”。写路由规则的时候我建议把最具体的规则放前面最宽泛的放后面。比如你先写“claude-code 且模型名包含 local 走本地”再写“claude-code 走云端”这样本地规则优先不会被子规则覆盖。注意YAML 里的布尔值 true/false 不要加引号加了引号就变成字符串了。openrig 在解析时如果发现类型不对可能会静默忽略这条规则导致你以为配了但实际没生效。5. 接入 Claude Code 与 Codex 的实操过程5.1 Claude Code 的接入配置Claude Code 的接入核心是让它把请求发到 openrig 的本地端口而不是直接发到官方端点。这通常通过设置环境变量或者修改 Claude Code 的配置文件来实现。具体变量名取决于 Claude Code 的版本常见的有ANTHROPIC_BASE_URL这类。在 openrig 这边你需要确保监听端口和 Claude Code 配置的端口一致。默认端口一般是 8787 或者类似的可以在配置里改server: host: 127.0.0.1 port: 8787然后在 Claude Code 那边把 base URL 指向http://127.0.0.1:8787。如果 Claude Code 有订阅校验openrig 的适配层需要正确处理认证头把请求原样转发或者替换成配置里的密钥。热搜词里有一条“your organization has disabled claude subscription access for claude code”这说明有些组织会禁用订阅访问。这种情况下openrig 的价值就更明显了——你可以把请求路由到其他兼容端点绕过组织限制。当然前提是你有合法的替代端点可用。5.2 Codex 的接入与端点适配Codex 的接入逻辑类似但它的请求格式和认证方式跟 Claude Code 不一样。openrig 需要针对 Codex 写一个适配器把它的请求转换成内部格式再转发到目标端点。Codex 有一个比较特殊的地方是它可能对模型名有校验。热搜词里那条“the gpt-5.6-sol model is not supported when using codex with a...”就是典型的模型名不匹配问题。openrig 可以在路由层做模型名映射把 Codex 发来的模型名替换成目标端点支持的模型名routes: - match: tool: codex model: gpt-5.6-sol target: cloud rewrite: model: gpt-4o这样 Codex 以为自己在用 gpt-5.6-sol实际上请求被转发到了 gpt-4o。这种映射在接入第三方端点时特别有用。5.3 本地模型与云端模型的混合路由混合路由是 openrig 最实用的场景之一。我的配置习惯是代码补全、简单问答走本地模型因为延迟低、不花钱复杂重构、长上下文分析走云端因为能力强。实现方式就是在路由规则里按请求特征分流。判断请求特征的方式有很多比如按请求的 token 数量、按模型名、按工具名。openrig 一般支持在匹配条件里写表达式你可以这样配routes: - match: tool: claude-code max_tokens_gt: 4000 target: cloud - match: tool: claude-code target: local第一条规则说如果请求的最大 token 数超过 4000走云端否则走本地。这样既保证了复杂任务的质量又节省了简单任务的成本。提示本地模型的上下文窗口通常比云端小如果请求超长本地模型可能会截断或者报错。在路由规则里加上 token 数判断可以避免这类问题。6. 常见问题与排查技巧实录6.1 启动失败与端口占用openrig 启动失败最常见的原因是端口被占用。报错信息一般是“EADDRINUSE”意思是地址已经在使用中。解决办法有两个换端口或者找到占用端口的进程杀掉。# macOS/Linux 下查看谁占用了 8787 端口 lsof -i :8787 # Windows 下用 netstat netstat -ano | findstr :8787找到 PID 之后确认那个进程不重要再杀。如果是另一个 openrig 实例在跑直接杀掉旧的就行。6.2 请求转发失败与超时请求转发失败的原因很多按排查顺序我一般这样查先看 openrig 日志有没有收到请求再看目标端点是否可达最后看认证是否通过。如果日志显示请求收到了但转发失败用 curl 直接测目标端点curl -X POST http://127.0.0.1:1234/v1/chat/completions \ -H Content-Type: application/json \ -d {model:local-model,messages:[{role:user,content:hi}]}如果 curl 能通但 openrig 转发不通那就是 openrig 的配置问题重点检查 base_url 和认证头。如果 curl 也不通那就是目标端点本身的问题跟 openrig 无关。6.3 模型名不匹配与端点报错模型名不匹配是接入第三方端点时的高频问题。不同端点支持的模型名不一样Codex 发来的模型名可能目标端点根本不认识。解决办法就是在路由规则里做重写把不认识的模型名映射成认识的。我整理了一个常见问题速查表方便你对照排查现象可能原因排查方法解决方式启动报 EADDRINUSE端口被占用lsof 查端口换端口或杀进程请求 404base_url 路径不对curl 测端点补全或去掉 /v1请求 401认证头缺失或错误看日志请求头检查 api_key 配置请求超时端点不可达或太慢curl 测延迟调大 timeout_ms模型不支持模型名不匹配看端点文档路由里 rewrite model配置不生效YAML 缩进或类型错误用 yamllint 检查修正缩进和引号6.4 配置文件语法错误的快速定位YAML 语法错误有时候报错信息很模糊只说“解析失败”但不告诉你哪一行。这时候可以用在线 YAML 校验工具或者本地装个 yamllintnpm install -g yaml-lint yaml-lint openrig.yaml它会精确指出哪一行哪个字符有问题。我踩过的最隐蔽的坑是中文冒号和英文冒号混用肉眼几乎看不出来但解析器直接报错。用 lint 工具一跑就现原形了。7. 我个人的实操心得与后续扩展用 openrig 这段时间最大的体会是配置文件的版本管理比配置本身更重要。我把 openrig.yaml 放进了 git 仓库每次改动都有记录出问题可以快速回滚。而且团队里其他人可以直接复用我的配置省去了重复沟通的成本。另一个心得是不要一次性把所有功能都配上。我一开始想把 Claude Code、Codex、本地模型、云端模型全接进来结果配置复杂到自己都看不懂。后来改成先接一个工具、一个端点跑通之后再逐步加每次只改一个变量出问题容易定位。后续如果想扩展我建议从两个方向入手一是写自定义适配器把公司内部的其他 AI 工具也接进来二是加监控和统计记录每个端点的调用次数、平均延迟、失败率用数据来优化路由规则。openrig 的架构留了这些扩展点只要 YAML 里能描述清楚实现起来并不复杂。最后分享一个小技巧在路由规则里加一条“兜底规则”把所有没匹配上的请求都转发到一个默认端点。这样即使前面的规则写漏了也不会导致请求直接失败至少有个地方能接住。 
长河君 · 2026/10/3 3:47:56 · 阅读 1.2k openrig 实战：用 YAML 统一编排 Claude Code 与 Codex 的本地化接入
1. openrig 到底是个什么东西第一次看到 openrig 这个名字我下意识以为是某个硬件外设的开源项目毕竟“rig”这个词在矿机、直播设备、测试台架这些圈子里太常见了。但把标题和那串热搜词放在一起看——Claude Code、Codex、YAML、Node.js——方向就很清楚了这是一个围绕 AI 编程助手做编排、配置和本地化接入的工具类项目。说白了openrig 想解决的是“我手头有好几个 AI 编程工具怎么把它们统一管起来、按需切换、还能本地跑”的问题。我接触这类工具的时间不算短从最早手动改配置文件到后来用脚本批量切换再到现在这种带 YAML 配置的编排方案踩过的坑能写满一个笔记本。openrig 吸引我的点在于它把配置这件事从“散落在各个工具目录里的 JSON”收敛成了“一份 YAML 说了算”而且明确绑定了 Node.js 生态。这意味着你不需要为了用它再去学一门新语言前端、后端、运维的同学都能快速上手。它适合谁三类人最值得看一是同时用 Claude Code 和 Codex 的开发者想省掉来回切换的麻烦二是需要在本地模型和云端模型之间做路由的人比如把简单补全丢给本地、复杂重构丢给云端三是团队里负责统一开发环境的人需要一份可版本管理的配置文件来约束所有人的工具行为。如果你只是偶尔用一下某个 AI 助手那 openrig 可能有点重但只要你开始认真把 AI 编程工具当生产力它就有价值。2. 核心设计思路与方案选型拆解2.1 为什么是 YAML 而不是 JSON 或 TOMLopenrig 选 YAML 作为配置载体这个决定背后有很实际的考量。JSON 的问题是写注释不方便而 AI 工具的配置里恰恰有大量需要解释的地方比如“这个模型走本地是因为延迟低”“这个端点只在特定网络环境下启用”。TOML 虽然支持注释但嵌套结构一深就变得很难读尤其是涉及多工具、多模型、多路由规则的时候。YAML 的优势在于它对层级和列表的表达非常自然。你可以这样描述一个路由规则当请求来自 Claude Code 且模型名包含“local”时转发到本地端点否则走云端。这种带条件的逻辑用 YAML 写出来几乎就是自然语言的映射。而且 YAML 在 DevOps 圈子里已经是事实标准Kubernetes、Ansible、GitHub Actions 都在用学习成本几乎为零。注意YAML 对缩进极其敏感Tab 和空格混用是新手最常见的翻车点。openrig 的配置文件建议统一用两个空格缩进并且在编辑器里开启“显示空白字符”一眼就能看出问题。2.2 Node.js 作为运行时的取舍选 Node.js 而不是 Python 或 Go我认为 openrig 的意图很明确贴近前端和全栈开发者的日常环境。Claude Code 和 Codex 的很多用户本身就是写 JavaScript/TypeScript 的机器上大概率已经装了 Node.js。用 Node.js 写编排层意味着安装成本几乎为零不需要额外配 Python 虚拟环境或者编译 Go 二进制。另一个原因是 Node.js 的异步 I/O 模型非常适合做代理和转发。openrig 的核心工作之一就是在本地起一个轻量服务接收来自各个 AI 工具的请求根据 YAML 里的规则决定转发到哪个上游。这种场景下Node.js 的事件循环机制比同步阻塞的模型更合适而且生态里有大量成熟的 HTTP 客户端和流处理库可以直接用。不过 Node.js 也有它的坑最典型的就是版本问题。热搜词里那条“error installing 24.21.0: node.js v24.21.0 is not yet released”就是活生生的例子——有人照着某个教程去装一个根本不存在的版本。openrig 对 Node.js 版本有要求但不会要求你装什么奇怪的非 LTS 版本老老实实用 LTS 就行。2.3 多工具接入的架构逻辑openrig 要同时伺候 Claude Code 和 Codex这两个工具虽然都是 AI 编程助手但它们的接口形态、认证方式、请求格式并不完全一样。Claude Code 有自己的订阅体系和端点规范Codex 则是另一套。openrig 的做法是在中间加一层适配把不同工具的请求归一化成内部格式再根据配置分发出去。这个设计的好处是解耦。今天你用的是 Claude Code 和 Codex明天想加一个新工具只需要写一个适配器不用动核心逻辑。对用户来说你只需要在 YAML 里声明“我要接入哪些工具、每个工具走哪个端点”剩下的脏活累活 openrig 帮你干了。3. 环境准备与安装实操3.1 Node.js 的正确安装方式不管你用 Windows、macOS 还是 Ubuntu装 Node.js 的第一原则是去官网下 LTS 版本别去第三方站点下什么“优化版”“绿色版”。Node.js 官网的下载页面很直白LTS 那一栏就是给你用的。截至我写这篇内容的时候Node.js 的 LTS 版本号是 20.x 和 22.x 这两个大版本openrig 在这两个版本上都跑得很稳。Windows 用户直接下 .msi 安装包一路下一步就行安装程序会自动把 node 和 npm 加到 PATH 里。macOS 用户如果装了 Homebrew一句brew install node22就搞定。Ubuntu 用户我建议用 NodeSource 的源比系统自带的版本新命令大概是先加源再 apt install具体版本号去 NodeSource 官网查最新的。# Ubuntu 下用 NodeSource 安装 Node.js 22 LTS 的示例 curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash - sudo apt-get install -y nodejs装完之后验证一下node -v npm -v两个命令都能输出版本号说明环境没问题。如果 node 能跑但 npm 报错大概率是 PATH 没配好检查一下安装路径有没有加到环境变量里。提示如果你之前装过其他版本的 Node.js建议先用 nvm 或者系统包管理器清理干净避免多个版本打架。我见过有人机器上同时存在三个 node 可执行文件最后自己都搞不清在用哪个。3.2 openrig 的获取与初始化openrig 的获取方式取决于它的发布形态。如果是 npm 包直接npm install -g openrig就行如果是源码仓库就 clone 下来再npm install。我建议优先看官方仓库的 README里面会写清楚推荐的安装方式。初始化通常分两步先生成一份默认配置再根据你的实际情况改。默认配置里一般会包含几个占位符比如端点地址、API Key 的引用方式、默认路由规则。不要急着把所有东西都填满先让最小配置跑起来再逐步加东西。# 假设 openrig 提供了 init 命令 openrig init # 这会在当前目录生成 openrig.yaml 或者 ~/.openrig/config.yaml生成之后先别改直接尝试启动一次看看能不能正常加载配置。如果启动就报错说明环境还有问题先解决环境再谈配置。3.3 目录结构与配置文件位置openrig 的配置文件位置通常有两个选择项目级和用户级。项目级的放在项目根目录只对当前项目生效用户级的放在 home 目录下对所有项目生效。我的习惯是把通用规则放用户级把项目特有的路由放项目级这样既不会污染全局也不用每个项目都重复写一遍。典型的目录结构大概长这样~/.openrig/ config.yaml # 全局配置 adapters/ # 自定义适配器 logs/ # 运行日志 项目目录/ openrig.yaml # 项目级配置会覆盖全局的同名配置项日志目录很重要出问题的时候第一件事就是看日志。openrig 的日志一般会记录每个请求的来源、目标端点、响应状态排查路由问题时非常有用。4. YAML 配置文件的编写要点4.1 配置文件的基本骨架一份能跑的 openrig 配置至少需要三个部分端点定义、工具定义、路由规则。端点定义告诉 openrig 有哪些上游可以转发工具定义说明要接入哪些 AI 编程工具路由规则决定什么请求走什么端点。endpoints: local: base_url: http://127.0.0.1:1234/v1 api_key: not-needed cloud: base_url: https://api.example.com/v1 api_key: ${CLOUD_API_KEY} tools: claude-code: enabled: true default_endpoint: cloud codex: enabled: true default_endpoint: local routes: - match: tool: claude-code model_contains: local target: local - match: tool: codex target: cloud这个骨架里${CLOUD_API_KEY}是环境变量引用不要把密钥明文写在 YAML 里。openrig 支持这种引用方式启动时会从环境变量里读。4.2 端点配置的细节与陷阱端点配置里最容易出问题的是 base_url 的格式。有些工具要求 URL 以/v1结尾有些要求不带还有些要求带完整的路径。openrig 一般会在适配器里处理这些差异但如果你自己写适配器就要特别注意。另一个坑是超时设置。本地模型端点如果没启动请求会一直挂着默认超时可能长达几十秒。建议在端点配置里显式设置超时endpoints: local: base_url: http://127.0.0.1:1234/v1 timeout_ms: 5000 retries: 1timeout_ms设成 5000 意味着 5 秒没响应就放弃retries设成 1 表示失败后重试一次。这两个参数要根据你的本地模型启动速度来调模型加载慢的话超时给大一点但别超过 30 秒否则用户体验很差。4.3 路由规则的匹配逻辑路由规则是 openrig 最灵活也最容易写错的部分。匹配条件通常支持按工具名、模型名、请求路径、甚至请求头来匹配。多个条件之间是“与”的关系多个规则之间是“从上到下先匹配先赢”。写路由规则的时候我建议把最具体的规则放前面最宽泛的放后面。比如你先写“claude-code 且模型名包含 local 走本地”再写“claude-code 走云端”这样本地规则优先不会被子规则覆盖。注意YAML 里的布尔值 true/false 不要加引号加了引号就变成字符串了。openrig 在解析时如果发现类型不对可能会静默忽略这条规则导致你以为配了但实际没生效。5. 接入 Claude Code 与 Codex 的实操过程5.1 Claude Code 的接入配置Claude Code 的接入核心是让它把请求发到 openrig 的本地端口而不是直接发到官方端点。这通常通过设置环境变量或者修改 Claude Code 的配置文件来实现。具体变量名取决于 Claude Code 的版本常见的有ANTHROPIC_BASE_URL这类。在 openrig 这边你需要确保监听端口和 Claude Code 配置的端口一致。默认端口一般是 8787 或者类似的可以在配置里改server: host: 127.0.0.1 port: 8787然后在 Claude Code 那边把 base URL 指向http://127.0.0.1:8787。如果 Claude Code 有订阅校验openrig 的适配层需要正确处理认证头把请求原样转发或者替换成配置里的密钥。热搜词里有一条“your organization has disabled claude subscription access for claude code”这说明有些组织会禁用订阅访问。这种情况下openrig 的价值就更明显了——你可以把请求路由到其他兼容端点绕过组织限制。当然前提是你有合法的替代端点可用。5.2 Codex 的接入与端点适配Codex 的接入逻辑类似但它的请求格式和认证方式跟 Claude Code 不一样。openrig 需要针对 Codex 写一个适配器把它的请求转换成内部格式再转发到目标端点。Codex 有一个比较特殊的地方是它可能对模型名有校验。热搜词里那条“the gpt-5.6-sol model is not supported when using codex with a...”就是典型的模型名不匹配问题。openrig 可以在路由层做模型名映射把 Codex 发来的模型名替换成目标端点支持的模型名routes: - match: tool: codex model: gpt-5.6-sol target: cloud rewrite: model: gpt-4o这样 Codex 以为自己在用 gpt-5.6-sol实际上请求被转发到了 gpt-4o。这种映射在接入第三方端点时特别有用。5.3 本地模型与云端模型的混合路由混合路由是 openrig 最实用的场景之一。我的配置习惯是代码补全、简单问答走本地模型因为延迟低、不花钱复杂重构、长上下文分析走云端因为能力强。实现方式就是在路由规则里按请求特征分流。判断请求特征的方式有很多比如按请求的 token 数量、按模型名、按工具名。openrig 一般支持在匹配条件里写表达式你可以这样配routes: - match: tool: claude-code max_tokens_gt: 4000 target: cloud - match: tool: claude-code target: local第一条规则说如果请求的最大 token 数超过 4000走云端否则走本地。这样既保证了复杂任务的质量又节省了简单任务的成本。提示本地模型的上下文窗口通常比云端小如果请求超长本地模型可能会截断或者报错。在路由规则里加上 token 数判断可以避免这类问题。6. 常见问题与排查技巧实录6.1 启动失败与端口占用openrig 启动失败最常见的原因是端口被占用。报错信息一般是“EADDRINUSE”意思是地址已经在使用中。解决办法有两个换端口或者找到占用端口的进程杀掉。# macOS/Linux 下查看谁占用了 8787 端口 lsof -i :8787 # Windows 下用 netstat netstat -ano | findstr :8787找到 PID 之后确认那个进程不重要再杀。如果是另一个 openrig 实例在跑直接杀掉旧的就行。6.2 请求转发失败与超时请求转发失败的原因很多按排查顺序我一般这样查先看 openrig 日志有没有收到请求再看目标端点是否可达最后看认证是否通过。如果日志显示请求收到了但转发失败用 curl 直接测目标端点curl -X POST http://127.0.0.1:1234/v1/chat/completions \ -H Content-Type: application/json \ -d {model:local-model,messages:[{role:user,content:hi}]}如果 curl 能通但 openrig 转发不通那就是 openrig 的配置问题重点检查 base_url 和认证头。如果 curl 也不通那就是目标端点本身的问题跟 openrig 无关。6.3 模型名不匹配与端点报错模型名不匹配是接入第三方端点时的高频问题。不同端点支持的模型名不一样Codex 发来的模型名可能目标端点根本不认识。解决办法就是在路由规则里做重写把不认识的模型名映射成认识的。我整理了一个常见问题速查表方便你对照排查现象可能原因排查方法解决方式启动报 EADDRINUSE端口被占用lsof 查端口换端口或杀进程请求 404base_url 路径不对curl 测端点补全或去掉 /v1请求 401认证头缺失或错误看日志请求头检查 api_key 配置请求超时端点不可达或太慢curl 测延迟调大 timeout_ms模型不支持模型名不匹配看端点文档路由里 rewrite model配置不生效YAML 缩进或类型错误用 yamllint 检查修正缩进和引号6.4 配置文件语法错误的快速定位YAML 语法错误有时候报错信息很模糊只说“解析失败”但不告诉你哪一行。这时候可以用在线 YAML 校验工具或者本地装个 yamllintnpm install -g yaml-lint yaml-lint openrig.yaml它会精确指出哪一行哪个字符有问题。我踩过的最隐蔽的坑是中文冒号和英文冒号混用肉眼几乎看不出来但解析器直接报错。用 lint 工具一跑就现原形了。7. 我个人的实操心得与后续扩展用 openrig 这段时间最大的体会是配置文件的版本管理比配置本身更重要。我把 openrig.yaml 放进了 git 仓库每次改动都有记录出问题可以快速回滚。而且团队里其他人可以直接复用我的配置省去了重复沟通的成本。另一个心得是不要一次性把所有功能都配上。我一开始想把 Claude Code、Codex、本地模型、云端模型全接进来结果配置复杂到自己都看不懂。后来改成先接一个工具、一个端点跑通之后再逐步加每次只改一个变量出问题容易定位。后续如果想扩展我建议从两个方向入手一是写自定义适配器把公司内部的其他 AI 工具也接进来二是加监控和统计记录每个端点的调用次数、平均延迟、失败率用数据来优化路由规则。openrig 的架构留了这些扩展点只要 YAML 里能描述清楚实现起来并不复杂。最后分享一个小技巧在路由规则里加一条“兜底规则”把所有没匹配上的请求都转发到一个默认端点。这样即使前面的规则写漏了也不会导致请求直接失败至少有个地方能接住。