Interne Plugin-Struktur

Dies ist die ausführliche Architekturreferenz für das Plugin-System von OpenClaw. Für praxisorientierte Anleitungen beginnen Sie mit einer der nachstehenden Themenseiten.

Öffentliches Fähigkeitsmodell

Fähigkeiten bilden das öffentliche Modell für native Plugins innerhalb von OpenClaw. Jedes native OpenClaw-Plugin registriert sich für einen oder mehrere Fähigkeitstypen:

Haltung zur externen Kompatibilität

Das Fähigkeitsmodell ist im Kern implementiert und wird heute von gebündelten und nativen Plugins verwendet. Für die Kompatibilität externer Plugins gelten jedoch strengere Anforderungen als „es wird exportiert und ist daher unveränderlich“.

Die Fähigkeitsregistrierung ist die vorgesehene Entwicklungsrichtung. Veraltete Hooks bleiben während des Übergangs für externe Plugins der sicherste Weg ohne Kompatibilitätsbrüche. Exportierte Hilfsunterpfade sind nicht alle gleichwertig – bevorzugen Sie eng gefasste, dokumentierte Verträge gegenüber beiläufig exportierten Hilfsfunktionen.

Plugin-Formen

OpenClaw ordnet jedes geladene Plugin anhand seines tatsächlichen Registrierungsverhaltens einer Form zu, nicht nur anhand statischer Metadaten:

Verwenden Sie openclaw plugins inspect <id>, um die Form und die Aufschlüsselung der Fähigkeiten eines Plugins anzuzeigen. Einzelheiten finden Sie in der CLI-Referenz.

Veraltete Hooks

Der Hook before_agent_start wird weiterhin als Kompatibilitätspfad für reine Hook-Plugins unterstützt. Bestehende, in der Praxis eingesetzte Plugins sind weiterhin davon abhängig.

Entwicklungsrichtung:

• funktionsfähig halten
• als veraltet dokumentieren
• für das Überschreiben von Modellen oder Providern bevorzugt before_model_resolve verwenden
• für Änderungen am Prompt bevorzugt before_prompt_build verwenden
• erst entfernen, wenn die tatsächliche Nutzung zurückgegangen ist und die Abdeckung durch Test-Fixtures eine sichere Migration nachweist

Kompatibilitätssignale

openclaw doctor, openclaw plugins inspect <id>, openclaw status --all und openclaw plugins doctor zeigen folgende Kompatibilitätshinweise an:

Keines der Hinweis- oder Warnsignale beeinträchtigt Ihr Plugin derzeit. Diese Signale werden auch in openclaw status --all und openclaw plugins doctor angezeigt.

Architekturübersicht

Das Plugin-System von OpenClaw besteht aus vier Schichten:

Speziell für die Plugin-CLI ist die Erkennung von Stammbefehlen in zwei Phasen unterteilt:

• Metadaten zur Auswertungszeit stammen aus registerCli(..., { descriptors: [...] })
• das eigentliche CLI-Modul des Plugins kann verzögert geladen und beim ersten Aufruf registriert werden

Dadurch verbleibt der Plugin-eigene CLI-Code im Plugin, während OpenClaw die Namen der Stammbefehle dennoch vor der Auswertung reservieren kann.

Die wichtige Entwurfsgrenze:

• die Manifest- und Konfigurationsvalidierung sollte anhand von Manifest-/Schema-Metadaten funktionieren, ohne Plugin-Code auszuführen
• die Erkennung nativer Fähigkeiten darf vertrauenswürdigen Plugin-Einstiegscode laden, um einen nicht aktivierenden Registry-Schnappschuss zu erstellen
• das native Laufzeitverhalten stammt aus dem Pfad register(api) des Plugin-Moduls, wobei api.registrationMode === "full" gilt

Diese Trennung ermöglicht OpenClaw, die Konfiguration zu validieren, fehlende oder deaktivierte Plugins zu erläutern und Hinweise für Benutzeroberfläche und Schema zu erstellen, bevor die vollständige Laufzeit aktiv ist.

Schnappschuss der Plugin-Metadaten und Nachschlagetabelle

