openrig 配置编排指南：统一管理 Claude Code 与 Codex 的模型接入

1. openrig 到底是个什么东西第一次看到 openrig 这个名字我下意识以为是某个硬件外设或者开源机械臂项目毕竟 rig 这个词在工程领域通常跟“装配、支架、设备”挂钩。但把 openrig 和 Claude Code、Codex、YAML、Node.js 这几个词放在一起看方向就清楚了——这是一个围绕 AI 编程助手做配置编排、环境搭建和模型接入的工具或配置方案集合。说白了openrig 解决的是这么一件事当你手头同时有 Claude Code、Codex 这类命令行 AI 编程工具又想让它们接入不同的模型后端本地模型、第三方 API、官方服务你需要一套统一、可维护、可复用的配置骨架而不是每次手动改一堆散落的配置文件。我接触这类需求是从去年开始密集起来的。那时候团队里几个人各用各的工具有人用 Claude Code 写代码有人用 Codex 跑补全还有人折腾本地模型。问题很快就暴露了每个人的配置散落在不同的目录换台机器就得重新配一遍模型切换靠手改 JSON 或者环境变量改错了还找不到原因。openrig 这类方案的价值就在于把“配置”这件事工程化——用 YAML 描述你的工具链和模型路由用 Node.js 做运行时支撑把 Claude Code、Codex 这些工具的接入方式标准化。它适合谁三类人最该关注。第一类是重度使用 AI 编程助手的开发者手里不止一个工具需要统一管理第二类是想把本地模型或第三方模型接进 Claude Code、Codex 的人需要一套清晰的配置模板第三类是团队里负责搭建开发环境的人需要让配置可复制、可版本控制。哪怕你只是刚装完 Node.js、正准备装 Claude Code 的新手理解 openrig 的思路也能帮你少走很多弯路因为它的核心逻辑就是“把零散的配置收拢成一份可读的 YAML”。我先把话说在前面openrig 不是一个点一下就能用的图形化软件它更像一套约定和骨架。你得理解 YAML 怎么写、Node.js 环境怎么配、Claude Code 和 Codex 各自的配置入口在哪才能真正把它用起来。下面我会从设计思路、核心细节、实操过程到问题排查一层层拆开讲尽量让刚入门的人也能跟上。2. 整体设计思路与方案选型拆解2.1 为什么用 YAML 做配置载体配置格式的选择看着是小事实际上决定了这套方案好不好维护。openrig 选 YAML 而不是 JSON 或 TOML我认为有三个很实际的理由。第一YAML 支持注释。你在配置模型路由的时候往往需要标注“这个 key 从哪申请的”“这个模型什么时候切换的”“为什么这里超时设成 60 秒”。JSON 不支持注释你只能另开一个文档记时间一长文档和配置就对不上了。YAML 的#注释让配置本身自带说明这对多人协作和长期维护太重要了。第二YAML 的层级结构更贴近人的阅读习惯。Claude Code 和 Codex 的配置往往涉及嵌套结构比如“工具 - 模型提供商 - 具体模型 - 参数”。YAML 用缩进表达层级视觉上一目了然而 JSON 那一堆花括号和引号在配置长了之后非常容易看花眼。第三YAML 对多行字符串和列表的处理更自然。比如你要配置多个模型后端做 fallbackYAML 的列表写法干净利落改起来不容易出错。注意YAML 对缩进极其敏感Tab 和空格混用是最常见的报错来源。我踩过的坑是复制粘贴别人的配置时编辑器自动把空格转成了 Tab结果解析直接失败报错信息还特别含糊。建议统一用两个空格缩进并在编辑器里开启“显示空白字符”。2.2 Node.js 在整套方案里扮演什么角色很多人会问配置而已为什么还要 Node.js直接用 shell 脚本不行吗这里要理解 openrig 的定位——它不只是静态配置还涉及运行时行为比如启动代理、转发请求、加载不同模型的适配层。Claude Code 和 Codex 本身都是基于 Node.js 生态分发的命令行工具它们的安装、运行、插件机制都依赖 Node.js 运行时。具体来说Node.js 在这里承担了几个职责。一是作为 Claude Code 和 Codex 的运行环境这两个工具通过 npm 全局安装没有 Node.js 根本跑不起来。二是作为配置加载和校验的运行时openrig 的配置在生效前往往需要经过解析、合并、环境变量替换等处理这些用 Node.js 脚本做最顺手。三是作为本地代理服务的载体当你要把 Claude Code 的请求转发到本地模型或第三方接口时中间那层代理通常就是一个 Node.js 进程。选 Node.js 而不是 Python 或 Go核心原因是生态一致性。Claude Code、Codex 都是 Node 生态的工具用同一套运行时能避免很多版本冲突和依赖管理问题。你不需要为了配置再单独装一个 Python 环境。2.3 统一编排 Claude Code 与 Codex 的接入逻辑openrig 最有价值的设计是把 Claude Code 和 Codex 这两个原本各自独立的工具用一套配置逻辑统一起来。这两个工具的配置方式其实差别不小Claude Code 有自己的配置目录和设置项Codex 也有自己的配置文件和模型声明方式。如果各配各的切换模型时你得改两个地方很容易漏。openrig 的思路是抽象出一层“模型提供商”的概念把 API 地址、密钥、模型名称、请求参数这些共性信息集中定义然后让 Claude Code 和 Codex 分别引用。这样你换一个模型后端只需要改一处两个工具同时生效。这个设计的好处在实际使用中非常明显——我试过同时维护五六个模型配置如果每个工具单独改一次切换要动十几个地方出错概率极高集中管理之后改一个字段就够了。2.4 方案选型的取舍与边界任何方案都有边界openrig 也不例外。它适合的是“配置驱动”的场景也就是你的工具链相对稳定主要痛点在配置管理。如果你的需求是频繁动态切换、需要图形界面、或者团队里有人完全不碰命令行那这套方案的学习成本就偏高了。另外要明确一点openrig 本身不提供模型能力它只是把请求路由到你已经有的模型服务上。你得先有可用的模型接口——不管是官方的、第三方的还是本地部署的——openrig 负责的是“怎么接、怎么管、怎么切”。这个边界想清楚了你就不会对它有不切实际的期待。3. 核心细节解析与实操要点3.1 环境准备Node.js 安装的正确姿势一切从 Node.js 开始。这一步看着简单但热词里那个error installing 24.21.0: node.js v24.21.0 is not yet released的报错说明很多人在这里就卡住了。这个错误的本质是你指定的版本号根本不存在可能是抄了别人的命令但版本号写错了也可能是某个工具内部硬编码了一个不存在的版本。正确的做法是去 Node.js 官网下载 LTS 版本。LTS 是长期支持版稳定性和兼容性都经过验证不要盲目追最新的 Current 版。截至我写这篇内容时Node.js 20.x 和 22.x 的 LTS 都是稳妥选择。安装方式上Windows 用户直接下.msi安装包一路下一步即可macOS 用户可以用官方.pkg或者包管理器Linux 用户建议用 NodeSource 的源或者版本管理工具。安装完成后必须验证这一步别省node -v npm -v两条命令都要能正常输出版本号。如果node -v有输出但npm -v报错说明 npm 没装上或者 PATH 有问题。我遇到过 Windows 上装了 Node 但 npm 命令找不到的情况原因是安装时没勾选“添加到 PATH”重新装一遍勾上就好。提示如果你需要在多个 Node.js 版本之间切换比如不同项目要求不同版本建议用 nvmNode Version Manager。它能让你一条命令切换版本避免全局环境被污染。但注意 nvm 在 Windows 上要用 nvm-windows命令和 Unix 版略有差异。3.2 Claude Code 的安装与配置入口Node.js 就绪后Claude Code 的安装通常通过 npm 全局安装完成。安装命令的形式是npm install -g加上对应的包名。装完之后你需要找到它的配置目录。不同操作系统下配置位置不一样Windows 一般在用户目录下的隐藏文件夹macOS 和 Linux 在~/.开头的目录里。配置 Claude Code 时有几个关键点。第一是认证方式它支持订阅账号登录也支持 API key 方式。热词里那个your organization has disabled claude subscription access for claude code的报错就是组织层面禁用了订阅访问这种情况下你只能走 API key 或者换用其他模型后端。第二是模型选择Claude Code 默认用官方模型但通过配置可以指向其他兼容接口。在 VS Code 里配置 Claude Code 是很多人的选择。你需要装对应的扩展然后在扩展设置里填入配置路径或者直接填参数。这里有个细节VS Code 扩展读的配置和命令行读的配置可能不是同一份改完记得确认两边是否一致。我踩过的坑是命令行里配好了VS Code 里还是旧的排查半天才发现是两份配置。3.3 Codex 的安装与模型接入Codex 的安装同样是 npm 全局安装的路子。装完后它的配置入口和 Claude Code 不同需要单独处理。Codex 的配置里比较关键的是模型声明部分你要告诉它用哪个模型、走哪个接口。热词里出现的the gpt-5.6-sol model is not supported when using codex这类报错本质是模型名称写错了或者该模型不被当前 Codex 版本支持。模型名称必须和提供方文档里写的完全一致大小写、连字符都不能错。另一个常见问题是codex无法加载组织设置这通常和认证状态或网络请求有关需要检查登录态是否有效。Codex 接入第三方模型比如 DeepSeek、Qwen、GLM 这些时核心是配置一个兼容的 API 端点。很多第三方服务提供 OpenAI 兼容接口Codex 可以通过改 base URL 和模型名来接入。这里要注意接口的路径拼接规则有的服务要求/v1后缀有的不要配错了就是 404。3.4 YAML 配置文件的编写规范openrig 的配置核心就是那份 YAML。我建议按下面的结构组织这是我在多个项目里验证过比较清晰的写法# openrig 配置示例 version: 1 providers: local: base_url: http://127.0.0.1:1234/v1 api_key: local-key models: - name: local-model-a context_window: 32768 remote: base_url: https://api.example.com/v1 api_key: ${REMOTE_API_KEY} models: - name: remote-model-b context_window: 128000 tools: claude_code: provider: remote model: remote-model-b timeout: 60 codex: provider: local model: local-model-a timeout: 30几个编写要点。第一api_key尽量用环境变量引用${VAR_NAME}形式不要把密钥明文写进配置文件尤其是要提交到版本控制的时候。第二context_window这类参数要按模型实际能力填填大了会导致请求被拒填小了浪费能力。第三timeout要结合模型响应速度设本地模型慢就设大点远程快可以设小点。注意YAML 里的布尔值true/false、数字、字符串有隐式类型转换。比如version: 1.0会被解析成浮点数如果你期望的是字符串1.0就得加引号。这种坑在配置校验不严的时候很难发现。3.5 模型路由与切换的配置逻辑openrig 最实用的功能就是模型切换。你可以在配置里定义多个 provider然后通过改tools下面的provider字段来切换。更进一步可以配置 fallback 链——主模型不可用时自动切到备用模型。实现 fallback 的思路是在配置里加一个优先级列表运行时按顺序尝试。这个逻辑用 Node.js 脚本实现比较自然读取配置依次请求第一个成功的就用。要注意的是 fallback 的触发条件要明确是超时触发、报错触发还是特定状态码触发不同条件对应不同的用户体验。切换模型时还有一个容易忽略的点不同模型的 prompt 格式和参数可能不同。有的模型对 system prompt 敏感有的对 temperature 有特定要求。openrig 的配置里可以给每个模型单独设参数这样切换时不用手动调。4. 实操过程与核心环节实现4.1 从零搭建 openrig 环境的完整流程我把整个搭建过程拆成可复现的步骤你照着走一遍就能跑通。第一步装 Node.js LTS。去官网下载对应系统的安装包装完用node -v和npm -v验证。这一步的验收标准是两条命令都有正常版本输出。第二步全局安装 Claude Code 和 Codex。分别执行对应的 npm 全局安装命令。装完后用各自的版本查询命令确认安装成功。如果提示命令找不到检查 npm 全局 bin 目录是否在 PATH 里。第三步创建 openrig 配置目录。我习惯放在用户目录下的一个统一位置比如~/.openrig/。在里面创建config.yaml按上一节的结构填入你的 provider 和 tools 配置。第四步配置环境变量。把 API key 这类敏感信息放到环境变量里配置文件用${VAR}引用。Windows 用系统环境变量设置界面macOS/Linux 在 shell 配置文件里 export。第五步写一个加载脚本。用 Node.js 读 YAML、替换环境变量、生成各工具需要的最终配置。这个脚本是 openrig 的“执行引擎”它把统一配置翻译成 Claude Code 和 Codex 各自认识的格式。第六步验证。启动 Claude Code 和 Codex各发一个测试请求确认能正常返回。如果某个工具报错回到对应章节排查。4.2 用 Node.js 脚本加载和校验 YAML 配置加载脚本是整个方案的中枢我给出一个可参考的实现思路。核心逻辑分三步读文件、解析、校验。const fs require(fs); const path require(path); const yaml require(js-yaml); function loadConfig(configPath) { const raw fs.readFileSync(configPath, utf8); // 替换环境变量 const replaced raw.replace(/\$\{(\w)\}/g, (_, name) { const val process.env[name]; if (val undefined) { throw new Error(环境变量 ${name} 未设置); } return val; }); const config yaml.load(replaced); validateConfig(config); return config; } function validateConfig(config) { if (!config.providers || Object.keys(config.providers).length 0) { throw new Error(至少需要配置一个 provider); } for (const [name, p] of Object.entries(config.providers)) { if (!p.base_url) throw new Error(provider ${name} 缺少 base_url); if (!p.models || p.models.length 0) { throw new Error(provider ${name} 没有配置模型); } } }这段代码的关键设计是环境变量替换放在 YAML 解析之前。为什么因为如果先解析再替换YAML 里如果有特殊字符比如密钥里带冒号解析就会出错。先做字符串替换让 YAML 看到的是已经填好的值解析更稳。校验函数的作用是提前暴露配置错误。我见过太多人配置写错了等到工具运行时报一堆看不懂的错排查半天。有了校验配置阶段就能告诉你“哪个 provider 缺了什么字段”定位效率高很多。4.3 把 Claude Code 接到本地模型的实操记录把 Claude Code 接到本地模型是很多人的核心诉求热词里claude code 调用lmstudio的本地模型就是这个场景。我完整走一遍。前提是你本地已经跑起来一个提供 OpenAI 兼容接口的模型服务比如 LM Studio 或者类似的本地推理工具。它会监听一个本地端口通常是http://127.0.0.1:1234这种形式。第一步确认本地服务可用。用 curl 测一下curl http://127.0.0.1:1234/v1/models能返回模型列表就说明服务正常。如果连不上先解决本地服务的问题别急着配 Claude Code。第二步在 openrig 配置里加一个 local providerbase_url 指向本地服务模型名填本地服务里实际加载的模型名。第三步让 Claude Code 使用这个 provider。具体方式取决于 Claude Code 的配置机制通常是通过环境变量或者配置文件指定 base URL 和模型。这里要注意 Claude Code 可能对接口格式有特定要求本地服务如果只是“大致兼容”OpenAI 格式可能会有字段缺失导致报错。第四步测试。发一个简单请求观察本地服务的日志确认请求确实打到了本地。如果 Claude Code 报错但本地服务没收到请求说明配置没生效如果本地服务收到了但返回错误说明接口格式不匹配。提示本地模型的上下文窗口通常比云端模型小配置里context_window要如实填写。填大了 Claude Code 会发超长请求本地服务直接拒绝或者截断表现就是“莫名其妙没响应”。4.4 Codex 接入第三方模型的配置细节Codex 接入第三方模型DeepSeek、Qwen、GLM 等的流程和 Claude Code 类似但配置入口不同。核心是找到 Codex 的配置文件改里面的模型端点和模型名。以接入一个 OpenAI 兼容的第三方服务为例你需要配置三项base URL、API key、模型名。base URL 要精确到版本路径比如https://api.example.com/v1。API key 走环境变量。模型名必须和服务商文档完全一致。这里有个高频坑第三方服务的接口路径拼接。有的服务 base URL 填到域名就行它自己会加/v1/chat/completions有的要求你填到/v1。填错了就是 404 或者 405。我的经验是先看服务商文档里的 curl 示例照着示例反推 base URL 该填到哪一层。另一个坑是模型名的大小写和连字符。deepseek-chat和DeepSeek-Chat在某些服务上是不等价的。配置时直接从服务商的模型列表里复制别手打。4.5 配置生效验证与快速自检清单配置改完别急着用先跑一遍自检。我整理了一个清单按顺序过一遍能挡掉大部分低级错误。检查项验证方法常见问题Node.js 环境node -v有输出版本过低或 PATH 未配npm 全局包npm list -g --depth0工具没装上YAML 语法用解析器加载一次缩进错误、Tab 混用环境变量echo $VAR_NAME变量名拼错、未 export本地服务curl 测接口服务没启动、端口占用模型名对照服务商文档大小写、连字符错误接口路径看 curl 示例多填或少填/v1超时设置结合模型速度设太短导致频繁超时这张表我建议打印出来贴在显示器边上每次配新环境照着过一遍能省下大量排查时间。5. 常见问题与排查技巧实录5.1 安装阶段的典型报错与解决安装阶段最烦人的就是版本相关报错。error installing 24.21.0: node.js v24.21.0 is not yet released这个错误的根源是版本号不存在。解决办法很简单去官网看当前实际发布的版本用真实存在的 LTS 版本号。别信任何来源不明的“推荐版本号”以官网为准。另一个常见问题是权限。Linux 和 macOS 上全局安装 npm 包有时会报权限错误这是因为全局目录需要管理员权限。解决方案有两个一是用sudo不推荐容易搞乱权限二是配置 npm 的用户级全局目录。我推荐后者一劳永逸。Windows 上还可能遇到“命令不是内部或外部命令”这基本就是 PATH 问题。找到 npm 全局 bin 目录手动加到系统 PATH 里。5.2 配置加载失败的排查思路配置加载失败时第一步永远是确认 YAML 语法正确。用一个独立的解析命令测一下别在完整流程里猜。如果解析报错看报错的行号大概率是缩进或者特殊字符问题。第二步确认环境变量都设置了。我写过一个脚本专门列出配置里引用的所有环境变量然后逐个检查是否存在。这个脚本帮我省了无数次“明明配了却读不到”的排查。第三步确认配置结构符合预期。有时候 YAML 解析成功了但结构和你以为的不一样比如某个字段被解析成了字符串而不是对象。打印出解析后的对象看一眼比盯着 YAML 猜快得多。5.3 模型请求失败的定位方法模型请求失败分几类。第一类是连接失败请求根本没到服务端。这通常是 base URL 或端口错了或者服务没启动。用 curl 直接测同一个地址能快速区分是配置问题还是服务问题。第二类是认证失败返回 401 或 403。检查 API key 是否正确、是否过期、是否有权限访问该模型。热词里your organization has disabled claude subscription access就是权限层面的问题这种只能换认证方式或换服务。第三类是模型不存在返回 404 或类似错误。检查模型名拼写对照服务商文档。第四类是超时。本地模型尤其容易超时因为推理速度受硬件限制。把 timeout 调大或者换更小的模型。5.4 工具间配置冲突的处理同时用 Claude Code 和 Codex 时配置冲突是隐蔽的坑。比如两个工具都读某个环境变量但期望的值不同。或者两个工具的配置目录有重叠改了一个影响了另一个。处理原则是隔离。给每个工具独立的配置命名空间环境变量加前缀区分比如CC_开头给 Claude CodeCODEX_开头给 Codex。openrig 的配置里通过 tools 下面的分节来隔离加载脚本生成配置时分别输出到不同位置。如果发现改了 A 工具的配置导致 B 工具异常先检查两者是否共享了某个配置文件或环境变量。共享是冲突的根源隔离是解决的根本。5.5 高频问题速查表现象可能原因排查动作命令找不到PATH 未配检查全局 bin 目录YAML 解析失败缩进/Tab显示空白字符检查环境变量读不到未 exportecho 验证请求 404路径或模型名错对照文档请求 401密钥问题检查 key 有效性请求超时模型慢或 timeout 小调大 timeout本地服务无响应服务未启动curl 测试切换模型无效配置未重载重启工具或重载配置组织设置加载失败认证态失效重新登录模型不支持版本或名称错核对支持列表这张表覆盖了我实际遇到过的绝大多数问题。遇到新问题时先往这几类里套能快速缩小范围。5.6 我踩过的几个印象深刻的坑第一个坑是 YAML 里的冒号。API key 里如果带冒号不加引号的话 YAML 会把它当成键值分隔符直接解析错误。解决办法是给所有可能含特殊字符的值加引号。这个坑我排查了快一个小时因为报错信息指向的行号是错的。第二个坑是本地模型的上下文窗口。我一开始按云端模型的标准填了 128k结果本地服务实际只支持 32k请求发过去直接被拒。后来改成如实填写问题消失。教训是配置参数要基于实际能力不能想当然。第三个坑是环境变量的作用域。我在一个终端窗口里 export 了变量换了个窗口就没了。后来把 export 写进 shell 配置文件才彻底解决。如果你用 IDE 内置终端还要注意 IDE 是否继承了系统环境变量。第四个坑是配置缓存。有的工具会缓存配置改完文件不重启不生效。我一度以为配置写错了反复检查最后发现是没重启。现在的习惯是改完配置先重启工具再测试。6. 进阶玩法与扩展思路6.1 多模型 fallback 链的配置基础配置跑通后可以上 fallback。思路是在 provider 层面定义一个优先级列表运行时按顺序尝试。配置上可以这样设计routing: default: - provider: remote model: remote-model-b - provider: local model: local-model-a加载脚本按列表顺序请求第一个成功的返回。要注意 fallback 的触发条件我建议只在连接失败和超时时 fallback认证失败和模型不存在这类错误 fallback 也没用直接报错更清晰。6.2 团队协作下的配置管理团队里用 openrig配置要进版本控制。但密钥不能进。做法是配置文件里只放${VAR}引用每个人在本地环境变量里填自己的密钥。再配一份.env.example说明需要哪些变量新人照着填就行。配置变更走正常的代码评审流程。谁改了模型路由、为什么改都在提交信息里写清楚。这样出问题能快速定位是哪次变更引入的。6.3 配置模板化与快速复制如果你经常需要在新机器上搭环境可以把整套配置做成模板。把 provider 定义、tools 配置、加载脚本打包成一个目录新机器上复制过去改几个环境变量就能用。我自己的模板里还带了一个初始化脚本自动检查 Node.js 版本、安装依赖、提示缺失的环境变量进一步降低上手成本。这套东西的价值随着你管理的工具和模型数量增加而放大。一个模型两个工具的时候手动配还行五个模型三个工具的时候没有统一配置管理就是灾难。openrig 这类方案的意义就是让你在规模变大之前就把配置这件事做对。我在实际使用中最大的体会是配置管理的投入是前期一次性、后期持续省心的。刚开始花半天把 openrig 搭起来后面每次换模型、加工具、上新机器省下的时间远超那半天。而且配置集中之后出问题的概率明显下降因为所有变更都在一个地方看得见、管得住。如果你现在还在手动改散落的配置文件真的建议花点时间把这套骨架搭起来。