Building plugins

Funktionen hinzufügen (Leitfaden für Mitwirkende)

Verwenden Sie dies, wenn OpenClaw eine neue gemeinsame Domäne benötigt, etwa für Embeddings, Bildgenerierung, Videogenerierung oder einen zukünftigen, von einem Anbieter gestützten Funktionsbereich.

Die Regel:

Plugin = Zuständigkeitsgrenze
Fähigkeit = gemeinsamer Kernvertrag

Binden Sie einen Anbieter nicht direkt in einen Kanal oder ein Tool ein. Definieren Sie zuerst die Fähigkeit.

Wann eine Fähigkeit erstellt werden sollte

Erstellen Sie eine neue Fähigkeit nur, wenn alle folgenden Bedingungen erfüllt sind:

Mehr als ein Anbieter könnte sie plausibel implementieren.
Kanäle, Tools oder Funktions-Plugins sollen sie nutzen können, ohne den Anbieter kennen zu müssen.
Der Kern muss Fallback-, Richtlinien-, Konfigurations- oder Auslieferungsverhalten verwalten.

Wenn die Funktion anbieterspezifisch ist und noch kein gemeinsamer Vertrag existiert, definieren Sie zuerst den Vertrag.

Die Standardabfolge

Definieren Sie den typisierten Kernvertrag.
Fügen Sie die Plugin-Registrierung für diesen Vertrag hinzu.
Fügen Sie eine gemeinsame Laufzeit-Hilfsfunktion hinzu.
Binden Sie als Nachweis ein echtes Anbieter-Plugin ein.
Stellen Sie die Funktions- und Kanalnutzer auf die Laufzeit-Hilfsfunktion um.
Fügen Sie Vertragstests hinzu.
Dokumentieren Sie die betreiberseitige Konfiguration und das Zuständigkeitsmodell.

Was wohin gehört

Ebene	Zuständig für
Kern	Anfrage-/Antworttypen; Provider-Registrierung und -Auflösung; Fallback-Verhalten; Konfigurationsschema mit weitergegebenen `title`-/`description`-Dokumentationsmetadaten für verschachtelte Objekt-, Platzhalter-, Array-Element- und Kompositionsknoten; Oberfläche der Laufzeit-Hilfsfunktionen.
Anbieter-Plugin	Anbieter-API-Aufrufe, Verarbeitung der Anbieter-Authentifizierung, anbieterspezifische Anfragenormalisierung und Registrierung der Fähigkeitsimplementierung.
Funktions-/Kanal-Plugin	Ruft `api.runtime.` oder die entsprechende `plugin-sdk/-runtime`-Hilfsfunktion auf. Ruft niemals direkt eine Anbieterimplementierung auf.

Schnittstellen für Provider und Harness

Verwenden Sie Provider-Hooks, wenn das Verhalten zum Vertrag des Modell-Providers und nicht zur generischen Agentenschleife gehört. Beispiele sind providerspezifische Anfrageparameter nach der Transportauswahl, die Präferenz für Authentifizierungsprofile, Prompt-Overlays und das anschließende Fallback-Routing nach einem Modell- oder Profil-Failover.

Verwenden Sie Agenten-Harness-Hooks, wenn das Verhalten zur Laufzeit gehört, die einen Durchlauf ausführt. Harnesses können explizite Protokollergebnisse wie eine leere Ausgabe, Schlussfolgerungen ohne sichtbare Ausgabe oder einen strukturierten Plan ohne endgültige Antwort klassifizieren, damit die äußere Modell-Fallback-Richtlinie über eine Wiederholung entscheiden kann.

Halten Sie beide Schnittstellen eng begrenzt:

Der Kern verwaltet die Wiederholungs-/Fallback-Richtlinie.
Provider-Plugins verwalten providerspezifische Hinweise zu Anfragen, Authentifizierung und Routing.
Harness-Plugins verwalten die laufzeitspezifische Klassifizierung von Versuchen.
Plugins von Drittanbietern geben Hinweise zurück und verändern den Kernzustand nicht direkt.

Datei-Checkliste

Für eine neue Fähigkeit sind voraussichtlich Änderungen in diesen Bereichen erforderlich:

src/<capability>/types.ts
src/<capability>/...registry/runtime.ts
src/plugins/types.ts
src/plugins/registry.ts
src/plugins/captured-registration.ts
src/plugins/contracts/registry.ts
src/plugins/runtime/types-core.ts
src/plugins/runtime/index.ts
src/plugin-sdk/<capability>.ts
src/plugin-sdk/<capability>-runtime.ts
Ein oder mehrere gebündelte Plugin-Pakete.
Konfiguration, Dokumentation, Tests.

Ausgearbeitetes Beispiel: Bildgenerierung

Die Bildgenerierung folgt der Standardstruktur:

Der Kern definiert ImageGenerationProvider.
Der Kern stellt registerImageGenerationProvider(...) bereit.
Der Kern stellt api.runtime.imageGeneration.generate(...) und .listProviders(...) bereit.
Anbieter-Plugins (comfy, deepinfra, fal, google, litellm, microsoft-foundry, minimax, openai, openrouter, vydra, xai) registrieren anbietergestützte Implementierungen.
Zukünftige Anbieter registrieren denselben Vertrag, ohne Kanäle oder Tools zu ändern.

Der Konfigurationsschlüssel ist bewusst vom Routing für die Bildanalyse getrennt:

agents.defaults.imageModel analysiert Bilder.
agents.defaults.mediaModels.image generiert Bilder.

Halten Sie diese getrennt, damit Fallback und Richtlinie explizit bleiben.

Embedding-Provider

Verwenden Sie registerEmbeddingProvider(...) / Vertrag embeddingProviders für wiederverwendbare Provider für Vektor-Embeddings. Dieser Vertrag ist bewusst umfassender als der Speicher: Tools, Suche, Abruf, Importprogramme oder zukünftige Funktions-Plugins können Embeddings nutzen, ohne von der Speicher-Engine abhängig zu sein. Die Speichersuche nutzt ebenfalls das generische embeddingProviders.

Die ältere speicherspezifische Registrierungs-API und der Vertrag memoryEmbeddingProviders sind veraltet. Verwenden Sie registerEmbeddingProvider und embeddingProviders für alle neuen Embedding-Provider.

Review-Checkliste

Prüfen Sie vor der Auslieferung einer neuen Fähigkeit Folgendes:

Kein Kanal oder Tool importiert Anbietercode direkt.
Die Laufzeit-Hilfsfunktion ist der gemeinsame Pfad.
Mindestens ein Vertragstest bestätigt die gebündelte Zuständigkeit.
Die Konfigurationsdokumentation nennt das neue Modell bzw. den neuen Konfigurationsschlüssel.
Die Plugin-Dokumentation erläutert die Zuständigkeitsgrenze.

Wenn ein PR die Fähigkeitsebene überspringt und Anbieterverhalten fest in einen Kanal oder ein Tool einprogrammiert, weisen Sie ihn zurück und definieren Sie zuerst den Vertrag.