1. openrig 到底想解决什么问题第一次看到openrig这个词是在几个折腾 Claude Code 和 Codex 的群里。有人丢出一句openrig 配好了终于不用每次手改 YAML 了底下立刻一堆人问怎么装、支持哪些模型、和 cc switch 有什么区别。但真去搜你会发现关于它的完整资料少得可怜官方仓库的 README 也写得相当克制大部分信息散落在各种 issue、讨论串和别人的配置片段里。我前后花了大概两周时间把 openrig 在自己的开发机上从零跑通中间踩了配置格式、Node.js 版本、模型端点对接、YAML 缩进等一堆坑。这篇就把整个过程中的判断、取舍和实测结论摊开讲清楚给同样在 Claude Code、Codex 这类命令行 AI 工具之间来回切换的人一个可复现的参考。先把定位说清楚openrig 本质上是一个面向 AI 编码工具的配置编排层。它不训练模型也不代理网络流量它做的事情是把用哪个模型、走哪个端点、传什么参数、在哪个工具里生效这些零散的配置收敛成一份结构化的 YAML然后由它统一分发到 Claude Code、Codex 等不同的客户端。你可以把它理解成AI 编码工具的 dotfiles 管理器——只不过它管的不只是 shell 配置而是模型接入这一整条链路。它适合谁三类人最需要它。第一类是同时用 Claude Code 和 Codex 的人两边配置格式不一样手动同步极其痛苦第二类是经常切换模型后端的人今天用官方订阅明天想接本地模型或者第三方兼容端点每次都要翻文档改配置第三类是把这套东西带进团队的人需要一份可版本化、可 review、可复现的配置基线而不是每个人电脑上一套私有设置。关键词里出现的Claude Code、Codex、YAML、Node.js基本勾勒出了它的技术底座Node.js 运行时、YAML 配置、面向 Claude Code 和 Codex 的适配。热搜词里那一堆claude code 安装codex 安装教程yaml 文件怎么创建node.js 是干什么的说明大量人卡在最基础的环境环节。所以这篇不会只讲 openrig 本身环境准备和配置原理会占相当篇幅因为这两块才是真正劝退人的地方。2. 环境底座Node.js 与 YAML 这两关必须先过2.1 Node.js 版本选择别追最新追 LTSopenrig 是 Node.js 生态里的工具跑起来第一件事就是确认 Node 版本。热搜里有一条特别典型error installing 24.21.0: node.js v24.21.0 is not yet released or is not available。这个报错几乎百分百是因为用了版本管理器去装一个还不存在的版本号或者镜像源没同步。我的建议很直接用当前 LTS 版本不要用 Current 版本。LTS 是长期支持版生态兼容性最好openrig 依赖的一些包在奇数版本比如 21、23上偶尔会有原生模块编译问题。截至我写这篇时的稳定选择是 Node.js 20.x 或 22.x 的 LTS 线。安装方式上Windows 用户直接去 Node.js 官网下载 LTS 的安装包一路下一步即可安装完在终端敲node -v npm -v两条都能正常输出版本号说明装好了。macOS 和 Linux 用户我更推荐用版本管理器方便以后切版本# 以 fnm 为例轻量且快 curl -fsSL https://fnm.vercel.app/install | bash fnm install --lts fnm use lts注意如果你之前装过多个 Node 版本务必确认当前 shell 里which node指向的是你想用的那个。我遇到过 npm 全局包装到了 A 版本、但终端实际跑的是 B 版本结果 openrig 命令找不到的情况排查了半天。国内网络环境下 npm 安装慢是常态可以换镜像源npm config set registry https://registry.npmmirror.com这条不是必须的但能省不少等待时间。换完之后npm install的速度会有肉眼可见的提升。2.2 YAML 不是随便写写缩进就是语法openrig 的配置核心是 YAML。热搜里yolov10 yaml 文件怎么创建rstudio 的 yaml 在哪里yaml 安装这些词说明很多人对 YAML 本身就不熟。这里必须把 YAML 的几个致命特性讲透否则你配 openrig 一定会在缩进上翻车。YAML 用缩进表示层级绝对不能用 Tab只能用空格。这是新手第一大坑。很多编辑器默认 Tab 键插入的是制表符粘进去看着对齐解析器直接报错。我的做法是在 VS Code 里针对.yaml/.yml文件强制设置{ [yaml]: { editor.insertSpaces: true, editor.tabSize: 2, editor.detectIndentation: false } }缩进宽度统一用 2 个空格这是社区最通用的约定。冒号后面必须跟一个空格key:value是错的key: value才对。列表项用-开头-后面也要有空格。一个最小可用的 YAML 长这样models: - name: local-qwen provider: openai-compatible endpoint: http://127.0.0.1:1234/v1 model: qwen2.5-coder - name: cloud-glm provider: openai-compatible endpoint: https://example.com/v1 model: glm-4你可以用在线 YAML 校验器先验证语法或者本地装个yaml命令行工具npm install -g yaml yaml config.yaml能正常输出 JSON 就说明语法没问题。这一步看着多余但能帮你把配置写错和工具本身有问题这两类故障彻底分开排查效率天差地别。2.3 全局安装 openrig 与首次初始化环境齐了之后装 openrignpm install -g openrig openrig --version如果openrig命令找不到八成是 npm 全局 bin 目录没进 PATH。查一下npm config get prefix把这个路径下的binWindows 是根目录本身加进环境变量即可。Windows 上 npm 全局包默认装在%APPDATA%\npm这个目录通常安装 Node 时就自动加进 PATH 了如果没加手动补上。首次使用建议先跑初始化让它生成一份默认配置骨架openrig init它会在用户目录下生成配置目录具体路径各平台不同用openrig config path可以打印出来。拿到路径后直接用编辑器打开那份 YAML后面所有改动都在这里做。3. 把 Claude Code 和 Codex 接进同一份配置3.1 两个工具的配置模型差异在哪要理解 openrig 的价值得先知道 Claude Code 和 Codex 各自怎么读配置。Claude Code 走的是环境变量加配置文件的路子模型端点、鉴权信息、订阅相关的开关分散在几个地方Codex 则更依赖它自己的配置文件格式和字段命名又是另一套。热搜里cc switch local proxy failed while handling codex endpoint /responses、your organization has disabled claude subscription access for claude code、codex 无法加载组织设置这些报错本质上都是配置没对齐导致的。openrig 的思路是你只维护一份中立的模型清单由它负责翻译成各工具认识的格式。这就避免了改了一边忘了另一边的经典问题。在 openrig 的 YAML 里模型定义是核心。一个完整的模型条目通常包含这些字段字段作用是否必填name模型在本地的别名工具里选它是provider协议类型如 openai-compatible是endpointAPI 基础地址是model传给后端的真实模型名是apiKeyEnv从哪个环境变量读密钥否headers额外请求头否provider这个字段最关键。绝大多数第三方服务和本地推理服务都兼容 OpenAI 的接口协议所以填openai-compatible基本能覆盖大部分场景。热搜里claude code 调用 lmstudio 的本地模型、codex 接入 deepseek、使用 cc switch 接入 deepseek v4, qwen, glm 等模型说的都是这类需求它们的共同点就是后端都提供 OpenAI 兼容接口。3.2 密钥管理别把 key 写进 YAML这是我要重点强调的一条经验。永远不要把 API Key 明文写进 YAML 文件尤其是这份配置要进 git 仓库的时候。正确做法是用环境变量引用models: - name: cloud-glm provider: openai-compatible endpoint: https://example.com/v1 model: glm-4 apiKeyEnv: GLM_API_KEY然后在 shell 配置文件里设置export GLM_API_KEY你的密钥Windows PowerShell 用$env:GLM_API_KEY 你的密钥想持久化就写进系统环境变量。这样 YAML 可以放心提交到仓库密钥留在本地。我见过有人把 key 提交到公开仓库几分钟内就被扫号脚本薅光额度这个教训太贵了。3.3 生成各工具配置并验证生效模型清单写好后让 openrig 把配置分发出去openrig apply它会根据你启用的工具把配置写到 Claude Code 和 Codex 各自读取的位置。执行完建议先 dry-run 看一眼它到底改了什么openrig apply --dry-run这个习惯能救命。有一次它要覆盖我手动调过的一个字段dry-run 直接打印出了 diff我及时把那个字段合并进了 openrig 的 YAML避免了配置被冲掉。验证是否生效最直接的办法是在对应工具里发一条测试请求。Claude Code 里可以问一个简单问题看是否正常返回Codex 里同理。如果报错先看错误信息指向哪一层连接被拒endpoint 地址或端口不对401/403密钥没读到或无效404endpoint 路径少了/v1或多了后缀模型不存在model字段填的名字后端不认热搜里the gpt-5.6-sol model is not supported when using codex with a...这类报错就是model字段和后端实际支持的模型名对不上。解决办法是去后端服务的模型列表接口确认准确名称别凭记忆填。4. 多模型切换与本地模型接入的实操细节4.1 切换逻辑别名机制比改配置优雅openrig 最实用的功能之一是模型别名切换。你可以在 YAML 里定义多个模型然后通过命令快速切换当前激活的那个openrig use local-qwen openrig use cloud-glm这比每次手动改配置文件再重启工具高效太多。背后的原理是 openrig 维护了一个当前激活模型的状态切换时它只更新各工具配置里指向的模型条目其他不变。我自己的用法是给常用组合起短别名fast指向响应快的云端小模型deep指向能力强的模型local指向本地推理。写代码时用deep改注释、写文档这种轻量活用fast断网或者不想消耗额度时切local。4.2 本地模型接入端口和路径最容易错接本地模型是热搜里的高频需求。以 LM Studio 为例它默认在http://127.0.0.1:1234提供 OpenAI 兼容接口但完整路径是/v1。所以 endpoint 要写endpoint: http://127.0.0.1:1234/v1少写/v1是最常见的 404 来源。另外本地服务要确认已经启动并且加载了模型否则连接会被拒。Ollama 的默认端口是11434路径同样是/v1endpoint: http://127.0.0.1:11434/v1本地模型还有个坑是上下文长度。云端模型动辄 128K 上下文本地跑的小模型可能只有 8K 或 32K。如果你把整个大文件丢进去超出上下文会被截断或直接报错。我的做法是本地模型只用来处理单文件、单函数的任务别指望它读整个仓库。提示本地推理服务如果监听的是127.0.0.1只有本机能访问。如果你在容器或远程环境里跑工具需要让服务监听0.0.0.0同时注意访问控制别把推理端口暴露到不可信网络。4.3 第三方兼容端点的参数微调接第三方兼容端点时除了 endpoint 和 model有时还要调请求头或超时。比如某些服务要求特定的User-Agent或者额外的鉴权头openrig 的headers字段可以满足models: - name: custom provider: openai-compatible endpoint: https://example.com/v1 model: some-model apiKeyEnv: CUSTOM_KEY headers: X-Custom-Header: value超时问题也常见。网络抖动时默认超时可能太短导致请求频繁失败。如果 openrig 支持超时配置把它调大一些比如 60 秒。这个值没有标准答案取决于你的网络和后端响应速度实测调整最靠谱。5. 踩坑排查从报错到定位的完整链路5.1 配置改了不生效先查缓存和重启最常见的玄学问题是明明改了 YAML工具里行为没变。排查顺序是这样的。第一步确认openrig apply真的执行成功了没有报错。第二步确认工具读取的配置文件路径和你以为的一致用openrig config path和工具自己的配置路径对比。第三步很多工具在启动时读一次配置就缓存了改完配置必须重启工具进程光刷新界面没用。我踩过一次改完配置直接在当前会话里测试怎么都不对重启终端后一切正常。从那以后我养成了改配置必重启的习惯。5.2 端点报错的分层定位法热搜里cc switch local proxy failed while handling codex endpoint /responses这种报错信息很长容易看懵。我的定位方法是分层剥离。先用最原始的方式直接打后端接口绕开所有中间层curl -X POST http://127.0.0.1:1234/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer $API_KEY \ -d {model:qwen2.5-coder,messages:[{role:user,content:hi}]}如果这条 curl 都失败问题在后端或网络跟 openrig 无关。如果 curl 成功但工具失败问题在配置翻译层回去检查 YAML 字段。这个二分法能砍掉一大半无效排查。/responses这个路径值得单独说。它是某些接口的特定端点和/chat/completions不是一回事。如果你的后端只支持/chat/completions但工具按/responses去请求就会 404。这时候要么换支持该端点的后端要么在 openrig 里确认 provider 类型选对了。5.3 订阅与权限类报错的本质your organization has disabled claude subscription access for claude code这类报错本质是账号层面的权限策略不是配置能解决的。遇到这种先确认你用的账号类型和订阅状态再确认组织是否限制了该工具的访问。这类问题改 YAML 没用别在配置上浪费时间。codex 无法加载组织设置类似属于账号或组织配置范畴。我的建议是把这类报错和配置类报错严格区分开配置类报错通常伴随连接、路径、字段相关字样权限类报错通常出现 organization、subscription、access 等词。分清楚能省大量时间。6. 把配置带进团队版本化与协作的几个原则6.1 什么该进仓库什么不该团队协作场景下openrig 的 YAML 应该进 git但要做剥离。进仓库的模型清单结构、endpoint、模型名、字段映射。不进仓库的任何密钥、个人 token、本地绝对路径。密钥用环境变量引用已经解决了大部分问题。本地路径这类因人而异的字段可以用 openrig 的变量替换功能如果支持或者干脆在文档里说明让各人自己填。我倾向于后者简单直接。6.2 用分支管理不同环境的配置一个实用技巧用 git 分支区分环境。main分支放团队通用配置个人分支放自己的本地模型和私有端点。合并时只把通用部分往上提。这样既共享了基线又保留了个人灵活性。如果 openrig 支持多配置文件叠加比如一个基础配置加一个覆盖配置那就更优雅了基础配置进仓库覆盖配置放本地并加进.gitignore。具体是否支持要看版本用之前先查文档确认。6.3 新人上手的检查清单给团队新人一份 checklist 比口头讲十遍有用。我整理的是这样装 Node.js LTSnode -v能输出版本全局装 openrigopenrig --version正常拉取团队配置仓库放到约定位置按文档设置所需环境变量跑openrig apply --dry-run确认无异常正式openrig apply在 Claude Code 和 Codex 里各发一条测试请求遇到报错按第 5 章的分层法定位这份清单把环境问题和配置问题提前分流新人自助解决率能提高不少。7. 我实际用下来的一些体会openrig 这类工具的价值用过一段时间才会真正体会到。刚开始你会觉得它只是省了几次手动改配置的功夫但当你同时维护三四个模型后端、两台机器、还要给团队同步时那份统一的 YAML 就成了唯一的真相来源。改一处处处生效这种一致性带来的安心感是手动配置给不了的。几个我反复验证过的经验Node 版本认准 LTS别追新YAML 缩进用空格不用 Tab编辑器里锁死密钥一律走环境变量改完配置先 dry-run 再 apply然后重启工具报错先分层用 curl 把后端和配置层切开。这几条看着简单但每一条背后都是我实打实踩过的坑。还有一个容易被忽略的点定期备份你的 openrig 配置目录。它承载了你所有模型接入的映射关系丢了重建很麻烦。我把它纳入了 dotfiles 仓库统一管理换机器时 clone 下来设好环境变量就能用省心。至于后续还能怎么扩展我目前在尝试的是把不同项目的模型偏好也纳入配置让 openrig 根据当前工作目录自动切换激活模型。这个需求是否值得做取决于你切换项目的频率。如果你一天要在好几个仓库之间跳那自动化切换确实能减少心智负担。