openrig 统一配置 Claude Code 与 Codex：YAML 编排与本地模型接入实战

1. openrig 到底想解决什么问题

第一次看到 openrig 这个名字，我下意识以为是某个硬件机架项目，毕竟 rig 在英文里常指设备支架、测试台架。但把 Claude Code、Codex、YAML、npm 这几个热搜词摆在一起，方向就清楚了：这是一个围绕 AI 编程助手做统一配置与编排的开源工具，核心价值在于把散落在不同工具里的配置、模型接入、代理转发、环境变量这些东西收拢到一份可维护的结构里。

我接触过不少团队，用 Claude Code 写业务代码，用 Codex 做补全和重构，本地还挂着 LM Studio 跑开源模型，结果每个人的配置文件各写各的，换台机器就得重新折腾一遍。openrig 想干的事，就是给这种多工具混用的场景提供一个统一的“装配台”。你可以把它理解成一个配置中枢：一份 YAML 描述清楚你要用哪些模型、走哪个端点、注入哪些环境变量，然后由它负责把这些配置分发到 Claude Code、Codex 各自的读取位置。

这件事听起来简单，实际踩坑的人非常多。热搜里那一堆“claude code 安装”“codex 安装教程”“npm 无法加载文件 npm.ps1”“yaml 文件怎么创建”，本质上都是同一类问题：工具链太碎，配置入口太多，官方文档又假设你已经懂了。openrig 这类项目的意义，就是把这些碎片化的操作收敛成可复现的流程。

适合读这篇的人有三类。第一类是刚上手 Claude Code 或 Codex，被安装和配置卡住的开发者；第二类是团队里负责统一开发环境的人，需要一套能提交到仓库、能 review 的配置方案；第三类是喜欢折腾本地模型、想把 LM Studio 或类似本地推理服务接进主流编程助手的人。下面我按实际落地的顺序，把 openrig 涉及的核心环节拆开讲。

2. 核心设计思路与方案选型拆解

2.1 为什么用 YAML 做配置载体

openrig 选择 YAML 而不是 JSON 或 TOML，这个决定值得说道。JSON 不支持注释，而 AI 工具配置里最需要的就是注释——你得写清楚“这个 key 是给哪个模型用的”“这个端点为什么指向本地”。TOML 表达嵌套结构时层级一多就变得啰嗦，尤其是描述多个 provider、多个模型映射的时候。

YAML 的优势在于它天然适合表达“列表套字典”这种结构，而这正是多模型配置的典型形态。一个 provider 下面挂若干 model，每个 model 又有自己的参数，用 YAML 写出来层次清晰，缩进即结构，肉眼扫一遍就能看懂。

但 YAML 的坑也在这里。它对缩进极其敏感，用 Tab 还是空格、缩进几个空格，直接决定解析成败。我见过太多人复制粘贴配置后报错，排查半天发现是某一行多了个空格。所以 openrig 这类项目通常会在文档里明确要求统一用两个空格缩进，并且建议在编辑器里开启 YAML 语法校验。

提示：写 YAML 时把编辑器的“显示空白字符”打开，Tab 和空格一眼就能分辨，能省掉大量低级排查时间。

2.2 统一配置与工具原生配置的关系

这里有个关键设计取舍：openrig 是取代 Claude Code 和 Codex 的原生配置，还是在其之上做一层封装？

从热搜词“cc switch local proxy failed while handling codex endpoint /responses”能看出，实际使用中经常出现代理转发失败的问题，根源往往是配置指向不一致。openrig 的思路更偏向后者——它不试图重写工具本身，而是做一层“配置生成与分发”。你在一份 openrig 配置里定义好模型和端点，它负责把内容写到 Claude Code 和 Codex 各自期望的位置。

这样做的好处是升级工具时不会因为 openrig 的封装而卡住，坏处是必须紧跟各工具的配置格式变化。对使用者来说，理解这一点很重要：openrig 是编排层，不是替代层。当某个工具改了配置字段名，你需要等 openrig 适配，或者手动调整生成结果。

2.3 模型接入的抽象层次

openrig 把模型接入抽象成 provider 和 model 两级。provider 描述“去哪里调用”，比如某个云端 API 端点或者本地推理服务地址；model 描述“调用哪个模型、用什么参数”。这个抽象的好处是同一个 provider 下可以挂多个 model，切换模型时只改一行。

