1. 从 openrig 这个标题说起它到底想解决什么问题第一次看到 openrig 这个词我脑子里蹦出来的第一反应是“open rig”也就是“开放式的设备/工具架”。结合热搜词里那一长串 Claude Code、Codex、YAML、Node.js基本可以判断openrig 不是一个单纯的软件包而更像是一套把本地 AI 编码工具Claude Code、Codex 这类 CLI Agent统一编排、统一配置的“脚手架”或者“控制台”。它要解决的核心痛点非常具体——现在每个人电脑上可能同时装了 Claude Code、Codex CLI甚至还想接本地模型比如通过 LM Studio 跑本地推理但每个工具的配置格式、启动方式、模型切换逻辑都不一样YAML 文件散落各处Node.js 版本还经常打架。openrig 想做的就是把这些零散的东西收拢到一个统一的 rig装备架上。我自己的实际场景是这样的主力用 Claude Code 写业务代码偶尔用 Codex 处理一些需要长上下文推理的任务本地还挂着一个 LM Studio 跑的小模型做隐私敏感的小活儿。三套工具三套配置每次换模型都要改环境变量、改 YAML、重启终端烦得要命。openrig 这类工具的价值就在于把这些重复劳动抽象掉用一份声明式的配置描述“我要用哪个模型、走哪个端点、用哪个 CLI”剩下的交给它去编排。所以这篇文章我不会只讲概念而是把 openrig 背后涉及的核心技术点——Node.js 运行时、YAML 配置、Claude Code 与 Codex 的接入方式、本地模型端点——全部拆开讲透让你看完能自己搭一套出来。适合谁看如果你已经在用 Claude Code 或者 Codex但被多工具配置搞得头大如果你想在 VS Code 里统一管理这些 CLI Agent如果你想把本地模型也纳入同一套工作流那这篇就是写给你的。哪怕你只是刚听说 Claude Code 想入门我也会把安装、配置、踩坑的细节讲清楚保证不同基础的人都能抄作业。2. 整体设计思路为什么是 Node.js YAML 这套组合2.1 为什么这类工具几乎都选 Node.js 作为运行时先说一个很多人忽略的事实Claude Code 和 Codex CLI 本身都是基于 Node.js 生态分发的。你去看它们的安装方式基本都是npm install -g或者通过 npx 直接跑。这不是巧合而是因为 Node.js 在“跨平台 CLI 工具分发”这件事上有天然优势——一套 JavaScript 代码Windows、macOS、Linux 都能跑npm 生态又能把依赖管理得明明白白。openrig 如果要做统一编排最省事的选择就是站在 Node.js 的肩膀上直接复用这套分发和依赖机制。但 Node.js 有个绕不开的坑版本。热搜词里那条error installing 24.21.0: node.js v24.21.0 is not yet released or is not available就是活生生的例子。很多人装 Node.js 时随手apt install nodejs结果装到的是系统源里那个老掉牙的版本跑 Claude Code 直接报错。我的建议很明确永远用 LTS 版本并且用版本管理器而不是系统包管理器。具体怎么装我在第 3 节会给出完整命令。2.2 YAML 为什么成了配置的事实标准再看 YAML。热搜词里yaml安装、yaml文件、yolov10 yaml文件怎么创建这些词混在一起说明很多人对 YAML 的认知还停留在“某个项目的配置文件格式”。但在 openrig 这类编排工具里YAML 承担的是“声明式描述整个运行环境”的角色。为什么不用 JSON因为 JSON 不能写注释而配置文件里注释极其重要——你得告诉未来的自己“这行是干嘛的”。为什么不用 TOMLTOML 表达嵌套结构时比较啰嗦而 openrig 要描述“多个工具、多个模型、多个端点”这种多层嵌套YAML 的缩进式结构读起来更直观。我举个实际对比。假设你要描述“Claude Code 用 A 模型走 B 端点Codex 用 C 模型走 D 端点”用 YAML 大概是这样tools: claude-code: model: claude-sonnet endpoint: http://localhost:1234/v1 codex: model: gpt-5.6-sol endpoint: https://api.example.com/v1同样的内容用 JSON 写光是引号和花括号就能让你看花眼而且没法加注释。这就是 YAML 在这类场景胜出的根本原因——它是给人读的不是给机器读的。当然 YAML 也有坑最大的坑就是缩进。YAML 用空格缩进表示层级Tab 和空格混用会直接报错而且报错信息往往指向一个莫名其妙的位置。我踩过最惨的一次是复制粘贴时混进了全角空格排查了半小时。所以记住第一条铁律YAML 文件里永远只用空格永远不用 Tab缩进统一用 2 个空格。2.3 openrig 的编排逻辑声明式优于命令式理解了 Node.js 和 YAML 的角色openrig 的整体设计思路就清晰了用 YAML 声明“我想要什么状态”用 Node.js 脚本去“达成这个状态”。这是典型的声明式设计和命令式一步步敲命令相比好处是配置可以版本化、可以复用、可以一键切换。比如你今天想用本地模型明天想用云端模型只需要改 YAML 里的一行然后重新跑一次 openrig 的同步命令不用手动去改每个工具的环境变量。这种设计还有一个隐藏好处可审计。当你的配置全部落在一个 YAML 文件里你能一眼看出“我到底用了哪些模型、哪些端点”。这在排查问题时价值巨大。热搜词里cc switch local proxy failed while handling codex endpoint /responses这种报错本质就是端点配置和实际请求路径对不上。如果配置是散落的你根本不知道去哪找如果集中在 YAML 里直接看 endpoint 那一行就定位了。3. 环境准备Node.js 与 YAML 工具链的正确安装姿势3.1 Node.js 安装别再用系统包管理器了我见过太多人卡在 Node.js 版本上。ubuntu安装node.js 20、node.js安装、node.js lts下载这些热搜词背后全是版本踩坑的血泪。系统自带的 apt 源里的 Node.js 版本通常落后好几个大版本而 Claude Code、Codex 这些工具对 Node.js 版本有硬性要求一般要求 18 以上推荐 20 LTS 或更高。正确做法是用 nvmNode Version Manager。在 Ubuntu 上curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash source ~/.bashrc nvm install 20 nvm use 20 nvm alias default 20最后那行nvm alias default 20很关键它保证你新开终端时默认用 20 版本而不是每次都要手动nvm use。装完验证node -v # 应该输出 v20.x.x npm -vWindows 用户直接用 nvm-windows或者去 Node.js 官网下载 LTS 安装包。这里要提醒一句热搜词里那个node.js v24.21.0 is not yet released的报错通常是因为你在某个配置文件里写死了一个不存在的版本号或者 nvm 的镜像源没同步。解决办法是nvm ls-remote看一下实际可用的版本别凭记忆写版本号。注意如果你之前用 apt 装过 Node.js先sudo apt remove nodejs npm卸干净否则 nvm 和系统版本会打架出现“明明 nvm 切了 20node -v还是 12”的诡异现象。3.2 YAML 工具链校验比编写更重要YAML 本身不需要“安装”它是文本格式。但你需要一个能校验 YAML 的工具否则写错了只能靠工具报错来猜。我推荐两个yamllint命令行校验能查出缩进、重复键、语法错误。安装pip install yamllint用法yamllint config.yaml。VS Code 的 YAML 插件实时高亮和错误提示写的时候就能发现缩进问题。为什么校验这么重要因为 YAML 的容错性极差。一个缩进错误可能导致整个配置被解析成完全不同的结构而工具报的错可能指向一个毫不相干的行号。我养成的习惯是每次改完 YAML先跑一遍 yamllint再让 openrig 去加载。这样能把“配置语法错误”和“工具逻辑错误”分开排查效率高很多。3.3 Claude Code 与 Codex 的安装前置检查在装 openrig 之前建议先把 Claude Code 和 Codex 单独装好、单独跑通。原因很简单如果单独都跑不起来套上 openrig 只会让问题更难定位。Claude Code 的安装一般是npm install -g anthropic-ai/claude-codeCodex 类似通过 npm 全局安装。装完先跑一次claude --version和codex --version确认能执行。热搜词里claude code安装、codex安装教程、codex安装包这些需求核心就是这一步。如果这一步报权限错误Linux/macOS 下加sudo或者更好的是配置 npm 的全局目录到用户目录下避免权限问题npm config set prefix ~/.npm-global export PATH~/.npm-global/bin:$PATH这样以后npm install -g就不需要 sudo 了也避免了全局包权限混乱。4. 核心配置解析用 YAML 把 Claude Code、Codex 和本地模型串起来4.1 openrig 配置文件的骨架长什么样基于这类编排工具的常见实践openrig 的配置文件假设叫openrig.yaml大致会包含几个顶层块运行时配置、工具定义、模型端点、以及可选的代理/转发设置。我按最可能的结构给你搭一个骨架你可以直接拿去改version: 1 runtime: node: 20 packageManager: npm endpoints: local-lmstudio: baseUrl: http://localhost:1234/v1 apiKey: not-needed cloud-default: baseUrl: https://api.example.com/v1 apiKey: ${CLOUD_API_KEY} tools: claude-code: enabled: true endpoint: local-lmstudio model: local-model-name extraArgs: - --verbose codex: enabled: true endpoint: cloud-default model: gpt-5.6-sol这个骨架里几个设计点值得说清楚。第一apiKey用${CLOUD_API_KEY}这种环境变量占位符而不是明文写死。这是安全底线配置文件很可能被提交到 Git明文密钥泄露是灾难性的。第二endpoints和tools分离好处是多个工具可以复用同一个端点改端点只改一处。第三extraArgs允许你给每个工具传额外的命令行参数保留了灵活性。4.2 端点配置本地模型和云端模型的差异处理热搜词里claude code 调用lmstudio的本地模型、codex接入deepseek这些本质都是“把工具的请求指向一个自定义端点”。这里有个关键技术点不同工具对端点的路径拼接规则不一样。有的工具会在 baseUrl 后面自动加/chat/completions有的加/responses有的什么都不加。热搜词里那个cc switch local proxy failed while handling codex endpoint /responses的报错就是路径拼接对不上导致的。我的处理经验是baseUrl 只写到/v1不要带后面的具体路径让工具自己去拼。如果工具拼错了再通过 openrig 的代理层做路径重写。LM Studio 的本地端点默认是http://localhost:1234/v1这个/v1必须保留因为它是 OpenAI 兼容 API 的版本标识。如果你写成了http://localhost:1234工具请求/v1/chat/completions时就会变成http://localhost:1234/v1/chat/completions——看起来对但如果工具本身会补/v1就变成/v1/v1/...了。所以配置完一定要用 curl 手动测一次curl http://localhost:1234/v1/models能返回模型列表说明端点通了。这一步能省掉后面 80% 的“连不上”问题。4.3 模型名称映射为什么模型名写错会报“不支持”热搜词里the gpt-5.6-sol model is not supported when using codex这个报错典型原因是模型名和端点实际提供的模型名不匹配。每个端点不管是云端还是本地都有自己的模型命名规则。LM Studio 里加载的模型名可能是qwen2.5-coder-7b-instruct但你在配置里写了个qwen-coder请求发过去端点不认识就报“不支持”。解决办法是先用/v1/models接口列出端点实际支持的模型名然后原样复制到配置里。别凭记忆写别简写。我一般会在 YAML 里加一行注释记录这个模型名的来源tools: codex: model: qwen2.5-coder-7b-instruct # 来自 localhost:1234/v1/models这样下次换模型时你知道去哪查正确的名字。4.4 环境变量与密钥管理前面提到用${VAR}占位符这里展开讲。openrig 在加载 YAML 时应该会把${VAR}替换成实际的环境变量值。所以你需要在一个不被提交的地方比如~/.bashrc或者一个.env文件设置这些变量export CLOUD_API_KEYyour-actual-key export LOCAL_ENDPOINThttp://localhost:1234/v1注意.env文件一定要加进.gitignore。我见过有人把带密钥的.env提交到公开仓库结果密钥被扫走账单直接爆掉。这种事一次就够记一辈子。5. 实操全流程从零跑通一套 openrig 编排5.1 第一步确认 Node.js 环境干净node -v npm -v which nodewhich node的输出应该是 nvm 管理的路径类似~/.nvm/versions/node/v20.x.x/bin/node而不是/usr/bin/node。如果是后者说明系统版本还在干扰回去执行 3.1 的卸载步骤。5.2 第二步安装 openrig 与相关 CLI假设 openrig 通过 npm 分发npm install -g openrig openrig --version同时确保 Claude Code 和 Codex 已装npm install -g anthropic-ai/claude-code npm install -g openai/codex装完分别验证版本。这一步如果报EACCES权限错误说明 npm 全局目录还是系统目录回去执行 3.3 的 prefix 配置。5.3 第三步编写并校验 openrig.yaml把 4.1 的骨架复制到~/.openrig/openrig.yaml按你的实际情况改端点和模型名。改完先校验yamllint ~/.openrig/openrig.yaml没有输出就是通过。有输出就按提示改缩进或语法。5.4 第四步启动本地模型端点如果用本地模型打开 LM Studio加载一个模型启动本地服务器默认端口 1234。然后curl http://localhost:1234/v1/models确认返回 JSON 里有你配置里写的模型名。如果没有要么模型没加载要么名字写错了。5.5 第五步让 openrig 同步配置并启动工具openrig sync openrig run claude-codesync的作用是把 YAML 里的配置“翻译”成各个工具能识别的环境变量或配置文件。run则是带着这套配置启动指定工具。如果一切正常Claude Code 应该会连到你配置的端点用你指定的模型。5.6 第六步验证请求真的走对了端点这一步很多人跳过结果出了问题不知道是配置没生效还是端点本身有问题。验证方法在 LM Studio 的日志窗口看有没有收到请求或者用openrig run codex --dry-run如果支持打印实际会发出的请求。我习惯在本地端点前面挂一个简单的日志代理把所有请求打出来这样一眼就能看出路径、模型名、请求体对不对。6. 常见问题与排查技巧实录6.1 端点连不上从 curl 开始逐层排查遇到“连不上”别急着改配置按这个顺序查排查层级检查命令预期结果网络层curl -v http://localhost:1234/v1/models返回 200 和模型列表配置层yamllint openrig.yaml无输出环境变量层echo $CLOUD_API_KEY输出实际密钥非空工具层openrig run claude-code --verbose打印实际请求 URL大部分“连不上”问题在第一步就暴露了——本地模型服务根本没启动或者端口不是 1234。6.2 模型不支持名字和端点必须严格对应前面讲过这里给一个速查表报错关键词根因解决model is not supported模型名与端点不匹配用/v1/models查实际名字endpoint /responses failed路径拼接错误baseUrl 只写到 /v1organization has disabled账号权限问题检查账号订阅状态proxy failed代理层配置错误检查代理转发规则6.3 YAML 缩进报错全角空格是隐形杀手这个坑我必须单独拎出来说。从网页或聊天窗口复制 YAML 时很容易混入全角空格U3000或不间断空格U00A0。这两种字符肉眼几乎看不出来但 YAML 解析器会直接报错而且报错行号经常是错的。排查方法grep -nP [\x{3000}\x{00A0}] openrig.yaml这条命令能揪出所有全角和不间断空格。找到后手动替换成普通空格。我现在养成的习惯是YAML 永远手打缩进绝不从别处复制。6.4 Node.js 版本冲突nvm 和系统版本打架症状是node -v显示的版本和你nvm use的不一致。根因是 PATH 里系统 Node.js 的路径排在 nvm 前面。检查echo $PATH | tr : \n | grep node如果/usr/bin排在~/.nvm前面就去~/.bashrc里把 nvm 的初始化脚本移到文件末尾保证它最后执行、优先级最高。6.5 密钥泄露配置文件提交前的最后一道检查在git add之前跑一遍grep -rn sk-\|api_key\|apikey . --include*.yaml --include*.env确认没有明文密钥。更好的做法是用 git 的 pre-commit hook 自动扫描。这个习惯能救命。7. 我踩过的坑和几条实在建议折腾这套东西大半年有几个体会是文档里不会写的。第一先把单个工具跑通再上编排。我一开始图省事直接配 openrig结果 Claude Code 连不上我花了两个小时排查 openrig 配置最后发现是 Claude Code 本身没装好。分层验证能省大量时间。第二本地模型的上下文窗口和云端差很多。你用云端模型时习惯了一次丢几千行代码进去换成本地 7B 模型可能直接爆上下文。配置里最好给每个工具单独设maxTokens之类的参数别指望一套参数通吃。第三YAML 里的注释是给未来的自己看的。每个非直觉的配置项旁边写一句为什么这么配三个月后你回来看会感谢自己。还有一点关于端点切换的热搜词里cc switch这类工具本质是帮你快速切换端点但切换后一定要重启对应的 CLI 进程。很多工具在启动时读取一次配置就缓存了你改了 YAML 不重启它还用旧的。openrig 的sync命令如果做了热重载最好没做的话就老老实实openrig run重新拉起。最后分享一个我常用的调试技巧在本地端点前面挂一个极简的日志转发脚本把所有请求的 URL、headers、body 打到文件里。这样任何“请求发出去但结果不对”的问题都能从日志里一眼看出是路径错了、模型名错了还是请求体格式错了。这个脚本用 Node.js 写也就二十行但排查效率提升是数量级的。