1. openrig 到底是个什么东西第一次看到 openrig 这个名字我下意识以为是某个硬件外设或者开源机械臂项目毕竟 rig 这个词在工程领域通常指代设备支架、测试台架或者整套装置。但结合热搜词里那一串 Claude Code、Codex、YAML、Node.js 来看这明显是一个围绕 AI 编程助手生态做文章的工具。实际接触下来openrig 的定位更接近一个本地化的 AI 编码助手配置管理与代理转发层它要解决的核心问题是当你同时使用 Claude Code、Codex 这类命令行 AI 编程工具时如何统一管理它们的模型接入、端点配置和请求转发。说白了现在用 AI 写代码的人越来越多但每个人手里的工具链都不一样。有人用 Claude Code 跑终端命令有人用 Codex 做代码补全还有人想把本地 LM Studio 的模型接进来。这些工具各自有各自的配置文件、环境变量和认证方式切换起来非常麻烦。openrig 就是在这个背景下出现的它试图用一套统一的 YAML 配置来管理多个 AI 编程助手的后端接入让你不用每次换模型都去改一堆环境变量。这个项目适合谁呢如果你只是偶尔用用网页版的 AI 对话那 openrig 对你来说可能有点重。但如果你已经习惯了在终端里用 Claude Code 或者 Codex 干活手头又有多个模型来源比如官方的、第三方的、本地跑的那 openrig 能帮你省下大量来回切换的时间。它本质上是一个中间层向上对接各种 AI 编程工具的调用请求向下对接不同的模型服务端点中间用 YAML 做配置描述。我之所以对这个项目感兴趣是因为最近半年 AI 编程工具的碎片化越来越严重。Claude Code 更新频繁Codex 的配置方式又和它不一样再加上各种第三方 API 的接入需求没有一个统一的配置层真的很难受。openrig 的出现恰好踩在了这个痛点上。2. 核心架构与设计思路拆解2.1 为什么选择 YAML 作为配置核心openrig 用 YAML 作为主要配置格式这个选择其实很讲究。YAML 的可读性比 JSON 好支持注释层级结构清晰非常适合用来描述多个工具对接多个模型这种一对多、多对多的关系。你可以在一个文件里定义好几个 provider每个 provider 下面再配置不同的模型和端点然后指定哪个工具用哪个 provider。对比一下其他方案如果用环境变量来管理当配置项超过十个之后就会变得难以维护而且没法表达嵌套关系如果用 JSON虽然结构化能力强但不能写注释改配置的时候容易忘记某个字段是干什么的如果用 TOML表达嵌套结构又不够直观。YAML 在这个场景下确实是最平衡的选择。更重要的是YAML 天然适合做配置即代码。你可以把 openrig 的配置文件纳入版本管理每次调整模型接入方式都留下记录团队协作的时候也能快速同步配置。这一点对于需要频繁切换模型端点的开发者来说非常实用。2.2 代理转发层的设计考量openrig 的另一个核心设计是代理转发。它在本机启动一个轻量服务接收来自 Claude Code 或 Codex 的请求然后根据配置把请求转发到对应的模型端点。这样做的好处是工具侧完全无感——你不需要修改 Claude Code 的源码也不需要给 Codex 打补丁只需要把它们的 API 地址指向 openrig 的本地端口就行。这个设计思路和常见的 API 网关很像但 openrig 更轻量专注于 AI 编程助手这个垂直场景。它不需要处理复杂的鉴权、限流、熔断只需要做好请求格式的转换和路由。比如 Claude Code 发出的请求格式和 Codex 可能不一样openrig 在中间做一层适配让同一个模型端点可以同时服务多个工具。代理层还有一个隐性好处请求日志和调试。当某个工具报错说模型不支持或者端点不通的时候你可以直接在 openrig 的日志里看到原始请求和转发结果排查问题的效率比去翻各个工具自己的日志高得多。2.3 与 Claude Code、Codex 的协作方式Claude Code 和 Codex 虽然都是 AI 编程助手但它们的配置方式差异很大。Claude Code 通常通过环境变量或者配置文件来指定 API 端点而 Codex 的配置更偏向于命令行参数和项目级配置文件。openrig 要同时兼容这两者就需要在配置层面做抽象。我的理解是openrig 的 YAML 配置里应该有一个 tools 段落用来描述每个工具的接入方式。比如 Claude Code 需要设置ANTHROPIC_BASE_URL指向 openrig 的本地地址而 Codex 可能需要通过--api-base参数或者配置文件来指定。openrig 在启动的时候会读取这些配置然后分别启动对应的监听端口或者路由规则。这种设计的好处是配置集中化。你不需要记住每个工具的环境变量名和参数格式只需要在 openrig 的 YAML 里写一次剩下的交给它去分发。对于同时使用多个 AI 编程工具的人来说这能显著降低心智负担。3. 环境准备与依赖安装实操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这说明某些版本号可能对应的是尚未正式发布的版本或者是镜像源同步延迟导致的。我的建议是直接上Node.js LTS 版本目前稳定的是 20.x 系列。LTS 版本经过长时间测试兼容性最好不会因为 Node.js 本身的 bug 导致 openrig 跑不起来。安装方式根据操作系统来Windows去 Node.js 官网下载 LTS 版本的安装包一路下一步就行。安装完成后在 PowerShell 里执行node -v和npm -v确认版本。macOS推荐用nvm或者brew install node20。用 nvm 的好处是可以随时切换版本不会污染系统环境。Ubuntu/Debian用 NodeSource 的源安装比系统自带的 apt 版本要新命令是curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -然后sudo apt install nodejs。安装完成后建议把 npm 的镜像源换成国内源不然装依赖的时候可能会很慢。命令是npm config set registry https://registry.npmmirror.com。这个操作对 openrig 的安装速度提升非常明显。3.2 openrig 的获取与初始化openrig 的获取方式通常有两种从代码仓库克隆或者通过 npm 全局安装。如果项目提供了 npm 包直接npm install -g openrig是最省事的。但考虑到这类工具更新频繁我更推荐从仓库克隆源码这样可以随时拉取最新改动也方便自己改配置。克隆下来之后进入项目目录执行npm install安装依赖。这一步可能会遇到 node-gyp 编译错误尤其是在 Windows 上。解决办法是安装 Visual Studio Build Tools 和 Python 3.x然后设置npm config set msvs_version 2022。如果还是报错可以尝试npm install --ignore-scripts跳过编译脚本但这样可能会影响某些原生模块的功能。依赖装完之后通常会有一个示例配置文件比如config.example.yaml。你需要把它复制成config.yaml然后根据自己的实际情况修改。这个文件就是 openrig 的核心后面所有的模型接入和工具配置都在这里完成。3.3 配置文件的基本结构一个典型的 openrig 配置文件大概长这样server: port: 8787 host: 127.0.0.1 providers: - name: anthropic-official type: anthropic base_url: https://api.anthropic.com api_key: ${ANTHROPIC_API_KEY} models: - claude-sonnet-4-20250514 - claude-opus-4-20250514 - name: local-lmstudio type: openai-compatible base_url: http://127.0.0.1:1234/v1 api_key: not-needed models: - qwen2.5-coder-32b - deepseek-coder-v2 tools: claude-code: enabled: true provider: anthropic-official model: claude-sonnet-4-20250514 codex: enabled: true provider: local-lmstudio model: qwen2.5-coder-32b这个结构里server定义 openrig 自己的监听地址providers定义后端模型来源tools定义每个 AI 编程工具用哪个 provider。用${ANTHROPIC_API_KEY}这种形式引用环境变量可以避免把密钥明文写在配置文件里这是一个很实用的安全习惯。注意配置文件里的缩进必须用空格不能用 Tab。YAML 对缩进非常敏感一个 Tab 就能让整个文件解析失败。建议在编辑器里设置Tab 转空格统一用两个空格做缩进。4. 接入 Claude Code 与 Codex 的完整流程4.1 Claude Code 的安装与配置Claude Code 的安装方式取决于你的使用场景。如果是 VS Code 用户可以直接在扩展市场搜索 Claude Code 安装。如果是终端用户通常通过 npm 全局安装npm install -g anthropic-ai/claude-code。安装完成后在项目目录下执行claude命令就能启动。关键的一步是让 Claude Code 把请求发给 openrig 而不是直接发给官方端点。这通常通过设置环境变量来实现export ANTHROPIC_BASE_URLhttp://127.0.0.1:8787 export ANTHROPIC_API_KEYyour-openrig-token在 Windows 上则是用set或者$env:来设置。设置完成后Claude Code 的所有请求都会先到 openrig再由 openrig 根据配置转发到真正的模型端点。这样做的好处是你可以在 openrig 层面随时切换后端模型而不用去动 Claude Code 的任何配置。有一个常见问题是your organization has disabled claude subscription access for claude code这个报错通常和账号权限有关不是 openrig 能解决的。但如果你是通过第三方 API 接入就不会遇到这个问题因为请求根本不走官方账号体系。4.2 Codex 的接入要点Codex 的配置方式和 Claude Code 不太一样。它更依赖命令行参数和项目级配置文件。在 openrig 的配置里你需要为 Codex 单独指定一个 provider然后确保 Codex 启动时指向 openrig 的地址。Codex 常见的启动方式是通过codex命令配合--api-base参数指定端点。如果 openrig 监听在http://127.0.0.1:8787那么启动命令大概是codex --api-base http://127.0.0.1:8787/v1 --api-key your-token这里要注意路径问题。有些工具要求 base URL 带/v1有些不需要。如果 Codex 报 404先检查一下 openrig 的路由配置和 Codex 请求的路径是否匹配。我一般会在 openrig 的日志里看实际收到的请求路径然后反推应该怎么配。另外Codex 对模型名称比较敏感。如果你在 openrig 里配置的模型名和 Codex 期望的不一致可能会遇到the gpt-5.6-sol model is not supported这类报错。解决办法是在 openrig 的 provider 配置里做模型名映射把 Codex 请求的模型名转换成后端实际支持的模型名。4.3 本地模型接入的实操细节把 LM Studio 或者 Ollama 的本地模型接入 openrig 是很多人关心的场景。以 LM Studio 为例首先在 LM Studio 里启动本地服务默认端口是 1234然后在 openrig 的 providers 里添加一个openai-compatible类型的 providerbase_url 指向http://127.0.0.1:1234/v1。这里有一个细节LM Studio 的 API 是 OpenAI 兼容格式但 Claude Code 发出的是 Anthropic 格式的请求。openrig 需要在中间做格式转换。如果 openrig 内置了转换逻辑那直接配就行如果没有可能需要额外的适配层。我在测试的时候发现部分本地模型对系统提示词的处理和官方模型有差异导致 Claude Code 的行为不太一样。这时候可以在 openrig 配置里加一些请求改写规则比如统一注入系统提示词或者调整 temperature 参数。本地模型的另一个问题是上下文长度。Claude Code 默认假设后端模型有 200K 的上下文窗口但本地跑的模型可能只有 32K 或 128K。如果请求超出模型的实际上下文就会报错。解决办法是在 openrig 配置里限制最大 token 数或者选用上下文更长的本地模型。5. 常见故障排查与避坑指南5.1 代理转发失败的典型原因cc switch local proxy failed while handling codex endpoint /responses这个报错我在测试过程中遇到过好几次。排查下来原因主要有三类第一类是端口冲突。openrig 默认监听的端口可能被其他程序占用了。用netstat -ano | findstr 8787Windows或者lsof -i :8787macOS/Linux检查一下端口占用情况如果被占了就改 openrig 的监听端口。第二类是路径不匹配。Codex 请求的是/responses端点但 openrig 可能只配置了/v1/chat/completions的路由。这时候需要在 openrig 的路由配置里补上对应的路径映射或者确认 openrig 版本是否支持 Codex 的端点格式。第三类是请求体格式不兼容。Codex 发出的请求体结构和 openrig 期望的不一致导致解析失败。这种情况通常需要看 openrig 的调试日志对比原始请求和期望格式然后在配置里加转换规则。5.2 模型不支持与配置错误的处理模型不支持的问题通常表现为model is not supported或者类似的报错。根本原因一般是 openrig 配置里的模型名和后端实际提供的模型名对不上。解决思路是先确认后端模型服务实际提供哪些模型。比如 LM Studio 可以在界面上看到已加载的模型列表第三方 API 一般有/models端点可以查询。然后在 openrig 的 provider 配置里把 models 列表更新为实际可用的模型名。如果工具侧请求的模型名和实际模型名不一致在 openrig 里加一层映射规则。我习惯在配置里保留一个fallback_model字段当请求的模型不可用时自动降级到备用模型。这样即使某个模型临时下线工具也不会直接报错中断。5.3 常见问题速查表问题现象可能原因排查方法解决方式连接被拒绝openrig 未启动或端口不对检查进程和端口监听启动 openrig 或修正端口配置404 Not Found请求路径不匹配查看 openrig 访问日志补充路由映射或调整 base URL401 UnauthorizedAPI Key 未配置或错误检查环境变量和配置文件正确设置 API Key模型不支持模型名不匹配查询后端可用模型列表更新配置或添加映射请求超时后端响应慢或网络问题测试后端端点连通性调整超时时间或更换端点YAML 解析失败缩进用了 Tab 或格式错误用 YAML 校验工具检查统一用空格缩进Node.js 版本报错版本过旧或过新node -v查看版本切换到 LTS 版本5.4 实操心得与避坑建议第一个心得是先跑通再优化。不要一上来就配一堆 provider 和 tool先用最简单的配置把 Claude Code 或者 Codex 其中一个跑通确认代理转发链路没问题再逐步添加其他模型和工具。这样出问题的时候容易定位。第二个心得是日志级别调到 debug。openrig 默认的日志级别可能只输出错误信息排查问题时把日志级别调到 debug可以看到完整的请求和响应内容。虽然日志会比较多但对于定位配置问题非常有用。第三个心得是配置文件做好备份和版本管理。openrig 的配置文件改多了之后很容易忘记哪个版本是能用的。我一般会在项目目录下建一个configs/文件夹每次调整都存一个带日期的副本出问题的时候可以快速回滚。第四个心得是注意环境变量的作用域。在终端里export的环境变量只对当前会话有效关掉终端就失效了。如果希望永久生效需要写进~/.bashrc或者~/.zshrc。Windows 上则是通过系统属性里的环境变量设置来永久生效。6. 进阶用法与扩展思路6.1 多模型负载均衡与故障转移当你有多个模型端点可用时openrig 可以配置成负载均衡模式把请求轮流分发到不同的 provider。这样做的好处是提高可用性某个端点挂了也不影响整体使用。配置上通常是在 tools 段落里指定多个 provider然后设置策略为round-robin或者failover。故障转移模式更适合对稳定性要求高的场景。当主 provider 返回错误或者超时openrig 自动把请求转发到备用 provider。我在配置里会把官方 API 设为主 provider本地模型设为备用这样即使网络波动导致官方 API 不可用本地模型也能顶上。6.2 请求改写与提示词注入openrig 的代理层还可以做请求改写。比如你希望所有经过 openrig 的请求都自动加上一段系统提示词或者统一调整 temperature 参数都可以在配置里定义改写规则。这个功能对于统一多个工具的行为很有用。举个例子Claude Code 和 Codex 默认的提示词风格不一样导致同一个模型在两个工具里的表现有差异。通过 openrig 注入统一的系统提示词可以让模型的行为更加一致。当然改写规则要谨慎使用过度改写可能会导致模型输出不符合工具预期。6.3 与 VS Code 的集成配置VS Code 里使用 Claude Code 或者 Codex 时openrig 的配置方式略有不同。VS Code 扩展通常有自己的设置界面你需要在扩展设置里找到 API 端点配置项填入 openrig 的地址。有些扩展还支持通过settings.json来配置这样可以把配置纳入项目版本管理。在 VS Code 的settings.json里配置大概是这样{ claude-code.apiBaseUrl: http://127.0.0.1:8787, claude-code.apiKey: your-token, codex.apiBaseUrl: http://127.0.0.1:8787/v1 }这样配置的好处是项目级别的设置可以跟着代码仓库走团队里每个人拉下代码后只需要启动 openrig 就能用统一的模型配置不需要各自去配环境变量。6.4 性能调优与资源占用控制openrig 本身是一个轻量代理资源占用主要取决于并发请求量和日志级别。如果发现 openrig 占用内存过高可以先检查日志级别是不是设成了 debugdebug 级别会缓存大量请求日志内存占用会明显上升。把日志级别调回 info 或者 warn 就能降下来。另外如果同时有多个工具通过 openrig 发请求可以适当调整 Node.js 的最大内存限制。通过NODE_OPTIONS--max-old-space-size4096可以把堆内存上限调到 4GB避免大量并发时出现内存不足的错误。当然对于个人使用场景默认配置通常就够用了。我在实际使用中的体会是openrig 这类工具的价值不在于它本身有多复杂而在于它把原本分散在各个工具里的配置集中到了一处。当你需要频繁切换模型或者同时使用多个 AI 编程助手时这种集中管理的优势会非常明显。刚开始配置的时候可能会觉得多了一层但一旦跑通后面换模型、加工具都是改几行 YAML 的事比逐个去改环境变量要省心得多。