openrig 装配指南：Claude Code 与 Codex 多模型切换配置实战

1. openrig 到底想解决什么问题第一次看到openrig这个词我下意识把它拆成了 open rig。rig 在工程语境里通常指装配、搭建一套可运行的工作台比如影视里的灯光组、音频里的机架设备都是把一堆零散部件固定成一套稳定系统。放到 AI 编程工具这个场景里openrig要干的事情其实很直白把 Claude Code、Codex 这类命令行 AI 编程助手和本地或第三方的模型服务、YAML 配置、Node.js 运行时环境装配成一套能长期跑、能随时切换、不容易崩的工作台。为什么会有这个需求因为现在用 AI 写代码的人几乎都经历过同一个痛点今天用 Claude Code 连官方模型明天想换成 Codex 接第三方接口后天又想试试本地跑的小模型。每换一次就要重新翻配置文件、改环境变量、重装依赖稍微一个字段写错终端就甩给你一句cc switch local proxy failed while handling codex endpoint /responses然后你盯着屏幕怀疑人生。openrig的核心价值就是把这套装配过程标准化、配置化让模型切换、端点管理、环境隔离变成改几行 YAML 就能搞定的事而不是每次都要重新踩一遍安装坑。这篇文章适合三类人看第一类是刚接触 Claude Code、Codex连 Node.js 都还没装明白的新手第二类是已经在用但被多模型切换、代理转发、配置冲突折磨过的中级用户第三类是想把这套工具链固化下来做成团队可复用配置的工程化玩家。我会从环境准备、YAML 配置逻辑、模型接入、常见报错排查几个角度把openrig这套思路讲透尽量让你看完就能自己搭一套。需要先说明一点openrig目前公开的完整文档并不算多很多细节需要结合 Claude Code、Codex 本身的配置机制去推断。所以下面涉及具体配置的部分我会明确区分官方明确支持的写法和基于常见实践的合理推断你照着做的时候遇到不一致的地方以你本地实际版本为准。2. 装 Claude Code 和 Codex 之前Node.js 这关必须先过2.1 为什么这两个工具都绕不开 Node.jsClaude Code 和 Codex 的 CLI 版本本质上都是 Node.js 写的命令行程序通过 npm 全局安装。这意味着你机器上必须有一个能正常工作的 Node.js 运行时否则npm install -g这一步就会直接失败。很多人卡在第一步不是因为工具本身难而是 Node.js 装得不对。我见过最常见的错误是版本问题。比如你看到这样的报错error installing 24.21.0: node.js v24.21.0 is not yet released or is not available这说明你用的安装脚本或者某个依赖指定了一个还不存在的 Node.js 版本号。Node.js 的版本发布是有节奏的偶数版本是 LTS长期支持奇数版本是当前版当前版生命周期短不适合生产环境。装的时候优先选 LTS比如 20.x 或 22.x 系列别去追最新的奇数版。2.2 各平台安装 Node.js 的稳妥做法Windows 用户最省事的方式是去 Node.js 官网下载 LTS 的.msi安装包一路下一步就行。安装完成后打开 PowerShell敲node -v npm -v两个命令都能输出版本号说明装好了。如果node -v报不是内部或外部命令八成是安装时没勾选Add to PATH重新跑一遍安装包把那个选项勾上。macOS 用户我建议用nvmNode Version Manager来管理版本而不是直接装 pkg。原因很简单你以后可能需要在不同项目间切换 Node 版本nvm 一条命令就能切直接装的话升级很麻烦。curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash # 重新打开终端后 nvm install --lts nvm use --ltsUbuntu 用户同理用 nvm 比用apt install nodejs更可控因为系统源里的 Node.js 版本往往偏旧。装完 nvm 之后同样nvm install --lts。提示如果你公司网络对 npm 源访问慢可以换成国内镜像源npm config set registry https://registry.npmmirror.com这一步能显著减少安装超时。2.3 全局安装 Claude Code 与 Codex 的实际命令Node.js 就绪后安装本身其实很快npm install -g anthropic-ai/claude-code npm install -g openai/codex装完之后分别验证claude --version codex --version能打印版本号就说明 CLI 可用了。这里有个坑要提醒如果你之前装过旧版本最好先npm uninstall -g卸载再重装避免新旧文件混在一起导致命令行为异常。我自己就遇到过claude命令能跑但配置读不到的情况卸载重装后立刻正常。另外VS Code 用户如果想在编辑器里直接用可以装对应的扩展Claude Code for VS Code、Codex 相关扩展但扩展本质上还是调用你本地的 CLI所以 CLI 装不好扩展也用不了。先把命令行跑通再折腾编辑器集成这个顺序别搞反。3. YAML 配置文件openrig 装配思路的核心载体3.1 为什么这类工具偏爱 YAMLClaude Code、Codex 以及围绕它们做封装的工具几乎都用 YAML 作为配置格式。原因不复杂YAML 比 JSON 好读支持注释层级结构清晰适合描述模型列表端点地址环境变量这种嵌套配置。你去看很多 AI 工具链的配置文件模型定义、代理规则、路由策略基本都是 YAML 写的。一个典型的模型配置片段大概长这样models: - name: claude-sonnet provider: anthropic endpoint: https://api.anthropic.com api_key_env: ANTHROPIC_API_KEY - name: gpt-codex provider: openai endpoint: https://api.openai.com/v1 api_key_env: OPENAI_API_KEY这段配置的意思是定义两个模型条目每个条目告诉工具这个模型叫什么、走哪个服务商、请求打到哪个地址、密钥从哪个环境变量读。openrig这类工具做的事情就是读取这份 YAML然后根据你当前选中的模型把请求转发到对应端点。3.2 YAML 缩进和语法新手最容易翻车的地方YAML 对缩进极其敏感而且不允许用 Tab 缩进只能用空格。这是新手第一大坑。你从网上复制一段配置如果里面混了 Tab工具解析时会直接报错而且报错信息往往很模糊只说解析失败不告诉你哪一行有问题。我总结了几条 YAML 保命规则统一用 2 个空格缩进别用 Tab编辑器里把Tab 转空格打开。冒号后面必须跟一个空格name:claude是错的name: claude才对。字符串如果包含特殊字符比如:、#用引号包起来。列表项用-开头-后面也要有空格。注释用#但注意#在字符串里可能被误判必要时加引号。如果你不确定自己写的 YAML 对不对可以用在线 YAML 校验工具过一遍或者本地装个yamllintpip install yamllint yamllint your-config.yaml这一步能帮你提前发现 90% 的低级语法错误比等到工具报错再回头找强得多。3.3 配置文件该放哪路径优先级要搞清楚Claude Code 和 Codex 读取配置是有优先级顺序的通常是项目目录下的配置 用户主目录下的全局配置 系统级默认配置。这意味着你可以在不同项目里放不同的 YAML实现这个项目用这个模型那个项目用那个模型。常见的全局配置位置平台典型配置目录WindowsC:\Users\你的用户名\.claude\或.codex\macOS~/.claude/或~/.codex/Linux~/.claude/或~/.codex/项目级配置一般放在项目根目录文件名可能是claude.yaml、codex.yaml或者工具约定的名字。具体叫什么以你用的版本为准但思路是一样的全局放通用配置项目级放覆盖配置。注意改完配置文件后很多工具需要重启 CLI 或者重新加载才会生效。如果你改了配置发现没反应先别怀疑配置写错了退出重进一次再说。4. 多模型切换与端点转发openrig 最实用的部分4.1 为什么需要切换这件事官方模型好用但有时候你会想用第三方接口或者本地跑一个模型来省钱、保隐私。这时候就需要一个中间层把 Claude Code 或 Codex 发出的请求转发到你指定的端点。这个中间层就是openrig这类工具的核心。它解决的问题可以用一句话概括让上层工具Claude Code / Codex以为自己在跟官方服务对话实际上请求被转发到了你配置的任意兼容端点。这样你就不用改上层工具的代码只改 YAML 里的 endpoint 就行。4.2 端点配置的关键字段一个能用的端点配置通常包含这几个要素provider: name: custom-endpoint base_url: https://your-endpoint.example.com/v1 api_key: ${CUSTOM_API_KEY} model_map: claude-sonnet: your-model-name gpt-codex: your-codex-model这里model_map是关键它把上层工具请求的模型名映射到端点实际支持的模型名。因为不同服务商的模型命名不一样没有这层映射请求就会因为模型不存在被拒。我踩过的一个坑是base_url结尾带不带/v1差别很大。有些端点要求必须带/v1有些带了反而 404。判断方法很简单看端点文档给的示例请求地址照抄它的路径结构。如果文档写的是https://xxx.com/v1/chat/completions那base_url就填https://xxx.com/v1。4.3 切换失败时的典型报错与定位思路热词里出现过一个很典型的报错cc switch local proxy failed while handling codex endpoint /responses这句话拆开看cc switch是切换动作local proxy failed是本地代理失败handling codex endpoint /responses说明它在处理 Codex 的/responses端点时出了问题。可能的原因有这么几类本地代理服务没启动或者端口被占用。端点地址配错请求打到了一个不存在的路径。密钥无效或过期端点返回 401/403。请求格式和端点期望的格式不匹配比如端点只支持/chat/completions但工具发的是/responses。排查顺序我建议这样先确认代理进程在跑netstat或lsof看端口再用curl手动打一次端点确认端点和密钥本身没问题最后再看工具的日志定位是转发环节还是端点环节出错。这个从外到内的排查思路比一上来就翻工具源码高效得多。5. 那些让人抓狂的报错其实都有迹可循5.1 组织已禁用订阅访问这类权限问题有人会遇到这样的提示your organization has disabled claude subscription access for claude code这不是配置问题而是账号权限问题。通常出现在用企业或团队账号登录的场景管理员在后台关闭了某个工具的访问权限。遇到这种情况自己能做的很有限要么换个人账号要么找管理员开通。别在这上面浪费时间反复改配置方向错了。5.2 模型不支持的报错怎么读{detail:the gpt-5.6-sol model is not supported when using codex with a ...}这类报错信息其实很友好它直接告诉你哪个模型不支持。问题往往出在model_map没配对或者你选的模型名端点根本不认。解决办法就是回到 YAML检查模型映射把上层请求的模型名映射到端点真实支持的模型名上。5.3 安装类报错的通用处理套路Node.js 相关的安装报错套路基本固定确认 Node.js 版本是 LTSnode -v看一眼。清 npm 缓存npm cache clean --force。换镜像源重试安装。卸载重装npm uninstall -g再npm install -g。实在不行用 nvm 换个 Node 版本再试。这五步能解决绝大多数安装问题。我自己的经验是第 3 步和第 4 步组合起来成功率最高。6. 把 openrig 思路用起来的几个实操建议6.1 配置分层别把所有东西塞一个文件我建议把配置分成三层全局层放通用模型定义和密钥引用项目层放项目专属的模型选择和端点覆盖临时层用环境变量做一次性覆盖。这样切换项目时不用改全局配置团队协作时也能各管各的。6.2 密钥永远走环境变量别写进 YAMLYAML 里写api_key: sk-xxxx是能跑但一旦这个文件被提交到代码仓库密钥就泄露了。正确做法是 YAML 里写${CUSTOM_API_KEY}真实密钥放环境变量或者.env文件并且把.env加进.gitignore。这是基本的安全习惯别偷懒。6.3 保留一份能跑通的最小配置每次调通一个新端点我都会把那份最小可用配置单独存一份标注好日期和端点信息。下次再遇到类似需求直接拿这份改比从零写快得多。这个习惯帮我省了大量重复调试的时间。6.4 日志级别调高排查问题时能救命很多工具默认日志级别比较低出错时只给一句笼统提示。排查阶段把日志级别调到 debug能看到完整的请求路径、端点地址、响应状态码。定位完问题再调回去避免日志刷屏。7. 我在这套工具链上踩过的真实坑说几个具体的。第一个坑是路径里的空格。Windows 下用户目录如果带空格某些工具解析配置路径时会出错表现是找不到配置文件。解决办法是把配置放到一个无空格路径下或者用引号把路径包起来。第二个坑是端口冲突。本地代理默认端口如果被别的程序占了代理起不来但报错信息不一定明说端口被占用。我现在的习惯是配代理前先netstat -ano | findstr 端口号Windows或lsof -i:端口号macOS/Linux确认端口空闲。第三个坑是模型名大小写。有些端点对模型名大小写敏感Claude-Sonnet和claude-sonnet会被当成两个不同的模型。配置时严格照端点文档的大小写来别凭感觉写。第四个坑是配置文件编码。YAML 文件如果存成了带 BOM 的 UTF-8某些解析器会报错。用 VS Code 保存时选UTF-8 无 BOM能避开这个问题。这些坑单看都不大但凑在一起能让你折腾一整天。把它们记下来下次遇到类似现象先往这几个方向想能省不少时间。8. 关于 openrig 后续可以怎么扩展如果你已经把基础的单模型跑通了下一步可以试试多端点负载均衡在 YAML 里配多个端点让工具按权重或轮询分发请求某个端点挂了自动切到备用。再进一步可以加请求日志和用量统计看看哪个模型用得多、哪个端点响应慢为后续优化提供依据。还有一个方向是把这套配置模板化做成团队共享的起步包。新人入职拉一份配置改几个环境变量就能跑不用再从头踩一遍安装和配置的坑。这才是openrig这类工具真正的价值所在——把个人的调试经验沉淀成可复用的工程资产。我自己现在的做法是维护一份带注释的 YAML 模板每个字段旁边写清楚这个字段干什么用、常见值有哪些、填错了会怎样。这份模板已经帮好几个同事快速上手了比口头讲一遍管用得多。如果你也在带人或者做团队工具链强烈建议你也维护这么一份。