1. 从 openrig 说起一个被名字耽误的本地 AI 编码环境编排工具第一次看到 openrig 这个名字我下意识以为是某个开源硬件项目——毕竟 rig 在英文里常指矿机、测试台架或者设备机架。直到我在几个折腾 Claude Code 和 Codex 的社群里反复看到它被提起才意识到这其实是一个围绕本地 AI 编码助手做环境编排与配置管理的工具。说白了它解决的是一个非常具体的痛点当你同时想在本地跑 Claude Code、Codex CLI 这类命令行编码助手还要接不同的模型后端本地模型、第三方 API、各种中转端点配置文件会迅速变成一团乱麻而 openrig 想做的就是把这团乱麻用 YAML 梳理清楚。我先把结论摆在前面openrig 的核心价值不在于它自己有多强的功能而在于它把 Node.js 运行时、YAML 配置、多套 AI 编码工具的启动参数、模型端点切换这几件事统一到一个可版本化、可复用的配置层里。对于每天要在 Claude Code、Codex、VS Code 插件之间来回切换的人来说这玩意儿能省下大量重复改配置的时间。它适合谁适合已经装过 Node.js、跑通过至少一个 AI 编码 CLI、并且开始觉得每次换模型都要改一堆环境变量很烦的中级用户。纯小白直接上手会有点懵因为前置依赖不少。这篇文章我会按我自己的实操顺序来拆先讲清楚 openrig 到底在编排什么、为什么用 YAML 而不是 JSON 或 TOML再拆解核心配置结构和每个字段背后的逻辑然后给出一套从零到跑通的完整流程最后把我踩过的坑和排查思路整理成速查表。中间涉及 Node.js 安装、YAML 语法、Claude Code 与 Codex 的接入差异这些我都会展开讲因为这几个恰恰是新手最容易卡住的地方。2. 核心设计思路拆解为什么是 YAML为什么是 Node.js2.1 openrig 到底在编排什么要理解 openrig得先理解它面对的现实场景。现在本地跑 AI 编码助手通常有这么几层东西需要协调第一层是运行时也就是 Node.js因为 Claude Code 和 Codex CLI 基本都是 npm 包或者依赖 Node 生态分发的第二层是工具本体比如 Claude Code 的命令行入口、Codex 的 CLI第三层是模型端点你要么接官方服务要么接第三方兼容端点要么接本地跑的模型服务第四层是项目级配置不同项目可能要用不同的模型、不同的权限策略、不同的上下文文件。传统做法是每层各管各的Node.js 用 nvm 管版本工具用全局 npm 装端点靠环境变量临时 export项目配置散落在各个隐藏文件里。这套做法在只跑一个工具时没问题一旦你要同时维护 Claude Code 和 Codex 两套还要在几个模型端点之间切换环境变量就会互相污染改错一个就报一堆看不懂的错。openrig 的思路是把这四层收敛到一个声明式的配置文件里用 YAML 描述我要跑哪个工具、接哪个端点、用哪个模型、带哪些参数然后由它来生成对应的运行环境。这个思路本质上和 Docker Compose 编排容器是一个道理——你不是手动 docker run 一堆参数而是写一份 compose 文件描述期望状态。openrig 就是 AI 编码工具界的轻量 compose。2.2 为什么选 YAML 而不是 JSON 或 TOML这是很多人会问的第一个问题。JSON 的问题是没法写注释而 AI 工具的配置里恰恰有大量需要注释的地方——比如这个端点为什么这么配这个参数是给哪个模型用的过两周自己都忘了。TOML 表达嵌套结构时又比较啰嗦尤其是当你要描述多个工具、多个端点、多层覆盖关系时TOML 的表格语法会写得很长。YAML 的优势在于支持注释、缩进表达层级直观、天然适合描述配置树。代价是它对缩进极其敏感多一个空格少一个空格结果完全不同这也是新手最容易翻车的地方。我见过太多人因为把两个空格写成四个空格导致整个配置解析失败然后对着报错一脸茫然。所以用 openrig 之前先把 YAML 的缩进规则刻进脑子里同级元素缩进必须完全一致层级靠缩进深度区分绝对不能用 Tab。这里给一个最小可用的 YAML 结构感受一下version: 1 tools: claude-code: enabled: true model: local-qwen codex: enabled: true model: deepseek-endpoint endpoints: local-qwen: base_url: http://127.0.0.1:1234/v1 api_key: local deepseek-endpoint: base_url: https://api.example.com/v1 api_key: ${DEEPSEEK_KEY}注意api_key那里用了${DEEPSEEK_KEY}这种占位符写法这是配置管理里的常见实践——敏感信息不写死在配置文件里而是从环境变量读取。openrig 这类工具基本都支持这种插值具体语法以官方文档为准但思路是通用的。2.3 Node.js 在整条链路里的角色很多人对 Node.js 的认知停留在前端用的其实它在 AI 编码工具生态里扮演的是运行时底座的角色。Claude Code、Codex CLI 这些工具大多是通过 npm 分发的npm 又是 Node.js 自带的包管理器。所以你装这些工具的前提是机器上有一个可用的 Node.js 环境。这里有个高频坑Node.js 版本。热词里那条 error installing 24.21.0: node.js v24.21.0 is not yet released 就是典型——有人照着某个教程抄了个版本号结果那个版本根本不存在或者还没发布npm 直接报错。我的建议是永远用 LTS长期支持版本别追最新的奇数版本。LTS 版本稳定、生态兼容性好AI 工具链对它的支持也最完整。截至我写这篇的时候Node.js 20.x 和 22.x 的 LTS 都是稳妥选择。安装方式上Windows 用户直接去 Node.js 官网下载 LTS 的安装包最省事一路下一步就行。macOS 和 Linux 用户我更推荐用 nvmNode Version Manager因为它能让你在同一台机器上装多个 Node 版本并随时切换这在测试不同工具兼容性时特别有用。用 nvm 装 Node 的命令大致是nvm install --lts nvm use --lts node -v npm -v最后两行是验证能打印出版本号就说明装好了。如果node -v报 command not found八成是 PATH 没配好nvm 装完通常会提示你怎么把初始化脚本加进 shell 配置里。3. 核心配置结构解析与实操要点3.1 配置文件的分层与覆盖逻辑openrig 这类编排工具通常支持多层配置全局层用户主目录下的配置、项目层项目根目录下的配置、以及运行时通过命令行参数传入的临时覆盖。理解这个覆盖顺序至关重要因为它决定了我改了配置为什么没生效。一般规律是越靠近当前上下文的配置优先级越高。也就是说命令行参数 项目配置 全局配置。这个设计的好处是你可以在全局配一套默认端点然后在某个特定项目里覆盖成另一个模型而不用动全局配置。我自己的习惯是全局配置只放最通用的东西比如默认的 Node 版本要求、日志级别项目配置放具体的模型端点和工具开关。实操中要注意的是不同工具对项目根目录的判定标准不一样。有的认.git目录有的认配置文件所在位置。如果你发现项目配置没被加载先确认你执行命令的目录是不是工具认定的项目根。这个细节官方文档一般会写但很容易被跳过。3.2 端点配置本地模型与第三方 API 的差异端点endpoint配置是 openrig 里最核心也最容易出错的部分。热词里 claude code 调用 lmstudio 的本地模型 和 codex 接入 deepseek 反映的就是两类典型场景一类是接本地跑的模型服务一类是接第三方兼容 API。本地模型服务比如 LM Studio、Ollama 这类通常监听在127.0.0.1的某个端口上提供一个 OpenAI 兼容的接口。配置时base_url指向本地地址api_key随便填一个非空值即可本地服务一般不校验。这里的关键是确认本地服务确实在跑并且端口对得上。我踩过的坑是LM Studio 默认端口和我配置里写的端口不一致结果一直连不上排查了半天才发现是端口写错了。第三方 API 的配置要点是base_url必须指向兼容 OpenAI 协议的那个路径很多服务是https://xxx/v1结尾少写或多写/v1都会导致 404。api_key强烈建议用环境变量注入别直接写进 YAML尤其是当这个配置文件要提交到 Git 仓库时。我见过有人把 key 写进配置然后推到公开仓库几分钟内就被扫号盗刷了这个教训很贵。下面这张表对比一下两类端点的配置差异配置项本地模型服务第三方兼容 APIbase_urlhttp://127.0.0.1:端口/v1https://服务商域名/v1api_key任意非空字符串真实密钥建议环境变量注入网络依赖无纯本地需要外网连通常见报错连接被拒绝、端口占用401 鉴权失败、404 路径错误延迟特征取决于本机算力取决于网络与服务商负载3.3 工具开关与模型绑定openrig 的配置里通常有一个 tools 段落用来声明启用哪些工具、每个工具绑定哪个模型端点。这个设计的巧妙之处在于模型和工具解耦了——你可以定义一堆端点然后自由地把它们分配给不同的工具甚至同一个工具在不同项目里绑不同端点。配置时要注意工具名的大小写和连字符。有的工具在配置里写claude-code有的写claude_code写错了不会报工具不存在而是静默忽略导致你以为启用了其实没启用。我的做法是配置完先跑一次openrig的状态查看命令如果有的话确认它识别到的工具列表和端点列表跟预期一致再往下走。还有一个细节是模型名的映射。第三方端点往往要求你传一个具体的模型标识符比如deepseek-chat或者qwen-max这个标识符必须和服务商文档里写的一模一样。写错了服务端会返回模型不存在但错误信息有时候很含糊容易让人以为是网络问题。所以配置模型名时直接复制服务商文档里的字符串别手打。4. 从零跑通 openrig 的完整实操流程4.1 环境准备Node.js 与包管理器第一步永远是确认 Node.js 环境。打开终端跑node -v npm -v如果两条命令都能输出版本号且 Node 版本是 LTS就可以跳过安装。如果没有去 Node.js 官网下载 LTS 安装包或者用 nvm 安装。Windows 用户注意安装时勾选添加到 PATH否则装完还是找不到命令。装完 Node.js 后建议顺手把 npm 的镜像源配一下如果你在国内网络环境能显著加快后续装包速度npm config set registry https://registry.npmmirror.com这条命令把 npm 的默认源换成了国内镜像装包时不用再忍受龟速。验证方式是npm config get registry能打印出你设置的地址就对了。4.2 安装 openrig 与相关工具环境就绪后安装 openrig 本体。具体命令以官方文档为准通常是全局安装npm install -g openrig装完跑openrig --version验证。如果报 command not found检查 npm 的全局 bin 目录是否在 PATH 里。用npm config get prefix能看到全局安装路径把这个路径下的 bin 目录加进 PATH 即可。接下来按需安装你要编排的工具。Claude Code 和 Codex CLI 的安装方式各自不同但基本都是 npm 全局装或者用官方提供的安装脚本。这里我不展开具体命令因为这类工具的安装方式更新很快直接看官方文档最靠谱。要提醒的是装之前先确认你的 Node 版本满足工具的最低要求版本太低会在安装阶段就报错。4.3 编写第一份 openrig 配置在项目根目录创建配置文件具体文件名以官方为准常见的是openrig.yaml或.openrig/config.yaml。从最小配置开始别一上来就写一大坨version: 1 tools: claude-code: enabled: true endpoint: local-model endpoints: local-model: base_url: http://127.0.0.1:1234/v1 api_key: local-no-auth这份配置的意思是启用 claude-code 工具让它走名为 local-model 的端点这个端点指向本机 1234 端口的本地模型服务。写完先别急着跑用 YAML 校验工具检查一下语法。很多编辑器VS Code 装个 YAML 插件能实时提示缩进错误强烈建议装上。4.4 启动与验证配置写好后先确保本地模型服务在跑。以 LM Studio 为例你需要在它的界面里加载一个模型并启动本地服务器确认它监听的端口和你配置里写的一致。然后执行 openrig 的启动命令观察输出。验证是否真的走通了最直接的办法是给工具发一个简单请求看它返回的内容是不是来自你配置的模型。如果返回的是官方模型的口吻说明端点没生效配置被忽略了如果返回的是本地模型那种略显笨拙的回答说明链路通了。这个看回答风格判断走没走对端点的技巧比看日志还快。5. 常见问题与排查技巧实录5.1 配置不生效的三层排查法配置改了但没生效是最高频的问题。我的排查顺序是先确认配置文件被加载了看工具启动日志里有没有打印配置路径再确认配置语法没被静默忽略YAML 解析失败有时不报错只是用默认值最后确认覆盖顺序是不是被更高优先级的配置盖掉了。这三层走一遍九成问题能定位。5.2 端点连接类报错速查报错现象可能原因排查动作连接被拒绝本地服务没启动或端口错确认服务在跑核对端口401 未授权api_key 缺失或错误检查环境变量是否注入成功404 路径错误base_url 少了或多写了 /v1对照服务商文档核对路径模型不存在模型标识符写错复制文档里的准确字符串超时无响应网络不通或服务过载先用 curl 直接测端点用 curl 直接测端点是个好习惯能快速区分是 openrig 的问题还是端点本身的问题curl http://127.0.0.1:1234/v1/models这条命令能列出本地服务支持的模型返回正常说明服务没问题问题在 openrig 配置返回失败说明服务本身没起来。5.3 版本与依赖类坑热词里那条 Node 版本不存在的报错根源是抄了不存在的版本号。解决办法很简单用nvm install --lts让工具自己选最新 LTS别手写版本号。另一个常见坑是全局包权限问题在 Linux 和 macOS 上用系统 Node 全局装包可能需要 sudo而 sudo 装出来的包后续升级会有权限麻烦。用 nvm 管理 Node 就能绕开这个问题因为 nvm 装的 Node 目录归当前用户所有不需要 sudo。5.4 我踩过的几个真实坑第一个坑是 YAML 里的 Tab。我从别处复制配置时编辑器自动把缩进转成了 Tab结果解析直接失败报错信息还指向了错误的行号害我查了半天。现在的习惯是编辑器里开启显示空白字符一眼就能看出是空格还是 Tab。第二个坑是环境变量没导出。我在配置里写了${API_KEY}但忘了在当前 shell 里 export 这个变量导致工具读到的是空字符串然后报鉴权失败。排查时先echo $API_KEY确认变量有值再往下查。第三个坑是多个工具抢同一个端口。我同时配了本地模型服务和另一个本地工具两者都想用 1234 端口结果后启动的失败。解决办法是给每个服务分配不同端口配置里对应改掉。6. 进阶玩法与配置复用建议6.1 把配置纳入版本管理openrig 配置最大的价值之一就是可以提交到 Git。但提交前务必确认敏感信息都用了环境变量占位符配置文件里不能出现真实密钥。我的做法是在仓库里放一份openrig.example.yaml作为模板真实的openrig.yaml加进.gitignore。这样团队里每个人克隆下来复制模板、填自己的 key就能快速拉起环境。6.2 多项目多模型的切换策略如果你手头有好几个项目每个项目要用不同的模型别在每个项目里复制一份完整配置。更好的做法是全局配置里定义所有端点项目配置里只写这个项目用哪个端点。这样端点信息只有一处维护改一次全局生效。这个思路和编程里的配置与代码分离是一脉相承的。6.3 和编辑器插件的配合VS Code 里的 Claude Code 插件、Codex 插件很多时候也能读取同一套配置或者环境变量。如果你把 openrig 的端点配置通过环境变量暴露出去编辑器插件也能复用省得在两处各配一遍。具体能不能复用取决于插件的实现但值得花十分钟试一下能省下长期维护成本。我在实际使用中最大的体会是这类编排工具的价值不在于功能多花哨而在于它逼着你把散落各处的配置收敛成一份可读、可版本化、可复用的声明式文件。一旦收敛完成后面换模型、加工具、拉新环境都是改几行 YAML 的事而不是重新回忆一遍当初是怎么配的。这个从手忙脚乱改环境变量到改一行配置的转变才是 openrig 这类工具真正省心的地方。