1. 从“openrig”这个名字说起它到底想解决什么问题第一次看到openrig这个词我脑子里蹦出来的第一反应是“open”加“rig”——一个开放的、可拼装的“装备架”。事实也确实八九不离十。在当下这个 AI 编程助手满天飞的阶段claude code、codex这类命令行智能体CLI Agent已经成了不少开发者日常写代码、改 bug、跑脚本的标配工具。但问题也随之而来每个工具都有自己的配置格式、自己的模型接入方式、自己的环境变量命名习惯。你今天用claude code接本地模型明天想换成codex接另一家 API后天又想在 VS Code 里同时管理好几套配置——光是来回改配置文件就能把人折腾到怀疑人生。openrig要干的事情本质上就是把这些零散的、各自为政的 AI 编程工具配置统一收拢到一个可管理、可切换、可复用的“装备架”上。它不是一个模型也不是一个 IDE 插件而更像是一层配置编排层用 YAML 描述你有哪些工具、每个工具用哪个模型、走哪个端点、带哪些参数然后由它来负责把这些配置正确地“喂”给对应的 CLI 工具。你可以把它理解成 AI 编程工具界的“docker-compose”——只不过它编排的不是容器而是claude code、codex这些智能体的运行配置。这个项目适合谁三类人最该关注。第一类是多工具重度用户同时用claude code和codex甚至还在试各种新出的 CLI Agent配置管理已经成了负担。第二类是本地模型玩家比如用 LM Studio、Ollama 跑本地模型想让claude code调用本地模型但被端点配置、模型名映射搞得头大。第三类是团队协作场景需要把一套统一的 AI 工具配置分发给多个成员保证大家用的模型、参数、端点一致避免“你那边能跑我这边报错”的经典问题。关键词里出现的yaml、node.js也印证了这个定位openrig大概率是一个基于 Node.js 运行时的 CLI 工具用 YAML 作为配置描述语言。YAML 的好处是结构清晰、人类可读、支持注释比 JSON 适合写配置比 TOML 在嵌套结构上更灵活。Node.js 则保证了跨平台Windows、macOS、Linux 都能跑和与前端工具链的天然亲和。接下来我会从设计思路、核心配置、实操流程、踩坑排查几个维度把这个“装备架”拆开讲透。2. 整体设计思路为什么是 YAML Node.js 这套组合2.1 配置编排层的核心价值在哪里要理解openrig的设计先得理解它面对的是一个什么样的混乱现场。claude code有自己的配置文件通常在用户目录下的某个隐藏文件夹里格式可能是 JSONcodex也有自己的一套环境变量名、端点路径、认证方式都可能不一样。更麻烦的是这些工具在迭代过程中配置格式还会变。你今天照着某篇教程配好了明天工具升级配置项改名了又得重新查文档。openrig的思路是抽象出一层中间配置。你不再直接去改每个工具的原生配置而是只维护一份openrig的 YAML 文件。这份文件里描述的是“意图”——我要用哪个模型、走哪个端点、给哪个工具用。至于怎么把这个意图翻译成claude code能认的格式、codex能认的格式那是openrig的事。这就好比你写 Dockerfile 描述的是“我要一个什么环境”而不是手动去敲一堆apt-get和export。这种设计带来的直接好处有三个。第一是切换成本极低想从模型 A 换到模型 B改一行 YAML 就行不用去翻每个工具各自的配置文档。第二是配置可版本化一份 YAML 可以提交到 Git团队共享出问题能追溯。第三是降低认知负担你只需要学一套配置语法就能管理多个工具不用为每个工具单独记一套配置规则。2.2 为什么选 YAML 而不是 JSON 或 TOML配置文件格式的选择看着是小事实际上直接影响日常使用体验。JSON 的问题是不支持注释而且嵌套深了之后括号对不齐人眼很难快速定位。你想想一个配置文件里要描述三四个工具、每个工具有五六个参数用 JSON 写出来就是一大坨花括号改的时候得小心翼翼数逗号。TOML 在简单配置上很优雅但一旦涉及到嵌套的对象数组比如“多个工具每个工具多个模型”表达起来就有点别扭。YAML 在这两者之间找到了平衡。它用缩进表达层级视觉上清爽支持#注释可以给每个配置项写说明支持锚点和引用能复用重复的配置块。对于openrig这种“描述多个工具、多个模型、多个端点”的场景YAML 的表达力刚好够用又不会过于复杂。当然 YAML 也有它的坑最著名的就是缩进必须用空格不能用 Tab以及某些特殊字符需要引号包裹这些后面讲实操的时候会具体说。2.3 Node.js 运行时带来的跨平台与生态优势选 Node.js 作为运行时我认为是openrig一个很务实的决定。首先claude code和codex这类工具本身就是 Node.js 生态的产物用 Node.js 来编排它们在进程调用、环境变量传递、标准输入输出处理上天然顺畅。其次Node.js 的跨平台能力成熟Windows 上用npm install -g装全局 CLI 已经是标准操作macOS 和 Linux 更不用说。第三Node.js 生态里有大量现成的库可以处理 YAML 解析、命令行参数解析、文件监听开发效率高。从使用者角度看这意味着你只需要装一个 Node.js 环境建议 LTS 版本就能通过 npm 把openrig装成全局命令然后在任何项目目录下用。不需要额外装 Python、不需要配 Java 环境对前端和全栈开发者尤其友好。关键词里反复出现的node.js安装、node.js lts下载、node.js官网下载也说明很多人的第一步卡点就在环境准备上这个后面会专门讲。3. 核心配置解析一份 openrig.yaml 应该长什么样3.1 配置文件的基本骨架与字段含义虽然openrig的具体字段命名可能随版本变化但基于这类配置编排工具的通用设计一份典型的openrig.yaml大致会包含以下几个顶层区块。我按最常见的实践给你梳理一个骨架你在实际使用时对照官方文档微调字段名即可。# openrig.yaml version: 1 # 定义可用的模型端点 providers: local-lmstudio: type: openai-compatible baseUrl: http://localhost:1234/v1 apiKey: not-needed remote-deepseek: type: openai-compatible baseUrl: https://api.deepseek.com/v1 apiKey: ${DEEPSEEK_API_KEY} # 定义模型别名映射到具体 provider models: fast-local: provider: local-lmstudio model: qwen2.5-coder-7b deep-reason: provider: remote-deepseek model: deepseek-chat # 定义工具及其使用的模型 tools: claude-code: model: deep-reason env: ANTHROPIC_BASE_URL: ${provider.baseUrl} codex: model: fast-local env: OPENAI_BASE_URL: ${provider.baseUrl}这个骨架里providers描述“去哪里调用模型”models描述“用哪个模型”tools描述“哪个工具用哪个模型”。三层分离的好处是换端点不用动模型定义换模型不用动工具定义。比如你本地 LM Studio 的端口从 1234 改成 8080只需要改providers里的一行所有引用它的模型和工具自动生效。${DEEPSEEK_API_KEY}这种写法是环境变量插值目的是避免把密钥明文写进配置文件。这一点非常重要因为配置文件很可能要提交到 Git 或者分享给同事密钥泄露的后果不用我多说。openrig在读取配置时会从系统环境变量里取值填充这样配置文件本身可以安全地版本化。3.2 provider、model、tool 三层抽象的设计逻辑为什么非要拆成三层直接用“工具 → 端点 模型名”两层不行吗行但会失去灵活性。我举个实际场景你就明白了。假设你有两个工具claude code和codex它们都想用同一个本地模型。如果只有两层你得在两个工具下面各写一遍端点地址和模型名重复且容易不一致。有了models这一层你定义一个fast-local模型别名两个工具都引用它改的时候只改一处。再比如同一个端点下可能有多个模型一个快的、一个强的你想让codex用快的做补全、claude code用强的做重构。三层结构下你定义两个 model 别名指向同一个 provider然后分别分配给两个工具清晰明了。这种“关注点分离”的设计在配置管理里是经典套路Kubernetes 的Service/Deployment/Pod也是类似思路。还有一点值得说type: openai-compatible这个字段。现在大量本地模型服务和第三方 API 都兼容 OpenAI 的接口格式所以只要标成openai-compatibleopenrig就知道用统一的协议去调用不用为每个服务写适配器。这也是为什么claude code 调用lmstudio的本地模型这类需求能通过配置解决——LM Studio 暴露的就是 OpenAI 兼容接口。3.3 环境变量插值与密钥管理的最佳实践密钥管理是配置编排里最容易出事的地方。我见过太多人把 API Key 直接写在配置文件里然后不小心提交到公开仓库第二天收到账单警告。openrig支持环境变量插值正确的做法是配置文件里只写${VAR_NAME}占位符真实的密钥放在系统环境变量或.env文件里.env文件加入.gitignore绝不提交在 Windows 上设置环境变量可以用setx命令或者系统设置界面在 macOS/Linux 上可以在~/.bashrc或~/.zshrc里export。如果你用.env文件openrig通常会自动加载当前目录下的.env这样每个项目可以有独立的密钥配置互不干扰。注意环境变量插值的语法在不同工具里可能是${VAR}也可能是$VAR甚至有的用{{VAR}}。以openrig官方文档为准别想当然。我踩过的坑就是照着别的工具语法写结果插值没生效工具拿着字面量${DEEPSEEK_API_KEY}去请求报了个莫名其妙的认证错误排查了半天才发现是语法问题。4. 实操全流程从零把 openrig 跑起来4.1 环境准备Node.js 安装与版本选择第一步永远是环境。openrig基于 Node.js所以你得先有 Node.js。这里有个关键选择装 LTS 版本还是最新版我的建议是无脑选 LTS。LTSLong Term Support是长期支持版稳定、bug 少、生态兼容性好。最新版虽然有一些新特性但可能和某些依赖不兼容尤其是你还要同时跑claude code、codex这些工具它们对 Node.js 版本可能有各自的要求LTS 是最安全的交集。安装方式按平台分Windows去 Node.js 官网下载 LTS 的.msi安装包双击一路下一步。安装完成后打开 PowerShell 或 CMD输入node -v和npm -v验证。如果提示“不是内部或外部命令”说明 PATH 没配好重启终端或者手动把 Node.js 安装目录加进系统 PATH。macOS推荐用nvmNode Version Manager管理命令是curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash然后nvm install --lts。用 nvm 的好处是可以在多个 Node.js 版本间切换遇到某个工具要求特定版本时不用重装。LinuxUbuntu/Debian同样推荐 nvm步骤和 macOS 一样。如果不想用 nvm可以用sudo apt install nodejs npm但 apt 源里的版本可能偏旧建议还是 nvm。装完之后验证一下node -v应该输出类似v20.x.x或v22.x.x的版本号。如果版本太老比如 v14 以下某些现代工具会跑不起来这时候用 nvm 升级一下。提示关键词里有个error installing 24.21.0: node.js v24.21.0 is not yet released or is not ava这是典型的版本号写错导致的。Node.js 的版本号是主版本.次版本.修订号24.21.0 这种组合可能根本不存在。装的时候认准官网或 nvm 给出的实际可用版本别手敲一个想当然的版本号。4.2 安装 openrig 并初始化第一个配置Node.js 就绪后安装openrig通常就是一条 npm 命令npm install -g openrig-g表示全局安装这样在任何目录下都能用openrig命令。装完后输入openrig --version验证。如果提示命令找不到检查 npm 的全局 bin 目录是否在 PATH 里。可以用npm config get prefix查看全局安装路径然后把这个路径下的binWindows 是根目录加进 PATH。接下来初始化配置。大多数这类工具会提供一个init命令openrig init它会在当前目录生成一个openrig.yaml模板文件。你也可以手动创建这个文件把上一节讲的骨架填进去。初始化之后用openrig validate之类的命令检查配置语法是否正确——YAML 的缩进错误很隐蔽有个校验命令能省很多事。4.3 接入本地模型以 LM Studio 为例的完整配置本地模型接入是很多人用openrig的核心诉求。以 LM Studio 为例完整流程是这样的打开 LM Studio在“Developer”或“Local Server”标签页启动服务默认端口 1234。确认它暴露的是 OpenAI 兼容接口地址通常是http://localhost:1234/v1。在 LM Studio 里加载一个模型比如qwen2.5-coder-7b记下模型标识符。在openrig.yaml里配置 provider 和 modelproviders: local-lmstudio: type: openai-compatible baseUrl: http://localhost:1234/v1 apiKey: lm-studio models: local-coder: provider: local-lmstudio model: qwen2.5-coder-7b tools: claude-code: model: local-coder运行openrig apply或类似命令让配置生效。这一步openrig会把你的意图翻译成claude code能认的环境变量或配置文件。启动claude code测试它是否能正常调用本地模型。这里有个细节apiKey字段对本地模型通常是摆设LM Studio 不校验但有些客户端库要求这个字段非空所以随便填一个占位符就行比如lm-studio。4.4 多工具切换claude code 与 codex 共存配置同时用claude code和codex是openrig的典型场景。配置上你只需要在tools区块下分别定义tools: claude-code: model: deep-reason env: ANTHROPIC_BASE_URL: ${provider.baseUrl} ANTHROPIC_API_KEY: ${provider.apiKey} codex: model: fast-local env: OPENAI_BASE_URL: ${provider.baseUrl} OPENAI_API_KEY: ${provider.apiKey}注意不同工具用的环境变量名不一样。claude code认的是ANTHROPIC_前缀codex认的是OPENAI_前缀。openrig的价值就在于帮你处理这些差异——你在 YAML 里写一次它负责翻译成各自需要的格式。切换的时候用openrig use claude-code或openrig use codex之类的命令激活对应配置或者它可能通过生成不同的配置文件来实现隔离。实操心得多工具共存时最容易出问题的是端口冲突和环境变量污染。比如你之前手动export过一个OPENAI_BASE_URLopenrig又设了一个到底哪个生效取决于加载顺序。建议在切换工具前先echo一下相关环境变量确认没有残留的旧值。我吃过这个亏明明配置改了工具却还在用旧端点查了半天才发现是 shell 里有个手动 export 的变量在捣乱。5. 常见问题与排查技巧实录5.1 配置不生效从加载顺序到缓存机制“我明明改了配置怎么没生效”这是最高频的问题。排查思路按以下顺序来第一确认配置文件被正确加载。openrig可能支持多级配置全局配置、项目配置、环境变量覆盖加载顺序决定了最终生效的值。用openrig config show或类似命令打印出实际生效的配置和你以为的配置对比。这一步能解决八成问题。第二检查环境变量残留。前面提过手动 export 的变量可能覆盖配置文件。在终端里env | grep -i相关前缀看看有没有意外设置。第三确认工具是否重启。很多 CLI 工具在启动时读取配置运行中不会热加载。改完配置后要重启工具进程。第四检查缓存。有些工具会缓存认证信息或端点配置存在用户目录的隐藏文件夹里。如果配置改了还不生效试试清缓存或者删掉工具自己的配置文件让openrig重新生成。5.2 模型调用报错端点、模型名与认证的三重检查调用模型时报错错误信息往往很模糊比如401 Unauthorized、404 Not Found、model not supported。按这三项逐一排查错误现象可能原因排查方法401 UnauthorizedAPI Key 错误或未传递检查环境变量插值是否生效echo $API_KEY确认值存在404 Not Found端点路径错误确认 baseUrl 是否包含/v1有些服务需要有些不需model not supported模型名不匹配确认模型标识符和服务端注册的名称完全一致连接超时本地服务未启动或端口错curl一下端点地址确认服务可达关键词里有个the gpt-5.6-sol model is not supported when using codex这就是典型的模型名不匹配。codex可能对模型名有白名单校验你配了一个它不认识的模型名它就拒绝。解决办法是查codex支持的模型列表用列表里的名字或者看openrig是否提供了模型名映射功能。5.3 组织策略限制与订阅访问问题关键词里出现了your organization has disabled claude subscription access for claude code这是企业环境下的常见限制。如果你的账号属于某个组织管理员可能关闭了通过订阅方式访问claude code的权限。这种情况下配置层面能做的有限你需要确认是否可以使用 API Key 方式而非订阅方式访问联系组织管理员确认策略如果是个人使用确认账号类型和订阅状态这类问题本质上是权限问题不是配置问题openrig帮不了你绕过策略但可以帮你快速切换到其他可用的模型端点保证工作流不中断。这也是配置编排层的价值——一条路走不通改一行配置换条路。5.4 YAML 语法坑缩进、引号与特殊字符YAML 看着简单坑不少。最常见的三个缩进必须用空格不能用 Tab。这是 YAML 的铁律。很多编辑器默认 Tab 缩进写出来的 YAML 解析直接报错。建议在编辑器里设置 YAML 文件用 2 空格缩进。含特殊字符的值要加引号。比如baseUrl: http://localhost:1234/v1里的冒号如果不加引号YAML 可能把http当成键、//localhost...当成值。稳妥做法是给所有 URL 加引号baseUrl: http://localhost:1234/v1。布尔值和字符串的歧义。yes、no、on、off在 YAML 里可能被解析成布尔值。如果你想要字符串no必须加引号。模型名或参数里出现这些词时要特别注意。提示写完 YAML 后用在线 YAML 校验器或者openrig validate过一遍能提前发现大部分语法问题。别等到运行时才报错那时候错误信息往往指向别处排查成本高得多。6. 进阶玩法与个人经验补充6.1 配置模板化与团队共享当你把openrig.yaml调通之后下一步就是团队共享。做法是把配置文件提交到项目仓库但密钥部分用环境变量占位每个成员在自己机器上设置环境变量。这样新人入职只需要装 Node.js、装openrig、设置环境变量、openrig apply四步就能拥有和你一致的 AI 工具配置。更进一步你可以准备多份配置模板一份接本地模型的适合离线开发、一份接云端 API 的适合需要强模型的场景、一份接公司内部端点的。用openrig的配置切换功能在不同场景间快速切换。这比每个人各自维护一套配置要可靠得多。6.2 与 VS Code 的协同配置关键词里vscode配置claude code、claude code for vs code、vscode接入claude code出现频率很高说明很多人是在 VS Code 里用这些工具的。openrig和 VS Code 的协同点在于VS Code 里的终端会继承系统环境变量所以openrig设置的环境变量在 VS Code 终端里也能生效。如果你在 VS Code 里装了claude code插件插件读取的也是同一套环境变量配置一次两边通用。需要注意的是VS Code 有时会缓存终端环境。改完环境变量后重启 VS Code 或者开一个新终端确保新变量被加载。如果插件有自己的配置文件确认它没有覆盖openrig设置的值。6.3 我踩过的几个真实坑最后分享几个我在配置这类工具时踩过的坑都是文档里不会写的。坑一端口被占用但不报错。本地模型服务启动时如果端口被占用有些服务会静默失败或者换端口但你的配置还指向旧端口。表现就是连接超时。养成习惯启动本地服务后先curl一下确认可达再启动 AI 工具。坑二模型加载慢导致首次请求超时。本地大模型首次加载可能要几十秒而 AI 工具的默认超时可能只有 10 秒。表现是第一次请求失败第二次就好了。解决办法是在配置里调大超时时间或者先手动预热模型。坑三不同工具的模型名大小写敏感。有的服务模型名区分大小写Qwen2.5-Coder和qwen2.5-coder是两个不同的东西。配置时直接从服务端的模型列表里复制粘贴别手敲。坑四环境变量在 GUI 应用里不生效。如果你在 VS Code 的图形界面里启动工具它可能不继承 shell 里 export 的变量。解决办法是把变量写进系统级环境变量或者在 VS Code 的settings.json里配置terminal.integrated.env。这套东西调通之后你会发现管理多个 AI 编程工具从“每个都要单独折腾”变成了“改一行 YAML 的事”。openrig这类配置编排工具的价值不在于它做了什么惊天动地的事而在于它把重复的、易错的、分散的配置工作收敛到了一处。对于同时用好几个 CLI Agent 的人来说省下的时间和避免的抓狂远比学习一套新配置语法的成本高。