1. 从“openrig”这个名字说起它到底想解决什么问题第一次看到openrig这个词我脑子里蹦出来的第一反应是“open”加“rig”——一个开放的、可拼装的“装备架”。事实也确实如此。openrig本质上是一套围绕 AI 编程助手尤其是 Claude Code、Codex 这类 CLI 工具构建的本地配置编排方案核心载体是 YAML 文件运行环境是 Node.js。它要解决的问题非常具体当你同时使用多个 AI 编程工具、多个模型供应商、多套 API 端点时配置会迅速变成一团乱麻而openrig想做的就是把这些零散的配置“装进一个架子”用一份结构化的 YAML 统一管理。我接触这个方向是因为身边太多人在折腾 Claude Code 和 Codex 的本地接入。有人用 Claude Code 调 LM Studio 的本地模型有人用 Codex 接 DeepSeek还有人想在 VS Code 里同时挂 Claude Code 和 Codex 两套 CLI。每个人的痛点都差不多配置文件散落各处、模型切换靠手改、端点写错一个字符就报错。openrig这类方案的价值就是把这些重复劳动收敛成一份可版本管理、可复用、可分享的 YAML。这篇文章适合三类人看。第一类是刚装完 Node.js、正准备上手 Claude Code 或 Codex 的新手你需要知道配置文件到底该长什么样第二类是已经在用但被多模型切换折磨的中级用户你需要一套结构化的编排思路第三类是想把团队里多个人的 AI 工具配置统一起来的人你需要的是可复制、可审查的配置模板。我会从设计思路讲到实操细节再到踩坑排查尽量让你看完就能动手。需要先说明一点openrig目前并不是一个官方标准它更像是一种约定俗成的配置组织方式。所以下面讲的内容一部分来自公开文档和常见实践一部分是我自己在多工具混用场景下总结出来的合理方案。你完全可以按自己的习惯调整核心逻辑不变。2. 整体设计思路为什么是 YAML Node.js 这套组合2.1 为什么配置文件选 YAML 而不是 JSON 或 TOML先说选型。AI 编程工具的配置本质上要描述几类东西模型供应商、端点地址、鉴权方式、模型名称、工具行为开关。这些内容有几个特点层级不深但字段多、需要写注释、经常要临时注释掉某一段做对比测试。JSON 的问题在于不能写注释而且尾部逗号、引号转义这些细节在手工编辑时特别容易出错。TOML 表达嵌套结构时又显得啰嗦尤其是当你要描述“多个供应商、每个供应商下多个模型”这种结构时TOML 的[[provider.models]]写法可读性一般。YAML 恰好卡在中间缩进即层级、支持注释、支持锚点和引用对于“配置编排”这个场景几乎是量身定做。我实测下来YAML 最大的好处是改起来心理负担小。你想临时禁用某个供应商前面加个#就行想把一段公共配置抽出来复用用锚点和引用*就能搞定。这在频繁切换模型的调试阶段非常省事。2.2 Node.js 在这里扮演什么角色很多人会问配置文件而已为什么非要 Node.js答案在于执行层。Claude Code、Codex 这类工具本身是 CLI它们需要一个运行时来加载配置、发起请求、处理流式响应。Node.js 的生态里有成熟的 HTTP 客户端、流处理、进程管理能力而且这些 AI CLI 工具大多本身就是 Node.js 写的或者优先支持 Node.js 环境。具体来说Node.js 在openrig这套方案里承担三件事读取并解析 YAML、把配置注入到工具的运行环境、在必要时做一层本地转发。第三点尤其关键——当你的工具只认某个固定端点格式而你的模型供应商提供的是另一种格式时中间就需要一层转换。这层转换用 Node.js 写是最顺手的因为可以复用大量现成的库。提示Node.js 版本建议用 LTS。我见过有人装了最新的奇数版本结果某些依赖编译失败回退到 LTS 就正常了。安装时去 Node.js 官网下载 LTS 版本别图新鲜。2.3 分层编排的核心思想openrig的设计精髓在于分层。我把它拆成三层来看基础层Node.js 运行时 工具本体Claude Code / Codex CLI配置层YAML 文件描述供应商、模型、端点、鉴权编排层一个轻量的调度逻辑决定当前用哪套配置、如何切换这样分层的好处是换模型不用动工具换工具不用重写配置。比如你今天用 Claude Code 接本地模型明天想换成 Codex 接云端模型配置层改几行编排层切一下工具本体完全不用重装。这就是“rig”这个词的含义——架子搭好了换零件很快。3. 核心细节解析YAML 配置到底该怎么写3.1 一份最小可用的配置结构先给一份我常用的最小结构你可以直接拿去改# openrig.yaml version: 1 providers: local: type: openai-compatible base_url: http://127.0.0.1:1234/v1 api_key: not-needed models: - name: local-model context_window: 32768 cloud: type: openai-compatible base_url: https://api.example.com/v1 api_key: ${CLOUD_API_KEY} models: - name: cloud-model-large context_window: 128000 active: provider: local model: local-model这份配置里providers是供应商列表每个供应商有type、base_url、api_key和models。active段决定当前生效的是哪一个。注意api_key用了${CLOUD_API_KEY}这种环境变量占位符这是强烈推荐的做法——密钥永远不要硬编码进 YAML尤其是这个文件要进 Git 仓库的时候。3.2 字段逐个拆解与常见取值type字段决定了这层配置怎么被解析。常见取值有openai-compatible、anthropic、custom。绝大多数第三方供应商和本地推理服务都兼容 OpenAI 的接口格式所以openai-compatible是覆盖面最广的选择。base_url是最容易出错的地方。我踩过的坑包括漏写/v1、多写一个斜杠、把http写成https。本地服务通常是http云端服务通常是https这个别搞反。另外注意端口LM Studio 默认是 1234其他本地服务可能是 8000、11434 等以你实际启动时打印的地址为准。context_window这个字段很多人会忽略但它直接影响工具的行为。如果填得比模型实际支持的大工具可能会发送超长上下文导致请求失败填得太小又会浪费模型能力。最稳妥的做法是查供应商文档或者先用一个保守值试。api_key用环境变量占位是标准操作。在 Linux 或 macOS 上你可以在 shell 配置里export CLOUD_API_KEY你的密钥在 Windows 上则通过系统环境变量设置。这样 YAML 文件可以放心分享密钥留在本地。3.3 多供应商与模型切换的编排写法当你需要频繁切换时active段手动改来改去很烦。更好的做法是用配置继承 命令行覆盖defaults: defaults type: openai-compatible timeout: 60 providers: local: : *defaults base_url: http://127.0.0.1:1234/v1 api_key: not-needed models: - name: qwen-local cloud: : *defaults base_url: https://api.example.com/v1 api_key: ${CLOUD_API_KEY} models: - name: cloud-large这里用了 YAML 的锚点defaults和合并键把公共字段抽出来。这样新增供应商时只需要写差异部分减少重复。切换时我习惯在启动脚本里传参比如openrig run --provider cloud --model cloud-large而不是去改 YAML 里的active段。配置保持静态切换交给运行时参数这是我在多项目并行时总结出的最省心模式。3.4 端点格式转换的注意事项热词里有个很典型的报错cc switch local proxy failed while handling codex endpoint /responses。这类问题的根源通常是工具的请求格式和供应商的接口格式对不上。Claude Code 和 Codex 各自有偏好的端点路径和请求体结构而你的供应商可能只认标准 OpenAI 格式。解决思路是在中间加一层转换。用 Node.js 写一个极简的转发服务把工具发来的请求体映射成供应商认识的格式再把响应映射回去。关键点有三个路径重写、请求体字段映射、流式响应的透传。流式这块最容易出问题因为一旦中间层缓冲了整个响应再返回工具那边的“逐字输出”体验就没了。所以转发时要用管道直接对接别做全量缓冲。注意做本地转发时端口别和已有服务冲突。我一般从 18080 这种不常用的端口开始试避免撞上 8080、3000 这些高频端口。4. 实操过程从零把 openrig 跑起来4.1 环境准备Node.js 安装与版本核对第一步永远是环境。去 Node.js 官网下载 LTS 版本安装完成后打开终端核对node -v npm -v如果node -v报错说找不到命令多半是安装时没勾选“添加到 PATH”重新装一遍并勾选即可。热词里有个报错error installing 24.21.0: node.js v24.21.0 is not yet released这通常是因为你指定的版本号根本不存在或者镜像源里还没有同步。解决办法很简单不要手动指定一个你猜的版本号直接用nvm install --lts或者官网的 LTS 安装包。版本核对完之后建议装一个nvmNode Version Manager来管理多版本。因为不同 AI 工具对 Node.js 版本的要求可能不一样有了 nvm 就能随时切换不用反复卸载重装。4.2 安装 Claude Code 与 Codex CLIClaude Code 和 Codex 的安装方式类似通常通过 npm 全局安装npm install -g anthropic-ai/claude-code npm install -g openai/codex安装完成后用claude --version和codex --version验证。如果提示命令找不到检查 npm 的全局 bin 目录是否在 PATH 里。在 Linux/macOS 上通常是~/.npm-global/bin或/usr/local/binWindows 上则是%APPDATA%\npm。这里有个常见坑全局安装权限不足。在 Linux 上直接npm install -g可能因为权限被拒这时候不要用sudo npm install -g会带来一堆权限后患而是配置 npm 的用户级全局目录npm config set prefix ~/.npm-global export PATH~/.npm-global/bin:$PATH把第二行写进你的 shell 配置文件之后全局安装就再也不需要 sudo 了。4.3 编写并加载 openrig.yaml环境齐了之后在项目根目录创建openrig.yaml内容参考第 3 节的模板。然后写一个极简的加载脚本用 Node.js 读取 YAML 并注入环境变量// load-rig.js const fs require(fs); const yaml require(js-yaml); const rig yaml.load(fs.readFileSync(./openrig.yaml, utf8)); const active rig.active; const provider rig.providers[active.provider]; process.env.OPENAI_BASE_URL provider.base_url; process.env.OPENAI_API_KEY provider.api_key; process.env.OPENAI_MODEL active.model; console.log(已加载供应商: ${active.provider}, 模型: ${active.model});运行node load-rig.js如果打印出正确的供应商和模型说明配置解析没问题。这一步看似简单但它是后面所有操作的基础配置解析错了后面全是白忙。4.4 在 VS Code 中接入与验证VS Code 里接入 Claude Code 或 Codex通常有两种方式一是用官方或社区的 VS Code 扩展二是在集成终端里直接跑 CLI。我推荐后者因为 CLI 的行为更透明出问题容易定位。在 VS Code 的settings.json里你可以配置终端启动时自动加载环境变量。或者更简单在项目里放一个.env文件配合dotenv在脚本里加载。验证是否接入成功最直接的办法是发一个最简单的请求比如让模型回复“ping”看是否能正常返回。如果返回超时或鉴权错误就回到配置层逐项核对base_url和api_key。4.5 参数选择与性能权衡timeout和context_window这两个参数值得单独说。timeout设太短长响应会被截断设太长出问题时你要等很久才知道失败。我的经验值是本地模型 60 秒云端模型 120 秒。本地模型因为算力有限首 token 延迟可能较高但一旦开始输出就很快云端模型则相反。context_window的权衡更微妙。填大了工具会尝试塞入更多历史可能导致请求体过大被拒填小了多轮对话很快就“失忆”。建议先用供应商文档标称值的 80% 作为配置值留出安全余量。比如标称 128k你填 100k 左右实测稳定性明显更好。5. 常见问题与排查技巧实录5.1 端点报错类问题的排查顺序遇到local proxy failed while handling codex endpoint /responses这类报错别慌按这个顺序查确认供应商服务是否在运行。本地服务用curl直接打一下base_url看有没有响应。确认路径是否正确。工具请求的路径和供应商提供的路径是否一致差一个/v1都可能 404。确认请求格式。抓一下工具发出的请求体和供应商文档对比字段名。确认转发层是否正常工作。如果用了中间转发先绕过转发直连供应商判断问题出在哪一层。我踩过最深的一个坑是转发层把stream: true这个字段吃掉了导致工具以为是非流式响应一直等到超时。排查时一定要把请求体和响应头都打出来看别只看状态码。5.2 鉴权与订阅类报错的应对热词里有your organization has disabled claude subscription access for claude code这种提示意思是当前账号的组织策略不允许通过订阅方式访问。这类问题不是配置能解决的属于账号权限层面。应对方式是改用 API Key 方式鉴权而不是订阅登录。在配置里把鉴权方式从订阅切换到 API Key通常就能绕过。另一类常见的是密钥格式错误。API Key 通常是一长串字符复制时容易带上空格或换行。粘贴后一定要检查首尾有没有多余空白这个低级错误我见过太多次。5.3 模型不支持类报错的定位the gpt-5.6-sol model is not supported when using codex with a...这种报错核心信息是“模型名不被支持”。可能的原因有两个一是模型名拼写错误二是该模型确实不在当前工具的兼容列表里。先核对模型名的拼写再去工具文档里查支持的模型列表。如果确实不支持就换一个兼容的模型名或者通过转发层做一次模型名映射。5.4 常见问题速查表报错关键词可能原因排查动作proxy failed / endpoint路径或格式不匹配核对 base_url 路径抓请求体organization disabled账号策略限制改用 API Key 鉴权model not supported模型名错误或不兼容核对拼写查支持列表node not yet released版本号不存在改用 LTS 版本命令找不到PATH 未配置检查全局 bin 目录请求超时timeout 太短或服务未启动加大 timeoutcurl 测服务5.5 几个独家避坑心得第一配置文件一定要进版本控制但密钥一定要抽离。我习惯把openrig.yaml提交到仓库把密钥放在.env里并加入.gitignore。这样团队协作时配置能共享密钥不会泄露。第二切换模型后先跑一个最小请求验证别直接上复杂任务。我吃过亏配置改完直接跑长任务结果跑到一半才发现模型名写错了浪费了十几分钟。第三保留一份“已知可用”的配置备份。每次大改之前先复制一份改崩了能立刻回滚。这个习惯帮我省了无数次重装的时间。第四本地服务的端口和地址要写死在一个地方。别在多个文件里重复写127.0.0.1:1234一旦端口变了要改好几处。用 YAML 锚点或者环境变量统一管理。6. 多工具混用场景下的编排进阶6.1 Claude Code 与 Codex 共存时的配置隔离当你同时用 Claude Code 和 Codex最忌讳的是让它们共用一套环境变量。因为两者可能对OPENAI_BASE_URL这类变量的解读不同互相覆盖就会出乱子。我的做法是给每个工具单独的环境变量前缀比如CLAUDE_RIG_*和CODEX_RIG_*在启动脚本里分别注入。具体来说写两个启动脚本run-claude.sh和run-codex.sh各自从openrig.yaml里读取对应段落的配置注入到各自的环境变量里再启动对应的 CLI。这样两个工具互不干扰可以同时开着。6.2 用一份 YAML 管理多套环境的实践开发、测试、生产三套环境如果各写一份 YAML维护成本很高。更好的做法是一份 YAML 里用环境维度分组environments: dev: provider: local model: qwen-local prod: provider: cloud model: cloud-large启动时通过--env dev或--env prod选择。这样公共的供应商定义只写一次环境差异只体现在选择哪一组。这个模式在团队里特别受欢迎因为新人只要知道--env参数就能跑起来不用理解全部配置。6.3 配置的可移植性与团队共享要让配置在团队里可移植有几个硬性要求不写绝对路径、不硬编码密钥、不依赖特定机器的端口。路径用相对路径或环境变量密钥用占位符端口通过配置项传入。做到这三点一份 YAML 就能在 Windows、macOS、Linux 上通用。另外建议在仓库里放一份openrig.example.yaml把真实配置里的敏感值全部替换成占位符新人复制一份改名就能用。这个小小的约定能省掉大量“你这配置怎么跑不起来”的沟通成本。7. 我个人的一些实操体会折腾openrig这套东西最大的收获不是某个具体配置写对了而是养成了“配置即代码”的习惯。以前我改 AI 工具配置全靠手改改完就忘出了问题完全不知道上次改了什么。现在所有配置进 Git每次改动都有记录回滚就是一条命令的事。还有一个体会是别追求一步到位。我一开始想把所有供应商、所有模型、所有环境一次性配全结果 YAML 写了三百多行自己都看不懂了。后来改成按需增量添加用到哪个加哪个配置反而清爽。配置这东西够用就好过度设计只会增加维护负担。最后分享一个小技巧在 YAML 顶部写一段注释记录这份配置的用途、最后修改时间和注意事项。三个月后你回头看会感谢当时的自己。这个习惯看起来微不足道但在多项目并行的时候它能帮你快速回忆起“这份配置到底是干嘛的”。