Beim Start des Gateway wird ein PluginMetadataSnapshot für den aktuellen Konfigurationsschnappschuss erstellt. Der Schnappschuss enthält ausschließlich Metadaten: Er speichert den Index der installierten Plugins, die Manifest-Registry, Manifestdiagnosen, Eigentümerzuordnungen, einen Normalisierer für Plugin-IDs und Manifesteinträge. Er enthält keine geladenen Plugin-Module, Provider-SDKs, Paketinhalte oder Laufzeitexporte.

Plugin-spezifische Konfigurationsvalidierung, automatische Aktivierung beim Start und das Bootstrapping von Gateway-Plugins verwenden diesen Schnappschuss, anstatt Manifest- und Indexmetadaten unabhängig voneinander neu zu erstellen. PluginLookUpTable wird aus demselben Schnappschuss abgeleitet und ergänzt den Plugin-Startplan für die aktuelle Laufzeitkonfiguration.

Nach dem Start behält das Gateway den aktuellen Metadatenschnappschuss als austauschbares Laufzeitprodukt bei. Wiederholte Erkennung von Providern zur Laufzeit kann diesen Schnappschuss verwenden, anstatt für jeden Durchlauf des Provider-Katalogs den installierten Index und die Manifest-Registry neu zu erstellen. Der Schnappschuss wird beim Herunterfahren des Gateway, bei Änderungen an der Konfiguration oder am Plugin-Bestand sowie beim Schreiben des installierten Index gelöscht oder ersetzt; Aufrufer greifen auf den kalten Manifest-/Indexpfad zurück, wenn kein kompatibler aktueller Schnappschuss vorhanden ist. Kompatibilitätsprüfungen müssen Plugin-Erkennungswurzeln wie plugins.load.paths und den standardmäßigen Agent-Arbeitsbereich einbeziehen, da Arbeitsbereichs-Plugins zum Umfang der Metadaten gehören.

Der Schnappschuss und die Nachschlagetabelle halten wiederholte Startentscheidungen auf dem schnellen Pfad:

• Kanalzuständigkeit
• verzögerter Kanalstart
• Plugin-IDs beim Start
• Zuständigkeit für Provider und CLI-Backends
• Zuständigkeit für Einrichtungs-Provider, Befehlsalias, Modellkatalog-Provider und Manifestvertrag
• Validierung des Plugin-Konfigurationsschemas und des Kanal-Konfigurationsschemas
• Entscheidungen zur automatischen Aktivierung beim Start

Die Sicherheitsgrenze besteht im Ersetzen des Schnappschusses, nicht in dessen Veränderung. Erstellen Sie den Schnappschuss neu, wenn sich die Konfiguration, der Plugin-Bestand, Installationsdatensätze oder die Richtlinie des persistenten Index ändern. Behandeln Sie ihn nicht als umfassende veränderliche globale Registry und bewahren Sie keine unbegrenzte Historie von Schnappschüssen auf. Das Laden von Plugins zur Laufzeit bleibt von Metadatenschnappschüssen getrennt, sodass veralteter Laufzeitzustand nicht hinter einem Metadaten-Cache verborgen werden kann.

Die Cache-Regel ist unter Interna der Plugin-Architektur dokumentiert: Manifest- und Erkennungsmetadaten sind aktuell, sofern ein Aufrufer nicht ausdrücklich einen Schnappschuss, eine Nachschlagetabelle oder eine Manifest-Registry für den aktuellen Ablauf vorhält. Verborgene Metadaten-Caches und zeitbasierte TTLs sind nicht Bestandteil des Ladens von Plugins. Nur Caches des Laufzeitladers sowie Modul- und Abhängigkeitsartefakt-Caches dürfen bestehen bleiben, nachdem Code oder installierte Artefakte tatsächlich geladen wurden.

Einige Aufrufer auf kalten Pfaden erstellen Manifest-Registrys weiterhin direkt aus dem persistent gespeicherten Index installierter Plugins neu, anstatt eine PluginLookUpTable des Gateway zu erhalten. Dieser Pfad erstellt die Registry nun bei Bedarf neu. Bevorzugen Sie die Weitergabe der aktuellen Nachschlagetabelle oder einer ausdrücklichen Manifest-Registry durch Laufzeitabläufe, wenn ein Aufrufer bereits über eine solche verfügt.

Aktivierungsplanung

