Building plugins

Funktionen hinzufügen (Leitfaden für Mitwirkende)

Verwenden Sie dies, wenn OpenClaw einen neuen gemeinsamen Funktionsbereich benötigt, etwa für Einbettungen, Bildgenerierung, Videogenerierung oder einen zukünftigen, von einem Anbieter bereitgestellten Funktionsbereich.

Die Regel:

Plugin = Zuständigkeitsgrenze
Fähigkeit = gemeinsamer Kernvertrag

Binden Sie einen Anbieter nicht direkt in einen Kanal oder ein Werkzeug 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 realistischerweise implementieren.
Kanäle, Werkzeuge oder Funktions-Plugins sollen sie verwenden können, ohne den Anbieter kennen zu müssen.
Der Kern muss Fallback-, Richtlinien-, Konfigurations- oder Auslieferungsverhalten verantworten.

Wenn die Funktion nur einen Anbieter betrifft und noch kein gemeinsamer Vertrag vorhanden ist, 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 zum Nachweis ein echtes Anbieter-Plugin ein.
Stellen Sie Funktions- und Kanalnutzer auf die Laufzeit-Hilfsfunktion um.
Fügen Sie Vertragstests hinzu.
Dokumentieren Sie die betreiberseitige Konfiguration und das Zuständigkeitsmodell.

Was gehört wohin?

Ebene	Zuständigkeit
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; Laufzeit-Hilfsoberfläche.
Anbieter-Plugin	Anbieter-API-Aufrufe, Handhabung der Anbieter-Authentifizierung, anbieterspezifische Normalisierung von Anfragen 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 Laufzeitumgebungen

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 Bevorzugung von Authentifizierungsprofilen, Prompt-Erweiterungen und die nachgelagerte Fallback-Weiterleitung nach einem Modell- oder Profil-Failover.

Verwenden Sie Hooks der Agenten-Laufzeitumgebung, wenn das Verhalten zu der Laufzeit gehört, die einen Durchlauf ausführt. Laufzeitumgebungen können explizite Protokollergebnisse klassifizieren, etwa eine leere Ausgabe, Schlussfolgerungen ohne sichtbare Ausgabe oder einen strukturierten Plan ohne abschließende Antwort, damit die äußere Modell-Fallback-Richtlinie über einen erneuten Versuch entscheiden kann.

Halten Sie beide Schnittstellen schlank:

Der Kern verantwortet die Richtlinie für erneute Versuche und Fallbacks.
Provider-Plugins verantworten providerspezifische Hinweise zu Anfragen, Authentifizierung und Weiterleitung.
Laufzeitumgebungs-Plugins verantworten 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 müssen Sie voraussichtlich diese Bereiche ändern:

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 und Tests.

Ausgearbeitetes Beispiel: Bildgenerierung

Die Bildgenerierung folgt dem Standardschema:

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 Werkzeuge zu ändern.

Der Konfigurationsschlüssel ist bewusst von der Weiterleitung für die Bildanalyse getrennt:

agents.defaults.imageModel analysiert Bilder.
agents.defaults.imageGenerationModel erzeugt Bilder.

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

Einbettungs-Provider

Verwenden Sie registerEmbeddingProvider(...) beziehungsweise den Vertrag embeddingProviders für wiederverwendbare Provider von Vektoreinbettungen. Dieser Vertrag ist bewusst umfassender als der Speicher: Werkzeuge, Suche, Abruf, Importprogramme oder zukünftige Funktions-Plugins können Einbettungen verwenden, ohne von der Speicher-Engine abhängig zu sein. Auch die Speichersuche verwendet generische embeddingProviders.

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

Checkliste für die Überprüfung

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

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

Wenn ein PR die Fähigkeitsebene überspringt und anbieterspezifisches Verhalten fest in einen Kanal oder ein Werkzeug einbaut, weisen Sie ihn zurück und definieren Sie zuerst den Vertrag.