2026 OpenClaw 2026.5.x externe Plug-ins per npm und 4.x-Migration:
~/.openclaw/npm mit Version pinnen, OPENCLAW_PLUGIN_STAGE_DIR, openclaw doctor wenn Gateway nicht startet, Disk-Planung auf Remote Mac M4 Pro

Wenn Sie OpenClaw auf einem Bare-Metal-Mac mini M4 Pro in Singapur, Japan, Südkorea, Hongkong, US-Ost oder US-West betreiben und auf 2026.5.2+ wechseln, liegt ein Gateway, das wegen fehlender externer Plug-in-Pakete nicht startet, selten an Modell-Keys. Nach der Verlagerung der Installationswurzel von globalem npm nach ~/.openclaw/npm zeigen Konfigurationen mit alten Pfaden weiterhin missing plugin, obwohl npm install -g @openclaw/discord erfolgreich war. Dieser Text richtet sich an Teams mit Upgrade von 4.x oder frühem 5.x: eine Installationspfad-Matrix, ein Zehn-Schritte-Migrations-Runbook, Grenzen von openclaw doctor --fix, --lint und --non-interactive sowie OPENCLAW_PLUGIN_STAGE_DIR auf Remote-Macs. Preise auf der NOVAKVM-Mietpreisseite; Bestellung über die Bestellseite; Sitzungs- und Verzeichnisrichtlinien im Hilfezentrum. Querverweise: First-Run, npm-Upgrade, 2026.5.x Health-Check.

Nach der Lektüre beantworten Sie drei Fragen mit Belegen: erstens, ob jedes aktivierte Plug-in unter globalem npm oder ~/.openclaw/npm/node_modules liegen soll; zweitens, wie Sie Pakete offline nachziehen, bevor doctor läuft, wenn Gateway nicht bootet; drittens, wie Sie Plug-in-Stage, Logs und Modell-Artefakte auf 256 GB versus 512 GB trennen, damit ein npm install die Systemplatte nicht füllt. CLI-Unterbefehle, Paketnamen und Verzeichnisverträge bitte gegen offizielle OpenClaw-Dokumentation und GitHub-Release-Notes zum Freeze-Datum prüfen. Bei personenbezogenen Daten in Cloud-Knoten orientiert sich der Beitrag an der DSGVO und interner Datenflusskontrolle.

[ SECTION_01 ] // PLUGIN_FAILURE Fünf Ursachen und versteckte Kosten, wenn Gateway nach 2026.5.x an externen Plug-ins scheitert

Erste Ursache: Installationsort driftet — im Wartungsfenster lief npm install -g, Gateway scannt ab 2026.5.2 aber ~/.openclaw/npm/node_modules nach Manifest-first-Regeln. Logs melden configured plugin not found, das Team sucht im globalen Baum. Zweite Ursache: Paketname versus Config-ID — manche Kanal-Plug-ins nutzen npm-Scopes, die nicht exakt zu ids in openclaw.json passen; doctor listet stale install, niemand wagt fix aus Angst vor Produktionskanal-Verlust.

Dritte Ursache: Zirkel doctor und Gateway — bei Boot-Verweigerung wird Gateway neu gestartet statt openclaw doctor --fix oder manuellem npm install im richtigen Wurzelverzeichnis abzuschließen. Ohne Config-Backup kann nicht-interaktives fix allow-only-Plug-ins aus dem Manifest entfernen; Cron-Jobs fallen still aus. Vierte Ursache: Plattenkonkurrenz auf 256-GB-Hosts: Stage, pnpm-Cache und Gateway-Logs auf einer Systemplatte; npm-Entpacken plus APFS-Snapshots — Install ok, Gateway-Timeout. Fünfte Ursache: halbe Cross-Node-Migration — rsync von ~/.openclaw ohne npm-Unterbaum: Config vollständig, Pakete fehlen.

  • Pfaddrift: globales npm und ~/.openclaw/npm parallel, Config nicht migriert.
  • ID-Mehrdeutigkeit: Brave, Discord, Voice — Scope und Manifest-ID weichen ab.
  • Falsche Reparierreihenfolge: Gateway-Neustart vor Paketen; doctor nicht fixierbar.
  • Risiko nicht-interaktiv: doctor --fix entfernt allow-only-Einträge im Migrationsfenster.
  • Plattenwasserstand: Stage und Logs auf einem Volume; Install-Spitzen lösen Alarme aus.
  • Teilsync zwischen Knoten: nur Config, kein npm-Unterverzeichnis.

