シンガポール、日本、韓国、香港、米国東部、米国西部 のベアメタル Mac mini M4 Pro 上で OpenClaw を運用している方が、2026.5.2 以降 のリリース追従後に 外部プラグイン欠落で Gateway が起動しない、あるいは npm install -g @openclaw/discord 後も missing plugin が消えない場合、原因はモデル API キーではなく、プラグインのインストールルートがグローバル npm から ~/.openclaw/npm へ移った のに設定が旧パスを指していることにあります。本稿は 4.x / 初期 5.x から上がった運用担当者向けに、インストールパスの決定マトリクス、十段階の移行手順、openclaw doctor --fix / --lint / --non-interactive の適用境界、および OPENCLAW_PLUGIN_STAGE_DIR をリモート Mac でどう切るかを示します。料金は 料金ページ、申込みは 注文ページ、リモート接続は ヘルプセンター を正とします。初回完走記事、npm アップグレード記事、2026.5.x ヘルスチェック記事 と併読してください。
読了後には次が判断できます。① プラグインを グローバル npm に置くか ~/.openclaw/npm/node_modules に置くか。② Gateway が既に落ちているとき、オフライン順序 で先にパッケージを補い、その後 doctor を走らせる方法。③ 256GB と 512GB のリモート Mac で、プラグイン stage、ログ、モデル成果物を どのボリュームに分けるか。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 と出ても、チームはグローバル node_modules を探し続けます。第二は パッケージ名と設定キーの不一致 です。Discord や Voice などの 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 から ~/.openclaw を rsync しても npm サブツリーを含めないと、B は設定だけ揃いパッケージが無い状態が数時間続きます。
- パス漂移：グローバル npm と
~/.openclaw/npmの二重系、設定未移行。 - パッケージ名の曖昧さ：Brave、Discord、Voice など scope が設定と不一致。
- 修復順序の誤り：先に Gateway 再起動、後からパッケージ導入。
- 非対話 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 サブツリーを tar 化可能 |
低〜中：プラグイン id 単位で版戻し |
| リモート Mac のディスク | システムボリュームのグローバル node_modules | STAGE_DIR と組み合わせて別巻可能 | プラグイン数に比例してキャッシュ増 |
マルチワークスペース記事 で ClawHub 版を固定している場合でも、外部 npm プラグインは ワークスペース単位で台帳登録 し、A プロジェクトの Discord 更新が B の共有ディレクトリを上書きしないようにします。
[ SECTION_03 ] // DOCTOR_STAGE openclaw doctor 修復モードと OPENCLAW_PLUGIN_STAGE_DIR の層分け要点
公式 doctor は読み取り専用の --lint と自動修復の --fix を提供します。変更窓では先に lint で欠落パッケージ・stale install・存在しないディレクトリ参照をテキスト化し、メンテナンス枠で fix を適用します。Gateway が既に起動不能なら、Gateway を起動せず に不足する @openclaw/* を ~/.openclaw/npm へ入れてから fix するのが安全です。2026.5.2 移行期にはグローバルに入れたが走査パスが違う事例があり、手動補完後の fix の方が restart ループより短いことが多いです。
OPENCLAW_PLUGIN_STAGE_DIR は展開先と実行時ロードルートを分けます。リモート Mac では stage をデータディスクへ、ホットパスを内蔵 SSD に置く構成が一般的です。launchd plist が環境変数を引き継ぐか、発版後に再確認してください。
以下は OpenClaw 公式の doctor およびリリース情報です。上流更新後はリンクを開き直してください。
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 で再現可能）
- プラグイン台帳の凍結：有効 id、バージョン、チャネル依存を変更票に書き出します。
- フルバックアップ：
~/.openclaw（npm含む）と launchd plist を保存し、openclaw --versionを記録します。 - CLI 本体の更新：リリースノートに従い OpenClaw を上げ、中間版の移行注意を飛ばしません。
- npm ルートの作成：
~/.openclaw/npm/package.jsonを用意し、グローバルのみに置かないようにします。 - 台帳どおりに導入：各外部プラグインを版指定で
~/.openclaw/npmに入れ、allow-only を先にします。 - STAGE_DIR の設定：512GB 以上は stage を非システムボリュームへ。256GB は少なくとも 20GB をプラグインとキャッシュに確保します。
- lint の後 fix：
doctor --lintで configured but missing が無いことを確認してから--fixします。 - Gateway の検証：
openclaw gateway statusと 18789 プローブを ヘルスチェック記事 と照合します。 - チャネルスモーク：有効チャネルごとにテストメッセージを送り、遅延とログパスを記録します。
- 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。複数ワークスペースと大容量ログなら 1TB/2TB 拡張 を検討します。
- doctor モード：
--lintは CI と変更前の読み取り、--non-interactiveは無人メンテナンス、--deepは重複インストールの掃除向けです。 - リリースペース：2026.5.3〜5.4 はファイル転送系ツールと Gateway 遅延ロードを強化し、プラグイン数が多いほど manifest キャッシュとディレクトリ層分けの効果が大きくなります。
FAQ：
- Q：グローバル npm のパッケージは使えますか。A：本番既定には向きません。
~/.openclaw/npmへ移し設定を合わせないと、更新後も掃描されないことがあります。 - Q：Gateway が落ちていても doctor は実行できますか。A：可能です。doctor は Gateway 待受に依存しませんが、fix 前に欠落パッケージを手動で入れるとエントリ誤削除を防げます。
- Q：アップグレード記事との役割分担は。A：アップグレード記事 は CLI と LaunchAgent、本稿は 外部プラグイン npm とパス移行 です。
- Q：六リージョンの選び方は。A：プラグイン導入と Gateway は同一ホストで十分です。跨国で排障するなら、最も操作するメンバーに近いリージョンを主控にしてください。
代替案を並べると、ローカルノート PC だけでプラグインを試しても リモート裸金属の launchd 環境変数 は検証できません。プラグインディレクトリを拡張できないシステムボリュームに置けば、npm の繰り返し更新 で早期に容量上限に達します。オフィス自前 Mac では、メンテナンス窓にリージョン変更やストレージ増設が難しい場合も多いです。OpenClaw 2026.5.x 外部プラグイン と iOS CI、AI Agent を本番に載せ、doctor と ~/.openclaw/npm を 監査可能・ロールバック可能 に保ちたいチームにとって、NOVAKVM の Mac mini クラウドレンタルは通常より適した選択 です。専有 Apple Silicon、六地域ベアメタル、日次・週次検証から M4 Pro 高構成とストレージ拡張まで段階的に上げられ、単一変更票でパッケージ位置合わせとマシン安定性を同時に満たしやすくなります。次のマイナーアップグレード前に、プラグイン台帳と npm サブツリーをバックアップに含めてください。深夜にパッケージの所在を当てるより、睡眠時間を守れます。