Plugins

Plugins erweitern OpenClaw um Kanäle, Modell-Provider, Agent-Harnesses, Tools, Skills, Sprache, Echtzeit-Transkription, Voice, Medienverständnis, Generierung, Webabruf, Websuche und weitere Runtime-Funktionen.

Verwenden Sie diese Seite, wenn Sie ein Plugin installieren, den Gateway neu starten, prüfen möchten, dass die Runtime es geladen hat, und häufige Setup-Fehler einordnen möchten. Nur-Befehl-Beispiele finden Sie unter Plugins verwalten. Das vollständige generierte Inventar gebündelter, offizieller externer und nur im Quellcode vorhandener Plugins finden Sie unter Plugin-Inventar.

Anforderungen

Stellen Sie vor der Installation eines Plugins sicher, dass Sie Folgendes haben:

• einen OpenClaw-Checkout oder eine OpenClaw-Installation, in der die openclaw-CLI verfügbar ist
• Netzwerkzugriff auf die ausgewählte Quelle, etwa ClawHub, npm oder einen Git-Host
• alle Plugin-spezifischen Anmeldedaten, Konfigurationsschlüssel oder Betriebssystem-Tools, die in der Setup-Dokumentation dieses Plugins genannt werden
• die Berechtigung, den Gateway, der Ihre Kanäle bereitstellt, neu zu laden oder neu zu starten

Schnellstart

openclaw plugins search "calendar"

# From ClawHub.openclaw plugins install clawhub:<package> # From npm.openclaw plugins install npm:<package> # From git.openclaw plugins install git:github.com/<owner>/<repo>@<ref> # From a local development checkout.openclaw plugins install ./my-pluginopenclaw plugins install --link ./my-plugin

openclaw plugins enable <plugin-id>

openclaw gateway restart

openclaw plugins inspect <plugin-id> --runtime --json

Konfiguration

Installationsquelle auswählen

