openrig 配置编排实战：用 YAML 统一管理 Claude Code 与 Codex 多模型切换

1. openrig 到底是个什么东西第一次看到 openrig 这个名字我下意识以为是某个硬件机架项目毕竟 rig 这个词在矿机、测试台架、无线电设备里出现频率太高了。直到我在几个 Claude Code 和 Codex 的讨论串里反复撞见它才反应过来这是围绕 AI 编程助手做的一套配置编排方案。简单说openrig 解决的是一个非常具体的痛点当你同时用 Claude Code、Codex CLI 这类终端里的 AI 编程工具还要在本地模型、第三方 API、不同项目配置之间来回切换时配置文件散落各处、环境变量互相打架、YAML 写得一塌糊涂openrig 就是把这些东西收拢到一套可复用、可版本管理的结构里。它适合谁如果你只是偶尔用一下网页版的对话那确实用不上。但只要你满足下面任意一条openrig 这套思路就值得花时间研究你在终端里高频使用 Claude Code 或 Codex你需要在多个模型供应商之间切换比如官方订阅、本地 LM Studio、第三方兼容接口你有多个项目每个项目想用不同的模型和参数你受够了每次换环境都要手动改一堆配置。这些场景下openrig 提供的 YAML 驱动配置方式能省掉大量重复劳动。我先把结论摆出来openrig 本身不是一个需要你去官网下载安装的软件包它更像是一套约定俗成的配置组织方法论核心载体是 YAML 文件加 Node.js 运行时。你搜 openrig 搜不到一个独立的安装包是正常的因为它的价值在于把 Claude Code、Codex 这些工具的配置项用统一的方式管理起来。理解了这一点后面的内容才不会跑偏。很多人卡在第一步就是因为把它当成一个 npm 包去找结果自然找不到。2. 核心思路拆解为什么用 YAML 加 Node.js 这套组合2.1 为什么是 YAML 而不是 JSON 或 TOML配置格式的选择看着是小事实际用起来差别很大。Claude Code 和 Codex 的配置文件天然就是 YAML 或 JSON 风格而 openrig 选择以 YAML 为主理由很实在。JSON 不支持注释你没法在配置里写这行是给本地模型用的别删过两个月自己都忘了。TOML 虽然支持注释但嵌套结构一深就变得很难读尤其是模型参数、请求头、路由规则这种多层嵌套的场景。YAML 的优势在于缩进即层级写起来干净注释随便加而且 Claude Code 的配置文件本身就是 YAML 格式Codex 的配置也能用 YAML 表达。这意味着你不需要在脑子里做格式转换一套语法走到底。我实测下来一个中等复杂度的多模型配置YAML 版本比 JSON 版本少了将近三分之一的字符而且可读性完全不是一个级别。注意YAML 对缩进极其敏感Tab 和空格混用会直接报解析错误。建议在编辑器里把 Tab 自动转成 2 个空格这是踩过无数次坑之后的血泪经验。2.2 Node.js 在这里扮演什么角色Claude Code 和 Codex CLI 都是基于 Node.js 生态分发的安装它们的前提就是本机有可用的 Node.js 环境。openrig 的配置管理脚本、模型切换逻辑、环境变量注入基本都跑在 Node.js 上。所以你会看到热词里 node.js 安装、node.js lts 下载、node.js 官网下载这些词频繁出现这不是巧合而是整条工具链的地基。Node.js 的版本选择有讲究。我建议直接用 LTS 版本不要追最新的 Current 版本。原因很简单Claude Code 和 Codex 这类工具对 Node.js 版本有最低要求但太新的版本反而可能因为原生模块编译问题出岔子。热词里那条 error installing 24.21.0: node.js v24.21.0 is not yet released 就是典型的版本号写错或者源里还没有这个版本导致的报错。稳妥做法是去 Node.js 官网下载 LTS 版本或者用版本管理工具锁定一个经过验证的版本。2.3 openrig 要解决的核心矛盾把场景摊开看一个同时用 Claude Code 和 Codex 的开发者日常面临的矛盾有这么几个。第一是模型来源冲突Claude Code 默认走官方订阅但你可能想让它调用 LM Studio 的本地模型Codex 默认走 OpenAI但你可能想接入 DeepSeek 或 Qwen。第二是配置分散每个工具都有自己的配置文件位置改一个忘一个。第三是环境隔离公司项目和私人项目想用不同的 API 端点但环境变量是全局的。openrig 的思路是用一套 YAML 定义所有模型端点、密钥引用、路由规则然后通过 Node.js 脚本在启动 Claude Code 或 Codex 之前把对应的环境变量和配置文件准备好。这样你切换项目时只需要切换一份 YAML而不是手动改五六个地方。这个设计的好处是配置即文档你打开 YAML 就知道当前项目用什么模型、走什么端点、参数怎么设的。3. 环境搭建从零把地基打牢3.1 Node.js 安装的正确姿势不管你用 Windows、macOS 还是 UbuntuNode.js 安装都是第一步。Windows 用户直接去 Node.js 官网下载 LTS 版本的安装包一路下一步就行安装程序会自动配好环境变量。macOS 用户如果用 Homebrew一条brew install node搞定但要注意 Homebrew 默认可能装的是 Current 版本想装 LTS 得指定。Ubuntu 用户我强烈建议不要用apt install nodejs因为系统源里的版本往往偏旧用 NodeSource 的源或者 nvm 更靠谱。# Ubuntu 上用 nvm 管理 Node.js 版本推荐做法 curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash source ~/.bashrc nvm install --lts nvm use --lts node -v npm -v装完之后一定要验证node -v和npm -v都能正常输出版本号。我见过太多人装完没验证后面 Claude Code 安装报错排查半天才发现是 Node.js 根本没进 PATH。Windows 用户如果遇到node不是内部或外部命令八成是安装时没勾选Add to PATH重新跑一遍安装程序勾上就行。3.2 Claude Code 和 Codex 的安装顺序这两个工具的安装没有严格的先后依赖但我建议先装 Claude Code 再装 Codex因为 Claude Code 的安装过程会顺带验证你的 Node.js 环境是否健康。Claude Code 的安装方式根据平台略有不同Windows 上现在有桌面版和 CLI 两种形态Ubuntu 和 macOS 主要走 CLI。安装命令通常是通过 npm 全局安装装完之后用claude --version验证。Codex 的安装类似也是 npm 全局包。这里有个坑要提醒如果你之前装过旧版本的 Codex升级时最好先卸载再装不然可能出现新旧文件混在一起导致命令行为异常。热词里 codex无法加载组织设置 这类问题很多时候就是版本残留或者配置文件格式不兼容导致的。# 全局安装 Claude Code 和 Codex CLI npm install -g anthropic-ai/claude-code npm install -g openai/codex # 验证安装 claude --version codex --version提示如果 npm 全局安装速度慢或者卡住可以临时切换 npm 镜像源。但注意不要长期用来源不明的镜像装完切回来比较稳妥。3.3 目录结构规划openrig 的配置要发挥作用目录结构得先规划好。我的习惯是在用户主目录下建一个.openrig文件夹里面放全局配置和模型定义然后在每个项目根目录放一个项目级的 YAML 覆盖文件。这样全局配置管通用端点项目配置管具体参数层级清晰。~/.openrig/ ├── models.yaml # 全局模型端点定义 ├── profiles.yaml # 不同使用场景的配置组合 └── scripts/ └── launch.js # 启动时注入环境变量的脚本 your-project/ └── .openrig.yaml # 项目级覆盖配置这个结构的好处是你换电脑或者重装系统时只要把.openrig目录备份走所有模型配置就都带走了。项目级的.openrig.yaml可以跟着代码仓库走团队里其他人拉下来就能用同一套配置省掉大量沟通成本。4. YAML 配置文件怎么写才不出错4.1 模型端点定义的标准写法先看一个最基础的模型端点定义。openrig 的 YAML 里每个模型是一个条目包含名称、类型、端点地址、密钥引用和默认参数。密钥不要直接写在 YAML 里用环境变量引用这是安全底线。models: claude-official: type: anthropic endpoint: https://api.anthropic.com api_key_env: ANTHROPIC_API_KEY default_model: claude-sonnet-4-20250514 local-lmstudio: type: openai-compatible endpoint: http://localhost:1234/v1 api_key_env: LMSTUDIO_KEY default_model: local-model deepseek: type: openai-compatible endpoint: https://api.deepseek.com/v1 api_key_env: DEEPSEEK_API_KEY default_model: deepseek-chat这里的关键点是type字段。Claude Code 走的是 Anthropic 的原生协议Codex 走的是 OpenAI 兼容协议。当你让 Claude Code 调用本地 LM Studio 时实际上是通过一个兼容层把 Anthropic 格式的请求转成 OpenAI 格式这个转换逻辑就是 openrig 脚本要处理的核心。热词里 claude code 调用 lmstudio 的本地模型 和 cc switch local proxy failed while handling codex endpoint /responses 说的就是这类转换过程中出的问题。4.2 参数覆盖与优先级YAML 配置最容易出错的地方是优先级。openrig 的约定是项目级配置覆盖全局配置命令行参数覆盖项目配置。这个顺序要记牢不然你会遇到明明改了配置却不生效的情况。# 全局 models.yaml 里定义了默认参数 models: deepseek: type: openai-compatible endpoint: https://api.deepseek.com/v1 api_key_env: DEEPSEEK_API_KEY default_model: deepseek-chat params: temperature: 0.7 max_tokens: 4096 # 项目级 .openrig.yaml 覆盖 temperature override: model: deepseek params: temperature: 0.2上面这个例子里项目实际生效的 temperature 是 0.2max_tokens 还是继承全局的 4096。这种分层覆盖的设计让你可以在全局设一套保守参数在具体项目里按需调整不用每个项目都写全量配置。4.3 常见 YAML 语法错误排查YAML 报错信息有时候很含糊我整理了几个高频错误和对应的排查方法。缩进错误是最常见的表现为解析到某一行突然报错这时候检查报错行的上一行缩进是否一致。冒号后面没加空格也是高频问题key:value和key: value在 YAML 里是完全不同的前者会被当成一个普通字符串。还有列表项的短横线后面要加空格-item是错的- item才对。错误现象可能原因解决方法解析到某行报错缩进不一致或用了 Tab统一用 2 空格缩进值被当成字符串冒号后缺空格改成key: value列表解析失败短横线后缺空格改成- item中文乱码文件编码不是 UTF-8编辑器另存为 UTF-8布尔值异常用了 yes/no 而非 true/false统一用 true/false注意YAML 里yes、no、on、off在某些解析器里会被当成布尔值如果你真的想表达字符串记得加引号。这个坑我在配置模型名称时踩过一个叫on的模型名直接被解析成了 true。5. 多模型切换的实操流程5.1 启动脚本的编写逻辑openrig 的核心操作是启动前的环境准备。你写一个 Node.js 脚本读取 YAML 配置根据当前选择的 profile 把对应的环境变量设置好然后拉起 Claude Code 或 Codex。这个脚本不需要多复杂关键是逻辑清晰。// ~/.openrig/scripts/launch.js const fs require(fs); const yaml require(js-yaml); const { execSync } require(child_process); const profileName process.argv[2] || default; const globalConfig yaml.load(fs.readFileSync(${process.env.HOME}/.openrig/models.yaml, utf8)); const profiles yaml.load(fs.readFileSync(${process.env.HOME}/.openrig/profiles.yaml, utf8)); const profile profiles[profileName]; if (!profile) { console.error(Profile ${profileName} not found); process.exit(1); } const model globalConfig.models[profile.model]; const env { ...process.env }; env.ANTHROPIC_BASE_URL model.endpoint; env.ANTHROPIC_API_KEY process.env[model.api_key_env] || ; env.ANTHROPIC_MODEL profile.params?.model || model.default_model; console.log(Launching with profile: ${profileName}, model: ${env.ANTHROPIC_MODEL}); execSync(profile.command || claude, { env, stdio: inherit });这个脚本的意图很明确把 YAML 里的抽象配置翻译成 Claude Code 认识的环境变量。Claude Code 读取ANTHROPIC_BASE_URL来决定请求发往哪里读取ANTHROPIC_API_KEY做鉴权读取ANTHROPIC_MODEL决定用哪个模型。Codex 的环境变量名不同但逻辑一样。5.2 profiles.yaml 的场景化配置profiles 的作用是把模型和场景绑定。你可以定义日常开发、深度推理、本地离线几个 profile每个指向不同的模型和参数。profiles: default: model: claude-official command: claude deep-think: model: deepseek command: claude params: model: deepseek-reasoner temperature: 0.3 local: model: local-lmstudio command: claude params: model: qwen2.5-coder codex-default: model: deepseek command: codex用的时候就是node launch.js deep-think脚本自动把环境变量配好然后启动。这套流程跑顺之后切换模型就是换一个参数的事不用再去翻配置文件改端点。5.3 本地模型接入的注意事项让 Claude Code 调用 LM Studio 的本地模型有几个点必须注意。第一是 LM Studio 的服务要开着并且开启了 OpenAI 兼容的 API 端点默认端口是 1234。第二是模型名称要和 LM Studio 里加载的模型标识一致写错了会报模型不存在。第三是本地模型的上下文窗口通常比云端小配置里要把 max_tokens 调低不然请求会被截断。热词里 cc switch local proxy failed while handling codex endpoint /responses 这个报错本质上是代理层在处理 Codex 的/responses端点时出了问题。Codex 用的是 OpenAI 的 Responses API 格式而很多本地模型服务只支持 Chat Completions 格式两者不兼容就会报这个错。解决办法是确认你的代理层支持 Responses API 转换或者改用支持该格式的模型服务。6. 常见问题与排查实录6.1 安装类问题速查安装阶段的问题占了新手求助的一大半。我把高频问题整理成表方便对照排查。报错信息根本原因解决步骤node 不是内部或外部命令Node.js 未加入 PATH重装并勾选 Add to PATHerror installing 24.21.0版本号不存在或源未同步改用 LTS 版本号npm install 卡住不动网络或镜像源问题切换镜像源后重试claude 命令找不到全局包未正确链接检查 npm 全局路径是否在 PATHcodex 无法加载组织设置配置文件格式或版本残留卸载重装并清理旧配置6.2 配置类问题排查思路配置类问题最让人头疼因为工具往往不告诉你具体哪里错了。我的排查顺序是这样的先确认 YAML 本身能解析用一个简单的 Node.js 脚本yaml.load一下能过说明语法没问题。然后确认环境变量真的被注入了在启动脚本里打印出来看。最后确认端点可达用 curl 直接打一下 API 地址。# 验证 YAML 语法 node -e const yrequire(js-yaml),frequire(fs);console.log(y.load(f.readFileSync(process.argv[1],utf8))) ~/.openrig/models.yaml # 验证端点可达 curl -s -o /dev/null -w %{http_code} http://localhost:1234/v1/models这两个命令能解决八成配置问题。YAML 解析过了说明格式没问题端点返回 200 说明服务正常剩下的就是环境变量和参数的事了。6.3 订阅与权限相关提示热词里有一条 your organization has disabled claude subscription access for claude code这是组织管理员在后台关闭了 Claude Code 的订阅访问权限。遇到这个提示说明你的账号所属组织限制了该功能需要联系组织管理员确认策略或者改用个人账号。这类问题不是配置能解决的属于账号权限层面。另一个常见情况是 API 密钥无效或额度耗尽。表现是请求返回 401 或 403。排查方法是先用 curl 直接带密钥打一次 API确认密钥本身有效再排查是不是 openrig 注入的环境变量名写错了。我遇到过环境变量名大小写不一致导致密钥没被读取的情况这种问题看日志很难发现只能靠仔细核对。6.4 实操心得与避坑清单最后分享几条我实际用下来觉得最有价值的经验。第一条配置文件一定要进版本控制但密钥绝对不能进。用.gitignore把包含真实密钥的文件排除掉只提交模板文件。第二条每次改完 YAML 先跑一遍解析验证别等到启动工具报错了才回头查。第三条本地模型和云端模型的参数不要混用上下文窗口、温度、最大 token 数这些差异很大建议在 YAML 里分开定义。第四条Claude Code 和 Codex 的配置文件位置不同openrig 的脚本要分别处理不要指望一套环境变量通吃。第五条遇到 model is not supported 这类报错先确认模型名称拼写再确认该模型是否在你使用的端点上可用。热词里 the gpt-5.6-sol model is not supported when using codex 就是典型的模型名或端点不匹配。提示把常用的排查命令写成 shell 别名或者小脚本出问题时一键跑一遍比每次手动敲命令快得多。我自己的习惯是维护一个check.sh里面包含 YAML 验证、端点探测、环境变量打印三件事。这套 openrig 的配置思路我用了大半年最大的感受是前期花时间把 YAML 结构设计好后期切换模型和项目几乎零成本。真正麻烦的从来不是工具本身而是配置散落各处带来的心智负担。把配置收拢到一套 YAML 加一个启动脚本里这个问题就基本解决了。