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.json，Codex 可能读自己的 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 用户可以用 Homebrew，brew install node@20。Ubuntu 用户建议用 NodeSource 的源，别用系统自带的 apt 版本，那个通常太老。

装完之后验证一下：

node -v npm -v

两个命令都能输出版本号，说明环境没问题。然后装 openrig：

npm 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 Studio，Codex 的请求会被转发到云端 Anthropic。

提示：api_key千万不要直接明文写在 YAML 里然后提交到 Git。用${ENV_VAR}的形式引用环境变量，然后在.env文件或系统环境变量里设置真实值。.env文件要加到.gitignore里。

3.3 本地模型接入的关键参数

把 LM Studio 接进来的时候，有几个参数容易搞错。第一个是base_url，LM 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.yaml：

version: 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单位是毫秒，本地模型推理慢，设大一点，云端设小一点。

第三步，启动 openrig：

openrig start --config ./openrig.yaml

它会输出监听地址，通常是http://localhost:8787。第四步，把 Claude Code 和 Codex 的 API 端点指向这个地址。Claude Code 可以通过环境变量ANTHROPIC_BASE_URL=http://localhost:8787来改，Codex 类似，具体变量名看它的文档。

注意：改完环境变量后要重启工具，有些工具是启动时读一次配置，运行中不会热加载。我踩过这个坑，改了配置半天不生效，后来发现是 Claude Code 进程还开着，重启就好了。

4.2 验证路由是否生效

配置完之后怎么确认请求真的走了 openrig？最直接的办法是看 openrig 的日志。启动时加--log-level debug，每个进来的请求都会打印来源工具、匹配到的路由、转发目标。你敲一个 Claude Code 的命令，日志里应该出现tool=claude-code route=primary-local target=local这样的记录。

另一个办法是用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 配置加载失败排查表

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: 2

weight 为 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，确认语法和引用都没问题，再正式启动。这个习惯帮我省了很多次“启动到一半报错然后回滚”的时间。