2026年 OpenClaw 2026.5.x 外部外掛 npm 安裝與 4.x 遷移實戰：
~/.openclaw/npm 路徑釘版本、OPENCLAW_PLUGIN_STAGE_DIR 分層、openclaw doctor 修復 Gateway 起不來與遠端 Mac M4 Pro 磁碟規劃

若你已在 新加坡 / 日本 / 韓國 / 香港 / 美東 / 美西 的 裸金屬遠端 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 而言，應先凍結「唯一真相目錄」，再談版本釘住。

OpenClaw 外部外掛安裝路徑對照（2026.5.x 遠端 Mac 實戰）
維度 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

plugin-migrate.example 
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 可復現）

  1. 凍結外掛清單：從現網設定匯出 enabled 外掛 id、版本號與通道依賴，寫入變更單。
  2. 全量備份：打包 ~/.openclaw（含 npm 子樹）與 launchd plist，記錄 openclaw --version。
  3. 升級 CLI 本體：按官方 release note 升級 OpenClaw，勿跳過中間大版本說明中的遷移提示。
  4. 建立 npm 根：確保 ~/.openclaw/npm/package.json 存在，禁止僅在全域性目錄留包。
  5. 按清單裝包：對每個外部外掛執行帶版本號的 npm install 到 ~/.openclaw/npm，先裝 allow-only 再裝可選通道。
  6. 設定 STAGE_DIR：在 512GB 及以上機型把 stage 指到非系統卷；256GB 機型至少單獨劃出 ≥20GB 給外掛與快取。
  7. lint 再 fix：先 doctor --lint，確認無「configured but missing」後再 --fix。
  8. 驗證 Gateway：openclaw gateway status 與 18789 探活，對照 健康檢查篇 的 probe 建議。
  9. 通道冒煙：對每個已啟用通道發一條測試訊息，記錄延遲與日誌路徑。
  10. 寫回 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 子樹打進備份——這比凌晨再猜一次「包到底裝在哪」更能保住睡眠時間。