★ FEATURED ARTICLE 1. openrig 到底是个什么东西第一次看到 openrig 这个名字我下意识以为是某个硬件机架项目毕竟 rig 在英文里就是“装配、机架”的意思。但翻了一圈社区讨论和热词关联之后才反应过来这玩意儿跟物理设备没半点关系它是一个围绕 AI 编程助手做本地代理与配置编排的工具层。简单说openrig 想解决的核心问题是当你同时用 Claude Code、Codex CLI 这类命令行 AI 编程工具时怎么把它们的请求统一管起来、怎么在本地模型和云端模型之间灵活切换、怎么用一份 YAML 就把所有配置说清楚。这个需求不是凭空冒出来的。热词里高频出现的cc switch local proxy failed while handling codex endpoint /responses、codex无法加载组织设置、claude code 调用lmstudio的本地模型全都是真实用户在折腾多工具协作时踩出来的坑。openrig 的定位就是站在这些工具之上做一层“接线板”——你不需要改每个工具的内部逻辑只需要在 openrig 里定义好路由规则剩下的交给它。适合谁来参考三类人最对口。第一类是已经在用 Claude Code 或 Codex CLI但被多套配置搞得头大的开发者第二类是想把本地模型比如通过 LM Studio 跑的模型接进这些工具又不想每次都手动改环境变量的折腾党第三类是对 Node.js 生态熟悉愿意用 YAML 做声明式配置的工程化选手。如果你连 Node.js 是干什么的都还没搞清楚那建议先补一下基础否则后面配置文件里的字段你会看得云里雾里。openrig 本身不是一个模型也不是一个 IDE 插件它更像是一个配置中枢。你可以把它理解成家里的配电箱电从外面进来通过不同的开关分配到各个房间。openrig 就是那个配电箱Claude Code 和 Codex 是房间里的电器YAML 文件就是你贴在配电箱上的标签纸告诉你哪个开关管哪路电。2. 为什么需要 openrig 这层代理2.1 多工具并行的配置噩梦我先说说没有 openrig 之前大家是怎么过的。假设你同时用 Claude Code 和 Codex CLI每个工具都有自己的配置文件、环境变量、API 端点设置。Claude Code 可能读~/.claude/settings.jsonCodex 可能读自己的 TOML 或环境变量。你想把两个工具都指向同一个本地模型服务就得分别改两套配置。更麻烦的是当你临时想从本地模型切回云端模型又得再改一遍。热词里那个cc switch local proxy failed while handling codex endpoint /responses就是典型症状。用户用 cc switch 做本地代理切换结果在处理 Codex 的/responses端点时失败了。为什么会失败因为不同工具对 API 路径的约定不一样Claude Code 走的是 Anthropic 风格的接口Codex 走的是 OpenAI 风格的/responses代理层如果没有做路径映射和协议转换就会在转发时撞墙。openrig 的思路是把这些差异抽象掉。你在 YAML 里声明“我有一个本地模型服务地址是http://localhost:1234/v1”然后声明“Claude Code 走这条路由Codex 走那条路由”openrig 在中间做协议适配和路径重写。这样你改一处配置所有工具跟着变。2.2 YAML 作为配置语言的取舍为什么选 YAML 而不是 JSON 或 TOML这里有个很实际的考量。JSON 不支持注释你写配置的时候想标注“这行是给本地模型用的”都没地方写。TOML 虽然支持注释但嵌套结构写起来比较啰嗦尤其是当你要定义多层路由规则的时候。YAML 在可读性和表达力之间取得了比较好的平衡缩进即层级注释用#就行。当然 YAML 也有坑最大的坑就是缩进必须用空格不能用 Tab。我见过太多人从网上复制一段 YAML 下来粘贴到编辑器里结果因为 Tab 和空格混用导致解析失败报错信息还特别模糊只说“mapping values are not allowed here”新手根本不知道哪里出了问题。openrig 用 YAML 做配置意味着你必须对缩进有洁癖这是使用它的前提。热词里yolov10 yaml文件怎么创建和rstudio的yaml在哪里虽然跟 openrig 不是同一个场景但说明 YAML 这个格式在各个领域都在被广泛使用大家对它的关注度很高。openrig 选择 YAML也是顺应了这个趋势。2.3 Node.js 运行时带来的生态便利openrig 跑在 Node.js 上这个选择很务实。Node.js 的异步 I/O 模型天然适合做代理转发请求进来、转发出去、响应回来整个过程是非阻塞的。而且 Node.js 生态里有大量现成的 HTTP 客户端和 YAML 解析库开发成本低。从用户角度看Node.js 的安装门槛也不算高。热词里node.js安装、node.js官网下载、node.js LTS下载都是高频搜索说明很多人已经在装 Node.js 了。你装完 Node.js用 npm 或 pnpm 全局装一个 openrig就能开始配置。不需要额外装 Python 环境也不需要编译原生模块对前端背景的开发者特别友好。不过要注意版本问题。热词里有个error installing 24.21.0: node.js v24.21.0 is not yet released or is not ava这说明有人试图安装一个还不存在的 Node.js 版本。openrig 对 Node.js 版本有最低要求一般建议用 LTS 版本比如 20.x 或 22.x。你如果用了太老的版本某些 ES 模块语法可能不支持用了太新的非稳定版又可能遇到依赖库还没适配的问题。3. 核心配置细节与实操要点3.1 安装 openrig 的完整步骤先把 Node.js 装好。去 Node.js 官网下载 LTS 版本Windows 用户直接下.msi安装包一路下一步就行。macOS 用户可以用 Homebrewbrew install node20。Ubuntu 用户建议用 NodeSource 的源别用系统自带的 apt 版本那个通常太老。装完之后验证一下node -v npm -v两个命令都能输出版本号说明环境没问题。然后装 openrignpm install -g openrig如果你用 pnpm可以换成pnpm add -g openrig。全局安装的好处是任何目录下都能直接敲openrig命令。装完之后跑一下openrig --version确认安装成功。注意如果你在公司网络环境下npm 全局安装可能会因为权限问题失败。Windows 上建议用管理员权限打开终端macOS 和 Linux 上如果遇到EACCES错误不要用sudo硬来正确做法是配置 npm 的全局目录到用户目录下具体命令是npm config set prefix ~/.npm-global然后把~/.npm-global/bin加到 PATH 里。3.2 YAML 配置文件的结构拆解openrig 的核心配置文件通常叫openrig.yaml放在项目根目录或者用户主目录下。一个典型的配置长这样version: 1 providers: local-lmstudio: type: openai-compatible base_url: http://localhost:1234/v1 api_key: not-needed cloud-anthropic: type: anthropic base_url: https://api.anthropic.com api_key: ${ANTHROPIC_API_KEY} routes: - name: claude-code-local match: tool: claude-code target: local-lmstudio - name: codex-cloud match: tool: codex target: cloud-anthropic我逐段解释一下。version是配置格式版本openrig 升级后如果配置结构有变会靠这个字段做兼容。providers定义模型服务提供方type决定用哪种协议去对话base_url是服务地址api_key可以直接写也可以用环境变量占位符。routes是路由规则match里的tool指定哪个工具发来的请求走这条路由target指向providers里定义的某个提供方。这样 Claude Code 的请求会被转发到本地 LM StudioCodex 的请求会被转发到云端 Anthropic。提示api_key千万不要直接明文写在 YAML 里然后提交到 Git。用${ENV_VAR}的形式引用环境变量然后在.env文件或系统环境变量里设置真实值。.env文件要加到.gitignore里。3.3 本地模型接入的关键参数把 LM Studio 接进来的时候有几个参数容易搞错。第一个是base_urlLM Studio 默认的 OpenAI 兼容端点是http://localhost:1234/v1注意结尾的/v1不能少少了之后请求路径会拼错。第二个是模型名称有些工具会在请求体里带model字段如果你的 LM Studio 里加载的模型名称和请求里的不一致会返回 404。热词里claude code 调用lmstudio的本地模型这个搜索说明很多人卡在这一步。我的经验是先在 LM Studio 里把模型加载好确认它的服务已经启动然后用 curl 测一下curl http://localhost:1234/v1/models如果返回一个 JSON 列表里面有你加载的模型说明服务正常。然后在 openrig 的 provider 配置里把type设为openai-compatible因为 LM Studio 提供的是 OpenAI 风格的接口。Claude Code 原生走的是 Anthropic 协议openrig 会在中间做协议转换把 Anthropic 格式的请求转成 OpenAI 格式发给 LM Studio再把响应转回去。这个转换过程不是无损的。Anthropic 的 messages 格式和 OpenAI 的 chat completions 格式在字段上有差异比如 system prompt 的位置、tool use 的表达方式。openrig 尽量做映射但某些高级功能可能会降级。如果你发现工具调用不正常先检查是不是协议转换丢掉了某些字段。4. 实操过程与核心环节实现4.1 从零搭建一个双工具路由环境我拿一个真实场景来演示。假设你有一台开发机装了 Claude Code 和 Codex CLI本地跑着 LM Studio同时你有 Anthropic 的 API key 想备用。目标是默认走本地模型当本地模型不可用时自动切到云端。第一步确认 LM Studio 服务在跑模型已加载。第二步创建openrig.yamlversion: 1 providers: local: type: openai-compatible base_url: http://localhost:1234/v1 api_key: dummy timeout: 30000 cloud: type: anthropic base_url: https://api.anthropic.com api_key: ${ANTHROPIC_API_KEY} timeout: 60000 routes: - name: primary-local match: tool: [claude-code, codex] target: local fallback: cloud这里fallback字段是关键它告诉 openrig 当local目标请求失败时自动重试cloud。timeout单位是毫秒本地模型推理慢设大一点云端设小一点。第三步启动 openrigopenrig start --config ./openrig.yaml它会输出监听地址通常是http://localhost:8787。第四步把 Claude Code 和 Codex 的 API 端点指向这个地址。Claude Code 可以通过环境变量ANTHROPIC_BASE_URLhttp://localhost:8787来改Codex 类似具体变量名看它的文档。注意改完环境变量后要重启工具有些工具是启动时读一次配置运行中不会热加载。我踩过这个坑改了配置半天不生效后来发现是 Claude Code 进程还开着重启就好了。4.2 验证路由是否生效配置完之后怎么确认请求真的走了 openrig最直接的办法是看 openrig 的日志。启动时加--log-level debug每个进来的请求都会打印来源工具、匹配到的路由、转发目标。你敲一个 Claude Code 的命令日志里应该出现toolclaude-code routeprimary-local targetlocal这样的记录。另一个办法是用openrig status命令它会显示当前活跃的路由和每个 provider 的健康状态。如果本地 LM Studio 挂了local会显示 unhealthy这时候请求会自动走 fallback。我还习惯用 curl 直接打 openrig 的端点来测试curl -X POST http://localhost:8787/v1/messages \ -H Content-Type: application/json \ -d {model:claude-3,messages:[{role:user,content:hi}]}如果返回正常响应说明整条链路通了。如果报错根据错误信息定位是 openrig 配置问题还是下游服务问题。4.3 处理 Codex 的/responses端点兼容问题热词里那个cc switch local proxy failed while handling codex endpoint /responses值得单独说。Codex 用的是 OpenAI 的/responses端点这个端点跟传统的/chat/completions不一样请求体和响应体的结构都有差异。如果你的代理层只实现了/chat/completions的转发Codex 的请求就会 404 或者 400。openrig 在路由匹配时会把/responses路径识别出来然后根据 target provider 的 type 做转换。如果 target 是openai-compatible它会把/responses的请求转成/chat/completions的格式发出去如果 target 是anthropic它会转成 Anthropic 的 messages 格式。这个转换逻辑是 openrig 内置的你不需要自己写。但如果你用的是别的代理工具遇到这个问题排查思路是先确认代理是否支持/responses路径再看请求体里的字段是否被正确映射。常见错误是model字段没传对或者stream参数处理有问题。5. 常见问题与排查技巧实录5.1 配置加载失败排查表现象可能原因解决方法启动报 YAML 解析错误缩进用了 Tab 或空格数不一致统一用 2 空格缩进编辑器设置显示空白字符提示 provider 未定义routes 里的 target 拼写和 providers 键名不一致检查大小写和连字符YAML 键名区分大小写环境变量未替换${VAR}写法但环境变量没设置用echo $VAR确认或在.env文件里定义端口被占用8787 端口已有其他进程换端口--port 8788或杀掉占用进程5.2 请求转发失败的典型场景第一种本地模型服务没启动。LM Studio 有时候会自己休眠你以为它在跑其实端口已经不通了。养成习惯每次开工前 curl 一下/v1/models。第二种API key 无效。云端 provider 如果 key 过期或额度用完会返回 401 或 429。openrig 的 fallback 机制在这种情况下也会触发但如果你两个 provider 都挂了那就只能报错了。第三种超时设置太短。本地模型加载大模型的时候首次推理可能要几十秒如果 timeout 设了 5000 毫秒请求还没出结果就被掐断了。我一般把本地 provider 的 timeout 设到 60000 以上。第四种协议转换丢字段。比如 Claude Code 发了一个带tools定义的请求转成 OpenAI 格式后 tool 的 schema 没对上模型就不知道怎么调工具。这种问题看日志里的请求体对比最直接openrig debug 日志会把转换前后的 payload 都打出来。5.3 我踩过的三个坑第一个坑YAML 里的布尔值。YAML 会把yes、no、on、off解析成布尔值如果你某个字段想写字符串no不加引号就会变成false。我在配置一个模型的别名时写了alias: no结果解析出来是布尔值后面一直报类型错误。加引号就好了。第二个坑路径匹配的优先级。openrig 的路由是按顺序匹配的第一条匹配上的就生效。如果你把宽泛的规则放在前面具体的规则放在后面具体规则永远不会被命中。我一开始把tool: [claude-code, codex]放在最前面后面又写了一条只匹配 codex 的规则想覆盖它结果没生效。后来把具体规则提到前面才行。第三个坑Node.js 版本和依赖的兼容性。我有一次用 nvm 切到了一个很新的 Node.js 版本结果 openrig 依赖的某个 YAML 解析库还没适配启动就报ERR_REQUIRE_ESM。切回 LTS 版本就正常了。所以别追新LTS 是生产环境的稳妥选择。5.4 性能调优的几个参数openrig 本身很轻量性能瓶颈通常在下游模型服务。但有几个参数可以调。max_concurrent控制同时转发的请求数默认是 10如果你本地模型推理慢调小一点避免排队堆积。retry_count控制失败重试次数默认 1配合 fallback 用。log_level生产环境设info就行debug日志量大长期开会影响性能。还有一个容易被忽略的点keep-alive。openrig 到下游 provider 的连接如果每次请求都重建开销不小。配置里可以开keep_alive: true让连接复用。本地模型服务一般支持云端也支持。6. 进阶玩法与扩展思路6.1 多模型负载均衡openrig 的 provider 可以定义多个同类型的目标然后在 route 里用targets数组做轮询或加权。比如你本地跑了两台机器各加载了一个模型可以这样配routes: - name: local-lb match: tool: claude-code targets: - provider: local-a weight: 1 - provider: local-b weight: 2weight 为 2 的会被分配更多请求。这个在团队共享模型服务的时候有用可以根据机器性能分配权重。6.2 请求日志与审计openrig 支持把请求日志写到文件配置logging.output: /var/log/openrig.log。日志里包含时间戳、工具名、路由名、目标 provider、响应状态码、耗时。这些数据可以用来分析哪个工具用得最多、哪个 provider 最稳定、平均响应时间是多少。对于想优化工作流的团队来说这些数据比拍脑袋决策靠谱。6.3 与 VS Code 的配合热词里vscode配置claude code和claude code for vs code说明很多人是在 VS Code 里用 Claude Code 的。openrig 跟 VS Code 不直接交互但你可以把 VS Code 终端里启动的 Claude Code 指向 openrig。方法是在 VS Code 的settings.json里配环境变量或者用.env文件。这样你在编辑器里写代码Claude Code 在终端里跑请求走 openrig 路由体验是连贯的。6.4 配置版本管理openrig.yaml建议纳入 Git 管理但 API key 用环境变量。你可以建一个openrig.example.yaml作为模板提交真实的openrig.yaml加到.gitignore。团队协作时每个人从 example 复制一份填上自己的环境变量。这样配置结构统一敏感信息不泄露。7. 一些个人体会openrig 这类工具的价值不在于它做了多复杂的事情而在于它把原本散落在各个工具里的配置收拢到了一处。我用了大概两个月最大的感受是切换模型的成本从“改三个地方重启两个工具”变成了“改一行 YAML 重启 openrig”。这个体验提升是实打实的。但它也不是银弹。协议转换的边界情况、本地模型的稳定性、YAML 本身的语法陷阱这些都需要你花时间去熟悉。我的建议是先用最小配置跑通一条链路确认 Claude Code 能通过 openrig 访问本地模型然后再逐步加路由、加 fallback、加负载均衡。别一上来就写一大坨配置出了问题排查起来很痛苦。最后分享一个小技巧openrig 的--dry-run模式可以在不实际启动代理的情况下校验配置文件。每次改完 YAML先跑一下 dry-run确认语法和引用都没问题再正式启动。这个习惯帮我省了很多次“启动到一半报错然后回滚”的时间。
阅读完成 · 觉得有帮助？