热搜里“claude code 调用 lmstudio 的本地模型”“codex 接入 deepseek”这类需求，本质上都是把非默认的模型接进工具。openrig 通过统一抽象，让这些接入方式变得一致：不管目标是本地还是远端，配置结构相同，只是端点地址和鉴权方式不同。

这种设计还有一个隐性收益：配置可以版本化。把 openrig 的 YAML 提交到团队仓库，新人拉下来就能得到一致的模型接入环境，不用再问“你那个端点地址是多少”。

3. 环境准备与安装实操要点

3.1 Node 与 npm 环境的正确姿势

openrig 通过 npm 分发，所以第一步是把 Node 环境弄干净。热搜里“node 安装后 npm 不能用”“npm 无法加载文件 npm.ps1，因为在此系统上禁止运行脚本”是高频问题，这里集中说清楚。

Windows 上出现 npm.ps1 无法加载，是因为 PowerShell 默认的执行策略禁止运行脚本。解决办法不是去改系统策略了事，而是理解原因：npm 在 Windows 上会生成 .ps1 包装脚本，PowerShell 出于安全默认拦截。你可以用管理员权限打开 PowerShell，执行设置执行策略的命令，把当前用户的策略调整为允许本地脚本运行。改完之后重开终端，npm 就能正常调用。

另一个常见问题是 Node 装完了但 npm 命令找不到，多半是安装时没勾选“添加到 PATH”，或者 PATH 里有多个 Node 版本互相打架。我的建议是：卸载所有旧版本，用官方安装包重装一次，安装时确认勾选 PATH 选项，装完在终端里分别执行 node -v 和 npm -v 验证。

注意：如果你之前用包管理器装过 Node，重装前先彻底清理，残留的全局目录会导致新版本命令指向错误位置。

3.2 npm 源的选择与切换

国内环境下 npm 官方源速度不稳定，热搜里“npm 国内源”“npm 淘宝源”“npm 镜像源地址”都是这个需求。切换源用一条命令即可，把 registry 指向国内镜像。但这里有个经验：不要全局永久切换，而是按项目或按需切换。

原因是国内镜像同步有延迟，某些刚发布的包在镜像上可能还没有，或者版本落后。我的做法是默认用官方源，遇到安装慢的时候临时切镜像，装完切回来。如果你确实想长期用镜像，记得定期检查关键依赖的版本是否同步。

安装 openrig 本身用全局安装即可，装完用版本命令验证是否成功。如果安装过程中报 peer dependency 相关的警告，先别慌，这类警告在 npm 生态里很常见，多数不影响使用，除非它明确报错中断。

3.3 全局包的管理与卸载

热搜里“npm 卸载全局包”说明很多人装了一堆全局工具后想清理。卸载全局包的命令很简单，但要注意包名和命令名可能不一致。比如你装的包叫 A，但提供的命令叫 B，卸载时要写包名 A。

我建议定期用列出全局包的命令看一眼自己装了什么，把不用的清掉。全局包太多不仅占空间，还可能因为版本冲突导致命令行为异常。openrig 这类工具建议保持最新，因为它需要跟进 Claude Code 和 Codex 的配置格式变化。

4. openrig 配置文件的完整写法

4.1 配置文件的基本骨架

一份典型的 openrig 配置从顶层结构开始，通常包含版本声明、provider 列表、model 映射和工具绑定几个部分。下面是一个基于常见实践整理的骨架，字段名以实际项目文档为准，这里重点讲结构逻辑。

version: 1 providers: - name: local type: openai-compatible base_url: http://127.0.0.1:1234/v1 api_key: local-key models: - name: qwen-coder provider: local context_window: 32768 tools: claude-code: default_model: qwen-coder codex: default_model: qwen-coder

这段配置表达的意思很直白：定义了一个本地 provider，指向本机某个兼容接口的服务；定义了一个模型，绑定到这个 provider；然后告诉 Claude Code 和 Codex 默认用这个模型。

4.2 provider 字段的填写要点

provider 里的 base_url 是最容易出错的地方。很多人填了地址但忘了带路径后缀，导致请求打到根路径返回 404。兼容接口通常要求 base_url 指向 /v1 这一级，具体以你用的推理服务文档为准。

