If you run OpenClaw on a bare-metal Mac mini M4 Pro in Singapore, Japan, South Korea, Hong Kong, US East, or US West and moved to 2026.5.2+, a Gateway that refuses to start because external plugin packages are missing is usually not a model-key problem. After the install root shifted from global npm to ~/.openclaw/npm, configs that still point at the old tree produce missing plugin errors even when npm install -g @openclaw/discord succeeds. This article targets teams upgrading from 4.x or early 5.x: an install-path decision matrix, a ten-step migration runbook, boundaries for openclaw doctor --fix, --lint, and --non-interactive, plus OPENCLAW_PLUGIN_STAGE_DIR disk layering on remote Macs. Pricing on the NOVAKVM pricing page; orders on the order page; session and directory policy in the help center. Cross-read the first-run closure note, the npm upgrade note, and the 2026.5.x health check note.
After reading you should answer three questions with evidence. First, whether each enabled plugin should live under global npm or ~/.openclaw/npm/node_modules. Second, how to install packages offline before doctor when Gateway cannot boot, avoiding a chicken-and-egg loop. Third, how to partition plugin stage, logs, and model artifacts on 256GB versus 512GB remote Macs so a single npm install spike does not fill the system volume. CLI subcommands, package names, and directory contracts must be verified against OpenClaw official documentation and GitHub release notes at the time you freeze the change.
[ SECTION_01 ] // PLUGIN_FAILURE Five root causes when Gateway fails on external plugins after 2026.5.x, plus hidden cost
The first root cause is install location drift: you ran npm install -g in a maintenance window, but Gateway after 2026.5.2 scans ~/.openclaw/npm/node_modules under manifest-first rules. Logs show configured plugin not found while the team searches the global tree. The second is package name versus config id mismatch: some channel plugins use npm scopes that do not exactly match ids in openclaw.json. Doctor lists stale install entries while nobody applies fix for fear of deleting a production channel.
The third is a doctor versus Gateway circular dependency: when Gateway refuses boot, teams restart it repeatedly instead of completing openclaw doctor --fix or a manual npm install into the correct root. On a remote Mac, a non-interactive fix without a config backup can drop allow-only plugins from the manifest and leave cron jobs failing silently. The fourth is disk contention: on 256GB hosts, plugin stage, pnpm cache, and Gateway logs on one system volume make npm extract peaks overlap APFS snapshots, so install succeeds but Gateway times out. The fifth is half-migrated cross-node copies: rsync of ~/.openclaw without the npm subtree leaves config complete and packages absent, stretching incidents to hours.
- Path drift: global npm and
~/.openclaw/npmcoexist; config never migrated. - Package id ambiguity: Brave, Discord, Voice, and similar scopes do not align with manifest ids.
- Wrong repair order: Gateway restart before packages land; doctor never reaches a fixable state.
- Non-interactive fix risk:
doctor --fixremoves allow-only entries during a migration window. - Disk headroom: plugin stage and logs share one volume; install peaks trigger space alerts.
- Partial cross-node sync: configuration copied without the
npmsubdirectory.
External plugin incidents reduce to one rule: every id in config must resolve to exactly one physical package in exactly one agreed directory, not another global CLI install.
[ SECTION_02 ] // PATH_MATRIX Global npm, ~/.openclaw/npm, and ClawHub: install path decision matrix
2026.5.x pushes many channel and extension plugins toward npm-first installs while manifest metadata reduces cold-start scan cost. Freeze a single source-of-truth directory before you pin versions.
| Dimension | A · Global npm (-g) | B · ~/.openclaw/npm (recommended default) | C · ClawHub / built-in channels |
|---|---|---|---|
| Best fit | CLI only, experiments, transitional alignment with 4.x docs | 2026.5.2+ production Gateway with multiple channels | Official built-ins or ClawHub-pinned extensions |
| Gateway visibility | Often installs but does not scan | Aligned with doctor repair logic | Depends on manifest and channel switches |
| Rollback | Medium: clear global tree and config together | Low: tarball the npm subtree |
Low to medium: roll back per plugin id |
| Remote Mac disk | Often lands in system global node_modules | Pairs with STAGE_DIR on a data volume | Cache grows roughly with plugin count |
If you already pinned ClawHub versions per project in the multi-workspace note, external npm plugins should still be registered per workspace so upgrading Discord for project A does not overwrite a shared directory used by project B.
[ SECTION_03 ] // DOCTOR_STAGE openclaw doctor repair modes and OPENCLAW_PLUGIN_STAGE_DIR layering
Doctor exposes read-only inspection and automatic repair. In a change window, run openclaw doctor --lint first to archive missing packages, stale installs, and config pointing at nonexistent directories, then apply openclaw doctor --fix in maintenance. If Gateway cannot start, install missing @openclaw/* packages into ~/.openclaw/npm without booting Gateway, then fix. Migration windows around 2026.5.2 often showed globally installed lobster packages that scan paths ignored; manual install followed by fix beats repeated restart loops.
OPENCLAW_PLUGIN_STAGE_DIR separates the npm extract root from the runtime load root. On a remote Mac, point stage at a data disk or expansion volume and keep hot paths on SSD. After each release, confirm launchd plist still exports the variable.
Official doctor and release documentation should be re-opened after every tag you adopt.
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 Ten steps to complete 4.x to 2026.5.x external plugin migration on a remote Mac
- Freeze the plugin manifest: export enabled plugin ids, versions, and channel dependencies into the change ticket.
- Full backup: tarball
~/.openclawincluding thenpmsubtree and launchd plists; recordopenclaw --version. - Upgrade the CLI: follow official release notes; do not skip migration hints between major lines.
- Create the npm root: ensure
~/.openclaw/npm/package.jsonexists; do not rely on global-only installs. - Install from the list: for each external plugin run version-pinned
npm installunder~/.openclaw/npm; install allow-only plugins before optional channels. - Set STAGE_DIR: on 512GB or larger hosts point stage off the system volume; on 256GB reserve at least 20GB for plugins and cache.
- Lint then fix: run
doctor --lintuntil no configured-but-missing entries remain, then--fix. - Verify Gateway:
openclaw gateway statusand port 18789 probes per the health check note. - Channel smoke tests: send one test message per enabled channel; record latency and log paths.
- Write back the runbook: document final directory layout, pinned versions, and rollback tarball location; review quarterly.
Sanitized team case: a three-person crew on a Tokyo M4 Pro upgraded from 2026.4.27 to 2026.5.4. Gateway reported a missing discord package after repeated global npm i failed. Following this sequence, packages landed under ~/.openclaw/npm with stage on an expansion volume; doctor --fix passed once and downtime dropped from an estimated 90 minutes to 28.
[ SECTION_05 ] // DATA_FAQ Citable technical parameters, disk budgets, and FAQ
The ranges below are planning intervals for capacity reviews, not guaranteed measurements for your host. Reconcile against official docs after each release.
- Plugin root: for 2026.5.2+ production, treat
~/.openclaw/npm/node_modulesas the default truth path; avoid mixing withnpm root -g. - Disk budget: on 256GB remote Macs reserve at least 20GB for plugin stage plus npm cache; with multiple workspaces and heavy logs, evaluate 1TB or 2TB expansion.
- Doctor modes:
--lintsuits CI and pre-change read-only checks;--non-interactivesuits unattended maintenance;--deephelps find duplicate install trees. - Release cadence: 2026.5.3 through 5.4 added file-transfer agent tools and Gateway lazy loading; larger plugin counts make manifest cache hits and directory layering more valuable.
FAQ:
- Q: Can I keep using globally installed packages? A: Not as production default. Migrate into
~/.openclaw/npmand align config, or upgrades may still miss them. - Q: Can I run doctor when Gateway is down? A: Yes. Doctor does not require Gateway to listen, but install missing packages before fix to avoid removing entries.
- Q: How does this differ from the upgrade note? A: The upgrade note covers CLI and LaunchAgent; this note covers external plugin npm paths and 4.x migration.
- Q: Which region should host the install? A: Run plugin installs on the same machine as Gateway. For cross-border troubleshooting, place the operator console near the people who touch it most; see regional notes on the pricing page.
Alternatives have real limits. Local laptop plugin trials do not prove launchd environment inheritance on remote bare metal. Keeping plugin trees on a non-expandable system volume eventually collides with repeated npm updates. Office-owned Macs rarely offer fast region moves or storage upgrades during a migration window. For teams shipping OpenClaw 2026.5.x external plugins alongside iOS CI and AI agents who need doctor output and ~/.openclaw/npm paths that are auditable and rollback-friendly, NOVAKVM Mac mini cloud rental is usually the better fit: dedicated Apple Silicon, six bare-metal regions, day or week validation before stepping up to M4 Pro tiers and storage expansion. Before the next minor OpenClaw bump, tarball the plugin manifest and npm subtree into backup. That beats guessing at 2 a.m. where the packages actually landed.