openrig 配置编排：多 AI 编程工具统一路由与 YAML 管理实战

1. openrig 到底是个什么东西第一次看到 openrig 这个名字我下意识以为是某个硬件外设的开源项目毕竟“rig”这个词在矿机和无线电圈子里太常见了。但翻了一圈社区讨论和仓库结构之后才反应过来它其实是围绕 Claude Code、Codex 这类命令行 AI 编程工具做的一套配置编排方案。说白了openrig 解决的是一个很具体、很烦人的问题当你同时用好几个 AI 编程助手每个都有自己的配置文件、环境变量、模型端点、代理设置手动切来切去迟早会疯。我自己的日常是这样的主力用 Claude Code 写业务逻辑遇到需要长上下文推理的时候切到 Codex偶尔还要把请求打到本地跑的模型上做隐私敏感的处理。这三套东西的配置格式完全不一样Claude Code 认自己的 settings 文件Codex 认 YAML本地模型又要单独配 endpoint。每次换工具都要改一遍配置改完还经常忘了上次改了什么导致“claude code 安装”明明成功了跑起来却报“your organization has disabled claude subscription access for claude code”这种让人一头雾水的错误。openrig 的思路就是把这些散落的配置统一收拢到一套 YAML 驱动的结构里用 Node.js 做运行时通过一层轻量的本地转发把不同工具的请求路由到正确的后端。它不替代任何工具本身而是在它们之上做了一层“接线板”。这个定位很聪明因为 Claude Code 和 Codex 都在快速迭代你去改它们的源码不现实但在外面套一层编排层就稳得多。适合读这篇的人大概分三类一是刚接触 Claude Code 或 Codex、被安装和配置卡住的新手二是已经在用但被多工具切换折磨的中级用户三是想把这套东西接进团队工作流、需要可复现配置的工程负责人。不管你是哪一类下面这些内容都是我踩过坑之后整理出来的能直接抄作业。2. 整体设计思路与方案选型2.1 为什么是 YAML 而不是 JSON 或 TOMLopenrig 选 YAML 作为配置载体这个决定值得展开说。JSON 的问题是没法写注释而 AI 工具的配置里有大量需要解释的地方比如“这个 endpoint 是给本地模型用的别删”“这个 key 只在测试环境有效”。TOML 虽然能写注释但嵌套结构一深就变得很难读尤其是当你需要描述“多个 provider、每个 provider 下有多个 model、每个 model 有各自的参数覆盖”这种三层结构时TOML 的表格语法会让人抓狂。YAML 的优势在于它对嵌套和列表的表达非常自然而且支持锚点和引用这在配置复用场景下特别有用。举个例子你有三个 provider 都指向同一个本地服务只是模型名不同用 YAML 的锚点可以只写一次 endpoint 和鉴权信息其他两处引用就行。这个特性在“codex 接入 deepseek”或者“claude code 调用 lmstudio 的本地模型”这类场景里能省掉大量重复配置。不过 YAML 也有它自己的坑最大的问题就是缩进敏感。我见过太多人因为多打了一个空格导致整个配置解析失败报错信息还特别模糊。所以 openrig 在解析层做了一层校验会在加载配置时给出相对明确的错误定位。这一点后面在排查章节会细说。2.2 Node.js 作为运行时的取舍选 Node.js 做运行时我觉得主要是三个考虑。第一是生态Claude Code 和 Codex 的 CLI 本身就是 Node 生态的产物用 Node 做编排层可以无缝调用它们的接口不需要跨语言通信。第二是跨平台Windows、macOS、Linux 上 Node 的行为一致性很好这对一个需要覆盖“codex 安装 windows 桌面版”和“ubuntu 配置 claude code”两种场景的工具来说很关键。第三是启动速度Node 的冷启动虽然比不上 Go但对于一个常驻的转发进程来说完全可以接受。这里要提醒一句Node.js 版本的选择有讲究。热词里出现了“error installing 24.21.0: node.js v24.21.0 is not yet released or is not available”这个报错说明有人试图装一个还不存在的版本。我的建议是直接用 LTS 版本也就是“node.js lts 下载”里那个长期支持版。当前 LTS 线在 20.x 和 22.x 之间openrig 对这两个版本都做了测试。不要追最新的奇数版本那些是实验性的依赖兼容性没保证。2.3 本地转发层的设计逻辑openrig 最核心的机制是一层本地转发。它的工作方式是Claude Code 或 Codex 以为自己在跟官方端点通信实际上请求先到了 openrig 在本机监听的端口openrig 根据配置决定这个请求该转发到哪里——可能是官方 API可能是第三方兼容端点也可能是本地跑的模型服务。这个设计解决了一个很实际的问题。很多工具在代码里硬编码了端点地址你没法通过配置改。但如果你在 hosts 层面或者通过环境变量把请求导向本地端口工具本身完全感知不到差异。openrig 就是利用了这个空间把“请求去哪”这个决策从工具内部抽离到了外部配置里。这样做还有一个附带好处所有请求都经过一个统一出口你可以在这里做日志记录、请求改写、失败重试。比如“cc switch local proxy failed while handling codex endpoint /responses”这个报错本质上就是转发层在处理 Codex 的 /responses 端点时出了问题有了统一出口排查起来就有据可依。3. 核心配置细节与实操要点3.1 YAML 配置文件的结构拆解openrig 的配置文件通常叫 openrig.yaml放在项目根目录或者用户主目录下。它的顶层结构大概分四块providers、routes、defaults、logging。providers 定义后端服务的连接信息routes 定义请求路径和 provider 的映射关系defaults 放全局默认参数logging 控制日志级别和输出位置。providers 下面每个条目至少要有 type、base_url、api_key 三个字段。type 决定用哪种协议适配器常见的有 anthropic、openai、local 三种。base_url 是后端地址api_key 可以是明文也可以引用环境变量。我强烈建议用环境变量引用格式是 ${ENV_VAR_NAME}这样配置文件可以进版本库而不会泄露密钥。routes 是很多人第一次配会搞混的地方。它的逻辑是“匹配请求路径然后转发到指定 provider”。比如 Codex 的请求路径是 /responsesClaude Code 的是 /v1/messages你需要为每个路径写一条路由规则。如果某个路径没有匹配到规则openrig 会走 defaults 里指定的 fallback provider或者直接返回错误。提示routes 的匹配是从上到下顺序执行的第一条匹配成功的规则生效。所以把更具体的路径规则放在前面通配规则放在最后。3.2 环境变量与密钥管理密钥管理这块我踩过坑值得单独说。最开始的版本我把 api_key 直接写在 YAML 里结果有一次不小心把配置文件提交到了公开仓库虽然及时发现删掉了但那种心惊肉跳的感觉不想再体验第二次。后来改成全部用环境变量引用配置文件里只留 ${ANTHROPIC_API_KEY} 这样的占位符。openrig 支持从 .env 文件加载环境变量这样你可以在项目目录下放一个 .env里面写实际的密钥然后把 .env 加到 .gitignore 里。.env 的格式很简单一行一个 KEYVALUE不要加引号不要加空格。如果值里本身有等号用引号包起来。还有一个细节是环境变量的作用域。openrig 启动时会读取当前 shell 的环境变量同时也会读 .env 文件。如果两者有同名变量.env 文件的优先级更高。这个行为在文档里没写清楚是我实测出来的。知道这一点之后你就可以用 .env 来覆盖 shell 里的全局设置做项目级的隔离。3.3 多工具共存的端口规划当你同时跑 Claude Code 和 Codex 的时候端口冲突是个绕不开的问题。openrig 默认监听 8787 端口但如果这个端口被占用了启动会失败。我建议在配置里显式指定端口并且给不同工具分配不同的端口段。我的做法是openrig 主进程监听 8787Claude Code 的转发规则走这个端口Codex 单独起一个 openrig 实例监听 8788。两个实例共享同一份 providers 配置但 routes 不同。这样即使一个实例出问题另一个还能正常工作不会互相影响。端口规划还要考虑本地模型服务。如果你用 LM Studio 或者类似工具跑本地模型它们通常也占端口常见的是 1234 或 8080。在配 openrig 的 provider 时base_url 要指向这些本地端口。我建议把本地模型的端口固定下来不要让它随机分配否则每次重启都要改配置。4. 完整实操流程与关键环节4.1 从零开始的环境准备假设你是一台干净的机器什么都没装。第一步是装 Node.js。去 node.js 官网下载 LTS 版本Windows 用户直接下 msi 安装包一路下一步就行。macOS 用户如果用 Homebrewbrew install node20 更省事。Linux 用户注意不要用系统自带的包管理器装那些版本往往太老去 NodeSource 的仓库装。装完之后验证一下终端里跑 node -v 和 npm -v能输出版本号就说明装好了。如果报 command not found大概率是 PATH 没配好。Windows 上重开一个终端窗口通常能解决Linux 上检查一下 /usr/local/bin 在不在 PATH 里。第二步是装 openrig 本身。它是个 npm 包npm install -g openrig 全局安装。如果网络慢可以配一个国内镜像源npm config set registry 后面跟镜像地址。装完之后 openrig --version 验证一下。第三步是准备配置文件。在项目目录下新建 openrig.yaml按照上一节的结构填内容。第一次配建议从最小可用配置开始只配一个 provider 和一条 route跑通了再往上加。4.2 Claude Code 的接入配置Claude Code 接入 openrig 的关键是让它把请求发到本地端口。Claude Code 支持通过环境变量 ANTHROPIC_BASE_URL 来覆盖默认端点你把它设成 http://localhost:8787 就行。但这里有个坑Claude Code 对 URL 的格式有要求末尾不能带斜杠否则会拼出双斜杠导致 404。设置环境变量的方式取决于你的 shell。bash 和 zsh 用 export ANTHROPIC_BASE_URLhttp://localhost:8787Windows PowerShell 用 $env:ANTHROPIC_BASE_URLhttp://localhost:8787。如果你想让这个设置永久生效bash 写进 ~/.bashrczsh 写进 ~/.zshrcPowerShell 写进 profile 文件。配好之后启动 Claude Code它应该能正常对话。如果报“your organization has disabled claude subscription access for claude code”先检查你的 API key 是不是有效再检查 openrig 的日志里请求有没有成功转发出去。这个报错有时候是 key 的问题有时候是转发层把请求改坏了看日志能区分。4.3 Codex 的接入与 YAML 适配Codex 的配置比 Claude Code 稍微复杂一点因为它本身就依赖 YAML 配置文件。Codex 的配置文件通常在 ~/.codex/config.yaml你需要把它的 endpoint 指向 openrig。Codex 的配置项里有一个 api_base 或者类似的字段改成 http://localhost:8788 就行。这里要注意 Codex 的 /responses 端点。热词里那个“cc switch local proxy failed while handling codex endpoint /responses”的报错就是因为转发层没有正确处理这个端点。openrig 在 routes 里需要为 /responses 单独写一条规则指向 Codex 对应的 provider。如果你用的是第三方兼容端点还要确认那个端点是否支持 /responses 这个路径有些只支持 /v1/chat/completions。Codex 还有一个组织设置的坑。热词里“codex 无法加载组织设置”这个报错通常是因为 Codex 尝试从服务端拉取组织级配置但失败了。如果你用的是个人 key 或者第三方端点可以在 Codex 配置里关掉组织设置的加载具体是哪个字段取决于 Codex 的版本一般在配置文件的顶层加一个 disable_org_settings: true 之类的开关。4.4 本地模型的对接实操把 Claude Code 或 Codex 接到本地模型上是 openrig 最有价值的场景之一。以 LM Studio 为例它启动后会在本地某个端口暴露一个兼容 OpenAI 协议的接口。你在 openrig 的 providers 里加一个 type 为 openai 的条目base_url 指向 LM Studio 的地址api_key 随便填一个非空字符串因为本地服务通常不校验。然后在 routes 里把 Claude Code 的 /v1/messages 路径映射到这个 provider。但这里有个协议转换的问题Claude Code 用的是 Anthropic 的 messages 格式LM Studio 用的是 OpenAI 的 chat completions 格式两者字段名不一样。openrig 内置了协议转换层会自动做映射。不过转换不是无损的有些 Anthropic 特有的参数在 OpenAI 格式里没有对应会被丢弃。如果你发现本地模型的表现和预期有差距先检查是不是参数在转换过程中丢了。本地模型的另一个问题是性能。消费级显卡跑大模型token 生成速度可能只有每秒几个Claude Code 这种交互式工具会显得很卡。我的建议是本地模型只用来做特定任务比如代码补全或者简单的重构建议复杂的推理还是走云端。5. 常见问题与排查技巧实录5.1 安装阶段的典型报错安装阶段最常见的就是 Node.js 版本问题。“error installing 24.21.0: node.js v24.21.0 is not yet released or is not available”这个报错原因是你指定的版本号在官方仓库里不存在。解决办法是去 Node.js 官网看当前 LTS 的实际版本号用那个号来装。不要凭记忆写版本号版本更新很快。另一个常见问题是权限。Linux 和 macOS 上全局安装 npm 包可能需要 sudo但用 sudo 装又会导致后续权限混乱。正确的做法是配置 npm 的全局目录到用户主目录下npm config set prefix ~/.npm-global然后把 ~/.npm-global/bin 加到 PATH 里。这样以后装全局包都不需要 sudo。Windows 上如果遇到“codex 安装包”下载后无法运行检查一下是不是被杀毒软件拦截了。有些安全软件对命令行工具比较敏感会静默隔离可执行文件。把 openrig 和 Codex 的安装目录加到白名单里。5.2 转发失败的排查路径转发失败的表现通常是工具报连接错误或者超时。排查的第一步是确认 openrig 进程在跑用 curl http://localhost:8787/health 之类的健康检查端点试一下。如果连不上说明 openrig 没启动或者端口不对。第二步是看 openrig 的日志。日志里会记录每个进来的请求和转发目标。如果请求进来了但没有转发出去说明 routes 配置有问题。如果转发出去了但返回错误说明后端 provider 有问题。日志级别调到 debug 能看到更详细的信息包括请求头和请求体的部分内容。第三步是直接测试后端。绕过 openrig用 curl 直接请求 provider 的 base_url看能不能通。如果直连都不通那问题不在 openrig而在网络或者密钥。如果直连通但经过 openrig 不通那就是转发层的问题重点检查 routes 匹配和协议转换。5.3 常见问题速查表报错信息可能原因排查方向your organization has disabled claude subscription accessAPI key 无效或权限不足检查 key 是否过期账户是否有对应权限cc switch local proxy failed while handling codex endpoint /responsesroutes 缺少 /responses 规则在 routes 里为 /responses 添加映射codex 无法加载组织设置服务端配置拉取失败关闭组织设置加载或检查网络error installing 24.21.0Node 版本号不存在去官网确认当前 LTS 版本号连接超时openrig 未启动或端口冲突检查进程状态和端口占用模型返回格式错误协议转换参数丢失检查转换层日志确认参数映射5.4 几个我踩过的坑第一个坑是 YAML 的缩进。有一次我复制了一段配置粘贴的时候编辑器自动把 tab 转成了空格但转得不彻底混用了 tab 和空格。YAML 解析器直接报错但错误信息指向的是文件末尾让我找了半天。后来我养成了习惯配置文件里全部用空格编辑器设置成“tab 转 2 空格”并且打开“显示空白字符”功能一眼就能看出问题。第二个坑是环境变量的加载顺序。我一开始以为 shell 里的环境变量优先级最高结果发现 .env 文件会覆盖它。这个行为导致我调试的时候改了 shell 变量但没生效白白浪费了半小时。知道之后我就在 .env 里做项目级配置shell 里只放全局的默认值。第三个坑是本地模型的并发限制。有些本地模型服务默认只允许一个并发请求Claude Code 在后台可能会同时发多个请求导致后面的请求被拒绝。解决办法是在 openrig 的 provider 配置里加一个并发限制或者把本地模型服务的并发数调高。这个参数在 LM Studio 的设置里能找到。6. 进阶玩法与扩展思路6.1 多模型路由策略openrig 的 routes 支持基于请求内容的条件匹配这意味着你可以做更精细的路由。比如根据请求里的模型名来决定转发到哪个 provider或者根据请求的长度来决定用本地还是云端。我现在的配置是这样的短请求走本地模型省 token 也省延迟长请求走云端保证质量。这个策略是通过在 routes 里加一个 match 条件实现的匹配请求体里的 max_tokens 字段。还有一个玩法是故障转移。你可以为一个路径配多个 provideropenrig 会按顺序尝试第一个失败了自动切到第二个。这个在云端服务不稳定的时候特别有用。配置方式是在 routes 的 provider 字段里写一个列表而不是单个字符串。6.2 日志分析与用量统计openrig 的日志是结构化的每条记录包含时间戳、请求路径、目标 provider、响应状态、耗时。把这些日志导到一个分析工具里你就能看到自己的用量分布。比如哪个模型用得最多平均响应时间是多少失败率有多高。我用一个简单的脚本把日志转成 CSV然后在表格软件里做透视表。这样每周能出一份用量报告知道自己的 token 消耗趋势。对于需要控制成本的团队来说这个数据很有价值。openrig 本身不提供统计面板但它的日志格式足够友好自己加工一下就能用。6.3 团队协作中的配置管理如果是团队使用配置文件的管理就变得重要。我的建议是把 openrig.yaml 拆成两部分一部分是团队共享的 providers 和 routes 模板进版本库另一部分是个人本地的覆盖配置放在 .env 或者单独的 local.yaml 里不进版本库。openrig 支持配置文件的合并启动时指定多个配置文件后面的覆盖前面的。这样新成员加入的时候只需要克隆仓库然后填自己的 .env 文件就行不用从头配一遍。团队共享的配置更新了大家拉一下代码就能同步。这个模式我们跑了几个月效果不错配置漂移的问题基本消失了。6.4 与 VS Code 的集成热词里出现了“vscode 配置 claude code”和“claude code for vs code”说明很多人是在 VS Code 里用这些工具的。openrig 跟 VS Code 的集成其实很简单因为 VS Code 里的 Claude Code 插件本质上还是调用底层的 CLI环境变量是共享的。你在 shell 里配好 ANTHROPIC_BASE_URLVS Code 启动的终端会继承这个设置。但有一个细节VS Code 的集成终端有时候不会加载 .bashrc 或 .zshrc导致环境变量丢失。解决办法是在 VS Code 的设置里把 terminal.integrated.inheritEnv 设为 true或者在 VS Code 的 settings.json 里直接配环境变量。我两种都试过后者更可靠因为不依赖 shell 的加载行为。7. 一些个人体会这套东西我从最初的手忙脚乱到现在稳定运行大概花了两个周末。最大的感受是配置管理这件事没有银弹openrig 也不是万能的。它解决的是“多工具多后端”的编排问题但如果你的场景很简单只用 Claude Code 官方端点那其实不需要它直接配环境变量就行。真正体现价值的时候是你开始混用多个模型、多个端点并且需要频繁切换的时候。这时候 openrig 的 YAML 配置和转发层能帮你把混乱收拢到一个地方。而且因为配置是文本的可以进版本库可以 review可以回滚这比在 GUI 里点来点去可靠得多。最后分享一个小技巧openrig 的配置支持热重载改完 YAML 文件不用重启进程它检测到文件变化会自动重新加载。这个功能在调试 routes 的时候特别省时间。不过热重载不是所有字段都支持providers 的改动有时候需要重启才能生效具体看版本。我一般改完配置先试热重载不行再手动重启。