1. openrig 到底是个什么东西第一次看到 openrig 这个名字我下意识以为是某个硬件外设的开源项目毕竟 rig 这个词在英文里本就有“装备、装置”的意思。但翻了一圈社区讨论和实际代码之后才明白它其实是一个围绕 AI 编程助手做本地化编排与代理转发的工具层核心解决的是 Claude Code、Codex 这类命令行 AI 编程工具在本地环境里“跑不顺、接不上、切不动”的问题。说白了openrig 干的事情可以类比成给 AI 编程助手做了一套“本地调度台”。你手里可能有 Claude Code也可能有 Codex甚至还想让它们调用本地跑的模型比如通过 LM Studio 暴露出来的接口。这些工具各自有各自的配置方式、认证流程、端点格式混在一起用的时候特别容易打架。openrig 就是把这些东西统一收拢让你在一个地方管理模型来源、代理转发和会话环境。它适合什么人我觉得有三类人特别需要关注。第一类是已经在用 Claude Code 或 Codex 做日常开发的工程师尤其是那些不满足于官方默认模型、想接入第三方 API 或者本地模型的人。第二类是在 Ubuntu 或者 Windows 上折腾 Node.js 环境、经常被版本问题卡住的人因为 openrig 的运行依赖 Node.js 生态环境没配好后面全是坑。第三类是喜欢用 tmux 做终端会话管理的人openrig 和 tmux 的配合能让你在多个 AI 会话之间快速切换不用反复登录和重配。我最初接触 openrig 是因为一个很具体的痛点我在本地用 LM Studio 跑了一个模型想让 Claude Code 直接调用它但 Claude Code 默认的端点格式和 LM Studio 暴露的接口对不上中间需要一个代理层做协议转换。试了几个方案之后发现 openrig 的设计思路最干净它不是简单粗暴地做端口转发而是把模型路由、端点适配和会话保持都考虑进去了。2. 核心机制拆解代理转发与模型路由2.1 为什么需要代理层Claude Code 和 Codex 这类工具在设计上默认只跟官方端点通信它们的请求格式、认证头、响应解析都是针对自家服务定制的。但实际使用中很多人想接入 DeepSeek、Qwen、GLM 这些第三方模型或者干脆用本地 LM Studio 跑模型。这时候直接改工具本身的配置往往行不通因为端点路径和请求体结构不匹配。openrig 的做法是在本地起一个代理服务把 Claude Code 或 Codex 发出来的请求接住按照目标模型提供方的格式重新组装再转发出去。返回的时候反过来做一次适配。这个思路跟常见的 API 网关很像但 openrig 更轻量配置也更贴近个人开发者的使用习惯。注意代理层最怕的是请求体里的字段名对不上。比如 Codex 发出来的请求里有个字段叫max_output_tokens但某些第三方接口只认max_tokens这种细节不处理就会直接报错。2.2 模型路由的基本逻辑openrig 的模型路由不是简单的“一个入口对应一个出口”它支持根据请求里的模型名称做分流。比如你在配置里写了三组映射claude-sonnet走官方端点deepseek-chat走 DeepSeek 的 APIlocal-qwen走本地 LM Studio。当 Claude Code 发起请求时openrig 会读取请求体里的模型标识匹配到对应的上游配置然后完成转发。这个机制的好处是你不需要频繁改 Claude Code 的配置。只要在 openrig 里把路由规则写好切换模型就是改一个字段的事情。我实测下来这种设计比每次手动改环境变量要稳得多尤其是在 tmux 里开了多个会话的时候每个会话可以独立指定模型互不干扰。2.3 与 tmux 的协同方式tmux 在 openrig 的使用场景里扮演的是“会话容器”的角色。因为 AI 编程助手往往是长时间运行的交互式进程如果你只有一个终端窗口切换模型或者重启服务的时候就得中断当前会话。用 tmux 的话你可以开多个 pane一个跑 openrig 代理服务一个跑 Claude Code一个跑 Codex还有一个留着看日志。我自己的习惯是开三个 pane左边大 pane 跑 Claude Code 主会话右上角小 pane 跑 openrig 的日志输出右下角跑一个备用 shell 用来改配置和重启服务。这样任何时候出问题我都能立刻看到日志里的报错信息不用切来切去。3. 环境准备Node.js 与基础依赖3.1 Node.js 版本选择openrig 跑在 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 20.x 的 LTS 是最稳妥的选择。在 Ubuntu 上装 Node.js 20 有两种主流方式。一种是用 NodeSource 的源另一种是用 nvm 做版本管理。如果你只是跑 openrig用 NodeSource 就够了但如果你同时还要折腾其他 Node.js 项目nvm 会更灵活。# 使用 NodeSource 安装 Node.js 20 LTS curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - sudo apt-get install -y nodejs # 验证版本 node -v npm -vWindows 用户直接去 Node.js 官网下载 LTS 版本的安装包就行安装的时候记得勾选“Add to PATH”不然后面在终端里调不到 node 命令。3.2 包管理器与全局安装Node.js 装好之后npm 会跟着一起装上。openrig 的安装方式取决于它发布的形式如果是 npm 包就直接全局安装如果是源码仓库就 clone 下来手动构建。我建议先确认一下 openrig 的发布渠道避免装到过时的版本。# 如果是 npm 包 npm install -g openrig # 如果是源码 git clone openrig-repo-url cd openrig npm install npm run build提示全局安装的时候如果遇到权限报错不要直接用 sudo 硬上那样会把 npm 的缓存和全局目录搞乱。正确的做法是配置 npm 的全局目录到用户目录下或者用 nvm 管理 Node.js 版本这样全局包都装在用户空间里不需要提权。3.3 验证基础环境装完之后别急着配 openrig先确认 Node.js 和 npm 都能正常工作。我见过有人 Node.js 装好了但 npm 的 registry 指向了一个不可用的镜像导致后面所有安装都失败。跑一下npm config get registry确认返回的是官方源或者可用的镜像地址。另外如果你打算用 tmux也顺便确认一下 tmux 的版本。老版本的 tmux 在某些终端模拟器下会有渲染问题建议用 3.0 以上的版本。4. openrig 的配置与实操流程4.1 配置文件结构openrig 的配置通常是一个 JSON 或者 YAML 文件放在用户目录下的隐藏文件夹里或者通过环境变量指定路径。配置的核心部分包括三块监听端口、上游端点列表、模型路由规则。监听端口就是 openrig 代理服务在本地的入口Claude Code 或 Codex 会把请求发到这个端口。上游端点列表里每一项是一个模型提供方的信息包括端点地址、认证方式、请求格式适配器。模型路由规则则是把请求里的模型名称映射到具体的上游端点。{ listen: { port: 8787, host: 127.0.0.1 }, upstreams: [ { name: local-lmstudio, endpoint: http://127.0.0.1:1234/v1, auth: { type: none }, adapter: openai-compatible }, { name: deepseek, endpoint: https://api.deepseek.com/v1, auth: { type: bearer, token: your-token-here }, adapter: openai-compatible } ], routes: [ { model: local-qwen, upstream: local-lmstudio }, { model: deepseek-chat, upstream: deepseek } ] }这个配置的意思是openrig 在本地 8787 端口监听收到模型名称为local-qwen的请求就转发到本地的 LM Studio收到deepseek-chat就转发到 DeepSeek 的 API。4.2 接入 Claude Code 的关键步骤Claude Code 默认会往官方端点发请求要让它走 openrig需要改它的端点配置。通常是通过环境变量或者配置文件指定 base URL。把 base URL 指向http://127.0.0.1:8787然后 Claude Code 发出的请求就会先到 openrig再由 openrig 决定转发到哪里。这里有个细节要注意Claude Code 的请求路径可能是/v1/messages或者类似的格式而 openrig 的上游适配器需要能正确处理这个路径。如果适配器只认/v1/chat/completions那就需要在 openrig 里做路径重写。我建议先在 openrig 的日志里确认请求的实际路径和请求体结构再针对性调整适配器配置。4.3 接入 Codex 的注意事项Codex 的情况稍微复杂一点因为它的请求格式和 Claude Code 不完全一样。社区里有人遇到过cc switch local proxy failed while handling codex endpoint /responses这种报错本质上就是 openrig 的适配器没有正确处理 Codex 发往/responses路径的请求。解决思路是在 openrig 的适配器配置里显式声明对/responses路径的支持并且把 Codex 请求体里的字段映射到目标模型能理解的格式。如果目标模型是 OpenAI 兼容的接口通常需要把 Codex 的请求转换成/v1/chat/completions的标准格式。提示Codex 有时候会忽略不认识的配置项日志里会出现codex is ignoring 1 unrecognized configuration setting这样的警告。这不一定是致命错误但如果发现配置没生效优先检查配置项的拼写和层级是否正确。4.4 调用本地 LM Studio 模型LM Studio 在本地跑模型的时候会暴露一个 OpenAI 兼容的接口默认端口是 1234。openrig 的上游配置里把 endpoint 指向http://127.0.0.1:1234/v1适配器选openai-compatible理论上就能通。但实际用的时候有几个坑。第一LM Studio 的模型名称必须和 openrig 路由规则里的模型名称对上否则 openrig 找不到匹配的上游。第二LM Studio 的接口对请求体里的某些字段比较敏感比如stream字段如果设成 true 但 LM Studio 那边没开流式输出就会卡住。第三本地模型的响应速度取决于你的硬件如果模型太大而显存不够响应会非常慢这时候要适当调大 openrig 的超时时间。5. 常见问题与排查技巧实录5.1 代理启动失败最常见的问题是端口被占用。openrig 默认监听 8787但如果这个端口已经被其他服务占了启动就会失败。排查方法是先用lsof -i :8787或者netstat -tlnp | grep 8787看看谁在用这个端口然后要么停掉那个服务要么改 openrig 的监听端口。另一个常见原因是配置文件格式错误。JSON 文件里多一个逗号或者少一个引号都会导致解析失败。我建议用jq工具先验证一下配置文件是不是合法的 JSONjq . openrig.json如果有语法错误jq 会直接告诉你错在哪一行。5.2 请求转发失败请求转发失败的表现通常是 Claude Code 或 Codex 那边报连接错误或者超时。排查步骤分三层第一层看 openrig 的日志有没有收到请求如果没收到说明 Claude Code 的 base URL 没配对第二层看 openrig 有没有成功转发到上游如果转发失败检查上游端点地址和认证信息第三层看上游返回了什么如果是 401 就是认证问题如果是 404 就是路径不对如果是 400 就是请求体格式不匹配。我整理了一个速查表方便对照排查现象可能原因排查方法openrig 启动报端口占用8787 被其他进程占用lsof -i :8787查看占用进程Claude Code 报连接拒绝base URL 没指向 openrig检查 Claude Code 的端点配置转发后返回 401上游认证信息错误检查 token 是否过期或拼写错误转发后返回 404上游路径不匹配检查适配器的路径重写规则转发后返回 400请求体字段不兼容对比请求体和目标接口文档响应超时本地模型推理太慢调大超时时间或换小模型5.3 模型切换不生效有时候你在 openrig 里改了路由规则但 Claude Code 那边还是走的老模型。这通常是因为 Claude Code 缓存了之前的连接或者配置。解决办法是重启 Claude Code 的会话或者在 tmux 里直接 kill 掉对应的 pane 重新开一个。还有一种情况是 openrig 的配置热重载没生效。有些版本的 openrig 不支持自动重载配置改完之后必须手动重启服务。我建议养成习惯改完配置先重启 openrig再重启 Claude Code确保两边都是最新状态。5.4 与 VS Code 的配合问题如果你在 VS Code 里用 Claude Code 的插件情况会稍微不一样。VS Code 插件可能会用自己的终端环境环境变量不一定和外部终端一致。这时候需要在 VS Code 的 settings.json 里显式配置终端环境变量或者直接在插件的配置项里指定 base URL。我实测下来VS Code 插件和终端版本的 Claude Code 在端点配置上是分开的改了终端的环境变量不一定影响插件。所以如果你两边都用记得两边都配一遍。6. 实操心得与进阶技巧6.1 日志级别调整openrig 默认的日志级别可能只输出错误信息但排查问题的时候你需要看到完整的请求和响应。把日志级别调到 debug 或者 trace能看到每个请求的路径、请求体、响应状态码和响应体。这对定位适配器问题特别有用。不过 debug 日志量很大长时间开着会拖慢性能也会把磁盘写满。我的做法是平时用 info 级别出问题的时候临时切到 debug问题解决后马上切回来。6.2 多模型并行会话用 tmux 开多个 pane每个 pane 里跑一个 Claude Code 会话每个会话通过环境变量指定不同的模型。这样你可以同时让一个会话用本地模型做代码补全另一个会话用 DeepSeek 做代码审查互不干扰。具体操作是在每个 pane 里 export 不同的模型环境变量然后启动 Claude Code。openrig 会根据请求里的模型名称自动路由到对应的上游。这个用法我在实际项目里试过效率提升很明显尤其是需要在不同模型之间对比输出的时候。6.3 超时与重试配置本地模型或者网络不稳定的第三方 API 经常会出现响应慢的情况。openrig 的超时配置要合理设置太短了会频繁超时太长了会卡住整个会话。我的经验是本地模型设 120 秒第三方 API 设 60 秒然后配上两次重试。重试策略也要注意不是所有错误都适合重试。比如 401 认证错误重试多少次都没用但 429 限流或者 503 服务不可用就值得重试。openrig 的重试配置里可以指定哪些状态码触发重试这个细节能省很多事。6.4 配置文件版本管理openrig 的配置文件里可能包含 API token 这类敏感信息直接提交到 Git 仓库不安全。我的做法是配置文件里用环境变量占位实际 token 放在.env文件里.env加入.gitignore。这样配置文件可以安全地做版本管理换机器的时候只需要重新填.env就行。{ auth: { type: bearer, token: ${DEEPSEEK_TOKEN} } }然后在启动 openrig 之前 export 对应的环境变量或者用 dotenv 之类的工具自动加载.env文件。6.5 性能监控如果你长时间跑 openrig建议加一个简单的监控看看请求量、平均响应时间、错误率这些指标。不需要搞得很复杂在 openrig 的日志里 grep 一下状态码就能大致判断。如果错误率突然升高通常是上游服务出了问题或者你的 token 快过期了。我在实际使用中发现openrig 最稳定的状态是上游端点不超过三个路由规则不超过十条。配置太复杂的时候排查问题的难度会指数级上升。所以我的建议是保持配置精简只加真正需要的上游和路由用不到的及时清理掉。6.6 关于 Codex 的特殊处理Codex 和 Claude Code 虽然都是 AI 编程助手但它们的请求格式差异不小。Codex 的/responses端点返回的数据结构跟标准的 chat completions 不一样openrig 的适配器需要专门处理。如果你发现 Codex 的响应解析出错优先检查适配器有没有正确转换响应体里的字段。另外Codex 对模型名称的校验比较严格如果你在路由规则里写的模型名称和 Codex 请求里带的不一致Codex 可能会直接报model is not supported之类的错误。解决办法是在 openrig 的路由规则里把 Codex 可能用到的模型名称都列上或者做一个通配符匹配。6.7 本地模型的选择建议通过 openrig 调用本地 LM Studio 模型的时候模型的选择很关键。不是所有模型都适合做编程助手有些模型在代码生成上的表现明显不如专门优化过的版本。我的经验是优先选参数量在 7B 到 14B 之间的代码专用模型太大了本地跑不动太小了效果差。另外LM Studio 里的模型加载参数也会影响 openrig 的转发效果。比如 context length 设得太小长对话会被截断设得太大显存不够会直接崩。建议根据你的硬件情况从 4096 的 context length 开始试稳定之后再往上调。6.8 跨平台注意事项Ubuntu 和 Windows 上跑 openrig 有一些差异。Ubuntu 下路径分隔符是正斜杠Windows 下是反斜杠配置文件里的路径要对应调整。另外 Windows 下防火墙可能会拦截 openrig 的监听端口第一次启动的时候如果 Claude Code 连不上先检查一下防火墙规则。还有一点Windows 下的终端环境比较复杂cmd、PowerShell、WSL 各有各的环境变量体系。如果你在 WSL 里跑 openrig但 Claude Code 装在 Windows 侧两边网络互通但环境变量不互通需要手动指定端点地址为 WSL 的 IP 而不是127.0.0.1。7. 关于 openrig 的后续扩展思路openrig 目前的定位是本地代理和路由层但这个架构其实还能做更多事情。比如可以在代理层加请求缓存相同的请求直接返回缓存结果减少对上游的调用次数。也可以加请求审计记录每个会话用了哪些模型、消耗了多少 token方便做成本分析。另一个方向是和 CI/CD 流程结合。比如在代码审查环节自动调用 openrig 转发到指定的模型做静态分析把结果写回 PR 评论。这个用法我在一个小项目里试过效果还不错但需要处理好并发和超时的问题。如果你对 openrig 的源码比较熟悉还可以自己写适配器来支持更多非标准的上游接口。适配器的接口设计得比较清晰基本上就是实现请求转换和响应转换两个方法剩下的路由和转发逻辑 openrig 已经帮你处理好了。我个人在实际操作中的体会是openrig 这类工具的价值不在于它本身有多复杂而在于它把原本散落在各处的配置和适配逻辑收拢到了一起。你不需要记住每个模型提供方的端点格式和认证方式只需要在 openrig 里配一次后面切换模型就是改一行配置的事情。这种“一次配置、多处复用”的思路在 AI 编程工具越来越多样化的今天会变得越来越重要。