Package-Spezifikationen ohne Präfix haben spezielles Kompatibilitätsverhalten. Wenn der reine Name einer gebündelten Plugin-ID entspricht, verwendet OpenClaw diese gebündelte Quelle. Wenn er einer offiziellen externen Plugin-ID entspricht, verwendet OpenClaw den offiziellen Package-Katalog. Andere gewöhnliche Package-Spezifikationen ohne Präfix werden während der Umstellung zum Launch über npm installiert. Rohe @openclaw/*-Package-Spezifikationen, die gebündelten Plugins entsprechen, werden ebenfalls auf die gebündelte Kopie aufgelöst, bevor auf npm zurückgegriffen wird. Verwenden Sie npm:@openclaw/<plugin>@<version>, wenn Sie bewusst das externe npm-Package statt der image-eigenen gebündelten Kopie verwenden möchten. Verwenden Sie clawhub:, npm:, git: oder npm-pack:, wenn Sie deterministische Quellenauswahl benötigen. Den vollständigen Befehlsvertrag finden Sie unter openclaw plugins.

Bei npm-Installationen wählen nicht gepinnte Package-Spezifikationen und @latest das neueste stabile Package, das Kompatibilität mit diesem OpenClaw-Build ausweist. Wenn das aktuelle neueste Release von npm ein neueres openclaw.compat.pluginApi oder openclaw.install.minHostVersion deklariert, durchsucht OpenClaw ältere stabile Package-Versionen und installiert die neueste passende Version. Exakte Versionen und explizite Channel-Tags wie @beta bleiben auf das ausgewählte Package gepinnt und schlagen fehl, wenn sie inkompatibel sind.

Installationsrichtlinie für Betreiber

Konfigurieren Sie security.installPolicy, um einen vertrauenswürdigen lokalen Richtlinienbefehl auszuführen, bevor die Plugin-Installation oder -Aktualisierung fortgesetzt wird. Die Richtlinie erhält Metadaten sowie den bereitgestellten Quellpfad und kann die Installation erlauben oder blockieren. Sie gilt für CLI- und Gateway-gestützte Plugin-Installations- und Aktualisierungspfade. Plugin-before_install-Hooks laufen später nur in OpenClaw-Prozessen, in denen Plugin-Hooks geladen sind. Verwenden Sie daher security.installPolicy für betreibereigene Installationsentscheidungen. Das veraltete --dangerously-force-unsafe-install-Flag wird aus Kompatibilitätsgründen akzeptiert, umgeht aber weder die Installationsrichtlinie noch die integrierte Denylist für Plugin-Abhängigkeiten von OpenClaw.

Das gemeinsame Exec-Schema für security.installPolicy, das sowohl von Skills als auch Plugins verwendet wird, finden Sie unter Skills-Konfiguration.

Plugin-Richtlinie konfigurieren

Die übliche Plugin-Konfigurationsform ist:

{  plugins: {    enabled: true,    allow: ["voice-call"],    deny: ["untrusted-plugin"],    load: { paths: ["~/Projects/oss/voice-call-plugin"] },    slots: { memory: "memory-core" },    entries: {      "voice-call": { enabled: true, config: { provider: "twilio" } },    },  },}

Wichtige Richtlinienregeln:

• plugins.enabled: false deaktiviert alle Plugins und überspringt Plugin-Discovery- und Ladearbeit. Veraltete Plugin-Referenzen sind inaktiv, solange dies aktiv ist; aktivieren Sie Plugins erneut, bevor Sie die Doctor-Bereinigung ausführen, wenn veraltete IDs entfernt werden sollen.
• plugins.deny hat Vorrang vor Allow und Plugin-spezifischer Aktivierung.
• plugins.allow ist eine exklusive Allowlist. Plugin-eigene Tools außerhalb der Allowlist bleiben nicht verfügbar, auch wenn tools.allow "*" enthält.
• plugins.entries.<id>.enabled: false deaktiviert ein einzelnes Plugin, während dessen Konfiguration erhalten bleibt.
• plugins.load.paths fügt explizite lokale Plugin-Dateien oder -Verzeichnisse hinzu. Verwaltete lokale Pfade für plugins install müssen Plugin-Verzeichnisse oder Archive sein; verwenden Sie plugins.load.paths für eigenständige Plugin-Dateien.
• Plugins aus dem Workspace sind standardmäßig deaktiviert; aktivieren Sie sie explizit oder nehmen Sie sie in die Allowlist auf, bevor Sie lokalen Workspace-Code verwenden.
• Gebündelte Plugins folgen ihren integrierten Default-on-/Default-off-Metadaten, sofern die Konfiguration sie nicht explizit überschreibt.
• plugins.slots.<slot> wählt ein Plugin für exklusive Kategorien wie Speicher- und Kontext-Engines aus. Die Slot-Auswahl aktiviert das ausgewählte Plugin für diesen Slot zwangsweise, indem sie als explizite Aktivierung zählt; es kann geladen werden, auch wenn es andernfalls opt-in wäre. plugins.deny und plugins.entries.<id>.enabled: false blockieren es weiterhin.
• Gebündelte Opt-in-Plugins können automatisch aktiviert werden, wenn die Konfiguration eine ihrer eigenen Oberflächen benennt, etwa eine Provider-/Modell-Ref, Channel-Konfiguration, ein CLI-Backend oder eine Agent- Harness-Runtime.
• OpenAI-Family-Codex-Routing hält Provider- und Runtime-Plugin-Grenzen getrennt: Legacy-Codex-Modell-Refs sind Legacy-Konfiguration, die von Doctor repariert wird, während das gebündelte codex-Plugin die Codex-App-Server-Runtime für kanonische openai/*-Agent- Refs, explizite agentRuntime.id: "codex" und Legacy-codex/*-Refs besitzt.

Wenn plugins.allow nicht gesetzt ist und nicht gebündelte Plugins aus Workspace- oder globalen Plugin-Roots automatisch entdeckt werden, protokolliert der Start plugins.allow is empty; discovered non-bundled plugins may auto-load: .... Die Warnung enthält entdeckte Plugin-IDs und bei kurzen Listen ein minimales plugins.allow-Snippet. Führen Sie openclaw plugins list --enabled --verbose oder openclaw plugins inspect <id> mit der aufgelisteten Plugin- ID aus, bevor Sie vertrauenswürdige Plugins in openclaw.json kopieren. Dieselbe Trust-Pinning- Empfehlung gilt, wenn Diagnosen melden, dass ein Plugin without install/load-path provenance geladen wurde: Inspizieren Sie diese Plugin-ID und pinnen Sie dann die vertrauenswürdige ID in plugins.allow oder installieren Sie aus einer vertrauenswürdigen Quelle neu, damit OpenClaw die Installationsprovenienz aufzeichnet.

Führen Sie openclaw doctor oder openclaw doctor --fix aus, wenn die Konfigurationsvalidierung veraltete Plugin-IDs, Allowlist-/Tool-Abweichungen oder Legacy-Pfade gebündelter Plugins meldet.

Plugin-Formate verstehen

OpenClaw erkennt zwei Plugin-Formate:

Beide Formate erscheinen in openclaw plugins list, openclaw plugins inspect, openclaw plugins enable und openclaw plugins disable. Siehe Plugin-Bundles für die Bundle-Kompatibilitätsgrenze und Plugins erstellen für natives Plugin-Authoring.

Plugin-Hooks

Plugins können zur Runtime Hooks registrieren, aber es gibt zwei verschiedene APIs mit unterschiedlichen Aufgaben.

• Verwenden Sie typisierte Hooks über api.on(...) für Runtime-Lifecycle-Hooks. Dies ist die bevorzugte Oberfläche für Middleware, Richtlinien, Nachrichtenumschreibung, Prompt-Gestaltung und Tool-Steuerung.
• Verwenden Sie api.registerHook(...) nur, wenn Sie am internen Hook-System teilnehmen möchten, das unter Hooks beschrieben ist. Dies ist hauptsächlich für grobe Befehls-/Lifecycle-Nebeneffekte und Kompatibilität mit vorhandener HOOK-artiger Automatisierung gedacht.

Kurzregel:

• Wenn der Handler Priorität, Merge-Semantik oder Blockier-/Abbruchverhalten benötigt, verwenden Sie typisierte Plugin-Hooks.
• Wenn der Handler nur auf command:new, command:reset, message:sent oder ähnliche grobe Ereignisse reagiert, ist api.registerHook(...) in Ordnung.

Plugin-verwaltete interne Hooks erscheinen in openclaw hooks list mit plugin:<id>. Sie können sie nicht über openclaw hooks aktivieren oder deaktivieren; aktivieren oder deaktivieren Sie stattdessen das Plugin.

Aktiven Gateway prüfen

openclaw plugins list und einfaches openclaw plugins inspect lesen kalte Config, Manifest- und Registry-Zustände. Sie belegen nicht, dass ein bereits laufender Gateway denselben Plugin-Code importiert hat.

Wenn ein Plugin installiert zu sein scheint, Live-Chat-Traffic es aber nicht verwendet:

openclaw gateway status --deep --require-rpcopenclaw plugins inspect <plugin-id> --runtime --jsonopenclaw gateway restart

Verwaltete Gateways starten automatisch neu, nachdem Plugin-Installationen, -Updates und -Deinstallationen Plugin-Quellen ändern. Stellen Sie bei VPS- oder Container-Installationen sicher, dass ein manueller Neustart den tatsächlichen openclaw gateway run-Child-Prozess trifft, der Ihre Kanäle bedient, nicht nur einen Wrapper oder Supervisor.

Fehlerbehebung

Wenn veraltete Plugin-Config weiterhin ein nicht mehr auffindbares Kanal-Plugin benennt, überspringt der Gateway-Start diesen Plugin-gestützten Kanal, statt alle anderen Kanäle zu blockieren. Führen Sie openclaw doctor --fix aus, um veraltete Plugin- und Kanal- Einträge zu entfernen. Unbekannte Kanalschlüssel ohne Hinweise auf veraltete Plugins schlagen weiterhin bei der Validierung fehl, damit Tippfehler sichtbar bleiben.

Für absichtliche Kanalersetzung sollte das bevorzugte Plugin channelConfigs.<channel-id>.preferOver mit der Legacy- oder niedriger priorisierten Plugin-ID deklarieren. Wenn beide Plugins explizit aktiviert sind, behält OpenClaw diese Anfrage bei und meldet doppelte Kanal- oder Tool-Diagnosen, statt stillschweigend einen Besitzer auszuwählen.

Wenn ein installiertes Paket meldet, dass es requires compiled runtime output for TypeScript entry ..., wurde das Paket ohne die JavaScript-Dateien veröffentlicht, die OpenClaw zur Laufzeit benötigt. Aktualisieren oder installieren Sie neu, nachdem der Publisher kompiliertes JavaScript ausgeliefert hat, oder deaktivieren/deinstallieren Sie das Plugin bis dahin.

Blockierter Plugin-Pfadbesitz

Wenn Plugin-Diagnosen blocked plugin candidate: suspicious ownership (... uid=1000, expected uid=0 or root) melden und die Config-Validierung mit plugin present but blocked folgt, hat OpenClaw Plugin-Dateien gefunden, die einem anderen Unix-Benutzer gehören als dem Prozess, der sie lädt. Behalten Sie die Plugin-Config bei; korrigieren Sie den Dateisystem-Besitz oder führen Sie OpenClaw als denselben Benutzer aus, dem das Zustandsverzeichnis gehört.

Bei Docker-Installationen läuft das offizielle Image als node (uid 1000), daher sollten die vom Host bind-gemounteten OpenClaw-Config- und Workspace-Verzeichnisse normalerweise uid 1000 gehören:

sudo chown -R 1000:1000 /path/to/openclaw-config /path/to/openclaw-workspace

Wenn Sie OpenClaw absichtlich als root ausführen, reparieren Sie stattdessen den verwalteten Plugin-Root auf root-Besitz:

sudo chown -R root:root /path/to/openclaw-config/npm

Nachdem Sie den Besitz korrigiert haben, führen Sie erneut openclaw doctor --fix oder openclaw plugins registry --refresh aus, damit die persistierte Plugin-Registry den reparierten Dateien entspricht.

Langsame Einrichtung von Plugin-Tools

Wenn Agent-Turns beim Vorbereiten von Tools zu hängen scheinen, aktivieren Sie Trace-Logging und prüfen Sie auf Timing-Zeilen der Plugin-Tool-Factory:

openclaw config set logging.level traceopenclaw logs --follow

Suchen Sie nach:

[trace:plugin-tools] factory timings ...

Die Zusammenfassung listet die gesamte Factory-Zeit und die langsamsten Plugin-Tool-Factorys auf, einschließlich Plugin-ID, deklarierter Tool-Namen, Ergebnisform und ob das Tool optional ist. Langsame Zeilen werden zu Warnungen hochgestuft, wenn eine einzelne Factory mindestens 1 s benötigt oder die gesamte Vorbereitung der Plugin-Tool-Factorys mindestens 5 s dauert.

OpenClaw cached erfolgreiche Ergebnisse der Plugin-Tool-Factory für wiederholte Auflösungen mit demselben effektiven Anfragekontext. Der Cache-Schlüssel enthält die effektive Runtime-Config, Workspace, Agent-/Session-IDs, Sandbox-Richtlinie, Browser-Einstellungen, Delivery-Kontext, Requester-Identität und Besitzstatus, sodass Factorys, die von diesen vertrauenswürdigen Feldern abhängen, erneut ausgeführt werden, wenn sich der Kontext ändert. Wenn die Timings hoch bleiben, erledigt das Plugin möglicherweise teure Arbeit, bevor es seine Tool- Definitionen zurückgibt.

Wenn ein Plugin das Timing dominiert, prüfen Sie seine Runtime-Registrierungen:

openclaw plugins inspect <plugin-id> --runtime --json

Aktualisieren, installieren Sie dieses Plugin dann neu, oder deaktivieren Sie es. Plugin-Autoren sollten teures Dependency-Laden hinter den Tool-Ausführungspfad verschieben, statt es innerhalb der Tool-Factory zu erledigen.

Für Dependency-Roots, Paketmetadaten-Validierung, Registry-Einträge, Startup- Reload-Verhalten und Legacy-Bereinigung siehe Plugin-Dependency-Auflösung.

Verwandt

• Plugins verwalten - Befehlsbeispiele für Auflisten, Installieren, Aktualisieren, Deinstallieren und Veröffentlichen
• openclaw plugins - vollständige CLI-Referenz
• Plugin-Inventar - generierte Liste gebündelter und externer Plugins
• Plugin-Referenz - generierte Referenzseiten pro Plugin
• Community-Plugins - ClawHub-Discovery und Docs-PR-Richtlinie
• Plugin-Dependency-Auflösung - Installations-Roots, Registry-Einträge und Runtime-Grenzen
• Plugins erstellen - Leitfaden zum Erstellen nativer Plugins
• Plugin SDK-Überblick - Runtime-Registrierung, Hooks und API-Felder
• Plugin-Manifest - Manifest- und Paketmetadaten