1. openrig 到底是个什么东西第一次看到 openrig 这个名字我下意识以为是某个硬件外设或者开源机械臂项目毕竟 rig 这个词在工程领域通常跟“装配、支架、设备”挂钩。但把 openrig 和 claude code、codex、yaml、node.js 这几个热搜词摆在一起看方向就清楚了——这是一个围绕 AI 编程助手做本地配置编排的工具核心思路是用一份 YAML 描述文件把 Claude Code、Codex 这类命令行 AI 编程工具的运行环境、模型接入、代理转发、参数覆盖统一管起来。说白了openrig 解决的是一个很具体的痛点现在搞 AI 辅助编程的人电脑上往往不止装一个工具。Claude Code 一套配置Codex 一套配置可能还有本地跑的 LM Studio、DeepSeek、Qwen、GLM 这些模型要接进来。每个工具都有自己的配置文件、环境变量、启动参数改来改去很容易乱。openrig 想做的事情就是让你写一份 YAML把“我要用哪个模型、走哪个端点、传什么参数、在哪个项目目录下生效”这些信息集中声明然后由它去驱动底层的 Node.js 运行时把对应的 CLI 工具拉起来。这篇文章适合谁看如果你已经在用或者准备用 Claude Code、Codex CLI 这类工具并且被多套配置、多模型切换、端点转发这些问题折腾过那 openrig 这套思路值得你花时间研究。如果你只是听说过这些工具还没上手也可以顺着往下看我会把 Node.js 环境、YAML 配置、CLI 工具安装这些前置环节一起讲清楚保证你能照着复现。需要先说明一点openrig 目前并不是一个像 VS Code 那样有庞大官方文档的成熟产品它更像是一个围绕 AI CLI 工具生态生长出来的配置编排层。所以下面很多内容是我基于这类工具常见的实现方式、以及 Claude Code、Codex 实际使用中踩过的坑做的合理推演和补充。你在实际使用时以你拿到的 openrig 版本的实际行为为准。2. 为什么需要 openrig 这层编排2.1 多工具多模型的配置地狱先说说没有 openrig 这类工具时大家是怎么干活的。假设你同时用 Claude Code 和 Codex还想在两者之间切换本地模型和第三方 API你的日常大概是这样Claude Code 要配ANTHROPIC_API_KEY、ANTHROPIC_BASE_URL可能还要通过 VS Code 插件配置Codex 要配自己的登录态、模型名、endpoint遇到cc switch local proxy failed while handling codex endpoint /responses这种报错还得去翻代理配置本地 LM Studio 要开一个 OpenAI 兼容端点端口通常是 1234DeepSeek、Qwen、GLM 各有各的 base_url 和 key。这些配置散落在 shell 的.zshrc、各工具的 config 目录、VS Code 的 settings.json 里。你想临时切个模型得改环境变量、重启终端、有时候还要重启编辑器。更麻烦的是不同项目可能要用不同模型——A 项目用 ClaudeB 项目用本地 Qwen 省钱C 项目用 DeepSeek 做代码补全。手动切来切去出错是迟早的事。openrig 的价值就在这里把这些“环境相关”的东西从各个工具的私有配置里抽出来收敛到一份 YAML 里。YAML 的好处是结构清晰、可读性强、方便版本管理你可以把不同项目的配置分别存成文件用的时候指定加载哪一份。2.2 为什么选 YAML 而不是 JSON 或 TOML这里有个选型问题值得展开。为什么这类工具偏爱 YAML我自己的体会是三点。第一YAML 支持注释。AI 工具的配置里经常需要标注“这个 key 从哪来的”“这个模型名对应哪个服务”JSON 不支持注释写起来很憋屈。第二YAML 的层级表达比 TOML 更灵活尤其是当你要描述“多个 provider、每个 provider 下有多个模型、每个模型有不同参数”这种嵌套结构时YAML 的缩进写法比 TOML 的[table.subtable]更直观。第三YAML 在 DevOps 圈子里已经是事实标准Kubernetes、GitHub Actions、Docker Compose 都用它大家看着眼熟学习成本低。当然 YAML 也有坑最大的坑就是缩进。用空格还是 Tab、缩进几个空格这些细节一旦搞错解析直接报错而且报错信息往往不告诉你具体哪一行有问题。后面我会专门讲怎么排查 YAML 语法错误。2.3 openrig 在技术栈里的位置把 openrig 放到整个链路里看它的位置大概是这样的你的项目代码 ↓ Claude Code / Codex CLIAI 编程助手 ↓ openrig配置编排层读 YAML注入环境变量和参数 ↓ Node.js 运行时这些 CLI 工具基本都是 Node 写的 ↓ 模型端点官方 API / 第三方 API / 本地 LM Studioopenrig 本身不产生智能它是个“调度员”。它读你的 YAML知道你要用哪个工具、哪个模型、哪个端点然后把这些信息组装成正确的启动命令和环境变量把工具拉起来。理解这一点很重要因为它决定了你排查问题时该往哪个方向看——如果模型回答不对问题可能在端点或 key如果工具根本起不来问题可能在 Node.js 环境或 YAML 解析。3. 前置环境Node.js 和 CLI 工具怎么装才不踩坑3.1 Node.js 版本选择与安装Claude Code、Codex CLI 这些都是 Node.js 写的所以 Node.js 是硬前置。这里第一个坑就是版本。热搜里有个报错很典型error installing 24.21.0: node.js v24.21.0 is not yet released or is not available。这说明有人试图装一个还不存在的版本号或者镜像源里没有这个版本。我的建议很明确用 LTS 版本别追最新。截至我写这篇内容时Node.js 的 LTS 线在 20.x 和 22.x这两个版本对绝大多数 AI CLI 工具都兼容。你去 Node.js 官网下载页面认准标着 LTS 的那个按钮别点 Current。安装方式分平台说Windows 用户直接下.msi安装包一路下一步就行。装完打开 PowerShell 敲node -v和npm -v能出版本号就成。注意 Windows 上有时会遇到权限问题如果 npm 全局安装报错用管理员身份开终端。macOS 用户我强烈建议用nvm或者fnm来管理 Node 版本别用官网 pkg 直接装。原因是你以后大概率会遇到“这个项目要 Node 18那个工具要 Node 20”的情况用版本管理器切换才不痛苦。用 Homebrew 的话brew install node20也行但同样不如 nvm 灵活。Ubuntu 用户可以用 NodeSource 的源或者干脆也用 nvm。用 apt 自带的 nodejs 包往往版本太老不建议。# 用 nvm 安装并切换到 Node 20 LTS nvm install 20 nvm use 20 node -v装完之后npm 的全局目录最好也确认一下。有些系统上 npm 全局包装完找不到命令是因为全局 bin 目录没在 PATH 里。npm config get prefix看一下前缀然后确认那个前缀下的 bin 目录在 PATH 中。3.2 Claude Code 和 Codex 的安装Node.js 就绪后装这两个工具本身通常就是一条 npm 命令的事。Claude Code 的安装命令大致是npm install -g anthropic-ai/claude-code这类形式Codex 也有对应的包。具体包名以官方文档为准因为这类工具更新很快包名和安装方式可能变。安装过程中常见的几个问题一是网络问题导致 npm 拉包失败。这时候可以换 npm 镜像源npm config set registry指向一个可用的镜像。注意这里说的是 npm 包镜像跟其他无关。二是权限问题。Linux 和 macOS 上如果不用 nvm 而是系统 Node全局安装经常要 sudo而 sudo 装出来的包又容易有权限混乱。这也是我推荐 nvm 的原因之一——nvm 装的 Node全局包目录在用户目录下不需要 sudo。三是装完之后命令找不到。先which claude或which codex看看有没有解析到路径。没有的话就是 PATH 问题把 npm 全局 bin 目录加进 PATH。3.3 VS Code 集成配置很多人是在 VS Code 里用这些工具的热搜里vscode配置claude code、claude code for vs code、vscode接入claude code都指向这个需求。VS Code 集成一般有两种方式一种是装官方或社区的扩展扩展内部调用 CLI另一种是直接在 VS Code 的集成终端里跑 CLI。我个人的偏好是后者——直接在终端里跑。原因是我对终端里的环境变量、工作目录有完全的控制权出问题好排查。扩展方式虽然界面友好但一旦配置出问题你很难知道它到底调了什么命令、传了什么参数。如果你要用扩展方式注意扩展的配置项和 CLI 的配置项可能是两套。比如你在 shell 里设了ANTHROPIC_BASE_URL但扩展可能读的是 VS Code settings.json 里的配置两者不互通。这是很多人“明明终端能用VS Code 里就不行”的根本原因。4. openrig 的 YAML 配置怎么写4.1 一份配置文件的骨架openrig 的核心是一份 YAML。虽然我没法给你官方 schema但基于这类工具的通用设计一份配置大概会包含这几个顶层字段工具选择、模型 provider 定义、端点地址、认证信息引用、启动参数、项目作用域。我按这个思路给你一个结构示例你可以对照你实际拿到的 openrig 文档调整字段名# openrig 配置示例 version: 1 # 默认使用哪个工具 default_tool: claude-code tools: claude-code: enabled: true model: claude-sonnet env: ANTHROPIC_BASE_URL: https://your-endpoint.example.com ANTHROPIC_API_KEY: ${CLAUDE_KEY} args: - --verbose codex: enabled: true model: gpt-5-codex env: OPENAI_BASE_URL: https://your-endpoint.example.com/v1 OPENAI_API_KEY: ${CODEX_KEY} providers: local-lmstudio: base_url: http://127.0.0.1:1234/v1 api_key: not-needed models: - qwen2.5-coder - deepseek-coder projects: my-app: path: ~/work/my-app tool: claude-code provider: local-lmstudio这份配置里几个设计点值得解释。${CLAUDE_KEY}这种写法是环境变量引用意思是“真正的 key 从环境变量里读不写死在 YAML 里”。这一点非常重要因为 YAML 文件很可能进 gitkey 写死在里面等于泄露。openrig 这类工具通常会支持这种变量插值。providers和tools分开定义是为了解耦。工具是“用什么客户端”provider 是“连哪个服务”。同一个工具可以连不同 provider同一个 provider 也能被不同工具用。这种解耦让你切换模型时只改一处。projects段落是给多项目场景准备的。你可以为每个项目指定默认工具和 provider进到那个目录就自动生效不用手动切。4.2 YAML 语法避坑指南YAML 写错是新手最高频的翻车点。我把最常见的几类错误列出来你写的时候对照检查。缩进必须用空格绝对不能用 Tab。这是铁律。很多编辑器默认 Tab 键插入的是 Tab 字符你得在编辑器设置里把它改成“插入空格”。VS Code 里右下角可以切换或者搜editor.insertSpaces设成 trueeditor.tabSize设成 2。冒号后面必须有空格。key:value是错的key: value才对。这个错误特别隐蔽因为有些解析器能容忍有些直接报错。字符串里的特殊字符要引号包裹。比如 URL 里有冒号base_url: http://...这种其实没问题但如果值以特殊符号开头或者包含#YAML 里#是注释符就必须加引号。api_key: abc#123不加引号的话#123会被当注释吃掉。列表项的短横线后面要有空格。-item是错的- item才对。多行字符串用|或。如果你要写一段带换行的 prompt 模板用|保留换行用折叠成一行。排查 YAML 错误有个笨办法但很有效把配置贴到在线的 YAML 校验器里它会告诉你具体哪一行哪一列出问题。本地的话Python 一行命令也能校验python3 -c import yaml,sys; yaml.safe_load(open(openrig.yaml)) echo YAML OK这条命令能过说明语法没问题报错的话错误信息里的行号就是你要看的地方。4.3 模型接入的几种典型场景openrig 配置里最核心的部分是模型接入。我按几种典型场景分别说。场景一接官方 API。最简单base_url 用官方地址key 用官方发的。注意有些工具默认就走官方你甚至不用配 base_url只配 key 就行。场景二接第三方兼容 API。热搜里codex接入deepseek、使用cc switch 接入 deepseek v4, qwen, glm等模型都是这个场景。关键点是第三方服务通常提供 OpenAI 兼容接口所以你要把 base_url 指向第三方的/v1路径key 用第三方发的。模型名要写第三方支持的模型标识不能写官方的模型名。场景三接本地 LM Studio。热搜里claude code 调用lmstudio的本地模型就是这个。LM Studio 启动本地服务后默认监听http://127.0.0.1:1234提供 OpenAI 兼容端点。配置时 base_url 写http://127.0.0.1:1234/v1api_key 随便填一个非空字符串本地服务通常不校验模型名写你在 LM Studio 里加载的模型标识。这里有个坑本地模型的上下文窗口往往比云端小如果你把 Claude Code 这种会塞大量上下文的工具指向本地小模型很容易爆上下文。解决办法是在配置里限制工具的上下文用量或者选一个上下文大一点的本地模型。场景四多 provider 切换。这是 openrig 相对手动配置的最大优势。你可以在 YAML 里定义好几个 provider然后通过命令行参数或者项目配置切换。比如openrig use local-lmstudio切到本地openrig use deepseek切到 DeepSeek。5. 实操从零把 openrig 跑起来5.1 环境检查清单动手之前先把这几项确认一遍能省掉后面一半的排查时间。检查项命令期望结果Node.js 版本node -vv20.x 或 v22.xnpm 版本npm -v10.x 左右npm 全局 bin 在 PATHecho $PATH包含 npm prefix 下的 binClaude Code 可用claude --version输出版本号Codex 可用codex --version输出版本号本地模型端点可达curl http://127.0.0.1:1234/v1/models返回模型列表 JSON最后那条 curl 特别重要。很多人配置写完发现工具连不上模型折腾半天其实本地服务根本没起来。先用 curl 确认端点活着再去看 openrig 配置。5.2 安装 openrig 并初始化openrig 的安装方式按这类工具的惯例大概率也是 npm 全局包或者是一个独立的二进制。假设是 npm 包npm install -g openrig openrig --version装完之后通常会有一个初始化命令帮你生成一份默认配置openrig init这个命令一般会在你的用户目录下创建一个配置目录比如~/.config/openrig/里面放一份config.yaml。也可能在当前项目目录下生成.openrig.yaml。具体行为看工具设计你跑完openrig init之后ls一下看多了什么文件就知道了。初始化之后第一件事是把默认配置里的占位符换成你自己的。别急着跑先打开配置文件通读一遍把 key、base_url、模型名这些改对。5.3 配置一个最小可用实例我建议第一次配置别贪多就配一个工具、一个 provider跑通了再加。下面是一个最小实例的思路。假设你要用 Claude Code 接本地 LM Studio 的 Qwen 模型。配置大概长这样version: 1 default_tool: claude-code tools: claude-code: env: ANTHROPIC_BASE_URL: http://127.0.0.1:1234/v1 ANTHROPIC_API_KEY: local model: qwen2.5-coder-7b这里有个技术细节要解释Claude Code 原生说的是 Anthropic 的 API 协议而 LM Studio 提供的是 OpenAI 兼容协议。这两套协议不完全一样。所以中间往往需要一个转换层把 Anthropic 格式的请求翻译成 OpenAI 格式。热搜里那个cc switch local proxy failed while handling codex endpoint /responses报错本质就是代理转换层在处理 Codex 的/responses端点时出了问题。openrig 如果内置了这个转换能力那你在配置里可能只需要声明“用 Anthropic 协议对接 OpenAI 兼容端点”它帮你转。如果没有内置你可能需要额外跑一个转换代理。这一点务必看你实际拿到的 openrig 文档确认。5.4 启动与验证配置写好后启动命令通常是openrig run # 或者指定工具 openrig run claude-code # 或者指定项目 openrig run --project my-app启动后工具应该会带着你配置的环境变量跑起来。验证方法是问它一个简单问题比如“你现在用的是哪个模型”。如果它回答的模型名跟你配置的一致说明链路通了。如果报错看错误信息指向哪一层。验证顺序建议自底向上先 curl 端点确认服务活着再确认环境变量注入正确可以在工具里执行env | grep ANTHROPIC看最后才怀疑 openrig 本身。6. 常见报错与排查实录6.1 端点与代理类报错cc switch local proxy failed while handling codex endpoint /responses这类报错关键词是“proxy failed”和“endpoint”。它告诉你代理层在处理某个端点时挂了。排查思路先确认端点路径对不对。Codex 用的端点路径可能跟 Claude Code 不一样一个走/v1/chat/completions一个走/responses或/v1/responses。如果你的转换代理只实现了前者后者就会 404 或 500。再确认请求体格式。不同工具发的请求体结构不同转换层要能正确解析。如果转换层版本旧了跟不上工具的新格式就会在处理时抛异常。解决办法是升级转换层或者换一个兼容性更好的方案。最后看代理日志。这类报错通常在代理的日志里有更详细的堆栈别只看工具端的报错去翻代理的日志。6.2 认证与权限类报错your organization has disabled claude subscription access for claude code这类报错是账号层面的权限问题不是配置问题。意思是你的账号所属组织关闭了 Claude Code 的订阅访问。这种只能找账号管理员解决或者换一个个人账号。配置层面怎么改都没用。codex无法加载组织设置类似也是账号或组织配置的问题。先确认你的登录态是有效的codex login重新走一遍认证流程。如果还不行就是服务端的事。6.3 模型不支持类报错the gpt-5.6-sol model is not supported when using codex with a...这种报错是模型名写错了或者你用的端点不支持这个模型。排查确认模型名拼写确认端点支持的模型列表curl/v1/models看确认你的账号有权限用这个模型。模型名这块有个常见误区不同 provider 对同一个模型的命名可能不同。官方叫gpt-4某个第三方可能叫gpt-4-turbo或者加前缀。以端点返回的模型列表为准别凭记忆写。6.4 排查速查表现象可能原因排查动作工具启动即报错Node 版本不对node -v确认 LTS配置读取失败YAML 语法错误用 yaml 校验器过一遍连不上模型端点没起或地址错curl 端点/v1/models认证失败key 错或权限不足检查 key、账号权限模型不存在模型名错或端点不支持查端点模型列表代理报错转换层不兼容看代理日志、升级转换层上下文爆掉本地模型窗口小换大窗口模型或限制上下文6.5 几个我踩过的坑第一个坑环境变量优先级。有些工具会同时读 shell 环境变量和配置文件两者冲突时谁赢不一定。我遇到过 shell 里设了旧的 base_url配置文件里写了新的结果工具用了旧的。排查时一定要env | grep确认实际生效的值。第二个坑YAML 里的布尔值。YAML 会把yes、no、on、off、true、false都解析成布尔值。如果你某个字段想写字符串no不加引号就变成布尔 false 了。这种坑很隐蔽因为不报错只是行为不对。第三个坑路径里的波浪号。~/work/my-app这种路径有些工具会正确展开成 home 目录有些不会直接当成字面量~目录。保险起见用绝对路径或者用${HOME}变量。第四个坑端口占用。本地模型服务默认端口可能跟别的服务冲突。起不来的时候lsof -i :1234看看谁占着。7. 进阶玩法与扩展思路7.1 多项目配置隔离当你手上项目多了一份全局配置不够用。openrig 这类工具通常支持项目级配置覆盖全局配置。你可以在项目根目录放一份.openrig.yaml里面只写跟全局不同的部分比如这个项目要用本地模型省钱那个项目要用云端模型保证质量。这种分层配置的设计跟 git 的.gitconfig加项目.git/config是一个思路。全局配置放通用设置项目配置放差异。加载时项目配置覆盖全局。7.2 把配置纳入版本管理YAML 配置的一大好处是可以进 git。但记住 key 不能进。做法是把配置里的敏感值都写成环境变量引用然后单独维护一个.env文件放真实 key.env加进.gitignore。这样团队协作时每个人 clone 下来配置自己填自己的.env配置结构共享敏感信息隔离。7.3 结合本地模型做成本控制如果你用 AI 编程工具的频率很高云端 API 的费用会累积得很快。一个实用的策略是日常的代码补全、简单问答走本地模型复杂的架构设计、疑难 bug 排查走云端模型。openrig 的多 provider 切换正好支持这种策略你甚至可以根据任务类型预设几套配置一键切换。本地模型的选择上代码类任务优先选专门做代码的模型比如 Qwen 的 coder 系列、DeepSeek 的 coder 系列。这些模型在代码补全上的表现比通用模型好而且参数量小一点的版本在消费级显卡上就能跑。7.4 自动化与脚本化openrig 的配置既然是文件就可以被脚本操作。你可以写个脚本根据当前目录自动选择配置或者根据时间段切换白天用云端保证效率晚上跑批用本地省钱。这类自动化能把你从手动切换里彻底解放出来。我自己的做法是给常用的几套配置起短名字然后用 shell 别名快速切换。比如alias or-localopenrig use local-lmstudio敲三个字母就切过去了。8. 关于 openrig 这类工具的一点个人判断用了这段时间我对 openrig 这类配置编排工具的看法是它的价值不在技术有多高深而在于它把散落各处的配置收敛到了一处。AI 编程工具这个领域现在更新极快今天这个工具火明天那个模型强配置方式三天两头变。在这种快速变化的环境里有一个统一的配置层能让你在换工具、换模型的时候少折腾很多。但它也有局限。它管的是配置管不了工具本身的兼容性。比如某个工具突然改了 API 协议转换层跟不上openrig 也救不了你。所以别指望它能解决所有问题它只是把你从“配置地狱”里捞出来剩下的坑还得自己踩。另外这类工具目前生态还比较早期文档可能不全字段名可能变行为可能跟预期有出入。我的建议是先跑通最小实例再逐步加功能。每加一个配置项就验证一次别一次性写一大坨然后一起调试那样出问题你根本不知道是哪一项导致的。最后分享一个我自己的习惯每次改完配置先openrig config validate之类的命令校验一遍如果有这个命令的话再启动工具。校验能过说明语法和基本结构没问题剩下的就是运行时的事了。这个习惯帮我省了不少“改了配置忘了存”或者“缩进错了”的低级排查时间。 
长河君 · 2026/10/3 18:07:43 · 阅读 1.2k openrig 配置编排：用 YAML 统一管理 Claude Code 与 Codex 多模型接入
1. openrig 到底是个什么东西第一次看到 openrig 这个名字我下意识以为是某个硬件外设或者开源机械臂项目毕竟 rig 这个词在工程领域通常跟“装配、支架、设备”挂钩。但把 openrig 和 claude code、codex、yaml、node.js 这几个热搜词摆在一起看方向就清楚了——这是一个围绕 AI 编程助手做本地配置编排的工具核心思路是用一份 YAML 描述文件把 Claude Code、Codex 这类命令行 AI 编程工具的运行环境、模型接入、代理转发、参数覆盖统一管起来。说白了openrig 解决的是一个很具体的痛点现在搞 AI 辅助编程的人电脑上往往不止装一个工具。Claude Code 一套配置Codex 一套配置可能还有本地跑的 LM Studio、DeepSeek、Qwen、GLM 这些模型要接进来。每个工具都有自己的配置文件、环境变量、启动参数改来改去很容易乱。openrig 想做的事情就是让你写一份 YAML把“我要用哪个模型、走哪个端点、传什么参数、在哪个项目目录下生效”这些信息集中声明然后由它去驱动底层的 Node.js 运行时把对应的 CLI 工具拉起来。这篇文章适合谁看如果你已经在用或者准备用 Claude Code、Codex CLI 这类工具并且被多套配置、多模型切换、端点转发这些问题折腾过那 openrig 这套思路值得你花时间研究。如果你只是听说过这些工具还没上手也可以顺着往下看我会把 Node.js 环境、YAML 配置、CLI 工具安装这些前置环节一起讲清楚保证你能照着复现。需要先说明一点openrig 目前并不是一个像 VS Code 那样有庞大官方文档的成熟产品它更像是一个围绕 AI CLI 工具生态生长出来的配置编排层。所以下面很多内容是我基于这类工具常见的实现方式、以及 Claude Code、Codex 实际使用中踩过的坑做的合理推演和补充。你在实际使用时以你拿到的 openrig 版本的实际行为为准。2. 为什么需要 openrig 这层编排2.1 多工具多模型的配置地狱先说说没有 openrig 这类工具时大家是怎么干活的。假设你同时用 Claude Code 和 Codex还想在两者之间切换本地模型和第三方 API你的日常大概是这样Claude Code 要配ANTHROPIC_API_KEY、ANTHROPIC_BASE_URL可能还要通过 VS Code 插件配置Codex 要配自己的登录态、模型名、endpoint遇到cc switch local proxy failed while handling codex endpoint /responses这种报错还得去翻代理配置本地 LM Studio 要开一个 OpenAI 兼容端点端口通常是 1234DeepSeek、Qwen、GLM 各有各的 base_url 和 key。这些配置散落在 shell 的.zshrc、各工具的 config 目录、VS Code 的 settings.json 里。你想临时切个模型得改环境变量、重启终端、有时候还要重启编辑器。更麻烦的是不同项目可能要用不同模型——A 项目用 ClaudeB 项目用本地 Qwen 省钱C 项目用 DeepSeek 做代码补全。手动切来切去出错是迟早的事。openrig 的价值就在这里把这些“环境相关”的东西从各个工具的私有配置里抽出来收敛到一份 YAML 里。YAML 的好处是结构清晰、可读性强、方便版本管理你可以把不同项目的配置分别存成文件用的时候指定加载哪一份。2.2 为什么选 YAML 而不是 JSON 或 TOML这里有个选型问题值得展开。为什么这类工具偏爱 YAML我自己的体会是三点。第一YAML 支持注释。AI 工具的配置里经常需要标注“这个 key 从哪来的”“这个模型名对应哪个服务”JSON 不支持注释写起来很憋屈。第二YAML 的层级表达比 TOML 更灵活尤其是当你要描述“多个 provider、每个 provider 下有多个模型、每个模型有不同参数”这种嵌套结构时YAML 的缩进写法比 TOML 的[table.subtable]更直观。第三YAML 在 DevOps 圈子里已经是事实标准Kubernetes、GitHub Actions、Docker Compose 都用它大家看着眼熟学习成本低。当然 YAML 也有坑最大的坑就是缩进。用空格还是 Tab、缩进几个空格这些细节一旦搞错解析直接报错而且报错信息往往不告诉你具体哪一行有问题。后面我会专门讲怎么排查 YAML 语法错误。2.3 openrig 在技术栈里的位置把 openrig 放到整个链路里看它的位置大概是这样的你的项目代码 ↓ Claude Code / Codex CLIAI 编程助手 ↓ openrig配置编排层读 YAML注入环境变量和参数 ↓ Node.js 运行时这些 CLI 工具基本都是 Node 写的 ↓ 模型端点官方 API / 第三方 API / 本地 LM Studioopenrig 本身不产生智能它是个“调度员”。它读你的 YAML知道你要用哪个工具、哪个模型、哪个端点然后把这些信息组装成正确的启动命令和环境变量把工具拉起来。理解这一点很重要因为它决定了你排查问题时该往哪个方向看——如果模型回答不对问题可能在端点或 key如果工具根本起不来问题可能在 Node.js 环境或 YAML 解析。3. 前置环境Node.js 和 CLI 工具怎么装才不踩坑3.1 Node.js 版本选择与安装Claude Code、Codex CLI 这些都是 Node.js 写的所以 Node.js 是硬前置。这里第一个坑就是版本。热搜里有个报错很典型error installing 24.21.0: node.js v24.21.0 is not yet released or is not available。这说明有人试图装一个还不存在的版本号或者镜像源里没有这个版本。我的建议很明确用 LTS 版本别追最新。截至我写这篇内容时Node.js 的 LTS 线在 20.x 和 22.x这两个版本对绝大多数 AI CLI 工具都兼容。你去 Node.js 官网下载页面认准标着 LTS 的那个按钮别点 Current。安装方式分平台说Windows 用户直接下.msi安装包一路下一步就行。装完打开 PowerShell 敲node -v和npm -v能出版本号就成。注意 Windows 上有时会遇到权限问题如果 npm 全局安装报错用管理员身份开终端。macOS 用户我强烈建议用nvm或者fnm来管理 Node 版本别用官网 pkg 直接装。原因是你以后大概率会遇到“这个项目要 Node 18那个工具要 Node 20”的情况用版本管理器切换才不痛苦。用 Homebrew 的话brew install node20也行但同样不如 nvm 灵活。Ubuntu 用户可以用 NodeSource 的源或者干脆也用 nvm。用 apt 自带的 nodejs 包往往版本太老不建议。# 用 nvm 安装并切换到 Node 20 LTS nvm install 20 nvm use 20 node -v装完之后npm 的全局目录最好也确认一下。有些系统上 npm 全局包装完找不到命令是因为全局 bin 目录没在 PATH 里。npm config get prefix看一下前缀然后确认那个前缀下的 bin 目录在 PATH 中。3.2 Claude Code 和 Codex 的安装Node.js 就绪后装这两个工具本身通常就是一条 npm 命令的事。Claude Code 的安装命令大致是npm install -g anthropic-ai/claude-code这类形式Codex 也有对应的包。具体包名以官方文档为准因为这类工具更新很快包名和安装方式可能变。安装过程中常见的几个问题一是网络问题导致 npm 拉包失败。这时候可以换 npm 镜像源npm config set registry指向一个可用的镜像。注意这里说的是 npm 包镜像跟其他无关。二是权限问题。Linux 和 macOS 上如果不用 nvm 而是系统 Node全局安装经常要 sudo而 sudo 装出来的包又容易有权限混乱。这也是我推荐 nvm 的原因之一——nvm 装的 Node全局包目录在用户目录下不需要 sudo。三是装完之后命令找不到。先which claude或which codex看看有没有解析到路径。没有的话就是 PATH 问题把 npm 全局 bin 目录加进 PATH。3.3 VS Code 集成配置很多人是在 VS Code 里用这些工具的热搜里vscode配置claude code、claude code for vs code、vscode接入claude code都指向这个需求。VS Code 集成一般有两种方式一种是装官方或社区的扩展扩展内部调用 CLI另一种是直接在 VS Code 的集成终端里跑 CLI。我个人的偏好是后者——直接在终端里跑。原因是我对终端里的环境变量、工作目录有完全的控制权出问题好排查。扩展方式虽然界面友好但一旦配置出问题你很难知道它到底调了什么命令、传了什么参数。如果你要用扩展方式注意扩展的配置项和 CLI 的配置项可能是两套。比如你在 shell 里设了ANTHROPIC_BASE_URL但扩展可能读的是 VS Code settings.json 里的配置两者不互通。这是很多人“明明终端能用VS Code 里就不行”的根本原因。4. openrig 的 YAML 配置怎么写4.1 一份配置文件的骨架openrig 的核心是一份 YAML。虽然我没法给你官方 schema但基于这类工具的通用设计一份配置大概会包含这几个顶层字段工具选择、模型 provider 定义、端点地址、认证信息引用、启动参数、项目作用域。我按这个思路给你一个结构示例你可以对照你实际拿到的 openrig 文档调整字段名# openrig 配置示例 version: 1 # 默认使用哪个工具 default_tool: claude-code tools: claude-code: enabled: true model: claude-sonnet env: ANTHROPIC_BASE_URL: https://your-endpoint.example.com ANTHROPIC_API_KEY: ${CLAUDE_KEY} args: - --verbose codex: enabled: true model: gpt-5-codex env: OPENAI_BASE_URL: https://your-endpoint.example.com/v1 OPENAI_API_KEY: ${CODEX_KEY} providers: local-lmstudio: base_url: http://127.0.0.1:1234/v1 api_key: not-needed models: - qwen2.5-coder - deepseek-coder projects: my-app: path: ~/work/my-app tool: claude-code provider: local-lmstudio这份配置里几个设计点值得解释。${CLAUDE_KEY}这种写法是环境变量引用意思是“真正的 key 从环境变量里读不写死在 YAML 里”。这一点非常重要因为 YAML 文件很可能进 gitkey 写死在里面等于泄露。openrig 这类工具通常会支持这种变量插值。providers和tools分开定义是为了解耦。工具是“用什么客户端”provider 是“连哪个服务”。同一个工具可以连不同 provider同一个 provider 也能被不同工具用。这种解耦让你切换模型时只改一处。projects段落是给多项目场景准备的。你可以为每个项目指定默认工具和 provider进到那个目录就自动生效不用手动切。4.2 YAML 语法避坑指南YAML 写错是新手最高频的翻车点。我把最常见的几类错误列出来你写的时候对照检查。缩进必须用空格绝对不能用 Tab。这是铁律。很多编辑器默认 Tab 键插入的是 Tab 字符你得在编辑器设置里把它改成“插入空格”。VS Code 里右下角可以切换或者搜editor.insertSpaces设成 trueeditor.tabSize设成 2。冒号后面必须有空格。key:value是错的key: value才对。这个错误特别隐蔽因为有些解析器能容忍有些直接报错。字符串里的特殊字符要引号包裹。比如 URL 里有冒号base_url: http://...这种其实没问题但如果值以特殊符号开头或者包含#YAML 里#是注释符就必须加引号。api_key: abc#123不加引号的话#123会被当注释吃掉。列表项的短横线后面要有空格。-item是错的- item才对。多行字符串用|或。如果你要写一段带换行的 prompt 模板用|保留换行用折叠成一行。排查 YAML 错误有个笨办法但很有效把配置贴到在线的 YAML 校验器里它会告诉你具体哪一行哪一列出问题。本地的话Python 一行命令也能校验python3 -c import yaml,sys; yaml.safe_load(open(openrig.yaml)) echo YAML OK这条命令能过说明语法没问题报错的话错误信息里的行号就是你要看的地方。4.3 模型接入的几种典型场景openrig 配置里最核心的部分是模型接入。我按几种典型场景分别说。场景一接官方 API。最简单base_url 用官方地址key 用官方发的。注意有些工具默认就走官方你甚至不用配 base_url只配 key 就行。场景二接第三方兼容 API。热搜里codex接入deepseek、使用cc switch 接入 deepseek v4, qwen, glm等模型都是这个场景。关键点是第三方服务通常提供 OpenAI 兼容接口所以你要把 base_url 指向第三方的/v1路径key 用第三方发的。模型名要写第三方支持的模型标识不能写官方的模型名。场景三接本地 LM Studio。热搜里claude code 调用lmstudio的本地模型就是这个。LM Studio 启动本地服务后默认监听http://127.0.0.1:1234提供 OpenAI 兼容端点。配置时 base_url 写http://127.0.0.1:1234/v1api_key 随便填一个非空字符串本地服务通常不校验模型名写你在 LM Studio 里加载的模型标识。这里有个坑本地模型的上下文窗口往往比云端小如果你把 Claude Code 这种会塞大量上下文的工具指向本地小模型很容易爆上下文。解决办法是在配置里限制工具的上下文用量或者选一个上下文大一点的本地模型。场景四多 provider 切换。这是 openrig 相对手动配置的最大优势。你可以在 YAML 里定义好几个 provider然后通过命令行参数或者项目配置切换。比如openrig use local-lmstudio切到本地openrig use deepseek切到 DeepSeek。5. 实操从零把 openrig 跑起来5.1 环境检查清单动手之前先把这几项确认一遍能省掉后面一半的排查时间。检查项命令期望结果Node.js 版本node -vv20.x 或 v22.xnpm 版本npm -v10.x 左右npm 全局 bin 在 PATHecho $PATH包含 npm prefix 下的 binClaude Code 可用claude --version输出版本号Codex 可用codex --version输出版本号本地模型端点可达curl http://127.0.0.1:1234/v1/models返回模型列表 JSON最后那条 curl 特别重要。很多人配置写完发现工具连不上模型折腾半天其实本地服务根本没起来。先用 curl 确认端点活着再去看 openrig 配置。5.2 安装 openrig 并初始化openrig 的安装方式按这类工具的惯例大概率也是 npm 全局包或者是一个独立的二进制。假设是 npm 包npm install -g openrig openrig --version装完之后通常会有一个初始化命令帮你生成一份默认配置openrig init这个命令一般会在你的用户目录下创建一个配置目录比如~/.config/openrig/里面放一份config.yaml。也可能在当前项目目录下生成.openrig.yaml。具体行为看工具设计你跑完openrig init之后ls一下看多了什么文件就知道了。初始化之后第一件事是把默认配置里的占位符换成你自己的。别急着跑先打开配置文件通读一遍把 key、base_url、模型名这些改对。5.3 配置一个最小可用实例我建议第一次配置别贪多就配一个工具、一个 provider跑通了再加。下面是一个最小实例的思路。假设你要用 Claude Code 接本地 LM Studio 的 Qwen 模型。配置大概长这样version: 1 default_tool: claude-code tools: claude-code: env: ANTHROPIC_BASE_URL: http://127.0.0.1:1234/v1 ANTHROPIC_API_KEY: local model: qwen2.5-coder-7b这里有个技术细节要解释Claude Code 原生说的是 Anthropic 的 API 协议而 LM Studio 提供的是 OpenAI 兼容协议。这两套协议不完全一样。所以中间往往需要一个转换层把 Anthropic 格式的请求翻译成 OpenAI 格式。热搜里那个cc switch local proxy failed while handling codex endpoint /responses报错本质就是代理转换层在处理 Codex 的/responses端点时出了问题。openrig 如果内置了这个转换能力那你在配置里可能只需要声明“用 Anthropic 协议对接 OpenAI 兼容端点”它帮你转。如果没有内置你可能需要额外跑一个转换代理。这一点务必看你实际拿到的 openrig 文档确认。5.4 启动与验证配置写好后启动命令通常是openrig run # 或者指定工具 openrig run claude-code # 或者指定项目 openrig run --project my-app启动后工具应该会带着你配置的环境变量跑起来。验证方法是问它一个简单问题比如“你现在用的是哪个模型”。如果它回答的模型名跟你配置的一致说明链路通了。如果报错看错误信息指向哪一层。验证顺序建议自底向上先 curl 端点确认服务活着再确认环境变量注入正确可以在工具里执行env | grep ANTHROPIC看最后才怀疑 openrig 本身。6. 常见报错与排查实录6.1 端点与代理类报错cc switch local proxy failed while handling codex endpoint /responses这类报错关键词是“proxy failed”和“endpoint”。它告诉你代理层在处理某个端点时挂了。排查思路先确认端点路径对不对。Codex 用的端点路径可能跟 Claude Code 不一样一个走/v1/chat/completions一个走/responses或/v1/responses。如果你的转换代理只实现了前者后者就会 404 或 500。再确认请求体格式。不同工具发的请求体结构不同转换层要能正确解析。如果转换层版本旧了跟不上工具的新格式就会在处理时抛异常。解决办法是升级转换层或者换一个兼容性更好的方案。最后看代理日志。这类报错通常在代理的日志里有更详细的堆栈别只看工具端的报错去翻代理的日志。6.2 认证与权限类报错your organization has disabled claude subscription access for claude code这类报错是账号层面的权限问题不是配置问题。意思是你的账号所属组织关闭了 Claude Code 的订阅访问。这种只能找账号管理员解决或者换一个个人账号。配置层面怎么改都没用。codex无法加载组织设置类似也是账号或组织配置的问题。先确认你的登录态是有效的codex login重新走一遍认证流程。如果还不行就是服务端的事。6.3 模型不支持类报错the gpt-5.6-sol model is not supported when using codex with a...这种报错是模型名写错了或者你用的端点不支持这个模型。排查确认模型名拼写确认端点支持的模型列表curl/v1/models看确认你的账号有权限用这个模型。模型名这块有个常见误区不同 provider 对同一个模型的命名可能不同。官方叫gpt-4某个第三方可能叫gpt-4-turbo或者加前缀。以端点返回的模型列表为准别凭记忆写。6.4 排查速查表现象可能原因排查动作工具启动即报错Node 版本不对node -v确认 LTS配置读取失败YAML 语法错误用 yaml 校验器过一遍连不上模型端点没起或地址错curl 端点/v1/models认证失败key 错或权限不足检查 key、账号权限模型不存在模型名错或端点不支持查端点模型列表代理报错转换层不兼容看代理日志、升级转换层上下文爆掉本地模型窗口小换大窗口模型或限制上下文6.5 几个我踩过的坑第一个坑环境变量优先级。有些工具会同时读 shell 环境变量和配置文件两者冲突时谁赢不一定。我遇到过 shell 里设了旧的 base_url配置文件里写了新的结果工具用了旧的。排查时一定要env | grep确认实际生效的值。第二个坑YAML 里的布尔值。YAML 会把yes、no、on、off、true、false都解析成布尔值。如果你某个字段想写字符串no不加引号就变成布尔 false 了。这种坑很隐蔽因为不报错只是行为不对。第三个坑路径里的波浪号。~/work/my-app这种路径有些工具会正确展开成 home 目录有些不会直接当成字面量~目录。保险起见用绝对路径或者用${HOME}变量。第四个坑端口占用。本地模型服务默认端口可能跟别的服务冲突。起不来的时候lsof -i :1234看看谁占着。7. 进阶玩法与扩展思路7.1 多项目配置隔离当你手上项目多了一份全局配置不够用。openrig 这类工具通常支持项目级配置覆盖全局配置。你可以在项目根目录放一份.openrig.yaml里面只写跟全局不同的部分比如这个项目要用本地模型省钱那个项目要用云端模型保证质量。这种分层配置的设计跟 git 的.gitconfig加项目.git/config是一个思路。全局配置放通用设置项目配置放差异。加载时项目配置覆盖全局。7.2 把配置纳入版本管理YAML 配置的一大好处是可以进 git。但记住 key 不能进。做法是把配置里的敏感值都写成环境变量引用然后单独维护一个.env文件放真实 key.env加进.gitignore。这样团队协作时每个人 clone 下来配置自己填自己的.env配置结构共享敏感信息隔离。7.3 结合本地模型做成本控制如果你用 AI 编程工具的频率很高云端 API 的费用会累积得很快。一个实用的策略是日常的代码补全、简单问答走本地模型复杂的架构设计、疑难 bug 排查走云端模型。openrig 的多 provider 切换正好支持这种策略你甚至可以根据任务类型预设几套配置一键切换。本地模型的选择上代码类任务优先选专门做代码的模型比如 Qwen 的 coder 系列、DeepSeek 的 coder 系列。这些模型在代码补全上的表现比通用模型好而且参数量小一点的版本在消费级显卡上就能跑。7.4 自动化与脚本化openrig 的配置既然是文件就可以被脚本操作。你可以写个脚本根据当前目录自动选择配置或者根据时间段切换白天用云端保证效率晚上跑批用本地省钱。这类自动化能把你从手动切换里彻底解放出来。我自己的做法是给常用的几套配置起短名字然后用 shell 别名快速切换。比如alias or-localopenrig use local-lmstudio敲三个字母就切过去了。8. 关于 openrig 这类工具的一点个人判断用了这段时间我对 openrig 这类配置编排工具的看法是它的价值不在技术有多高深而在于它把散落各处的配置收敛到了一处。AI 编程工具这个领域现在更新极快今天这个工具火明天那个模型强配置方式三天两头变。在这种快速变化的环境里有一个统一的配置层能让你在换工具、换模型的时候少折腾很多。但它也有局限。它管的是配置管不了工具本身的兼容性。比如某个工具突然改了 API 协议转换层跟不上openrig 也救不了你。所以别指望它能解决所有问题它只是把你从“配置地狱”里捞出来剩下的坑还得自己踩。另外这类工具目前生态还比较早期文档可能不全字段名可能变行为可能跟预期有出入。我的建议是先跑通最小实例再逐步加功能。每加一个配置项就验证一次别一次性写一大坨然后一起调试那样出问题你根本不知道是哪一项导致的。最后分享一个我自己的习惯每次改完配置先openrig config validate之类的命令校验一遍如果有这个命令的话再启动工具。校验能过说明语法和基本结构没问题剩下的就是运行时的事了。这个习惯帮我省了不少“改了配置忘了存”或者“缩进错了”的低级排查时间。