1. openrig 到底是个什么东西第一次看到 openrig 这个名字很多人会以为是某个硬件项目毕竟 rig 这个词在英文里本来就有“装配、设备”的意思。但如果你最近在折腾 Claude Code、Codex 这类命令行 AI 编程工具大概率已经在某些讨论里见过它。简单说openrig 是一个围绕 AI 编程助手做“统一接入与配置管理”的开源思路或工具集核心目标是把 Claude Code、Codex 这类工具的模型接入、端点配置、环境变量管理用一套相对标准化的方式管起来而不是每换一个模型就手动改一遍配置文件。它解决的问题很具体。现在用 Claude Code 的人越来越多用 Codex 的人也不少但这两套工具各自有自己的配置方式、自己的环境变量、自己的端点约定。你想让 Claude Code 走本地模型得改一套东西想让 Codex 接第三方兼容端点又得改另一套东西。来回切换的时候配置文件改来改去很容易把之前能用的配置覆盖掉最后自己也记不清哪个版本是对的。openrig 想做的就是把这层配置抽象出来用 YAML 描述“我要用哪个模型、走哪个端点、带哪些参数”然后由工具去生成或注入对应的配置。适合谁来参考这份内容三类人最合适。第一类是已经在用 Claude Code 或 Codex但每次换模型都要翻文档、改环境变量的开发者第二类是想在本地或内网环境里跑 AI 编程助手需要把端点指向自己服务的人第三类是对 Node.js 工具有一定了解愿意花半小时把配置理顺之后长期省事的人。如果你完全没接触过命令行工具也没关系我会把 Node.js 安装、YAML 怎么写这些基础环节都拆开讲。提示openrig 目前更像是一种配置管理思路的集合不同人手里的实现可能不完全一样。下面讲的是基于常见实践整理出来的通用方案你落地时以自己实际拿到的仓库说明为准。2. 为什么需要一层配置抽象2.1 Claude Code 和 Codex 各自的配置痛点Claude Code 的配置主要围绕环境变量和它自己的设置文件展开。你想让它走非默认端点通常要设置类似ANTHROPIC_BASE_URL、ANTHROPIC_API_KEY这样的变量或者写进它的配置文件里。Codex 这边则是另一套它有自己的端点约定比如处理/responses这类路径时的行为还有模型名称校验像gpt-5.6-sol这种不被支持的模型名会直接报错。两套工具的环境变量名不一样配置文件位置不一样连“模型不支持”这种报错的触发条件都不一样。痛点就在这里。你如果同时用这两个工具或者经常在“官方端点”和“第三方兼容端点”之间切换就会陷入一种重复劳动改 Claude Code 的配置测试改 Codex 的配置测试想切回去又得把之前的配置找回来。更麻烦的是有些配置是写在 shell 的启动脚本里的改错了会影响整个终端会话排查起来很费时间。2.2 用 YAML 做统一描述的好处YAML 最大的好处是可读性好而且结构清晰。你可以在一个文件里描述多个“配置档”每个档位对应一套模型和端点组合。比如一个档位叫local指向本地跑的模型服务另一个档位叫remote指向一个兼容端点。切换的时候只需要告诉工具“用 local 这个档”剩下的环境变量注入、配置文件生成都由工具完成。这种做法的另一个好处是可版本管理。你把 YAML 文件放进 Git每次改动都有记录哪天配置坏了直接回滚到上一个提交就行。相比之下手动改环境变量很难追溯改完就忘了改了什么。YAML 还能写注释你可以标注每个端点的用途、申请方式、注意事项团队协作的时候别人一看就懂。2.3 Node.js 在其中的角色openrig 这类工具大概率是用 Node.js 写的因为 Claude Code 和 Codex 本身都跟 Node.js 生态关系密切。Node.js 在这里扮演的是“运行时”的角色工具本身是一段 JavaScript 代码需要 Node.js 来执行。你安装 Node.js本质上是在给这些工具准备一个能跑起来的环境。这里有个常见的坑Node.js 版本不是越新越好。有些工具对 Node.js 版本有要求太新的版本可能还没被支持安装时会报node.js v24.21.0 is not yet released or is not available这类错误。稳妥的做法是装 LTS 版本也就是长期支持版稳定性和兼容性都更好。Node.js 官网下载页面会明确标出 LTS 版本选那个就行。3. 环境准备Node.js 与基础工具安装3.1 Node.js 安装的正确姿势Windows 用户直接去 Node.js 官网下载 LTS 版本的安装包一路下一步就行。安装完成后打开 PowerShell 或 CMD输入node -v和npm -v能看到版本号就说明装好了。macOS 用户可以用官网的 pkg 安装包也可以用 Homebrew命令是brew install nodelts。Ubuntu 用户建议用 NodeSource 的源来装比系统自带的版本新具体命令是先加源再apt install nodejs。装完之后有一个关键检查确认npm的全局安装目录在 PATH 里。Windows 上一般是%APPDATA%\npmmacOS 和 Linux 上一般是/usr/local/bin或~/.npm-global/bin。如果全局安装的工具命令找不到多半是这里没配好。你可以用npm config get prefix看当前的前缀路径然后把这个路径下的bin目录加到 PATH 里。注意不要用sudo npm install -g在 macOS 和 Linux 上装全局包容易造成权限混乱。正确做法是配置一个用户级的全局目录或者用 nvm 这类版本管理工具来管理 Node.js。3.2 YAML 文件的基本写法YAML 的语法看着简单但有几个地方特别容易写错。第一是缩进必须用空格不能用 Tab而且同一层级缩进要一致。第二是冒号后面要跟一个空格key: value是对的key:value在某些解析器里会被当成一个整体。第三是字符串如果包含特殊字符最好用引号包起来单引号双引号都行但双引号里支持转义。一个典型的 openrig 配置大概长这样profiles: local: provider: local base_url: http://127.0.0.1:1234 api_key: not-needed model: local-model remote: provider: compatible base_url: https://api.example.com api_key: your-key-here model: gpt-5.6-sol default_profile: local这个结构里profiles下面挂了两个档位每个档位有自己的base_url、api_key和model。default_profile指定默认用哪个。你实际拿到的配置字段名可能不一样但思路是相通的把变化的部分抽出来用键值对描述。3.3 安装 openrig 或同类工具如果 openrig 是以 npm 包的形式发布安装命令通常是npm install -g openrig。装完之后用openrig --help看它支持哪些子命令。常见的子命令包括init生成初始配置、use切换档位、apply把配置写入目标工具、list列出所有档位。如果它不是 npm 包而是一个仓库那就先git clone下来然后npm install装依赖再用node直接跑入口文件。安装过程中如果遇到网络问题导致包下载失败可以换一个 npm 镜像源。命令是npm config set registry https://registry.npmmirror.com这个镜像在国内访问速度比较稳定。装完之后如果想换回官方源把 registry 设回https://registry.npmjs.org就行。4. 核心配置解析与实操要点4.1 端点与模型名称的对应关系配置里最容易出错的地方是端点路径和模型名称的匹配。Claude Code 和 Codex 对端点的要求不一样。Claude Code 通常期望一个兼容 Anthropic 接口的端点而 Codex 走的是另一套约定处理/responses这类路径时有自己的逻辑。如果你把 Claude Code 的端点直接填给 Codex很可能报cc switch local proxy failed while handling codex endpoint /responses这类错误。模型名称也是同理。Codex 对模型名有校验像gpt-5.6-sol这种不在支持列表里的名字会直接报the gpt-5.6-sol model is not supported when using codex。解决办法是查一下你用的端点支持哪些模型名填一个明确支持的。如果你用的是第三方兼容端点通常它的文档里会列出可用模型名照着填就行。工具端点特征模型名校验常见报错Claude Code兼容 Anthropic 接口相对宽松端点不通、密钥无效Codex自有端点约定含/responses严格有支持列表模型不支持、端点处理失败4.2 环境变量注入的时机openrig 这类工具在“切换档位”时通常要做一件事把 YAML 里的配置转换成目标工具能识别的环境变量或配置文件。这里有个时机问题。如果你是在当前 shell 里直接跑 Claude Code那环境变量需要在启动 Claude Code 之前就设好。如果 openrig 是通过生成一个包装脚本来实现那这个脚本里会先export变量再调用目标命令。实操中我建议用“生成配置文件”而不是“改当前 shell 环境变量”的方式。原因是改当前 shell 的环境变量只对当前会话有效新开一个终端就没了容易让人困惑“为什么昨天能用今天不行”。生成配置文件则是持久化的目标工具每次启动都会读行为一致。4.3 多档位切换的实操心得我自己的做法是至少保留三个档位一个local指向本地模型服务一个remote指向常用的兼容端点一个official指向官方端点。日常写代码用local速度快、不消耗额度需要更强模型的时候切remote排查问题的时候切official做对照。切换命令就是openrig use local这种一秒钟的事。这里有个细节切换之后最好验证一下当前生效的配置。可以加一个openrig current之类的命令或者直接看目标工具的配置文件内容。我踩过的坑是切换命令执行了但因为权限问题配置文件没写进去工具还在用旧配置排查了半天才发现是文件权限的事。所以切换后验证这一步不能省。提示把 YAML 配置文件纳入 Git 管理但api_key这类敏感信息不要直接写进去。可以用环境变量引用比如api_key: ${MY_API_KEY}然后在 shell 里设这个变量。这样配置文件可以放心提交。5. 完整实操流程从零到能用5.1 第一步确认 Node.js 环境可用打开终端跑node -v。如果提示命令找不到说明 Node.js 没装好或者 PATH 没配。回到第 3 节的安装步骤重新来一遍。如果版本号低于 18建议升级到 LTS 版本因为很多现代工具要求 Node.js 18 以上。升级可以用 nvm命令是nvm install --lts然后nvm use --lts。5.2 第二步安装并初始化 openrig假设是 npm 包执行npm install -g openrig。装完后跑openrig init它会在当前目录或用户目录下生成一个初始的 YAML 配置文件。打开这个文件你会看到一些示例档位。把示例里的base_url、api_key、model换成你自己的。如果你用的是本地模型服务base_url一般填http://127.0.0.1:端口号api_key随便填一个非空字符串就行本地服务通常不校验。5.3 第三步配置 Claude Code 档位在 YAML 里加一个专门给 Claude Code 用的档位。关键字段是base_url和api_key对应 Claude Code 需要的环境变量。有些实现里还会有一个tool: claude-code的标记告诉 openrig 这个档位是给谁用的。配好之后执行openrig apply claude-code它会把这套配置写入 Claude Code 能读到的位置。5.4 第四步配置 Codex 档位Codex 的档位单独配。注意model字段要填 Codex 支持的模型名别填它不认的。base_url要符合 Codex 的端点约定如果你的端点不支持/responses路径Codex 可能会报错。配好后执行openrig apply codex。如果报模型不支持就换一个模型名再试。5.5 第五步验证与切换两个工具都配好之后分别启动它们看是否能正常对话。Claude Code 启动后随便问一句Codex 同理。如果都能正常返回说明配置生效了。之后切换档位就用openrig use 档位名然后重启对应的工具。注意有些工具是启动时读配置运行中改配置不生效所以切换后要重启。# 查看当前所有档位 openrig list # 切换到 local 档 openrig use local # 把当前档位应用到 Claude Code openrig apply claude-code # 把当前档位应用到 Codex openrig apply codex6. 常见问题与排查技巧实录6.1 报错“模型不支持”怎么处理这个报错在 Codex 上最常见。原因是你填的模型名不在 Codex 的支持列表里。解决办法是查你所用端点的文档找一个明确支持的模型名。如果你用的是第三方兼容端点它可能支持很多模型但 Codex 只认其中一部分。实在找不到就先用一个已知支持的模型名测试确认链路通了再换。6.2 端点处理失败怎么排查cc switch local proxy failed while handling codex endpoint /responses这类错误说明请求打到了端点但端点不认识这个路径或这个请求格式。排查顺序是先确认base_url填对了没有多斜杠或少斜杠再确认端点本身是否支持 Codex 的请求格式最后看是不是代理层做了路径重写导致路径变了。如果是本地代理检查代理的转发规则。6.3 组织策略限制导致的订阅访问问题有些环境下会提示your organization has disabled claude subscription access for claude code意思是组织层面禁用了订阅方式的访问。这种情况通常需要用 API 密钥方式而不是订阅方式或者联系管理员确认策略。这不是配置能绕过的属于权限层面的限制。6.4 常见问题速查表现象可能原因处理方式命令找不到Node.js 未装或 PATH 未配重装 Node.js检查 PATH模型不支持模型名不在支持列表换用支持的模型名端点处理失败路径不匹配或端点不支持检查 base_url 和端点能力切换后不生效工具未重启或配置未写入重启工具检查配置文件权限安装报版本错误Node.js 版本过新或过旧换 LTS 版本订阅访问被禁组织策略限制改用 API 密钥或联系管理员6.5 我踩过的几个坑第一个坑是 YAML 缩进用了 Tab解析器直接报错但报错信息很模糊只说“解析失败”没说是哪一行。后来用了一个在线 YAML 校验工具才定位到。第二个坑是api_key里带了空格YAML 把它当成了字符串的一部分导致认证失败。第三个坑是切换档位后忘了重启工具一直以为配置没生效其实是工具还在用启动时读的旧配置。提示改完 YAML 之后先跑一遍 YAML 语法校验再执行 apply。很多工具自带openrig validate之类的命令没有的话用在线校验工具也行。这一步花十秒钟能省掉后面十分钟的排查。7. 进阶用法与扩展思路7.1 把配置纳入团队协作团队里每个人用的模型和端点可能不一样但配置结构可以统一。做法是把 YAML 里的敏感信息用环境变量占位配置文件本身提交到仓库。每个人在自己机器上设好自己的环境变量然后openrig apply一下就行。这样新人入职的时候clone 仓库、装 Node.js、设环境变量、apply四步就能跑起来不用挨个问“你那个端点怎么配的”。7.2 结合 VS Code 使用VS Code 里可以用集成终端跑 Claude Code 或 Codex。如果你在 VS Code 里装了相关插件配置读取的路径可能和独立终端不一样。这时候要确认 openrig 生成的配置文件放对了位置。有些插件会读工作区下的配置文件有些读用户目录下的具体看插件文档。我的做法是两边都配一份或者用符号链接把工作区配置指向用户目录配置避免不一致。7.3 本地模型接入的注意事项本地跑模型服务的时候base_url通常是http://127.0.0.1:端口。注意不要写成localhost有些环境下localhost解析会有问题用127.0.0.1更稳。另外本地服务的并发能力有限如果你同时开 Claude Code 和 Codex 都指向同一个本地服务可能会排队等待。这种情况可以给两个工具配不同的本地服务实例或者错开使用。7.4 配置的备份与迁移换电脑的时候YAML 配置文件直接拷过去就行但环境变量要重新设。我习惯把环境变量的设置也写成一个脚本放在配置文件旁边换机器的时候一起拷过去跑一下脚本就恢复环境。脚本里不要硬编码密钥而是从系统密钥管理或者加密文件里读这样更安全。8. 一些个人体会这套东西用下来最大的感受是“配置即代码”这个思路确实省事。以前换模型要翻半天文档现在改一行 YAML 就行。但前提是 YAML 本身要写对缩进、引号、空格这些细节不能马虎。我现在的习惯是每次改完配置先校验语法再 apply再重启工具验证三步走完才放心。另外一点是不要贪多。档位不用配太多三四个够用了。配太多自己都记不住哪个是哪个反而增加心智负担。命名也要清晰local、remote、official这种一看就懂别用a、b、c这种。最后敏感信息一定不要写进 YAML 提交到仓库用环境变量引用这是底线。 openrig 统一配置管理：Claude Code 与 Codex 模型接入实战
1. openrig 到底是个什么东西第一次看到 openrig 这个名字很多人会以为是某个硬件项目毕竟 rig 这个词在英文里本来就有“装配、设备”的意思。但如果你最近在折腾 Claude Code、Codex 这类命令行 AI 编程工具大概率已经在某些讨论里见过它。简单说openrig 是一个围绕 AI 编程助手做“统一接入与配置管理”的开源思路或工具集核心目标是把 Claude Code、Codex 这类工具的模型接入、端点配置、环境变量管理用一套相对标准化的方式管起来而不是每换一个模型就手动改一遍配置文件。它解决的问题很具体。现在用 Claude Code 的人越来越多用 Codex 的人也不少但这两套工具各自有自己的配置方式、自己的环境变量、自己的端点约定。你想让 Claude Code 走本地模型得改一套东西想让 Codex 接第三方兼容端点又得改另一套东西。来回切换的时候配置文件改来改去很容易把之前能用的配置覆盖掉最后自己也记不清哪个版本是对的。openrig 想做的就是把这层配置抽象出来用 YAML 描述“我要用哪个模型、走哪个端点、带哪些参数”然后由工具去生成或注入对应的配置。适合谁来参考这份内容三类人最合适。第一类是已经在用 Claude Code 或 Codex但每次换模型都要翻文档、改环境变量的开发者第二类是想在本地或内网环境里跑 AI 编程助手需要把端点指向自己服务的人第三类是对 Node.js 工具有一定了解愿意花半小时把配置理顺之后长期省事的人。如果你完全没接触过命令行工具也没关系我会把 Node.js 安装、YAML 怎么写这些基础环节都拆开讲。提示openrig 目前更像是一种配置管理思路的集合不同人手里的实现可能不完全一样。下面讲的是基于常见实践整理出来的通用方案你落地时以自己实际拿到的仓库说明为准。2. 为什么需要一层配置抽象2.1 Claude Code 和 Codex 各自的配置痛点Claude Code 的配置主要围绕环境变量和它自己的设置文件展开。你想让它走非默认端点通常要设置类似ANTHROPIC_BASE_URL、ANTHROPIC_API_KEY这样的变量或者写进它的配置文件里。Codex 这边则是另一套它有自己的端点约定比如处理/responses这类路径时的行为还有模型名称校验像gpt-5.6-sol这种不被支持的模型名会直接报错。两套工具的环境变量名不一样配置文件位置不一样连“模型不支持”这种报错的触发条件都不一样。痛点就在这里。你如果同时用这两个工具或者经常在“官方端点”和“第三方兼容端点”之间切换就会陷入一种重复劳动改 Claude Code 的配置测试改 Codex 的配置测试想切回去又得把之前的配置找回来。更麻烦的是有些配置是写在 shell 的启动脚本里的改错了会影响整个终端会话排查起来很费时间。2.2 用 YAML 做统一描述的好处YAML 最大的好处是可读性好而且结构清晰。你可以在一个文件里描述多个“配置档”每个档位对应一套模型和端点组合。比如一个档位叫local指向本地跑的模型服务另一个档位叫remote指向一个兼容端点。切换的时候只需要告诉工具“用 local 这个档”剩下的环境变量注入、配置文件生成都由工具完成。这种做法的另一个好处是可版本管理。你把 YAML 文件放进 Git每次改动都有记录哪天配置坏了直接回滚到上一个提交就行。相比之下手动改环境变量很难追溯改完就忘了改了什么。YAML 还能写注释你可以标注每个端点的用途、申请方式、注意事项团队协作的时候别人一看就懂。2.3 Node.js 在其中的角色openrig 这类工具大概率是用 Node.js 写的因为 Claude Code 和 Codex 本身都跟 Node.js 生态关系密切。Node.js 在这里扮演的是“运行时”的角色工具本身是一段 JavaScript 代码需要 Node.js 来执行。你安装 Node.js本质上是在给这些工具准备一个能跑起来的环境。这里有个常见的坑Node.js 版本不是越新越好。有些工具对 Node.js 版本有要求太新的版本可能还没被支持安装时会报node.js v24.21.0 is not yet released or is not available这类错误。稳妥的做法是装 LTS 版本也就是长期支持版稳定性和兼容性都更好。Node.js 官网下载页面会明确标出 LTS 版本选那个就行。3. 环境准备Node.js 与基础工具安装3.1 Node.js 安装的正确姿势Windows 用户直接去 Node.js 官网下载 LTS 版本的安装包一路下一步就行。安装完成后打开 PowerShell 或 CMD输入node -v和npm -v能看到版本号就说明装好了。macOS 用户可以用官网的 pkg 安装包也可以用 Homebrew命令是brew install nodelts。Ubuntu 用户建议用 NodeSource 的源来装比系统自带的版本新具体命令是先加源再apt install nodejs。装完之后有一个关键检查确认npm的全局安装目录在 PATH 里。Windows 上一般是%APPDATA%\npmmacOS 和 Linux 上一般是/usr/local/bin或~/.npm-global/bin。如果全局安装的工具命令找不到多半是这里没配好。你可以用npm config get prefix看当前的前缀路径然后把这个路径下的bin目录加到 PATH 里。注意不要用sudo npm install -g在 macOS 和 Linux 上装全局包容易造成权限混乱。正确做法是配置一个用户级的全局目录或者用 nvm 这类版本管理工具来管理 Node.js。3.2 YAML 文件的基本写法YAML 的语法看着简单但有几个地方特别容易写错。第一是缩进必须用空格不能用 Tab而且同一层级缩进要一致。第二是冒号后面要跟一个空格key: value是对的key:value在某些解析器里会被当成一个整体。第三是字符串如果包含特殊字符最好用引号包起来单引号双引号都行但双引号里支持转义。一个典型的 openrig 配置大概长这样profiles: local: provider: local base_url: http://127.0.0.1:1234 api_key: not-needed model: local-model remote: provider: compatible base_url: https://api.example.com api_key: your-key-here model: gpt-5.6-sol default_profile: local这个结构里profiles下面挂了两个档位每个档位有自己的base_url、api_key和model。default_profile指定默认用哪个。你实际拿到的配置字段名可能不一样但思路是相通的把变化的部分抽出来用键值对描述。3.3 安装 openrig 或同类工具如果 openrig 是以 npm 包的形式发布安装命令通常是npm install -g openrig。装完之后用openrig --help看它支持哪些子命令。常见的子命令包括init生成初始配置、use切换档位、apply把配置写入目标工具、list列出所有档位。如果它不是 npm 包而是一个仓库那就先git clone下来然后npm install装依赖再用node直接跑入口文件。安装过程中如果遇到网络问题导致包下载失败可以换一个 npm 镜像源。命令是npm config set registry https://registry.npmmirror.com这个镜像在国内访问速度比较稳定。装完之后如果想换回官方源把 registry 设回https://registry.npmjs.org就行。4. 核心配置解析与实操要点4.1 端点与模型名称的对应关系配置里最容易出错的地方是端点路径和模型名称的匹配。Claude Code 和 Codex 对端点的要求不一样。Claude Code 通常期望一个兼容 Anthropic 接口的端点而 Codex 走的是另一套约定处理/responses这类路径时有自己的逻辑。如果你把 Claude Code 的端点直接填给 Codex很可能报cc switch local proxy failed while handling codex endpoint /responses这类错误。模型名称也是同理。Codex 对模型名有校验像gpt-5.6-sol这种不在支持列表里的名字会直接报the gpt-5.6-sol model is not supported when using codex。解决办法是查一下你用的端点支持哪些模型名填一个明确支持的。如果你用的是第三方兼容端点通常它的文档里会列出可用模型名照着填就行。工具端点特征模型名校验常见报错Claude Code兼容 Anthropic 接口相对宽松端点不通、密钥无效Codex自有端点约定含/responses严格有支持列表模型不支持、端点处理失败4.2 环境变量注入的时机openrig 这类工具在“切换档位”时通常要做一件事把 YAML 里的配置转换成目标工具能识别的环境变量或配置文件。这里有个时机问题。如果你是在当前 shell 里直接跑 Claude Code那环境变量需要在启动 Claude Code 之前就设好。如果 openrig 是通过生成一个包装脚本来实现那这个脚本里会先export变量再调用目标命令。实操中我建议用“生成配置文件”而不是“改当前 shell 环境变量”的方式。原因是改当前 shell 的环境变量只对当前会话有效新开一个终端就没了容易让人困惑“为什么昨天能用今天不行”。生成配置文件则是持久化的目标工具每次启动都会读行为一致。4.3 多档位切换的实操心得我自己的做法是至少保留三个档位一个local指向本地模型服务一个remote指向常用的兼容端点一个official指向官方端点。日常写代码用local速度快、不消耗额度需要更强模型的时候切remote排查问题的时候切official做对照。切换命令就是openrig use local这种一秒钟的事。这里有个细节切换之后最好验证一下当前生效的配置。可以加一个openrig current之类的命令或者直接看目标工具的配置文件内容。我踩过的坑是切换命令执行了但因为权限问题配置文件没写进去工具还在用旧配置排查了半天才发现是文件权限的事。所以切换后验证这一步不能省。提示把 YAML 配置文件纳入 Git 管理但api_key这类敏感信息不要直接写进去。可以用环境变量引用比如api_key: ${MY_API_KEY}然后在 shell 里设这个变量。这样配置文件可以放心提交。5. 完整实操流程从零到能用5.1 第一步确认 Node.js 环境可用打开终端跑node -v。如果提示命令找不到说明 Node.js 没装好或者 PATH 没配。回到第 3 节的安装步骤重新来一遍。如果版本号低于 18建议升级到 LTS 版本因为很多现代工具要求 Node.js 18 以上。升级可以用 nvm命令是nvm install --lts然后nvm use --lts。5.2 第二步安装并初始化 openrig假设是 npm 包执行npm install -g openrig。装完后跑openrig init它会在当前目录或用户目录下生成一个初始的 YAML 配置文件。打开这个文件你会看到一些示例档位。把示例里的base_url、api_key、model换成你自己的。如果你用的是本地模型服务base_url一般填http://127.0.0.1:端口号api_key随便填一个非空字符串就行本地服务通常不校验。5.3 第三步配置 Claude Code 档位在 YAML 里加一个专门给 Claude Code 用的档位。关键字段是base_url和api_key对应 Claude Code 需要的环境变量。有些实现里还会有一个tool: claude-code的标记告诉 openrig 这个档位是给谁用的。配好之后执行openrig apply claude-code它会把这套配置写入 Claude Code 能读到的位置。5.4 第四步配置 Codex 档位Codex 的档位单独配。注意model字段要填 Codex 支持的模型名别填它不认的。base_url要符合 Codex 的端点约定如果你的端点不支持/responses路径Codex 可能会报错。配好后执行openrig apply codex。如果报模型不支持就换一个模型名再试。5.5 第五步验证与切换两个工具都配好之后分别启动它们看是否能正常对话。Claude Code 启动后随便问一句Codex 同理。如果都能正常返回说明配置生效了。之后切换档位就用openrig use 档位名然后重启对应的工具。注意有些工具是启动时读配置运行中改配置不生效所以切换后要重启。# 查看当前所有档位 openrig list # 切换到 local 档 openrig use local # 把当前档位应用到 Claude Code openrig apply claude-code # 把当前档位应用到 Codex openrig apply codex6. 常见问题与排查技巧实录6.1 报错“模型不支持”怎么处理这个报错在 Codex 上最常见。原因是你填的模型名不在 Codex 的支持列表里。解决办法是查你所用端点的文档找一个明确支持的模型名。如果你用的是第三方兼容端点它可能支持很多模型但 Codex 只认其中一部分。实在找不到就先用一个已知支持的模型名测试确认链路通了再换。6.2 端点处理失败怎么排查cc switch local proxy failed while handling codex endpoint /responses这类错误说明请求打到了端点但端点不认识这个路径或这个请求格式。排查顺序是先确认base_url填对了没有多斜杠或少斜杠再确认端点本身是否支持 Codex 的请求格式最后看是不是代理层做了路径重写导致路径变了。如果是本地代理检查代理的转发规则。6.3 组织策略限制导致的订阅访问问题有些环境下会提示your organization has disabled claude subscription access for claude code意思是组织层面禁用了订阅方式的访问。这种情况通常需要用 API 密钥方式而不是订阅方式或者联系管理员确认策略。这不是配置能绕过的属于权限层面的限制。6.4 常见问题速查表现象可能原因处理方式命令找不到Node.js 未装或 PATH 未配重装 Node.js检查 PATH模型不支持模型名不在支持列表换用支持的模型名端点处理失败路径不匹配或端点不支持检查 base_url 和端点能力切换后不生效工具未重启或配置未写入重启工具检查配置文件权限安装报版本错误Node.js 版本过新或过旧换 LTS 版本订阅访问被禁组织策略限制改用 API 密钥或联系管理员6.5 我踩过的几个坑第一个坑是 YAML 缩进用了 Tab解析器直接报错但报错信息很模糊只说“解析失败”没说是哪一行。后来用了一个在线 YAML 校验工具才定位到。第二个坑是api_key里带了空格YAML 把它当成了字符串的一部分导致认证失败。第三个坑是切换档位后忘了重启工具一直以为配置没生效其实是工具还在用启动时读的旧配置。提示改完 YAML 之后先跑一遍 YAML 语法校验再执行 apply。很多工具自带openrig validate之类的命令没有的话用在线校验工具也行。这一步花十秒钟能省掉后面十分钟的排查。7. 进阶用法与扩展思路7.1 把配置纳入团队协作团队里每个人用的模型和端点可能不一样但配置结构可以统一。做法是把 YAML 里的敏感信息用环境变量占位配置文件本身提交到仓库。每个人在自己机器上设好自己的环境变量然后openrig apply一下就行。这样新人入职的时候clone 仓库、装 Node.js、设环境变量、apply四步就能跑起来不用挨个问“你那个端点怎么配的”。7.2 结合 VS Code 使用VS Code 里可以用集成终端跑 Claude Code 或 Codex。如果你在 VS Code 里装了相关插件配置读取的路径可能和独立终端不一样。这时候要确认 openrig 生成的配置文件放对了位置。有些插件会读工作区下的配置文件有些读用户目录下的具体看插件文档。我的做法是两边都配一份或者用符号链接把工作区配置指向用户目录配置避免不一致。7.3 本地模型接入的注意事项本地跑模型服务的时候base_url通常是http://127.0.0.1:端口。注意不要写成localhost有些环境下localhost解析会有问题用127.0.0.1更稳。另外本地服务的并发能力有限如果你同时开 Claude Code 和 Codex 都指向同一个本地服务可能会排队等待。这种情况可以给两个工具配不同的本地服务实例或者错开使用。7.4 配置的备份与迁移换电脑的时候YAML 配置文件直接拷过去就行但环境变量要重新设。我习惯把环境变量的设置也写成一个脚本放在配置文件旁边换机器的时候一起拷过去跑一下脚本就恢复环境。脚本里不要硬编码密钥而是从系统密钥管理或者加密文件里读这样更安全。8. 一些个人体会这套东西用下来最大的感受是“配置即代码”这个思路确实省事。以前换模型要翻半天文档现在改一行 YAML 就行。但前提是 YAML 本身要写对缩进、引号、空格这些细节不能马虎。我现在的习惯是每次改完配置先校验语法再 apply再重启工具验证三步走完才放心。另外一点是不要贪多。档位不用配太多三四个够用了。配太多自己都记不住哪个是哪个反而增加心智负担。命名也要清晰local、remote、official这种一看就懂别用a、b、c这种。最后敏感信息一定不要写进 YAML 提交到仓库用环境变量引用这是底线。