Externe Plug-in-Vorfälle lassen sich auf eine Regel reduzieren: Jede id in der Config muss in genau einem vereinbarten Verzeichnis auf genau ein physisches Paket zeigen — nicht auf eine weitere globale CLI-Installation.

[ SECTION_02 ] // PATH_MATRIX Global npm, ~/.openclaw/npm und ClawHub: Installationsmatrix

2026.5.x treibt viele Kanal- und Erweiterungs-Plug-ins zu npm-first; Manifest-Metadaten verkürzen Kaltstart-Scans. Zuerst ein einziges Wurzelverzeichnis als Wahrheit festlegen, dann Versionen pinnen.

OpenClaw externe Plug-in-Pfade (2026.5.x Remote-Mac-Praxis)
Dimension A · Global npm (-g) B · ~/.openclaw/npm (Empfehlung) C · ClawHub / eingebaute Kanäle
Einsatz nur CLI, Experimente, Übergang zu 4.x-Doku 2026.5.2+ Produktions-Gateway, mehrere Kanäle Offizielle Built-ins oder ClawHub-gepinnte Erweiterungen
Gateway-Sicht oft installiert, nicht gescannt stimmt mit doctor-Reparatur überein abhängig von Manifest und Kanalschaltern
Rollback mittel: global und Config gemeinsam säubern niedrig: npm-Unterbaum tarballen niedrig bis mittel: pro Plug-in-id
Remote-Mac-Disk oft System-global node_modules STAGE_DIR auf Datenträger Cache wächst mit Plug-in-Anzahl

Wer in der Multi-Workspace-Notiz ClawHub pro Projekt pinnt, sollte externe npm-Plug-ins pro Workspace registrieren, damit ein Discord-Upgrade für Projekt A den gemeinsamen Ordner von Projekt B nicht überschreibt.

[ SECTION_03 ] // DOCTOR_STAGE openclaw doctor und OPENCLAW_PLUGIN_STAGE_DIR-Schichtung