api_key 字段在本地服务场景下往往随便填一个占位符就行，但有些工具会校验这个字段非空，所以别留空。type 字段决定 openrig 用哪种协议去调用，选错了会出现请求格式不匹配的问题。

提示：配置完 provider 后，先用 curl 或类似工具直接请求一次端点，确认服务本身可达，再去排查 openrig 的问题。把问题分层，能大幅缩短排查时间。

4.3 model 与 context_window 的匹配

context_window 这个参数值得单独说。它表示模型能处理的上下文长度，填小了会导致长对话被截断，填大了如果模型实际不支持会报错。热搜里“claude code 1m 上下文”反映的就是大家对长上下文的关注。

填写原则是：以模型实际支持的最大值为准，不要凭感觉填。本地模型尤其要注意，显存不够时即使模型声称支持很长上下文，实际跑起来也会爆。我的经验是把 context_window 设成模型标称值的八成左右，留一点余量，稳定性更好。

4.4 工具绑定的映射逻辑

tools 这一段是 openrig 的核心价值所在。它把抽象出来的 model 映射到具体工具。Claude Code 和 Codex 各自读取配置的方式不同，openrig 负责把统一配置翻译成它们能识别的格式。

这里要注意的是默认模型和备用模型的关系。有些配置支持指定多个模型，主模型不可用时自动切换。如果你有这种需求，在 tools 段里按项目文档的格式补充备用项。但别配太多，切换逻辑复杂了反而难排查。

5. 与 Claude Code、Codex 的对接实操

5.1 Claude Code 侧的配置落地

Claude Code 读取配置有自己的约定位置。openrig 生成配置后，你需要确认它写到了正确路径。热搜里“vscode 配置 claude code”“claude code windows”“ubuntu 安装 claude code”说明跨平台配置差异是痛点。

Windows 和类 Unix 系统的配置目录不同，openrig 通常会根据当前系统自动判断。如果自动判断出错，你可以在配置里显式指定输出路径。验证是否生效的方法很简单：启动 Claude Code，看它加载的模型是不是你配置的那个。

如果启动后仍走默认模型，检查两件事：一是 openrig 是否真的执行了分发动作，二是 Claude Code 是否有更高优先级的配置覆盖了它。配置优先级问题是最隐蔽的坑，建议从工具文档里确认加载顺序。

5.2 Codex 侧的端点对接

Codex 对接的复杂度通常高于 Claude Code，因为它对端点路径更敏感。热搜里“cc switch local proxy failed while handling codex endpoint /responses”就是典型的端点路径不匹配问题。

Codex 期望的请求路径往往带特定后缀，如果你的 provider base_url 没配对，请求就会打到错误路径。解决办法是确认你的推理服务是否支持 Codex 期望的接口格式。有些本地服务只实现了部分兼容接口，这时候要么换服务，要么在中间加一层转换。

我的实操建议是：先用最简单的配置跑通一次请求，确认链路通了，再逐步加复杂度。一上来就配一堆模型和备用项，出问题时根本不知道是哪一层的问题。

5.3 本地模型接入的注意事项

把本地模型接进 Claude Code 或 Codex，最大的变量是本地服务的接口兼容性。LM Studio 这类工具提供了兼容接口，但不同版本行为可能有差异。

接入时重点确认三件事：接口路径是否正确、请求格式是否匹配、返回格式是否被工具接受。任何一环不匹配都会表现为“请求失败”或“无响应”，但原因完全不同。我的排查顺序是先确认服务本身能响应，再确认响应格式符合工具预期，最后才怀疑 openrig 的配置。

注意：本地模型首次加载可能很慢，工具侧如果有超时设置，记得调大，否则会在模型还没加载完时就报超时。

6. 常见问题与排查技巧实录

6.1 安装类问题速查

这张表覆盖了热搜里出现频率最高的几类安装问题。核心思路是把“环境问题”和“工具问题”分开，环境没弄好之前不要碰工具配置。

6.2 配置类问题排查

配置类问题的典型表现是工具启动了但行为不对。排查时按这个顺序走：先看 openrig 生成的配置文件内容是否符合预期，再看工具实际读取的配置路径是否一致，最后看工具日志里加载的模型和端点是什么。

