1. openrig 到底是个什么东西第一次看到 openrig 这个名字我下意识以为是某个硬件机架项目毕竟 rig 这个词在英文里就是“装配、机架”的意思。但翻了一圈社区讨论和代码仓库之后才明白它其实是一个围绕 AI 编程助手做配置编排与多模型路由的工具层。简单说openrig 想解决的问题是当你同时用 Claude Code、Codex 这类命令行 AI 编程工具又想在本地模型、云端模型、第三方 API 之间灵活切换时配置文件散落各处、格式不统一、切换一次要改半天openrig 就是把这些东西收拢到一套 YAML 配置里统一管理。它为什么会出现因为现在用 AI 写代码的人手里往往不止一个工具。Claude Code 擅长长上下文理解和复杂重构Codex 系工具在补全和快速生成上很顺手本地跑 LM Studio 或者接 DeepSeek、Qwen、GLM 这些模型又能省成本、保隐私。问题是每个工具都有自己的配置方式Claude Code 认它自己的一套环境变量和配置文件Codex 认另一套本地模型的 endpoint 又是第三种写法。你想换个模型试试效果就得挨个文件去改改错了还容易把原来的配置搞坏。openrig 的价值就在于提供一个中间层用一份 YAML 描述“我要用哪个模型、走哪个端点、给哪个工具用”然后由它去生成或注入各个工具需要的配置。适合谁来参考三类人最需要。第一类是已经在用 Claude Code 或 Codex但被多套配置折磨得够呛的开发者第二类是想在本地跑模型、又想让 Claude Code 这类工具调用本地模型的折腾党第三类是做团队协作需要把 AI 编程工具的配置标准化、让新人一键上手的工程负责人。如果你只是偶尔用用网页版 AI 聊天那这个内容对你帮助有限但只要你开始把 AI 编程工具当成日常生产力配置管理这件事迟早会找上你。我写这篇东西的出发点是把 openrig 背后的配置思路、YAML 怎么写、Node.js 环境怎么准备、Claude Code 和 Codex 怎么接进去、本地模型怎么挂载这些实操环节一次讲透。网上关于单个工具的教程很多但把“多工具 多模型 统一配置”这条链路串起来的资料很少我自己踩过的坑也不少索性整理成一篇能直接抄作业的长文。2. 整体设计思路与方案选型2.1 为什么是 YAML 而不是 JSON 或 TOMLopenrig 选择 YAML 作为配置载体这个决定值得说道说道。JSON 的问题是写起来太啰嗦每个键都要引号不能写注释多层嵌套之后括号看得人眼花。TOML 虽然简洁但表达嵌套结构时层级一深就不够直观尤其是描述“多个工具、每个工具多个模型候选”这种树状关系时TOML 的[table.subtable]写法会让人迷失。YAML 的优势在于缩进即层级天然适合表达嵌套支持注释你可以在一份配置里写清楚“这行是给 Claude Code 用的”“这个端点是本地 LM Studio”支持锚点和引用多个工具共用同一段模型定义时不用复制粘贴。我实测下来一份中等复杂度的 openrig 配置大概长这样顶层是版本号和全局设置下面分providers模型提供方、tools要配置的编程工具、routes路由规则几个大块。用 YAML 写出来大概一百多行换成 JSON 至少要两百行而且没法加注释。对于需要频繁调整模型和端点的场景YAML 的可读性优势非常明显。注意YAML 对缩进极其敏感Tab 和空格不能混用一个缩进错误就可能导致整个配置解析失败。建议统一用两个空格缩进并在编辑器里开启“显示空白字符”。2.2 为什么依赖 Node.js 生态openrig 本身是个 Node.js 工具这一点从热搜词里频繁出现 node.js 安装、node.js 官网下载就能看出来。为什么选 Node.js因为 Claude Code 和 Codex 这类工具本身就是 Node.js 写的或者通过 npm 分发的整个 AI 编程工具链在 Node.js 生态里最活跃。openrig 作为配置编排层需要能读写这些工具的配置文件、能调用它们的命令行接口、能处理 npm 包的安装和版本管理用 Node.js 来做这些事情是最顺手的。另一个原因是跨平台。Node.js 在 Windows、macOS、Linux 上行为基本一致openrig 的用户可能用任何系统用 Node.js 能保证一份配置在三个平台上都能跑。相比之下如果用 Python 写虽然也能跨平台但和 Claude Code、Codex 的集成就没那么自然因为那些工具的命令行接口和配置格式都是围绕 Node.js 生态设计的。2.3 多模型路由的核心设计openrig 最核心的能力是多模型路由。它的设计思路是把“模型提供方”和“使用模型的工具”解耦。你在一处定义好 provider比如“本地 LM Studio 跑 Qwen”“DeepSeek 官方 API”“某个第三方中转端点”然后在 tool 配置里引用这些 provider 的名字。这样当你想把 Claude Code 从云端模型切到本地模型时只需要改 tool 配置里引用的 provider 名字不用去动 Claude Code 自己的配置文件。这个设计的好处是显而易见的。第一切换成本极低改一行引用就行。第二配置复用同一个 provider 可以被 Claude Code 和 Codex 同时引用不用重复定义。第三便于版本管理一份 YAML 提交到 Git团队里所有人拉下来就能用同样的模型配置新人入职不用再问“你的 Claude Code 是怎么配的”。路由规则还支持条件匹配。比如你可以配置“当请求的上下文长度超过 100k 时走云端长上下文模型否则走本地模型”或者“代码补全请求走本地快速模型复杂重构请求走云端强模型”。这种细粒度控制是单工具原生配置做不到的必须有一个中间层来拦截和分发请求。3. 环境准备与 Node.js 安装实操3.1 先确认你机器上有没有 Node.js动手之前先查一下现状别急着装。打开终端Windows 用 PowerShell 或 CMDmacOS 和 Linux 用默认终端输入node -v npm -v如果两行都输出了版本号比如v20.11.0和10.2.4说明已经装好了可以跳到下一节。如果提示“command not found”或者“不是内部或外部命令”那就是没装或者没配好环境变量。还有一种情况是装了但版本太老。openrig 和 Claude Code 这类工具通常要求 Node.js 18 以上最好用 20 或 22 的 LTS 版本。如果你的版本是 16 甚至更低建议升级。热搜词里有个报错error installing 24.21.0: node.js v24.21.0 is not yet released这就是版本号写错了导致的Node.js 的版本号不会跳到 24.21.0 这种组合安装时一定要去官网确认当前的真实版本。3.2 各平台安装 Node.js 的稳妥方式Windows 用户最省心的方式是去 Node.js 官网下载 LTS 版本的安装包一路下一步就行。安装时注意勾选“Add to PATH”这样装完直接在终端就能用。如果你不想污染系统环境也可以用 nvm-windows 来管理多个 Node.js 版本切换起来方便。macOS 用户我强烈建议用 nvm 而不是直接下载 pkg 安装包。原因很简单macOS 系统本身可能依赖某个特定版本的 Node.js你直接覆盖安装可能影响系统工具。用 nvm 装curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash装完 nvm 之后nvm install 20装 Node.js 20nvm use 20切换过去。这样每个项目可以用不同的 Node.js 版本互不干扰。Linux 用户同样推荐 nvm流程和 macOS 一样。如果你用 Ubuntu 的 apt 装注意 apt 源里的 Node.js 版本往往偏老可能需要额外加 NodeSource 的源才能装到新版。提示安装完 Node.js 后npm 会跟着一起装好。但 npm 的默认源在国内访问可能较慢可以换成国内镜像源加速命令是npm config set registry https://registry.npmmirror.com。这个操作只影响包下载速度不影响功能。3.3 安装 openrig 与验证Node.js 就绪之后安装 openrig 本身。如果 openrig 发布在 npm 上直接npm install -g openrig全局安装后终端里输入openrig --version应该能看到版本号。如果提示找不到命令检查 npm 的全局 bin 目录有没有加到 PATH 里。用npm config get prefix可以看到全局安装路径把这个路径下的 bin 目录加到环境变量就行。验证安装成功的另一个方式是跑openrig init它会在当前目录生成一份示例配置文件。打开看看结构对照下一节的讲解理解每个字段的含义。如果 init 报错多半是权限问题Linux 和 macOS 下可能需要sudo但更好的做法是配置 npm 的全局目录到用户目录下避免用 sudo 装全局包。4. openrig 配置文件逐字段拆解4.1 顶层结构与版本声明一份典型的 openrig 配置顶层大概是这样version: 1 providers: - name: local-qwen type: openai-compatible base_url: http://127.0.0.1:1234/v1 api_key: not-needed models: - qwen2.5-coder-7b tools: - name: claude-code provider: local-qwen model: qwen2.5-coder-7b - name: codex provider: local-qwen model: qwen2.5-coder-7bversion字段是配置格式的版本号openrig 升级后如果配置格式有变化会靠这个字段做兼容处理。写配置时先确认你用的 openrig 版本对应哪个配置版本别拿着旧格式往新版本上套。providers是一个列表每个元素描述一个模型提供方。name是自定义的标识符后面 tools 里引用它。type指明这个 provider 的协议类型常见的有openai-compatible兼容 OpenAI 接口格式的端点、anthropicClaude 官方接口、custom自定义。base_url是端点地址本地模型通常指向http://127.0.0.1:端口/v1。api_key对于本地模型通常不需要填个占位符就行但有些工具会检查这个字段是否存在所以别留空。4.2 provider 的模型列表与参数models字段列出这个 provider 下可用的模型名。注意这里的模型名必须和端点实际提供的模型标识一致写错了请求会返回模型不存在的错误。本地 LM Studio 里加载的模型名字要和在 LM Studio 界面里看到的一致云端 API 的模型名要查官方文档。除了模型名还可以给每个模型配参数models: - name: qwen2.5-coder-7b context_window: 32768 max_tokens: 4096 temperature: 0.2context_window告诉 openrig 这个模型能接受多长的上下文路由时如果请求超过这个长度openrig 可以自动切换到上下文更大的模型。max_tokens限制单次生成的最大长度。temperature控制随机性写代码场景建议调低0.1 到 0.3 之间比较稳太高了生成的代码容易跑偏。4.3 tool 配置与工具对接tools部分描述你要配置哪些编程工具。每个 tool 至少要有name、provider、model三个字段。name是工具标识openrig 靠它知道该往哪个工具的配置文件里写东西。provider引用上面定义的 provider 名字。model指定用这个 provider 下的哪个模型。不同工具的对接方式不一样。Claude Code 的配置通常涉及环境变量和它自己的 settings 文件openrig 会帮你生成这些内容。Codex 系工具可能是通过配置文件或者命令行参数来指定模型端点。openrig 内部为每个支持的工具写了适配器你只需要在 YAML 里声明意图适配器负责翻译成目标工具能理解的格式。注意工具名必须用 openrig 支持的标识。如果你写了个 openrig 不认识的名字它可能会报错或者静默忽略。写之前查一下 openrig 文档里支持的工具列表别自己造名字。4.4 路由规则的高级写法基础配置只能做到“一个工具用一个模型”但 openrig 的路由规则能做得更细routes: - match: tool: claude-code context_length: 100000 provider: cloud-long-context model: claude-sonnet - match: tool: claude-code provider: local-qwen model: qwen2.5-coder-7b这段配置的意思是Claude Code 发来的请求如果上下文超过 100k走云端长上下文模型否则走本地 Qwen。规则从上往下匹配第一条命中就不再看后面的。这种写法适合既要控制成本、又要在关键时刻用强模型的场景。路由规则的匹配条件可以组合除了tool和context_length还可能有request_type区分补全和对话、time_range按时间段切换等。具体支持哪些条件取决于 openrig 的版本写之前确认一下。5. 把 Claude Code 和 Codex 接进 openrig5.1 Claude Code 的配置注入Claude Code 是 Anthropic 出的命令行编程助手它默认连的是 Claude 官方模型。想让它走 openrig 管理的模型需要让 openrig 生成 Claude Code 能识别的配置。Claude Code 通常读环境变量里的 API 端点和密钥openrig 的做法是生成一个环境文件或者直接修改 Claude Code 的 settings。实际操作时先确认 Claude Code 已经装好并且能跑。热搜词里your organization has disabled claude subscription access for claude code这个报错说明账号权限有问题这种情况 openrig 也救不了得先解决账号层面的访问权限。确认 Claude Code 本身可用之后再让 openrig 接管它的模型配置。openrig 注入配置后启动 Claude Code 时要确保它读到了 openrig 设置的环境变量。如果你是在 shell 里直接跑claudeopenrig 可能会生成一个包装脚本你通过这个脚本来启动。或者 openrig 会写一个.env文件你在启动前 source 一下。具体方式看 openrig 的文档不同版本可能不一样。5.2 Codex 的对接要点Codex 系工具的配置方式和 Claude Code 不同。热搜词里cc switch local proxy failed while handling codex endpoint /responses这个报错说明 Codex 在通过本地代理访问/responses端点时出了问题。这类问题的根源通常是端点地址写错、代理没启动、或者模型名不匹配。用 openrig 配置 Codex 时重点检查三件事。第一provider 的base_url要指向正确的端点Codex 可能对路径有特定要求比如必须带/v1或者必须用/responses而不是/chat/completions。第二模型名要和端点实际提供的名字完全一致大小写都不能错。第三如果用了本地代理确认代理进程在跑端口没被占用。Codex 还有个gpt-5.6-sol model is not supported这类报错意思是 Codex 不认这个模型名。这时候要么换成 Codex 支持的模型名要么在 openrig 里做一层模型名映射把 Codex 请求的模型名翻译成端点实际支持的模型名。5.3 本地模型接入的完整链路让 Claude Code 或 Codex 调用本地模型是很多人折腾 openrig 的主要动机。完整链路是这样的本地推理引擎比如 LM Studio、Ollama加载模型并暴露 OpenAI 兼容接口openrig 把这个接口定义成 providertool 引用这个 provider启动工具时 openrig 把端点信息注入进去。以 LM Studio 为例先在 LM Studio 里加载一个代码模型比如 Qwen2.5-Coder然后在 LM Studio 的开发者设置里启动本地服务器默认端口是 1234。确认http://127.0.0.1:1234/v1/models能返回模型列表。然后在 openrig 配置里写providers: - name: lmstudio type: openai-compatible base_url: http://127.0.0.1:1234/v1 api_key: lmstudio models: - name: qwen2.5-coder-7b-instruct context_window: 32768模型名一定要和/v1/models返回的一致。我见过有人照着网上的教程写qwen2.5-coder但实际加载的模型名带-instruct后缀结果请求一直失败排查半天才发现是名字对不上。提示本地模型跑代码任务7B 参数起步显存够的话上 14B 或 32B 效果明显更好。7B 模型在简单补全和单文件修改上够用但涉及多文件重构和复杂逻辑时容易力不从心。6. 常见问题与排查技巧实录6.1 配置解析失败类问题YAML 配置最常见的错误就是缩进和格式。报错信息通常是yaml: line X: did not find expected key或者mapping values are not allowed in this context。遇到这类报错先看报错行号和它上面几行的缩进。YAML 要求同一层级的键缩进完全一致多一个空格少一个空格都会出问题。另一个坑是特殊字符。YAML 里冒号后面如果跟空格会被解析成键值对如果你的字符串里本身有冒号加空格必须用引号包起来。比如base_url: http://127.0.0.1:1234/v1这种URL 里的冒号后面没有空格所以没问题但如果你写description: 这是一个: 测试中间的冒号加空格就会导致解析错误得写成description: 这是一个: 测试。排查技巧用在线 YAML 校验工具粘贴你的配置它会指出具体哪一行有问题。或者用 Python 的yaml.safe_load读一下报错信息比 openrig 的更详细。6.2 模型请求失败类问题请求失败的表现形式很多连接被拒绝、401 未授权、404 模型不存在、超时。连接被拒绝通常是端点地址或端口写错或者本地推理引擎没启动。先在浏览器或 curl 里直接访问base_url下的/models端点确认服务活着。401 一般是 api_key 问题。本地模型通常不校验 key但有些工具会强制要求非空随便填一个字符串就行。云端 API 的 key 要确认没过期、没超额度。404 模型不存在九成是模型名写错。用 curl 拉一下模型列表把名字复制粘贴到配置里别手打。超时问题在本地模型上很常见尤其是模型大、显存小的时候生成速度慢请求还没返回就超时了。解决办法是调大 openrig 或工具的超时设置或者换更小的模型、量化版本。6.3 工具侧报错速查表报错关键词可能原因排查方向local proxy failed代理未启动或端口冲突检查代理进程和端口占用endpoint /responses端点路径不匹配确认工具要求的路径格式model is not supported模型名不被工具识别做模型名映射或换模型organization disabled access账号权限问题检查账号订阅状态node.js not yet released版本号写错去官网确认真实版本号command not foundPATH 未配置检查全局 bin 目录是否在 PATH这张表是我自己踩坑之后整理的遇到报错先对号入座能省不少时间。表格里没覆盖的情况去 openrig 的 issue 区搜报错关键词大概率有人遇到过。6.4 多工具同时使用的冲突处理同时用 Claude Code 和 Codex又都通过 openrig 走同一个本地模型可能会遇到端口冲突或者配置互相覆盖。openrig 的设计是每个工具生成独立的配置片段理论上不冲突但如果你手动改过某个工具的配置文件openrig 再注入时可能覆盖你的修改。我的做法是所有模型和端点配置只在 openrig 的 YAML 里改不直接动工具自己的配置文件。工具配置文件由 openrig 全权管理这样升级和切换都不会乱。如果确实需要工具特有的设置看看 openrig 的 tool 配置里有没有对应的扩展字段没有的话再考虑手动改但要做好被覆盖的心理准备。7. 我个人的实操体会折腾 openrig 这段时间最大的感受是配置管理这件事工具本身只解决一半问题另一半靠纪律。openrig 提供了统一配置的能力但如果你还是习惯性地去改各个工具的原生配置文件那 openrig 的价值就发挥不出来。真正用好它的前提是你愿意把 openrig 的 YAML 当成唯一的配置源其他工具的配置都交给它生成。另一个体会是本地模型和云端模型的搭配使用比单纯用某一种更实际。日常的代码补全、简单修改走本地模型省成本、响应快遇到复杂重构、长上下文理解路由到云端强模型。openrig 的路由规则让这种搭配变得很自然不用手动切换。最后分享一个小技巧把 openrig 的配置文件纳入 Git 管理但 api_key 这类敏感信息用环境变量引用不要直接写在 YAML 里。openrig 支持在配置里写${ENV_VAR}这样的占位符运行时从环境变量读取。这样配置文件可以安全地提交和分享密钥留在本地环境里。团队协作时新人拉下配置只需要设置自己的环境变量就能跑起来省去了大量沟通成本。