1. 从 openrig 说起一个被低估的 AI 编码工具编排层第一次看到openrig这个名字我下意识以为是某个开源钻机项目——毕竟 rig 在工业领域就是钻井平台的意思。直到我在几个 Claude Code 和 Codex 的讨论串里反复撞见它才意识到这是 AI 编码工具生态里一个相当有意思的编排层工具。简单说openrig 解决的是这样一个问题当你同时使用 Claude Code、Codex CLI 这类 AI 编码助手时如何统一管理它们的配置、模型接入、代理转发和会话状态。这个需求不是凭空冒出来的。过去大半年AI 编码工具的格局变化非常快Claude Code 从终端工具扩展到 VS Code 插件和桌面版Codex 从网页版进化出 CLI 形态还有大量开发者想把本地模型比如通过 LM Studio 跑的模型接进这些工具。每个人手里可能同时装着三四个 AI 编码工具每个工具有自己的配置文件、自己的认证方式、自己的模型端点。切换一次工具就要改一遍配置模型换一个就要重新调一遍参数这种碎片化的体验非常折磨人。openrig 的定位就是把这些碎片收拢到一个统一的 YAML 配置体系下。它本身不是一个 AI 模型也不是一个编码工具而是一个配置编排与请求路由层。你可以把它理解成 AI 编码工具领域的统一遥控器——底层接什么模型、走什么端点、用什么认证全部由 openrig 的配置文件说了算上层的 Claude Code 或 Codex 只管发请求就行。适合读这篇内容的人有三类一是已经在用 Claude Code 或 Codex但被多工具配置搞得头大的开发者二是想把本地模型接入这些工具但卡在端点配置和协议适配上的折腾党三是单纯对 AI 编码工具生态感兴趣想搞清楚这些工具之间怎么协作的技术爱好者。不管你属于哪一类接下来的内容都会从配置结构、实操步骤、常见坑三个维度把 openrig 这套东西讲透。2. openrig 的核心设计思路与配置体系拆解2.1 为什么是 YAML配置即契约的设计哲学openrig 选择 YAML 作为配置载体这个决定背后有很实际的考量。AI 编码工具的配置涉及大量嵌套结构——模型端点、认证信息、路由规则、工具映射这些用 JSON 写会非常啰嗦用 TOML 又不够灵活。YAML 的缩进层级天然适合表达某个工具在某个场景下使用某个模型的某个端点这种多层关系。更重要的是YAML 对非程序员相对友好。很多用 Claude Code 的人并不是专业后端工程师可能是数据分析师、运维、甚至产品经理。让他们写 JSON 的大括号和逗号是折磨YAML 的缩进至少看起来像大纲笔记。openrig 把配置门槛压到最低本质上是在扩大 AI 编码工具的受众面。从工程角度看YAML 还有一个隐性优势它天然适合做版本管理和 diff。你把 openrig 的配置文件放进 Git 仓库每次调整模型端点或路由规则都有清晰的变更记录。团队协作时谁改了哪个工具的配置一目了然。这种配置即契约的思路和基础设施即代码IaC的理念是一脉相承的。2.2 核心配置结构三层模型openrig 的配置体系可以抽象成三层提供商层、工具层、路由层。这三层的关系决定了整个系统的灵活性。提供商层Provider定义模型来源。一个提供商条目包含端点地址、认证方式、可用模型列表。比如你可以定义一个指向 LM Studio 本地服务的提供商端点写http://localhost:1234/v1认证方式设为 none再定义一个指向云端 API 的提供商端点写对应的 API 地址认证方式用 API Key。工具层Tool定义 AI 编码工具的接入方式。Claude Code 和 Codex 的请求格式不完全一样Claude Code 走的是 Anthropic 的消息格式Codex 走的是 OpenAI 的 responses 格式。openrig 在工具层做协议适配把不同工具的请求统一转换成提供商层能理解的格式。路由层Route定义什么工具在什么场景下用哪个提供商。这是最灵活的一层。你可以配置 Claude Code 默认走云端模型但当请求包含特定关键词时切换到本地模型也可以配置 Codex 在处理代码补全时用轻量模型处理架构设计时用重量模型。这种三层结构的价值在于解耦。你想换模型提供商只改提供商层想加一个新工具只加工具层条目想调整策略只动路由层。每一层的变更不会波及其他层维护成本大幅降低。2.3 与 Claude Code、Codex 的协作机制openrig 和 Claude Code、Codex 的协作方式本质上是一个本地代理转发的模式。openrig 在本地启动一个轻量服务监听某个端口。Claude Code 或 Codex 的配置里把 API 端点指向这个本地端口请求先到 openrigopenrig 根据路由规则决定转发到哪个真实端点收到响应后再回传给工具。这个模式的好处是对上层工具完全透明。Claude Code 以为自己只是在和一个普通的 API 端点通信它不知道背后有路由、有协议转换、有模型切换。你不需要修改 Claude Code 的源码也不需要它支持什么插件机制只要它能配置 API 端点就能被 openrig 接管。这里有个关键细节Claude Code 和 Codex 的请求格式差异。Claude Code 发的是 Anthropic 格式的请求Codex 发的是 OpenAI 格式的请求。openrig 需要在转发前做格式转换。比如 Anthropic 的messages数组结构和 OpenAI 的messages结构在字段命名上有差异工具调用tool use的表示方式也不同。openrig 的适配层就是干这个的。注意协议转换不是无损的。某些工具特有的功能比如 Claude Code 的某些扩展字段在转换后可能丢失。如果你重度依赖某个工具的特有功能建议在路由层配置直连不走转换。3. 从零搭建 openrig 环境npm 安装与配置实操3.1 环境准备Node.js 与 npm 的正确安装姿势openrig 通过 npm 分发所以第一步是把 Node.js 和 npm 装好。这一步看起来简单但我在不同平台上踩过的坑足够写一篇避坑指南。Windows 用户最常见的报错是npm : 无法加载文件 C:\Program Files\nodejs\npm.ps1因为在此系统上禁止运行脚本。这不是 npm 装错了而是 PowerShell 的执行策略默认禁止运行脚本。解决方法是以管理员身份打开 PowerShell执行Set-ExecutionPolicy RemoteSigned然后输入 Y 确认。这个策略的意思是本地脚本可以运行从网络下载的脚本需要签名。对开发环境来说这个安全级别是合理的。另一个高频问题是 npm 全局包安装后命令找不到。这通常是 PATH 环境变量没配好。npm 的全局包默认装在%APPDATA%\npmWindows或/usr/local/binmacOS/Linux。你需要确认这个路径在系统的 PATH 里。Windows 上可以在系统属性 → 环境变量里检查macOS/Linux 上检查.bashrc或.zshrc里的 PATH 配置。国内用户还会遇到 npm 官方源速度慢的问题。切换国内镜像源是常规操作npm config set registry https://registry.npmmirror.com这个命令把默认源换成国内镜像。如果你只想为某个项目临时切换可以在项目根目录建.npmrc文件写入registryhttps://registry.npmmirror.com。项目级配置的优先级高于全局配置适合团队协作时统一源地址。提示切换镜像源后如果遇到包版本不一致的问题执行npm cache clean --force清一下缓存。镜像源同步官方源有延迟极少数情况下会拿到旧版本。3.2 openrig 的安装与初始化环境准备好之后安装 openrig 本身npm install -g openrig-g表示全局安装这样你在任何目录下都能调用 openrig 命令。安装完成后执行openrig --version验证。如果提示命令找不到回到上一步检查 PATH。初始化配置目录openrig init这个命令会在用户主目录下创建~/.openrig/目录里面包含默认的配置文件config.yaml和示例路由规则。我建议不要直接改默认配置而是复制一份出来改cp ~/.openrig/config.yaml ~/.openrig/config.local.yaml然后在启动时指定openrig start --config ~/.openrig/config.local.yaml。这样做的好处是升级 openrig 时默认配置会被覆盖但你的本地配置不受影响。3.3 编写第一个 openrig 配置文件下面是一个最小可用的配置示例同时接入了本地 LM Studio 和云端 APIproviders: local-lmstudio: type: openai-compatible base_url: http://localhost:1234/v1 api_key: none models: - qwen2.5-coder-7b - deepseek-coder-v2 cloud-api: type: openai-compatible base_url: https://api.example.com/v1 api_key: ${CLOUD_API_KEY} models: - gpt-4o - claude-sonnet-4 tools: claude-code: protocol: anthropic default_provider: cloud-api default_model: claude-sonnet-4 codex: protocol: openai default_provider: local-lmstudio default_model: qwen2.5-coder-7b routes: - match: tool: claude-code keyword: 本地 target: provider: local-lmstudio model: deepseek-coder-v2 server: port: 8787 log_level: info这个配置做了几件事定义了两个提供商本地 LM Studio 和云端 API定义了两个工具Claude Code 和 Codex的默认行为加了一条路由规则当 Claude Code 的请求包含本地关键词时切换到本地模型最后配置了 openrig 服务的监听端口。${CLOUD_API_KEY}是环境变量引用语法。openrig 启动时会从环境变量里读取实际值。这样做避免把密钥硬编码在配置文件里配置文件可以安全地提交到 Git。3.4 启动服务并接入 Claude Code配置写好后启动服务openrig start --config ~/.openrig/config.local.yaml看到Server listening on port 8787就说明启动成功了。接下来配置 Claude Code 指向 openrigexport ANTHROPIC_BASE_URLhttp://localhost:8787 export ANTHROPIC_API_KEYopenrig-placeholderClaude Code 会读取这两个环境变量。ANTHROPIC_BASE_URL指向 openrig 的监听地址ANTHROPIC_API_KEY随便填一个占位符就行因为真正的认证在 openrig 的提供商层处理。Codex 的配置类似但环境变量名不同export OPENAI_BASE_URLhttp://localhost:8787/v1 export OPENAI_API_KEYopenrig-placeholder配置完成后你在 Claude Code 里发的每一条消息都会先到 openrigopenrig 根据路由规则决定转发到哪个模型。你可以在 openrig 的日志里看到完整的请求转发记录这对调试非常有用。4. 进阶玩法本地模型接入与多工具协同4.1 把 LM Studio 的本地模型接进 Claude Code这是很多人折腾 openrig 的核心诉求用 Claude Code 的交互体验跑本地模型的推理。动机很实际——本地模型免费、数据不出本机、响应延迟可控。LM Studio 启动本地服务后默认监听http://localhost:1234提供 OpenAI 兼容的 API。在 openrig 里配置一个指向它的提供商然后把 Claude Code 的路由指过去就行。但这里有几个细节需要注意。第一模型名称要匹配。LM Studio 加载的模型名称必须和 openrig 配置里的models列表一致。你可以在 LM Studio 的开发者页面看到当前加载的模型标识符直接复制过来。第二上下文长度要调。Claude Code 的请求往往携带大量上下文整个文件内容、项目结构等本地模型的默认上下文窗口可能不够。在 LM Studio 里加载模型时把 context length 调到 8192 或更高具体取决于你的显存。第三工具调用能力。Claude Code 重度依赖工具调用读文件、写文件、执行命令。不是所有本地模型都支持工具调用即使支持格式也可能和 Anthropic 的规范有差异。openrig 的协议转换层会尽量适配但如果模型本身不支持转换也无能为力。实测下来Qwen2.5-Coder 和 DeepSeek-Coder-V2 的工具调用支持比较好。4.2 Codex 接入本地模型的配置要点Codex 的协议是 OpenAI 格式和 LM Studio 的原生输出格式更接近所以配置起来比 Claude Code 简单一些。但 Codex 有一个特殊之处它使用/responses端点而不是/chat/completions。如果你在 openrig 日志里看到cc switch local proxy failed while handling codex endpoint /responses这类报错说明协议转换层没有正确处理这个端点。解决方法是确认 openrig 版本支持 responses 端点的转换。较新的版本已经内置了这个适配。如果还是报错可以在配置里显式指定端点映射tools: codex: protocol: openai endpoint_mapping: /responses: /chat/completions default_provider: local-lmstudio这个配置告诉 openrig当 Codex 请求/responses时转发给提供商的/chat/completions端点。大多数 OpenAI 兼容的本地服务只实现了/chat/completions这个映射就是用来桥接差异的。4.3 多工具共存的端口与路由规划当你同时跑 Claude Code、Codex 和其他 AI 工具时端口规划就变得重要了。我的建议是给 openrig 分配一个固定端口比如 8787所有工具都指向这一个端口由 openrig 内部的路由规则区分请求来源。区分请求来源有两种方式。一种是按路径区分Claude Code 走/anthropic/*Codex 走/openai/*openrig 根据路径前缀判断是哪个工具。另一种是按请求头区分在工具的环境变量里加一个自定义 headeropenrig 读取这个 header 来判断来源。路径区分更简单但需要工具支持自定义路径。请求头区分更灵活但配置稍复杂。我个人的做法是混合使用Claude Code 和 Codex 用路径区分其他自定义脚本用请求头区分。routes: - match: path_prefix: /anthropic target: provider: cloud-api model: claude-sonnet-4 - match: path_prefix: /openai target: provider: local-lmstudio model: qwen2.5-coder-7b - match: header: X-OpenRig-Tool: my-script target: provider: local-lmstudio model: deepseek-coder-v2这种配置下不同工具共享同一个 openrig 实例但走不同的模型和提供商。资源利用率高管理也集中。5. 常见问题与排查技巧实录5.1 安装与启动阶段的典型报错npm 脚本执行被禁止前面提过的 PowerShell 执行策略问题。除了Set-ExecutionPolicy RemoteSigned另一个临时方案是在命令前加powershell -ExecutionPolicy Bypass -Command npm install -g openrig。但这只是绕过不是解决建议还是改执行策略。npm warn ERESOLVE overriding peer dependency这是依赖版本冲突的警告。openrig 依赖的某个包和你的项目里已有的包版本不一致。大多数情况下这个警告可以忽略npm 会自动选择一个兼容版本。如果安装后运行报错再考虑用--legacy-peer-deps参数重新安装。openrig 命令找不到全局安装后命令不在 PATH 里。Windows 上检查%APPDATA%\npm是否在 PATHmacOS/Linux 上检查 npm 的全局 bin 目录npm config get prefix可以看到是否在 PATH。5.2 请求转发失败的排查思路请求转发失败是最常见的问题类型。我的排查顺序是这样的第一步确认 openrig 服务在跑。curl http://localhost:8787/health看有没有响应。没有响应说明服务没启动或端口被占用。第二步确认提供商端点可达。直接用 curl 打提供商的端点绕过 openrig。如果直连都不通问题在提供商侧不在 openrig。第三步看 openrig 日志。把log_level调到debug重启服务重现问题。日志里会显示请求的完整路径、匹配到的路由规则、转发目标、响应状态码。大部分问题看日志就能定位。第四步检查协议转换。如果提供商端点直连正常但通过 openrig 转发失败大概率是协议转换出了问题。对比 openrig 日志里的请求体和提供商期望的格式看字段有没有缺失或命名不一致。报错信息可能原因解决方法connection refusedopenrig 未启动或端口错误检查服务状态和端口配置401 unauthorized提供商 API Key 无效检查环境变量和提供商配置404 not found端点路径不匹配检查 endpoint_mapping 配置400 bad request协议转换字段错误开启 debug 日志对比请求体timeout提供商响应超时调大 timeout 配置或检查网络5.3 模型切换不生效的排查路由规则写了但模型没切换通常有三个原因。一是匹配条件写错了。比如关键词匹配是大小写敏感的你写本地但请求里是Local就匹配不上。二是路由顺序问题。openrig 按配置顺序匹配第一条匹配上的规则生效。如果前面有一条宽泛的规则先匹配了后面的精确规则就不会执行。三是缓存问题。某些工具会缓存 API 响应你改了配置但工具还在用旧响应。重启工具或清缓存。实操心得路由规则从具体到宽泛排列。把精确匹配的规则放前面兜底的默认规则放最后。这样能避免宽泛规则截胡精确规则。5.4 本地模型响应质量差的调优用本地模型跑 Claude Code 时响应质量往往不如云端模型。这不是 openrig 的问题是模型能力差异。但有几个调优方向可以改善体验。选对模型。代码任务优先选代码专精模型Qwen2.5-Coder 和 DeepSeek-Coder-V2 是目前本地模型里代码能力比较强的。通用模型在代码任务上往往力不从心。调低温度。代码生成任务需要确定性温度调到 0.1 到 0.3 之间。温度太高模型会发挥创意生成不存在的 API 或语法。给足上下文。本地模型的上下文窗口有限但 Claude Code 的请求可能很长。在 openrig 里配置请求截断策略优先保留最近的对话和当前文件内容丢弃早期的无关历史。接受能力边界。本地 7B 模型和云端大模型的差距是客观存在的。把本地模型用在简单任务上代码补全、格式转换、简单重构复杂任务还是走云端。openrig 的路由层正好支持这种混合策略。6. 配置管理与团队协作的实践经验6.1 配置文件的版本管理策略openrig 的配置文件应该纳入版本管理但密钥不能进仓库。我的做法是配置文件里用环境变量引用仓库里只存配置文件本身密钥通过.env文件或 CI/CD 的密钥管理注入。目录结构建议这样组织openrig-config/ ├── config.yaml # 主配置提交到仓库 ├── config.local.yaml # 本地覆盖加入 .gitignore ├── .env.example # 环境变量模板提交到仓库 └── .env # 实际环境变量加入 .gitignoreconfig.yaml里写通用的提供商和路由规则config.local.yaml里写个人特有的配置比如本地模型端点。openrig 支持配置合并启动时同时加载两个文件后者覆盖前者。6.2 团队共享配置的注意事项团队协作时提供商端点和模型选择需要统一但每个人的本地环境不同。解决方案是把配置分成共享层和个人层。共享层定义团队统一的云端提供商和路由策略个人层定义各自的本地模型和调试配置。共享层的配置由团队负责人维护变更走代码审查流程。个人层各自管理不互相干扰。openrig 的配置合并机制天然支持这种分层。还有一个细节模型名称的标准化。团队里有人用gpt-4o有人写gpt-4o-2024-08-06路由规则匹配时就会出问题。建议在共享层定义模型别名个人层引用别名而不是具体版本号。这样模型升级时只改共享层一处。6.3 监控与日志的实用配置openrig 的日志是排查问题的核心工具但默认的 info 级别日志在长期运行时会产生大量文件。我的配置是日常运行用 info 级别日志按天轮转保留最近 7 天排查问题时临时切到 debug问题解决后切回。logging: level: info file: ~/.openrig/logs/openrig.log rotation: max_size: 10MB max_files: 7 format: jsonJSON 格式的日志便于用工具分析。你可以用jq过滤出所有转发失败的请求cat ~/.openrig/logs/openrig.log | jq select(.status 400)这个命令列出所有状态码大于等于 400 的请求快速定位问题请求。7. 我对 openrig 这类工具的看法折腾 openrig 这段时间我最大的感受是AI 编码工具的竞争已经从模型能力转向工程体验。模型能力大家都在追差距在缩小但配置管理、多工具协同、本地与云端的混合调度这些工程层面的体验差距还很大。openrig 这类编排层工具的价值就在于它把工程体验这块补齐了。它不完美。协议转换有损耗本地模型的能力边界明显配置复杂度对新手不算友好。但它解决了一个真实存在的痛点当你手里有三四个 AI 编码工具、两三个模型来源时你需要一个统一的管理层。没有这个层你就在重复劳动有了这个层你就能把精力放在真正重要的事情上——写代码。如果你刚开始接触我的建议是先用最小配置跑通一个工具比如 Claude Code 接云端 API确认链路通了再逐步加本地模型、加路由规则、加第二个工具。不要一上来就搞复杂配置那样出了问题很难定位。一步一步来每加一个东西就验证一次这样踩的坑最少。