Die Aktivierungsplanung ist Teil der Steuerungsebene. Aufrufer können vor dem Laden umfassenderer Laufzeitregistrierungen abfragen, welche Plugins für einen konkreten Befehl, Provider, Kanal, eine Route, eine Agent-Harness oder eine Fähigkeit relevant sind.

Der Planer bleibt mit dem aktuellen Manifestverhalten kompatibel:

• activation.*-Felder sind explizite Planungshinweise
• providers, channels, commandAliases, setup.providers, contracts.tools und Hooks bleiben der auf Manifest-Eigentümerschaft basierende Rückfallmechanismus
• die Planer-API, die nur IDs zurückgibt, bleibt für bestehende Aufrufer verfügbar
• die Plan-API meldet Begründungsbezeichnungen, damit die Diagnose explizite Hinweise vom eigentümerschaftsbasierten Rückfallmechanismus unterscheiden kann

Kanal-Plugins und das gemeinsame Nachrichtenwerkzeug

Kanal-Plugins müssen für gewöhnliche Chataktionen kein separates Werkzeug zum Senden, Bearbeiten oder Reagieren registrieren. OpenClaw stellt im Kern ein gemeinsames message-Werkzeug bereit, während Kanal-Plugins die dahinterliegende kanalspezifische Ermittlung und Ausführung übernehmen.

Die aktuelle Abgrenzung lautet:

• der Kern ist für den Host des gemeinsamen message-Werkzeugs, die Prompt-Anbindung, die Sitzungs- und Thread-Verwaltung sowie die Ausführungsverteilung zuständig
• Kanal-Plugins sind für die bereichsbezogene Ermittlung von Aktionen und Fähigkeiten sowie für alle kanalspezifischen Schemafragmente zuständig
• Kanal-Plugins sind für die providerspezifische Grammatik von Sitzungskonversationen zuständig, etwa dafür, wie Konversations-IDs Thread-IDs codieren oder von übergeordneten Konversationen erben
• Kanal-Plugins führen die endgültige Aktion über ihren Aktionsadapter aus

Für Kanal-Plugins ist ChannelMessageActionAdapter.describeMessageTool(...) die SDK-Oberfläche. Mit diesem einheitlichen Ermittlungsaufruf kann ein Plugin seine sichtbaren Aktionen, Fähigkeiten und Schemabeiträge gemeinsam zurückgeben, damit diese Bestandteile nicht auseinanderlaufen.

Wenn ein kanalspezifischer Parameter des Nachrichtenwerkzeugs eine Medienquelle wie einen lokalen Pfad oder eine Remote-Medien-URL enthält, sollte das Plugin außerdem mediaSourceParams aus describeMessageTool(...) zurückgeben. Der Kern verwendet diese explizite Liste, um die Normalisierung von Sandbox-Pfaden und Hinweise für den ausgehenden Medienzugriff anzuwenden, ohne Parameternamen fest einzucodieren, die dem Plugin gehören. Bevorzugen Sie dort aktionsbezogene Zuordnungen statt einer einzigen flachen, kanalweiten Liste, damit ein nur für Profile bestimmter Medienparameter nicht bei nicht zugehörigen Aktionen wie send normalisiert wird.

Der Kern übergibt den Laufzeitbereich an diesen Ermittlungsschritt. Wichtige Felder sind:

• accountId
• currentChannelId
• currentThreadTs
• currentMessageId
• sessionKey
• sessionId
• agentId
• die vertrauenswürdige eingehende requesterSenderId

Dies ist für kontextabhängige Plugins wichtig. Ein Kanal kann Nachrichtenaktionen anhand des aktiven Kontos, des aktuellen Raums, Threads oder der aktuellen Nachricht sowie der vertrauenswürdigen Identität des Anfragenden aus- oder einblenden, ohne kanalspezifische Verzweigungen im zentralen message-Werkzeug fest einzucodieren.

Deshalb bleiben Änderungen am Routing eingebetteter Runner weiterhin Plugin-Arbeit: Der Runner ist dafür verantwortlich, die aktuelle Chat- und Sitzungsidentität an die Ermittlungsgrenze des Plugins weiterzuleiten, damit das gemeinsame message-Werkzeug für den aktuellen Durchlauf die richtige, dem Kanal gehörende Oberfläche bereitstellt.

