1. 从 openrig 说起一个把 Claude Code 和 Codex 装进统一工作流的工具第一次看到openrig这个名字我下意识把它拆成了 open 和 rig 两个词——rig 在工程语境里通常指装配、搭建一套设备或环境合起来大概就是开放式的工具装配架。事实也确实如此它想解决的核心问题是当下同时使用 Claude Code 和 Codex 这两类命令行 AI 编程助手的开发者普遍面临的一个尴尬——每个工具都有自己的配置格式、自己的启动方式、自己的模型接入逻辑切换一次就要重新折腾一遍环境。如果你最近在折腾 Claude Code 或者 Codex大概率踩过这些坑npm全局安装报无法加载文件 npm.ps1因为在此系统上禁止运行脚本、codex登录后提示无法加载组织设置、想接本地模型却卡在 endpoint 配置上、YAML 文件写错一个缩进整个流程跑不起来。这些零散的痛点本质上都是工具链没有统一装配层导致的。openrig的定位就是充当这一层装配架用一份 YAML 描述你的工具、模型、代理和启动参数然后由它统一拉起 Claude Code、Codex 或者其他 CLI 助手。这篇文章适合三类人看一是刚接触 Claude Code、Codex被安装和配置卡住的新手二是已经在用但想把手头多个 AI 编程工具统一管理的进阶用户三是想理解YAML 驱动 npm 分发这套组合拳背后设计逻辑的工程实践者。我会从整体设计思路讲到具体实操把安装、配置、模型接入、常见报错排查全部拆开讲清楚尽量让你看完就能照着搭一套自己的环境。需要先说明一点openrig本身是一个相对小众的工具网络上公开的完整文档并不多所以文中涉及的具体配置项、参数命名我会基于一个合格的工具装配层在这个场景下最合理的做法来补全并在关键处标注哪些是通用实践、哪些需要你以实际版本为准。这样即使版本迭代你也能理解背后的逻辑而不是死记命令。2. 整体设计思路为什么是 YAML npm 这套组合2.1 统一装配层的核心价值在聊具体怎么用之前得先想明白一个问题为什么需要一个装配层直接分别装 Claude Code 和 Codex 不行吗行但代价是重复劳动。Claude Code 和 Codex 虽然都是 CLI 形态的 AI 编程助手但它们的配置体系是割裂的。Claude Code 有自己的配置目录和模型接入方式Codex 有另一套登录和 endpoint 逻辑。你要接本地模型比如通过 LM Studio 暴露的本地推理服务两边要各配一遍你要切换国内镜像源加速 npm 安装两边又各折腾一遍。工具越多这种重复成本越高。openrig的思路是把这些共性抽出来模型接入、代理设置、启动参数、环境变量全部收敛到一份 YAML 里。YAML 的好处是结构清晰、可读性强、天然支持嵌套非常适合描述一个工具由哪些部分组成这种层级关系。你写一次配置openrig负责把它翻译成各个工具能识别的格式再分别拉起进程。提示YAML 对缩进极其敏感用空格不用 Tab这是后面所有配置能跑通的前提。很多人第一次写 YAML 失败90% 是缩进问题。2.2 为什么用 npm 分发openrig选择 npm 作为分发渠道这个决策其实很务实。Claude Code 和 Codex 的官方安装方式本身就大量依赖 npm用户群体天然装了 Node.js 环境。用 npm 分发意味着安装命令统一成npm install -g openrig这种形式用户不用学新的包管理器版本管理交给 npm升级、回滚都是一条命令可以借助 npm 的镜像源机制在国内网络环境下也能较快安装。但 npm 也带来了一堆经典问题比如 Windows 上的 PowerShell 执行策略限制、全局包路径没进 PATH、peer dependency 冲突警告等。这些不是openrig独有的而是所有 npm 全局工具的通病后面我会专门用一节讲怎么排查。2.3 与 Claude Code、Codex 的关系定位这里要理清一个容易混淆的点openrig不是 Claude Code 或 Codex 的替代品也不是它们的插件而是一个外层的编排器。它不参与实际的代码生成和对话只负责把环境准备好、把进程拉起来、把参数传对。打个比方Claude Code 和 Codex 是两台不同品牌的机床openrig是车间的总控台。总控台不加工零件但它知道每台机床该用什么电压、该装什么刀具、该按什么顺序启动。你换一台机床只需要在总控台上改一行配置而不用重新布线。理解了这层定位后面所有的配置项就都好理解了——它们本质上都是在回答这台机床需要什么。3. 环境准备Node、npm 与镜像源的正确姿势3.1 Node.js 版本选择与安装openrig依赖 Node.js 运行Claude Code 和 Codex 的 CLI 也大多基于 Node。版本上建议用Node 18 LTS 或更高因为较新的 CLI 工具普遍用到了较新的 ES 特性和 fetch APINode 16 及以下容易出兼容问题。安装方式上Windows 用户我强烈建议用官方安装包或者nvm-windows而不是某些第三方打包版。原因很简单官方安装包会自动把 Node 和 npm 的路径写进系统 PATH省掉后面手动配环境变量的麻烦。用nvm-windows的好处是可以随时切换 Node 版本遇到某个工具只兼容特定版本时特别有用。macOS 和 Linux 用户用nvm或者系统包管理器都行。用nvm的话装完记得确认node -v和npm -v都能正常输出版本号。3.2 npm 国内镜像源配置国内网络环境下npm 默认源拉包经常慢到让人怀疑人生。换镜像源是最直接的加速手段。常用的是淘宝源现在叫 npmmirrornpm config set registry https://registry.npmmirror.com设置完可以用npm config get registry确认。想临时用一次而不改全局配置可以在命令后加--registry参数。注意镜像源偶尔会有同步延迟某个包刚发布时镜像上可能还没有。遇到找不到包的报错先试试切回官方源https://registry.npmjs.org再装一次确认是不是同步问题。3.3 Windows PowerShell 执行策略这个经典坑如果你在 Windows 上执行 npm 命令时看到这样的报错npm : 无法加载文件 C:\Program Files\nodejs\npm.ps1因为在此系统上禁止运行脚本这不是 npm 坏了而是 PowerShell 的执行策略默认禁止运行脚本文件。解决办法是以管理员身份打开 PowerShell执行Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSignedRemoteSigned的含义是本地写的脚本可以直接跑从网络下载的脚本需要有签名。这个策略在安全性和便利性之间比较平衡是官方推荐给开发者的设置。执行完关掉 PowerShell 重开一个窗口再试 npm 命令就正常了。如果你不想改执行策略也可以改用 CMD 而不是 PowerShell 来执行命令CMD 不受这个策略限制。但长期看改策略更省事。3.4 全局包路径与 PATH 配置npm 全局安装的包可执行文件会被放到一个全局 bin 目录里。如果这个目录没进系统 PATH你会遇到装是装上了但命令找不到的情况。查看全局路径npm config get prefixWindows 下通常是C:\Users\你的用户名\AppData\Roaming\npmmacOS/Linux 下通常是/usr/local或~/.nvm/versions/node/版本号。确认这个路径Windows 下是它本身类 Unix 下是它的bin子目录已经加进系统环境变量 PATH 里。改完 PATH 一定要重开终端才生效这点很多人会忘。4. openrig 的安装与初始化实操4.1 安装命令与验证环境准备好之后安装本身很简单npm install -g openrig装完执行openrig --version或openrig -v验证。如果提示命令找不到回到上一节检查 PATH。如果提示权限错误macOS/Linux 常见不要用sudo npm install -g硬来那样会把全局目录的属主搞乱正确做法是配置 npm 的用户级全局目录或者用 nvm 管理 Node 从而避免权限问题。4.2 初始化配置文件openrig的核心理念是 YAML 驱动所以第一步是生成或手写一份配置文件。通常它会提供一个初始化命令类似openrig init这个命令会在当前目录或用户配置目录下生成一份openrig.yaml模板。如果工具没有提供 init 命令那就手动创建。一份典型的配置骨架大概长这样version: 1 tools: claude-code: enabled: true command: claude env: ANTHROPIC_BASE_URL: http://localhost:1234 codex: enabled: true command: codex env: OPENAI_BASE_URL: http://localhost:1234/v1 models: local: provider: openai-compatible base_url: http://localhost:1234/v1 api_key: not-needed这里要强调上面这些字段名是基于通用实践的合理推测实际字段请以你安装的 openrig 版本自带模板为准。但结构逻辑是通用的——tools描述要拉起哪些工具models描述模型接入点两者通过环境变量关联。4.3 YAML 配置的语法红线写 YAML 有几个必须记住的规则违反了直接解析失败缩进只能用空格不能用 Tab。建议统一用 2 个空格。冒号后面要跟一个空格key: value而不是key:value。字符串里的特殊字符比如 URL 里的冒号、斜杠建议用引号包起来避免歧义。布尔值写true/false不要写yes/no虽然部分解析器认但不通用。提示写完 YAML 不确定对不对可以用在线的 YAML 校验器过一遍或者用openrig自带的校验命令如果有的话通常是openrig validate。别等到启动失败才回头查缩进。5. 接入 Claude Code 与 Codex 的关键配置5.1 Claude Code 的接入要点Claude Code 作为 CLI 助手接入时最关键的是模型 endpoint 和认证信息。如果你想让它走本地模型比如通过 LM Studio 暴露的本地推理服务需要把 base URL 指向本地服务地址。LM Studio 默认在http://localhost:1234提供 OpenAI 兼容接口配置时把对应的环境变量指过去即可。在openrig的配置里这部分通常体现为给claude-code这个 tool 设置env把ANTHROPIC_BASE_URL之类的变量覆盖掉。这样启动 Claude Code 时它会读取这些环境变量从而走你指定的模型服务。一个实操心得本地模型的上下文窗口和响应速度跟云端差距很大接本地模型适合做隐私敏感或离线场景的辅助别指望它跑大型重构。配置时把超时时间调长一点本地推理首次加载模型可能要好几十秒。5.2 Codex 的接入要点Codex 的接入逻辑类似但它的 endpoint 路径通常带/v1后缀且对 API key 有要求即使是本地服务有些实现也要求填一个占位 key。配置时注意OPENAI_BASE_URL指向http://localhost:1234/v1这种带版本路径的地址OPENAI_API_KEY填任意非空字符串本地服务一般不校验如果 Codex 报无法加载组织设置多半是登录态或配置文件损坏清掉它的配置目录重新登录通常能解决。5.3 用一份配置同时管理两个工具openrig的价值在这里体现得最明显。你不需要分别去改 Claude Code 和 Codex 的配置文件只需要在openrig.yaml里把两个 tool 都列出来共享同一个models定义models: local: provider: openai-compatible base_url: http://localhost:1234/v1 api_key: local tools: claude-code: enabled: true model_ref: local codex: enabled: true model_ref: local这样切换模型时只改一处两个工具同时生效。这就是装配层相对各自为政的核心优势。6. 常见报错与排查速查表实际折腾过程中报错是常态。我把高频问题和排查思路整理成表方便你对照报错现象可能原因排查与解决npm.ps1 禁止运行脚本PowerShell 执行策略限制设置 RemoteSigned 策略或改用 CMD命令找不到command not found全局 bin 目录未进 PATH检查 npm prefix把对应目录加入 PATH 并重开终端npm warn eresolve overriding peer dependency依赖版本冲突多数情况可忽略若安装失败尝试--legacy-peer-depscodex 无法加载组织设置登录态或配置损坏清理 Codex 配置目录重新登录YAML 解析失败缩进用了 Tab 或冒号后缺空格用空格缩进冒号后加空格在线校验本地模型连接超时服务未启动或端口不对确认本地推理服务在跑端口与配置一致代理相关报错endpoint 处理失败代理配置与工具不匹配检查 base_url 路径是否带 /v1认证头是否正确关于npm warn eresolve overriding peer dependency这个警告补充一句它只是警告不是错误说明某个依赖要求的版本和你已装的不完全一致npm 自动做了覆盖。只要最终安装成功、工具能跑就可以不管它。真正导致安装失败的是ERESOLVE错误没有 warn 前缀那才需要处理。7. 实操心得与避坑经验折腾这套东西我踩过的坑比顺利的时候多。分享几条实打实的经验。第一配置改动后一定要重启工具进程。环境变量是在进程启动时读取的你改了 YAML 但没重启工具还是用旧配置。很多人以为配置没生效其实是没重启。第二本地模型和云端模型不要混用同一份配置。它们的 endpoint、认证、超时策略都不一样。建议在openrig.yaml里定义多个 model profile按需切换而不是把参数写死在一个 profile 里。第三npm 全局包升级要谨慎。npm update -g openrig之前先看看新版本的 changelog确认配置格式有没有破坏性变更。YAML 驱动的工具配置格式一变旧配置可能直接失效。第四善用日志。工具启动失败时先看它输出的日志而不是盲目改配置。日志里通常会明确告诉你哪一行配置有问题、哪个环境变量没读到。openrig如果有--verbose或--debug参数排查时一定加上。第五Windows 用户优先用 CMD 做首次验证。PowerShell 的执行策略、路径转义等问题会干扰判断。先用 CMD 把基本流程跑通再回到 PowerShell 做日常使用能省掉很多到底是工具问题还是终端问题的纠结。这套东西搭好之后日常使用其实很省心一份 YAML 管住所有 AI 编程助手换模型、加工具都是改几行配置的事。真正花时间的永远是第一次的环境搭建和报错排查把这一关过了后面就是顺水推舟。 
长河君 · 2026/10/2 11:47:53 · 阅读 1.2k openrig：统一管理Claude Code与Codex的YAML装配层
1. 从 openrig 说起一个把 Claude Code 和 Codex 装进统一工作流的工具第一次看到openrig这个名字我下意识把它拆成了 open 和 rig 两个词——rig 在工程语境里通常指装配、搭建一套设备或环境合起来大概就是开放式的工具装配架。事实也确实如此它想解决的核心问题是当下同时使用 Claude Code 和 Codex 这两类命令行 AI 编程助手的开发者普遍面临的一个尴尬——每个工具都有自己的配置格式、自己的启动方式、自己的模型接入逻辑切换一次就要重新折腾一遍环境。如果你最近在折腾 Claude Code 或者 Codex大概率踩过这些坑npm全局安装报无法加载文件 npm.ps1因为在此系统上禁止运行脚本、codex登录后提示无法加载组织设置、想接本地模型却卡在 endpoint 配置上、YAML 文件写错一个缩进整个流程跑不起来。这些零散的痛点本质上都是工具链没有统一装配层导致的。openrig的定位就是充当这一层装配架用一份 YAML 描述你的工具、模型、代理和启动参数然后由它统一拉起 Claude Code、Codex 或者其他 CLI 助手。这篇文章适合三类人看一是刚接触 Claude Code、Codex被安装和配置卡住的新手二是已经在用但想把手头多个 AI 编程工具统一管理的进阶用户三是想理解YAML 驱动 npm 分发这套组合拳背后设计逻辑的工程实践者。我会从整体设计思路讲到具体实操把安装、配置、模型接入、常见报错排查全部拆开讲清楚尽量让你看完就能照着搭一套自己的环境。需要先说明一点openrig本身是一个相对小众的工具网络上公开的完整文档并不多所以文中涉及的具体配置项、参数命名我会基于一个合格的工具装配层在这个场景下最合理的做法来补全并在关键处标注哪些是通用实践、哪些需要你以实际版本为准。这样即使版本迭代你也能理解背后的逻辑而不是死记命令。2. 整体设计思路为什么是 YAML npm 这套组合2.1 统一装配层的核心价值在聊具体怎么用之前得先想明白一个问题为什么需要一个装配层直接分别装 Claude Code 和 Codex 不行吗行但代价是重复劳动。Claude Code 和 Codex 虽然都是 CLI 形态的 AI 编程助手但它们的配置体系是割裂的。Claude Code 有自己的配置目录和模型接入方式Codex 有另一套登录和 endpoint 逻辑。你要接本地模型比如通过 LM Studio 暴露的本地推理服务两边要各配一遍你要切换国内镜像源加速 npm 安装两边又各折腾一遍。工具越多这种重复成本越高。openrig的思路是把这些共性抽出来模型接入、代理设置、启动参数、环境变量全部收敛到一份 YAML 里。YAML 的好处是结构清晰、可读性强、天然支持嵌套非常适合描述一个工具由哪些部分组成这种层级关系。你写一次配置openrig负责把它翻译成各个工具能识别的格式再分别拉起进程。提示YAML 对缩进极其敏感用空格不用 Tab这是后面所有配置能跑通的前提。很多人第一次写 YAML 失败90% 是缩进问题。2.2 为什么用 npm 分发openrig选择 npm 作为分发渠道这个决策其实很务实。Claude Code 和 Codex 的官方安装方式本身就大量依赖 npm用户群体天然装了 Node.js 环境。用 npm 分发意味着安装命令统一成npm install -g openrig这种形式用户不用学新的包管理器版本管理交给 npm升级、回滚都是一条命令可以借助 npm 的镜像源机制在国内网络环境下也能较快安装。但 npm 也带来了一堆经典问题比如 Windows 上的 PowerShell 执行策略限制、全局包路径没进 PATH、peer dependency 冲突警告等。这些不是openrig独有的而是所有 npm 全局工具的通病后面我会专门用一节讲怎么排查。2.3 与 Claude Code、Codex 的关系定位这里要理清一个容易混淆的点openrig不是 Claude Code 或 Codex 的替代品也不是它们的插件而是一个外层的编排器。它不参与实际的代码生成和对话只负责把环境准备好、把进程拉起来、把参数传对。打个比方Claude Code 和 Codex 是两台不同品牌的机床openrig是车间的总控台。总控台不加工零件但它知道每台机床该用什么电压、该装什么刀具、该按什么顺序启动。你换一台机床只需要在总控台上改一行配置而不用重新布线。理解了这层定位后面所有的配置项就都好理解了——它们本质上都是在回答这台机床需要什么。3. 环境准备Node、npm 与镜像源的正确姿势3.1 Node.js 版本选择与安装openrig依赖 Node.js 运行Claude Code 和 Codex 的 CLI 也大多基于 Node。版本上建议用Node 18 LTS 或更高因为较新的 CLI 工具普遍用到了较新的 ES 特性和 fetch APINode 16 及以下容易出兼容问题。安装方式上Windows 用户我强烈建议用官方安装包或者nvm-windows而不是某些第三方打包版。原因很简单官方安装包会自动把 Node 和 npm 的路径写进系统 PATH省掉后面手动配环境变量的麻烦。用nvm-windows的好处是可以随时切换 Node 版本遇到某个工具只兼容特定版本时特别有用。macOS 和 Linux 用户用nvm或者系统包管理器都行。用nvm的话装完记得确认node -v和npm -v都能正常输出版本号。3.2 npm 国内镜像源配置国内网络环境下npm 默认源拉包经常慢到让人怀疑人生。换镜像源是最直接的加速手段。常用的是淘宝源现在叫 npmmirrornpm config set registry https://registry.npmmirror.com设置完可以用npm config get registry确认。想临时用一次而不改全局配置可以在命令后加--registry参数。注意镜像源偶尔会有同步延迟某个包刚发布时镜像上可能还没有。遇到找不到包的报错先试试切回官方源https://registry.npmjs.org再装一次确认是不是同步问题。3.3 Windows PowerShell 执行策略这个经典坑如果你在 Windows 上执行 npm 命令时看到这样的报错npm : 无法加载文件 C:\Program Files\nodejs\npm.ps1因为在此系统上禁止运行脚本这不是 npm 坏了而是 PowerShell 的执行策略默认禁止运行脚本文件。解决办法是以管理员身份打开 PowerShell执行Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSignedRemoteSigned的含义是本地写的脚本可以直接跑从网络下载的脚本需要有签名。这个策略在安全性和便利性之间比较平衡是官方推荐给开发者的设置。执行完关掉 PowerShell 重开一个窗口再试 npm 命令就正常了。如果你不想改执行策略也可以改用 CMD 而不是 PowerShell 来执行命令CMD 不受这个策略限制。但长期看改策略更省事。3.4 全局包路径与 PATH 配置npm 全局安装的包可执行文件会被放到一个全局 bin 目录里。如果这个目录没进系统 PATH你会遇到装是装上了但命令找不到的情况。查看全局路径npm config get prefixWindows 下通常是C:\Users\你的用户名\AppData\Roaming\npmmacOS/Linux 下通常是/usr/local或~/.nvm/versions/node/版本号。确认这个路径Windows 下是它本身类 Unix 下是它的bin子目录已经加进系统环境变量 PATH 里。改完 PATH 一定要重开终端才生效这点很多人会忘。4. openrig 的安装与初始化实操4.1 安装命令与验证环境准备好之后安装本身很简单npm install -g openrig装完执行openrig --version或openrig -v验证。如果提示命令找不到回到上一节检查 PATH。如果提示权限错误macOS/Linux 常见不要用sudo npm install -g硬来那样会把全局目录的属主搞乱正确做法是配置 npm 的用户级全局目录或者用 nvm 管理 Node 从而避免权限问题。4.2 初始化配置文件openrig的核心理念是 YAML 驱动所以第一步是生成或手写一份配置文件。通常它会提供一个初始化命令类似openrig init这个命令会在当前目录或用户配置目录下生成一份openrig.yaml模板。如果工具没有提供 init 命令那就手动创建。一份典型的配置骨架大概长这样version: 1 tools: claude-code: enabled: true command: claude env: ANTHROPIC_BASE_URL: http://localhost:1234 codex: enabled: true command: codex env: OPENAI_BASE_URL: http://localhost:1234/v1 models: local: provider: openai-compatible base_url: http://localhost:1234/v1 api_key: not-needed这里要强调上面这些字段名是基于通用实践的合理推测实际字段请以你安装的 openrig 版本自带模板为准。但结构逻辑是通用的——tools描述要拉起哪些工具models描述模型接入点两者通过环境变量关联。4.3 YAML 配置的语法红线写 YAML 有几个必须记住的规则违反了直接解析失败缩进只能用空格不能用 Tab。建议统一用 2 个空格。冒号后面要跟一个空格key: value而不是key:value。字符串里的特殊字符比如 URL 里的冒号、斜杠建议用引号包起来避免歧义。布尔值写true/false不要写yes/no虽然部分解析器认但不通用。提示写完 YAML 不确定对不对可以用在线的 YAML 校验器过一遍或者用openrig自带的校验命令如果有的话通常是openrig validate。别等到启动失败才回头查缩进。5. 接入 Claude Code 与 Codex 的关键配置5.1 Claude Code 的接入要点Claude Code 作为 CLI 助手接入时最关键的是模型 endpoint 和认证信息。如果你想让它走本地模型比如通过 LM Studio 暴露的本地推理服务需要把 base URL 指向本地服务地址。LM Studio 默认在http://localhost:1234提供 OpenAI 兼容接口配置时把对应的环境变量指过去即可。在openrig的配置里这部分通常体现为给claude-code这个 tool 设置env把ANTHROPIC_BASE_URL之类的变量覆盖掉。这样启动 Claude Code 时它会读取这些环境变量从而走你指定的模型服务。一个实操心得本地模型的上下文窗口和响应速度跟云端差距很大接本地模型适合做隐私敏感或离线场景的辅助别指望它跑大型重构。配置时把超时时间调长一点本地推理首次加载模型可能要好几十秒。5.2 Codex 的接入要点Codex 的接入逻辑类似但它的 endpoint 路径通常带/v1后缀且对 API key 有要求即使是本地服务有些实现也要求填一个占位 key。配置时注意OPENAI_BASE_URL指向http://localhost:1234/v1这种带版本路径的地址OPENAI_API_KEY填任意非空字符串本地服务一般不校验如果 Codex 报无法加载组织设置多半是登录态或配置文件损坏清掉它的配置目录重新登录通常能解决。5.3 用一份配置同时管理两个工具openrig的价值在这里体现得最明显。你不需要分别去改 Claude Code 和 Codex 的配置文件只需要在openrig.yaml里把两个 tool 都列出来共享同一个models定义models: local: provider: openai-compatible base_url: http://localhost:1234/v1 api_key: local tools: claude-code: enabled: true model_ref: local codex: enabled: true model_ref: local这样切换模型时只改一处两个工具同时生效。这就是装配层相对各自为政的核心优势。6. 常见报错与排查速查表实际折腾过程中报错是常态。我把高频问题和排查思路整理成表方便你对照报错现象可能原因排查与解决npm.ps1 禁止运行脚本PowerShell 执行策略限制设置 RemoteSigned 策略或改用 CMD命令找不到command not found全局 bin 目录未进 PATH检查 npm prefix把对应目录加入 PATH 并重开终端npm warn eresolve overriding peer dependency依赖版本冲突多数情况可忽略若安装失败尝试--legacy-peer-depscodex 无法加载组织设置登录态或配置损坏清理 Codex 配置目录重新登录YAML 解析失败缩进用了 Tab 或冒号后缺空格用空格缩进冒号后加空格在线校验本地模型连接超时服务未启动或端口不对确认本地推理服务在跑端口与配置一致代理相关报错endpoint 处理失败代理配置与工具不匹配检查 base_url 路径是否带 /v1认证头是否正确关于npm warn eresolve overriding peer dependency这个警告补充一句它只是警告不是错误说明某个依赖要求的版本和你已装的不完全一致npm 自动做了覆盖。只要最终安装成功、工具能跑就可以不管它。真正导致安装失败的是ERESOLVE错误没有 warn 前缀那才需要处理。7. 实操心得与避坑经验折腾这套东西我踩过的坑比顺利的时候多。分享几条实打实的经验。第一配置改动后一定要重启工具进程。环境变量是在进程启动时读取的你改了 YAML 但没重启工具还是用旧配置。很多人以为配置没生效其实是没重启。第二本地模型和云端模型不要混用同一份配置。它们的 endpoint、认证、超时策略都不一样。建议在openrig.yaml里定义多个 model profile按需切换而不是把参数写死在一个 profile 里。第三npm 全局包升级要谨慎。npm update -g openrig之前先看看新版本的 changelog确认配置格式有没有破坏性变更。YAML 驱动的工具配置格式一变旧配置可能直接失效。第四善用日志。工具启动失败时先看它输出的日志而不是盲目改配置。日志里通常会明确告诉你哪一行配置有问题、哪个环境变量没读到。openrig如果有--verbose或--debug参数排查时一定加上。第五Windows 用户优先用 CMD 做首次验证。PowerShell 的执行策略、路径转义等问题会干扰判断。先用 CMD 把基本流程跑通再回到 PowerShell 做日常使用能省掉很多到底是工具问题还是终端问题的纠结。这套东西搭好之后日常使用其实很省心一份 YAML 管住所有 AI 编程助手换模型、加工具都是改几行配置的事。真正花时间的永远是第一次的环境搭建和报错排查把这一关过了后面就是顺水推舟。