很多人跳过第一步直接看工具，结果在工具层面绕半天，回头发现是 openrig 根本没生成配置。养成“先验证中间产物”的习惯，能省很多时间。

6.3 请求失败的分层定位

请求失败是最难排查的一类，因为可能出在任意一层。我的分层方法是：第一层，直接用命令行请求 provider 端点，确认服务可达；第二层，用工具的最小配置请求，确认工具能发出正确请求；第三层，加上 openrig 的完整配置，确认编排层没有引入问题。

这三层逐层验证，任何一层失败就停在那里解决，不要跳层。热搜里那些代理转发失败的问题，用这个方法基本都能定位到具体是哪一层的配置错了。

6.4 我踩过的几个坑

第一个坑是 YAML 缩进。有次配置怎么都不生效，最后发现是复制时混入了 Tab。从那以后我所有 YAML 都用两个空格，并且开编辑器校验。

第二个坑是端点路径。base_url 少写一段路径，请求全打到 404，但工具报的错很含糊，让人以为是鉴权问题。后来我养成习惯，配置完先手动请求一次端点。

第三个坑是模型名大小写。有些服务对模型名大小写敏感，配置里写错一个字母就报模型不存在。这个错误信息通常比较明确，看到“model not found”先检查拼写。

7. 团队协作与配置版本化

7.1 把配置提交到仓库

openrig 的配置适合提交到团队仓库，这样新人拉下来就能用。但要注意别把敏感信息写进去，比如真实的 API key。做法是把 key 抽成环境变量引用，配置文件里只写变量名。

这样做的另一个好处是不同人可以用不同的 key，但共享同一套模型和端点定义。团队里有人用云端、有人用本地时，通过环境变量区分即可。

7.2 配置变更的评审

配置变更应该像代码变更一样走评审。模型端点改了、默认模型换了，这些都会影响所有人的开发体验，值得让团队知道。把 openrig 配置纳入代码评审流程，能避免“某个人本地改了配置导致别人跑不起来”的情况。

7.3 多环境配置的组织

团队通常有本地开发、测试、生产几套环境，模型接入也可能不同。openrig 支持多份配置或者配置继承的话，按环境拆分是最清晰的做法。基础配置放公共部分，环境差异放各自文件，用的时候指定加载哪份。

这种组织方式的好处是公共部分改一次，所有环境都受益，而环境特有的差异又不会互相污染。

8. 性能与稳定性调优经验

8.1 上下文长度与响应速度的平衡

context_window 设得越大，模型处理请求时需要的内存和计算越多，响应越慢。本地模型尤其明显。我的经验是根据实际任务调整：写小函数用不着超长上下文，做大型重构才需要。

如果工具支持按任务切换模型，可以配一个短上下文快模型做日常补全，一个长上下文模型做复杂任务。这样兼顾速度和能力。

8.2 超时与重试的设置

本地模型冷启动慢，超时设置太短会频繁失败。建议把超时设得宽松一些，同时开启有限次数的重试。但重试次数别太多，否则一个请求卡很久，体验很差。

重试策略上，连接失败可以重试，但如果是模型返回了明确的错误响应，重试通常没用，应该直接报错让人处理。

8.3 日志与可观测性

openrig 和工具本身的日志是排查问题的关键。建议把日志级别调到能看到请求端点和模型名的程度，这样出问题时一眼能看出请求发去了哪里、用了哪个模型。

日志别开太详细，否则刷屏影响判断。找到问题后把级别调回去，保持日常使用的清爽。

9. 后续可扩展的方向

openrig 这类编排工具的价值会随着接入工具增多而放大。目前主要围绕 Claude Code 和 Codex，后续如果接入更多编程助手，统一配置的收益会更明显。

另一个方向是配置的模板化。把常见场景（本地模型、云端模型、混合）做成模板，新人选一个模板填几个参数就能用，进一步降低上手门槛。

我在实际使用中的体会是，这类工具真正的价值不在于省那几行配置，而在于把“环境搭建”这件事从个人经验变成团队资产。配置写一次、评审一次、提交一次，后面所有人受益。踩过的坑沉淀成文档和模板，比任何口头传授都可靠。