Bei kanaleigenen Ausführungshilfen sollten gebündelte Plugins die Ausführungslaufzeit in ihren eigenen Plugin-Modulen belassen. Der Kern ist nicht länger für die Laufzeiten der Nachrichtenaktionen von Discord, Slack, Telegram oder WhatsApp unter src/agents/tools zuständig. Wir veröffentlichen keine separaten Unterpfade vom Typ plugin-sdk/*-action-runtime, und gebündelte Plugins sollten ihren eigenen lokalen Laufzeitcode direkt aus ihren Plugin-eigenen Modulen importieren.

Dieselbe Abgrenzung gilt allgemein für nach Providern benannte SDK-Schnittstellen: Der Kern sollte keine kanalspezifischen Komfort-Barrels für Discord, Signal, Slack, WhatsApp oder ähnliche Plugins importieren. Benötigt der Kern ein Verhalten, sollte er entweder das eigene api.ts- oder runtime-api.ts-Barrel des gebündelten Plugins verwenden oder den Bedarf zu einer eng gefassten generischen Fähigkeit im gemeinsamen SDK erheben.

Für gebündelte Plugins gilt dieselbe Regel. Die Datei runtime-api.ts eines gebündelten Plugins sollte nicht dessen eigene markenspezifische Fassade openclaw/plugin-sdk/<plugin-id> erneut exportieren. Diese markenspezifischen Fassaden bleiben Kompatibilitätsschichten für externe Plugins und ältere Nutzer, gebündelte Plugins sollten jedoch lokale Exporte sowie eng gefasste generische SDK-Unterpfade wie openclaw/plugin-sdk/channel-policy, openclaw/plugin-sdk/runtime-store oder openclaw/plugin-sdk/webhook-ingress verwenden. Neuer Code sollte keine Plugin-ID-spezifischen SDK-Fassaden hinzufügen, es sei denn, die Kompatibilitätsgrenze eines bestehenden externen Ökosystems erfordert dies.

Speziell für Umfragen gibt es zwei Ausführungspfade:

• outbound.sendPoll ist die gemeinsame Grundlage für Kanäle, die dem allgemeinen Umfragemodell entsprechen
• actions.handleAction("poll") ist der bevorzugte Pfad für kanalspezifische Umfragesemantik oder zusätzliche Umfrageparameter

Der Kern verschiebt nun die gemeinsame Umfrageanalyse, bis die Plugin-Umfrageverteilung die Aktion abgelehnt hat. Dadurch können Plugin-eigene Umfrage-Handler kanalspezifische Umfragefelder akzeptieren, ohne zuvor vom generischen Umfrageparser blockiert zu werden.

Die vollständige Startsequenz finden Sie unter Interne Plugin-Architektur.

Eigentümerschaftsmodell für Fähigkeiten

OpenClaw behandelt ein natives Plugin als Eigentümerschaftsgrenze für ein Unternehmen oder eine Funktion, nicht als Sammelsurium nicht zusammengehöriger Integrationen.

Das bedeutet:

• ein Unternehmens-Plugin sollte normalerweise alle OpenClaw-seitigen Oberflächen dieses Unternehmens abdecken
• ein Funktions-Plugin sollte normalerweise die vollständige von ihm eingeführte Funktionsoberfläche abdecken
• Kanäle sollten gemeinsame Kernfähigkeiten verwenden, anstatt Providerverhalten ad hoc neu zu implementieren

Der angestrebte Endzustand lautet:

• die OpenClaw-seitige Oberfläche eines Providers befindet sich in einem Plugin, auch wenn sie Textmodelle, Sprache, Bilder und Video umfasst
• andere Provider können dasselbe für ihren eigenen Oberflächenbereich tun
• Kanälen ist gleichgültig, welches Provider-Plugin für den Provider zuständig ist; sie verwenden den vom Kern bereitgestellten gemeinsamen Fähigkeitsvertrag

Dies ist der entscheidende Unterschied:

• Plugin = Eigentümerschaftsgrenze
• Fähigkeit = Kernvertrag, den mehrere Plugins implementieren oder verwenden können

Wenn OpenClaw also einen neuen Bereich wie Video hinzufügt, lautet die erste Frage nicht: „Welcher Provider sollte die Videoverarbeitung fest eincodieren?“ Die erste Frage lautet: „Wie sieht der Kernvertrag für die Videofähigkeit aus?“ Sobald dieser Vertrag vorhanden ist, können sich Provider-Plugins dafür registrieren und Kanal- sowie Funktions-Plugins ihn verwenden.

Wenn die Fähigkeit noch nicht vorhanden ist, ist normalerweise folgendes Vorgehen richtig:

Dadurch bleibt die Eigentümerschaft explizit, während Kernverhalten vermieden wird, das von einem einzelnen Provider oder einem einmaligen Plugin-spezifischen Codepfad abhängt.

Schichtung der Fähigkeiten

Verwenden Sie bei der Entscheidung, wohin Code gehört, folgendes Denkmodell:

TTS folgt beispielsweise diesem Aufbau:

• der Kern ist für die TTS-Richtlinie zur Antwortzeit, die Rückfallreihenfolge, Einstellungen und die Kanalzustellung zuständig
• elevenlabs, google, microsoft und openai sind für die Syntheseimplementierungen zuständig
• voice-call verwendet die TTS-Laufzeithilfe für Telefonie

Dasselbe Muster sollte für zukünftige Fähigkeiten bevorzugt werden.

Beispiel für ein Unternehmens-Plugin mit mehreren Fähigkeiten

Ein Unternehmens-Plugin sollte sich von außen geschlossen anfühlen. Wenn OpenClaw gemeinsame Verträge für Modelle, Sprache, Echtzeittranskription, Echtzeit-Sprache, Medienverständnis, Bildgenerierung, Videogenerierung, Webabruf und Websuche besitzt, kann ein Provider alle seine Oberflächen an einer Stelle abdecken:

    describeImageWithModel,  transcribeOpenAiCompatibleAudio,} from "openclaw/plugin-sdk/media-understanding"; const plugin: OpenClawPluginDefinition = {  id: "exampleai",  name: "ExampleAI",  register(api) {    api.registerProvider({      id: "exampleai",      // Authentifizierungs-/Modellkatalog-/Laufzeit-Hooks    });     api.registerSpeechProvider({      id: "exampleai",      // Provider-Sprachkonfiguration — die SpeechProviderPlugin-Schnittstelle direkt implementieren    });     api.registerMediaUnderstandingProvider({      id: "exampleai",      capabilities: ["image", "audio", "video"],      async describeImage(req) {        return describeImageWithModel({          ...req,          provider: "exampleai",        });      },      async transcribeAudio(req) {        return transcribeOpenAiCompatibleAudio({          ...req,          provider: "exampleai",        });      },    });     api.registerWebSearchProvider(      createPluginBackedWebSearchProvider({        id: "exampleai-search",        // Anmeldedaten- und Abruflogik      }),    );  },}; export default plugin;

Entscheidend sind nicht die genauen Namen der Hilfsfunktionen, sondern der Aufbau:

• ein Plugin ist für die Provideroberfläche zuständig
• der Kern bleibt für die Fähigkeitsverträge zuständig
• Kanäle und Funktions-Plugins verwenden api.runtime.*-Hilfen statt Providercode
• Vertragstests können sicherstellen, dass das Plugin die Fähigkeiten registriert hat, für die es nach eigener Angabe zuständig ist

Fähigkeitsbeispiel: Videoverständnis

OpenClaw behandelt Bild-, Audio- und Videoverständnis bereits als eine gemeinsame Fähigkeit. Dort gilt dasselbe Eigentümerschaftsmodell:

Dadurch werden die Videoannahmen eines einzelnen Providers nicht fest in den Kern eingebaut. Das Plugin ist für die Provideroberfläche zuständig; der Kern ist für den Fähigkeitsvertrag und das Rückfallverhalten zuständig.

Die Videogenerierung verwendet bereits dieselbe Abfolge: Der Kern ist für den typisierten Fähigkeitsvertrag und die Laufzeithilfe zuständig, während Provider-Plugins Implementierungen mit api.registerVideoGenerationProvider(...) dafür registrieren.

Benötigen Sie eine konkrete Checkliste für die Einführung? Weitere Informationen finden Sie im Fähigkeiten-Kochbuch.

Verträge und Durchsetzung

Die Plugin-API-Oberfläche ist bewusst typisiert und in OpenClawPluginApi zentralisiert. Dieser Vertrag definiert die unterstützten Registrierungspunkte und die Laufzeithilfen, auf die sich ein Plugin verlassen darf.

Warum dies wichtig ist:

• Plugin-Autoren erhalten einen einheitlichen, stabilen internen Standard
• der Kern kann doppelte Zuständigkeiten zurückweisen, etwa wenn zwei Plugins dieselbe Provider-ID registrieren
• beim Start können aussagekräftige Diagnosen für fehlerhafte Registrierungen ausgegeben werden
• Vertragstests können die Zuständigkeit gebündelter Plugins durchsetzen und unbemerkte Abweichungen verhindern

Die Durchsetzung erfolgt auf zwei Ebenen:

In der Praxis bedeutet dies, dass OpenClaw von Anfang an weiß, welches Plugin für welche Oberfläche zuständig ist. Dadurch können der Kern und die Kanäle nahtlos zusammenwirken, weil die Zuständigkeit deklariert, typisiert und testbar ist, statt nur implizit zu bestehen.

Was in einen Vertrag gehört

Erhöhen Sie im Zweifelsfall die Abstraktionsebene: Definieren Sie zuerst die Fähigkeit und lassen Sie anschließend Plugins daran anbinden.

Ausführungsmodell

Native OpenClaw-Plugins werden prozessintern zusammen mit dem Gateway ausgeführt. Sie sind nicht durch eine Sandbox isoliert. Ein geladenes natives Plugin befindet sich auf derselben Vertrauensgrenze auf Prozessebene wie der Kerncode.

Kompatible Bundles sind standardmäßig sicherer, da OpenClaw sie derzeit als Metadaten-/Inhaltspakete behandelt. In aktuellen Versionen bedeutet dies hauptsächlich gebündelte Skills.

Verwenden Sie für nicht gebündelte Plugins Positivlisten sowie explizite Installations- und Ladepfade. Behandeln Sie Workspace-Plugins als Code für die Entwicklungsphase und nicht als Produktionsstandard.

Bei Namen gebündelter Workspace-Pakete muss die Plugin-ID im npm-Namen verankert bleiben: standardmäßig @openclaw/<id> oder mit einem genehmigten typisierten Suffix wie -provider, -plugin, -speech, -sandbox oder -media-understanding, wenn das Paket absichtlich eine enger gefasste Plugin-Rolle bereitstellt.

Exportgrenze

OpenClaw exportiert Fähigkeiten und keine Hilfsfunktionen, die lediglich die Implementierung vereinfachen.

Halten Sie die Registrierung von Fähigkeiten öffentlich. Entfernen Sie Hilfsexporte, die nicht zum Vertrag gehören:

• Hilfs-Unterpfade, die nur für bestimmte gebündelte Plugins gelten
• Unterpfade der Laufzeitinfrastruktur, die nicht als öffentliche API vorgesehen sind
• anbieterspezifische Komfortfunktionen
• Hilfsfunktionen für Einrichtung und Onboarding, die Implementierungsdetails darstellen

Reservierte Hilfs-Unterpfade für gebündelte Plugins wurden aus der generierten SDK-Exportzuordnung entfernt. Belassen Sie zuständigkeitsspezifische Hilfsfunktionen innerhalb des jeweils zuständigen Plugin-Pakets; übernehmen Sie nur wiederverwendbares Host-Verhalten in generische SDK-Verträge wie plugin-sdk/gateway-runtime, plugin-sdk/security-runtime und plugin-sdk/plugin-config-runtime.

Interna und Referenz

Informationen zur Lade-Pipeline, zum Registry-Modell, zu Laufzeit-Hooks für Provider, zu Gateway-HTTP-Routen, zu Schemas für Nachrichten-Tools, zur Auflösung von Kanalzielen, zu Provider-Katalogen, zu Plugins für Kontext-Engines sowie eine Anleitung zum Hinzufügen einer neuen Fähigkeit finden Sie unter Interna der Plugin-Architektur.

Verwandte Themen

• Plugins erstellen
• Plugin-Manifest
• Plugin-SDK einrichten