若你已在 新加坡 / 日本 / 韩国 / 香港 / 美东 / 美西 的 裸金属远程 Mac mini M4 Pro 上跑 OpenClaw，却在跟随 2026.5.2+ 发版后遇到 Gateway 因缺少外部插件包而无法启动、或发现 npm install -g @openclaw/discord 装完仍报 missing plugin，问题往往不在模型 Key，而在 插件安装根目录从全局 npm 迁到 ~/.openclaw/npm 后，配置里仍指向旧路径。本文面向已从 4.x / 早期 5.x 升级的进阶用户与自建运维，给出可对照的安装路径矩阵、十步迁移跟做清单、openclaw doctor --fix / --lint / --non-interactive 的适用边界，以及 OPENCLAW_PLUGIN_STAGE_DIR 在远程 Mac 上的磁盘分层建议。价格与库存以 NOVAKVM 定价页 为准；下单见 订购页；远程会话与目录权限见 帮助中心；可与站内 首跑闭环篇、npm 升级篇、2026.5.x 健康检查篇 交叉阅读。
读完你应能回答：① 你的插件应落在全局 npm 还是 ~/.openclaw/npm/node_modules；② 当 Gateway 已起不来时，如何按离线顺序先补包再跑 doctor，避免「鸡生蛋」；③ 在 256GB 与 512GB 远程 Mac 上，插件缓存、日志与模型工件应如何分卷，避免一次 npm install 把系统卷打满。下文 CLI 子命令、包名与目录约定以 OpenClaw 官方文档与 GitHub 发版说明为准，入库或发版后请再次打开链接核对。
[ SECTION_01 ] // PLUGIN_FAILURE 2026.5.x 升级后 Gateway 因外部插件起不来的五类根因与隐性成本
第一类根因是安装位置不一致：你在维护窗执行了全局 npm install -g，但 Gateway 在 2026.5.2 之后按 manifest-first 规则只扫描 ~/.openclaw/npm/node_modules，启动日志里出现「configured plugin not found」，团队却仍在全局目录里找包。第二类根因是包名与配置键不匹配：部分通道插件在 npm 上的 scope 与 openclaw.json 里登记的 id 不完全一致，doctor 能列出「stale install」却无人敢点 fix，怕误删生产通道。
第三类根因是doctor 与 Gateway 的循环依赖：Gateway 因缺插件拒绝启动时，有人习惯先 openclaw gateway restart，而修复动作本应通过 openclaw doctor --fix 或手动 npm install 到正确根完成；在远程 Mac 上若未先备份配置，一次非交互 fix 还可能把 allow-only 插件从清单里摘掉，凌晨 cron 静默失败。第四类根因与磁盘争用有关：在 256GB 机型上把插件 stage、pnpm 缓存与 Gateway 日志都堆在系统卷，npm install 解压高峰与 APFS 快照叠加，表现为「安装成功但 Gateway 超时」。第五类根因是跨节点复制了半套目录：从 A 节点 rsync 了 ~/.openclaw 却未带上 npm 子树，B 节点配置齐全、包体缺失，排障时间被拉长到数小时。
- 路径漂移：全局 npm 与
~/.openclaw/npm双轨并存，配置未迁移。 - 包名歧义：Brave、Discord、Voice 等外部包 scope 不统一，清单与磁盘不一致。
- 修复顺序错误：先重启 Gateway 再装包，doctor 无法进入可修复状态。
- 非交互 fix 误伤：
doctor --fix在迁移窗删除 allow-only 插件条目。 - 磁盘水位：插件 stage 与日志同卷，安装高峰触发空间告警。
- 跨节点半迁移：只同步配置不同步
npm子目录。
「外部插件问题的本质，是让配置里写的每一个 id 都能在唯一约定的目录里解析到物理包，而不是再多装一遍全局 CLI。」
[ SECTION_02 ] // PATH_MATRIX 全局 npm、~/.openclaw/npm 与 ClawHub：安装路径决策矩阵
2026.5.x 把大量通道类与扩展类插件推向 npm-first 安装，同时用 manifest 元数据减少 Gateway 冷启动扫描量。对你方 runbook 而言，应先冻结「唯一真相目录」，再谈版本钉住。
| 维度 | A · 全局 npm（-g） | B · ~/.openclaw/npm（推荐默认） | C · ClawHub / 内置通道 |
|---|---|---|---|
| 适用场景 | 仅 CLI 本体、临时试验、与旧 4.x 文档对齐的过渡 | 2026.5.2+ 生产 Gateway、多通道并存 | 官方内置或已通过 ClawHub 钉版本的扩展 |
| Gateway 可见性 | 易「装得上、扫不到」 | 与 doctor 修复逻辑一致 | 取决于 manifest 与通道开关 |
| 回滚难度 | 中：需同时清全局与配置 | 低：可打包 npm 子树做快照 |
低～中：按插件 id 回滚版本 |
| 远程 Mac 磁盘 | 常落在系统卷全局 node_modules | 可配合 STAGE_DIR 分卷 | 缓存体积随插件数量线性增 |
若你已在 多 Workspace 篇 为不同项目钉过 ClawHub 版本，外部 npm 插件仍应按 Workspace 维度登记，避免 A 项目升级 Discord 包导致 B 项目 Gateway 共用目录被覆盖。
[ SECTION_03 ] // DOCTOR_STAGE openclaw doctor 修复模式与 OPENCLAW_PLUGIN_STAGE_DIR 分层要点
官方 doctor 提供只读巡检与自动修复两类能力：在变更窗先用 openclaw doctor --lint 把「缺包 / stale install / 配置指向不存在目录」写成可归档文本，再在维护窗用 openclaw doctor --fix 应用推荐修复。若 Gateway 已无法启动，应先在不启动 Gateway 的前提下，把缺失的 @openclaw/* 包装进 ~/.openclaw/npm，再执行 fix；社区在 2026.5.2 迁移窗曾出现「全局装了 lobster 但扫描路径不对」类问题，手动补包后 fix 往往比反复 restart 更省时间。
OPENCLAW_PLUGIN_STAGE_DIR 用于把「安装解压根」与「运行加载根」分层：在远程 Mac 上可把 stage 指到数据盘或扩容卷，把热路径留在 SSD 上。发版后请核对环境变量是否仍被 launchd plist 继承。
https://docs.openclaw.ai/gateway/doctor
https://github.com/openclaw/openclaw/releases
openclaw doctor --lint > /tmp/oc-doctor-lint.txt
cd ~/.openclaw/npm && npm install @openclaw/discord@<pinned>
export OPENCLAW_PLUGIN_STAGE_DIR="/Volumes/data/openclaw-stage"
openclaw doctor --fix --non-interactive
openclaw gateway status
[ SECTION_04 ] // RUNBOOK 十步完成 4.x→2026.5.x 外部插件迁移（远程 Mac 可复现）
- 冻结插件清单：从现网配置导出 enabled 插件 id、版本号与通道依赖，写入变更单。
- 全量备份：打包
~/.openclaw（含npm子树）与 launchd plist，记录openclaw --version。 - 升级 CLI 本体：按官方 release note 升级 OpenClaw，勿跳过中间大版本说明中的迁移提示。
- 创建 npm 根：确保
~/.openclaw/npm/package.json存在，禁止仅在全局目录留包。 - 按清单装包：对每个外部插件执行带版本号的
npm install到~/.openclaw/npm，先装 allow-only 再装可选通道。 - 设置 STAGE_DIR：在 512GB 及以上机型把 stage 指到非系统卷；256GB 机型至少单独划出 ≥20GB 给插件与缓存。
- lint 再 fix：先
doctor --lint，确认无「configured but missing」后再--fix。 - 验证 Gateway：
openclaw gateway status与 18789 探活，对照 健康检查篇 的 probe 建议。 - 通道冒烟：对每个已启用通道发一条测试消息，记录延迟与日志路径。
- 写回 runbook：把最终目录树、钉版本号与回滚 tar 包路径登记到团队 wiki，季度复查一次。
小团队案例（脱敏）：三人团队在东京节点 M4 Pro 上从 2026.4.27 升到 2026.5.4，升级后 Gateway 报缺 discord 包，成员反复全局 npm i 无效。按本文顺序把包装入 ~/.openclaw/npm 并设 STAGE 到扩容卷后，doctor --fix 一次通过，断服窗口从预估 90 分钟压到 28 分钟。
[ SECTION_05 ] // DATA_FAQ 可引用技术信息、磁盘预算与 FAQ
下列数值为工程规划常用区间，用于评审与容量表，不代表你方实测；发版后请以官方文档为准。
- 插件根目录：2026.5.2+ 生产环境宜以
~/.openclaw/npm/node_modules为默认真相路径，避免与全局npm root -g混用。 - 磁盘预算：256GB 远程 Mac 建议为插件 stage + npm 缓存预留 ≥20GB；若同时跑多 Workspace 与大体量日志，优先评估 1TB/2TB 扩容。
- doctor 模式：
--lint适合 CI 与变更前只读；--non-interactive适合无人值守维护窗；--deep用于排查多份安装残留。 - 发版节奏：2026.5.3～5.4 引入文件传输类 agent 工具与 Gateway 懒加载，插件数量增多时冷启动时间更依赖 manifest 缓存命中，目录分层收益更明显。
FAQ：
- Q：全局 npm 装的包能不能继续用？A：不建议作为生产默认；应迁移到
~/.openclaw/npm并改配置指向，否则升级后仍可能扫不到。 - Q：Gateway 起不来还能跑 doctor 吗？A：可以；doctor 不依赖 Gateway 已监听，但 fix 前最好先手动补缺失包，避免 fix 误删条目。
- Q：与升级篇有何分工？A：升级篇 管 CLI 与 LaunchAgent；本文管外部插件 npm 通道与路径迁移。
- Q：六地节点怎么选？A：插件安装与 Gateway 同机执行即可；若团队成员跨国排障，主控机宜靠近最常操作的人，参见定价页中的区域说明。
把替代方案摊开看：只在笔记本本地试装插件无法验证远程裸金属上的 launchd 环境变量；把插件目录放在不可扩容的系统卷上，则在多次 npm 更新后容易触顶；自购办公室 Mac 又难在升级窗快速换区与升配。对于要把 OpenClaw 2026.5.x 外部插件 与 iOS CI、AI Agent 一起交给生产环境、又希望 doctor 与 ~/.openclaw/npm 路径可审计、可回滚的团队来说，NOVAKVM 的 Mac mini 云端租赁通常是更优解：独占 Apple Silicon、六地裸金属、从日租周租验证到 M4 Pro 高配与存储扩容逐级升级，更适合在单一变更单里同时完成「包装对位置」与「机器跑得稳」。下一次升级 OpenClaw 小版本前，先把插件清单与 npm 子树打进备份——这比凌晨再猜一次「包到底装在哪」更能保住睡眠时间。