Doctor bietet Lesemodus und automatische Reparatur. Im Änderungsfenster zuerst openclaw doctor --lint archivieren (fehlende Pakete, stale install, Config auf nicht existierende Pfade), danach openclaw doctor --fix. Startet Gateway nicht, fehlende @openclaw/*-Pakete nach ~/.openclaw/npm legen ohne Gateway-Boot, dann fix. Migrationsfenster um 2026.5.2 zeigten oft global installierte lobster-Pakete mit falschem Scan-Pfad; manuelles Install plus fix schlägt Restart-Schleifen.

OPENCLAW_PLUGIN_STAGE_DIR trennt npm-Entpack-Wurzel von Laufzeit-Ladewurzel. Auf Remote-Mac Stage auf Datenträger oder Erweiterungsvolume, Hot-Pfade auf SSD. Nach jedem Release prüfen, ob launchd-plist die Variable noch exportiert.

Offizielle doctor- und Release-Dokumentation nach jedem adoptierten Tag erneut öffnen.

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 Zehn Schritte: externe Plug-ins von 4.x auf 2026.5.x auf Remote-Mac

  1. Plug-in-Manifest einfrieren: aktivierte ids, Versionen und Kanalabhängigkeiten ins Change-Ticket.
  2. Vollbackup: ~/.openclaw inkl. npm und launchd-plists; openclaw --version notieren.
  3. CLI upgraden: Release Notes befolgen; Migrationshinweise zwischen Major-Linien nicht überspringen.
  4. npm-Wurzel anlegen: ~/.openclaw/npm/package.json muss existieren; nicht nur global installieren.
  5. Nach Liste installieren: versioniertes npm install unter ~/.openclaw/npm; allow-only vor optionalen Kanälen.
  6. STAGE_DIR setzen: ab 512 GB Stage vom Systemvolume; bei 256 GB mindestens 20 GB für Plug-ins und Cache.
  7. Lint dann fix: doctor --lint ohne configured-but-missing, dann --fix.
  8. Gateway prüfen: openclaw gateway status und Port 18789 laut Health-Check-Notiz.
  9. Kanal-Smoke-Tests: je aktiviertem Kanal eine Testnachricht; Latenz und Logpfad dokumentieren.
  10. Runbook zurückschreiben: Verzeichnisbaum, Pins und Rollback-tarball; vierteljährlich prüfen.

Fallstudie (anonymisiert): Dreiköpfiges Team auf Tokio-M4-Pro von 2026.4.27 auf 2026.5.4; fehlendes discord-Paket trotz globalem npm i. Pakete unter ~/.openclaw/npm, Stage auf Erweiterungsvolume; doctor --fix einmal grün; Ausfall von geschätzten 90 auf 28 Minuten.

[ SECTION_05 ] // DATA_FAQ Kennzahlen, Plattenbudget und FAQ

Die folgenden Intervalle dienen der Kapazitätsplanung, nicht als Garantie für Ihren Host. Nach jedem Release mit offizieller Doku abgleichen.

  • Plug-in-Wurzel: ab 2026.5.2 Produktion mit ~/.openclaw/npm/node_modules als Standard; nicht mit npm root -g mischen.
  • Plattenbudget: auf 256-GB-Remote-Macs mindestens 20 GB für Stage und npm-Cache; bei mehreren Workspaces und schweren Logs 1 TB oder 2 TB Erweiterung prüfen.
  • Doctor-Modi: --lint für CI und Vorab-Checks; --non-interactive für unbeaufsichtigte Fenster; --deep bei doppelten Install-Bäumen.
  • Release-Takt: 2026.5.3 bis 5.4 mit Dateiübertragungs-Tools und Gateway-Lazy-Load; mehr Plug-ins machen Manifest-Cache und Schichtung wichtiger.

FAQ:

  • F: Globale Pakete weiter nutzen? A: Nicht als Produktionsstandard. Nach ~/.openclaw/npm migrieren und Config anpassen.
  • F: Doctor bei Gateway-Ausfall? A: Ja. Gateway muss nicht lauschen; fehlende Pakete vor fix installieren.
  • F: Abgrenzung zur Upgrade-Notiz? A: Upgrade-Notiz für CLI und LaunchAgent; dieser Text für externe npm-Plug-ins und 4.x-Migration.
  • F: Region für Installation? A: Plug-in-Install auf demselben Host wie Gateway; Konsolenplatzierung nahe den Operatoren; Regionshinweise auf der Preisseite.

Alternativen haben Grenzen: lokale Laptop-Tests beweisen kein launchd-Umgebungsvererbung auf Remote-Bare-Metal; Plug-in-Bäume auf nicht erweiterbarer Systemplatte kollidieren mit wiederholten npm-Updates; Büro-Macs erlauben selten schnellen Regions- oder Speicherwechsel im Migrationsfenster. Wer OpenClaw 2026.5.x externe Plug-ins mit iOS-CI und AI-Agenten produktiv betreibt und doctor sowie ~/.openclaw/npm auditierbar und rollback-fähig braucht, findet bei NOVAKVM Mac-mini-Cloud-Miete meist die bessere Lösung: dediziertes Apple Silicon, sechs Bare-Metal-Regionen, Tages- oder Wochenmiete vor M4-Pro-Stufen und Speichererweiterung. Vor dem nächsten Minor-Upgrade Plug-in-Manifest und npm-Unterbaum sichern — das schlägt Raten um zwei Uhr morgens, wo die Pakete wirklich liegen.