Plugin-Typen erklärt

Die meisten Plugin-Fehler passieren vor der ersten Zeile Code. Nicht weil das SDK schwer wäre, sondern weil die Erweiterungsform falsch gewählt wurde.

OpenClaw hat mehrere Plugin-Typen aus gutem Grund. Ein Tool-Plugin, ein Provider-Plugin, ein Channel-Plugin und ein CLI-Backend-Plugin lösen verschiedene Aufgaben. Wenn du sie als austauschbar behandelst, kaufst du dir meist nur zusätzliche Komplexität ohne Gewinn ein.

Die einfache Sicht darauf ist: Du wählst kein Feature-Label. Du wählst die Grenze, die dein Paket besitzen wird. Diese Grenze bestimmt deine Wartungslast, deine Tests und die Probleme, die du später erbst.

Starte mit der Frage, die wirklich zählt

Frag zuerst: Was soll OpenClaw gewinnen, wenn dein Plugin installiert ist?

• Wenn es eine neue Agent-Aktion bekommt, willst du wahrscheinlich ein Tool-Plugin.
• Wenn es einen neuen Modell- oder Medien-Backend bekommt, willst du wahrscheinlich ein Provider-Plugin.
• Wenn es eine neue Messaging-Oberfläche bekommt, willst du ein Channel-Plugin.
• Wenn es eine lokale AI-Command-Brücke bekommt, willst du ein CLI-Backend-Plugin.

Das klingt offensichtlich. Ist es auch, bis Leute Kategorien vermischen, weil der Upstream gleichzeitig eine API, eine Desktop-App und eine Chat-Integration anbietet. Dann wird es schnell unnötig chaotisch.

Die vier zentralen Plugin-Typen

Tool-Plugins: der beste Standard-Startpunkt

Tool-Plugins sind für die meisten Leute der sauberste erste Bau. Sie ergänzen ein oder mehrere vom Agenten aufrufbare Tools, ohne dass du zusätzlich einen Chat-Transport, einen Modellkatalog oder einen lokalen CLI-Runner besitzen musst.

Denk daran wie an einen neuen Aufsatz für eine Werkbank, nicht wie an den Umbau der ganzen Werkstatt. Du registrierst eine Fähigkeit, definierst ihre Parameter und hältst die Grenze eng.

Die offiziellen Plugin-Dokumente behandeln das minimale Tool-Plugin als kürzeste nützliche Plugin-Form. Das ist genau richtig. Wenn dein Ziel nur ist: „Der Agent soll noch eine Sache können“, ist alles andere oft nur Architektur-Eitelkeit.

Innerhalb dieser Kategorie gibt es noch eine sinnvolle Trennung. Wenn dein Paket nur Tools mit einer festen Tool-Liste enthält, bietet OpenClaw inzwischen einen eigenen Tool-Plugin-Workflow rund um defineToolPlugin. Mischt dein Paket Tools mit Hooks, Services oder anderen Runtime-Flächen, nimm den allgemeineren Plugin-Entry-Weg.

Provider-Plugins: wenn du die Inferenzschicht erweiterst

Provider-Plugins sind keine „schickeren Tool-Plugins“. Sie sitzen näher an der Modell-Pipeline. Du nutzt sie, wenn OpenClaw einen neuen Provider, eine neue Auth-Methode, einen Katalog oder eine neue Familie von Modell-Refs verstehen soll.

Hier steigt die Wartungslast. Ein Provider-Plugin besitzt oft API-Key-Semantik, Setup-Metadaten, Live-Modellkataloge und Provider-spezifische Eigenheiten. Das ist mächtig, aber eher so, als würdest du eine neue Stromquelle ins Gebäude legen, statt ein Handwerkzeug hinzuzufügen.

Nutze diese Form, wenn der Upstream-Dienst bereits wie ein echter Provider funktioniert und normal am Model Routing teilnehmen soll. Nutze sie nicht bloß, weil „AI im Spiel ist“. Wenn der Agent nur eine externe Aktion braucht, bist du weiter im Tool-Plugin-Land.

Channel-Plugins: Transport plus Policy, nicht nur Messaging

Ein Channel-Plugin wirkt glamourös, weil es OpenClaw in Telegram, Discord, Slack oder eine andere Messaging-Oberfläche bringt. Unter der Haube geht es aber weniger ums Senden von Nachrichten als um den ganzen unordentlichen Rest darum herum.

Die offiziellen Channel-Plugin-Dokumente sind da klar: Der Core behält das gemeinsame message-Tool. Dein Channel-Plugin besitzt vor allem Konfiguration, Account-Auflösung, Pairing, DM-Policy, Versand, Threading und Session-Grammatik.

Das ist wichtig, weil Anfänger ein Channel-Plugin oft als „Webhook plus Send-API“ vorstellen. Ist es nicht. Es ist eher Empfang, Ausweiskontrolle und Poststelle in einem. Wer diese Form wählt, wählt operative Verantwortung mit.

CLI-Backend-Plugins: eine lokale CLI anbinden, keine normale API ersetzen

CLI-Backend-Plugins gibt es aus einem sehr bestimmten Grund. Manchmal lebt die gewünschte Integration bereits hinter einem lokalen Command, bringt ihren eigenen Login-Zustand mit oder ergibt als lokaler Prozess-Fallback mehr Sinn als als Standard-Provider-API.

In diesem Fall kann OpenClaw die CLI als Text-Inferenz-Backend behandeln, mit Konfiguration für Command-Start, Session-Ids, Input-Modus, Output-Parsing, Watchdog-Verhalten und Serialisierung.

Die Falle liegt darin, diesen Typ zu nutzen, obwohl ein Provider-Plugin richtig gewesen wäre. Wenn der Dienst bereits eine saubere HTTP-Modell-API hat, wird eine CLI-Hülle schnell zu einem unnötigen Zwischenstück. Es funktioniert dann zwar, aber du debugst plötzlich sowohl die lokale Prozessebene als auch den Upstream-Dienst.

So wählst du die richtige Form

1. Benenne, was OpenClaw gewinnt. Tool, Provider, Channel oder CLI-Backend.
2. Suche die engste wahrheitsgemäße Grenze. Schmalere Plugins sind leichter zu verstehen und zu testen.
3. Prüfe, welche Infrastruktur OpenClaw schon mitbringt. Channels nutzen etwa das gemeinsame Message-Tool, das du nicht neu erfinden solltest.
4. Wähle die Form passend zur Runtime-Ownership. Besitzt dein Plugin Transport, denke Channel. Besitzt es Modellkataloge, denke Provider.
5. Mische Fähigkeiten nur absichtlich. Gemischte Plugins sind okay, wenn die Integration sie wirklich braucht, nicht weil alles in einem Ordner landen soll.

Was sich bei der Wartung ändert

Diesen Teil lassen viele Tutorials weg. Der Plugin-Typ ist auch eine Wartungsvorhersage.

• Tool-Plugin: Niedrigste laufende Komplexität, solange der Scope eng bleibt.
• Provider-Plugin: Mittlere bis hohe Komplexität, weil Upstream-Modellkataloge, Auth und Kompatibilität sich ändern.
• Channel-Plugin: Hohe operative Komplexität, weil Messaging-Plattformen voll von Randfällen sind.
• CLI-Backend-Plugin: Mittlere Komplexität, die hoch wird, wenn die eingehängte CLI instabil oder schlecht spezifiziert ist.

Eine brauchbare Faustregel lautet: Je näher dein Plugin an Netzwerktransport, Auth oder langlebigem Prozessmanagement sitzt, desto mehr Wartung solltest du erwarten.

Das Manifest bleibt in jedem Fall wichtig

Egal welchen Typ du wählst, openclaw.plugin.json bleibt der Cold-Start-Contract. OpenClaw liest dieses Manifest, bevor Plugin-Runtime geladen wird. Deshalb müssen Ownership, Config-Validierung und Discovery-Metadaten dort explizit stehen.

Wenn du die offiziellen Referenzen willst, ist der Building-Plugins-Guide der beste Startpunkt, und die Plugin-Manifest-Referenz erklärt, welche Metadaten vor jeder Runtime-Ausführung ins Manifest gehören.

Eine praktische Entscheidungsmatrix

Wo Anfänger falsch abbiegen

Sie optimieren auf Prestige statt Passung

Ein Provider- oder Channel-Plugin kann sich „echter“ anfühlen als ein schlichtes Tool-Plugin. Dieses Gefühl ist teuer. Wenn die kleinere Form das Problem löst, nimm die kleinere Form.

Sie verwechseln das Upstream-Produkt mit der OpenClaw-Grenze

Ein Upstream-Unternehmen kann API, Desktop-App und Chat-Bot gleichzeitig anbieten. Trotzdem musst du entscheiden, was dein OpenClaw-Paket wirklich besitzen soll. Ein einziges Upstream-Produkt kann je nach Ziel verschiedene Plugin-Typen rechtfertigen.

Sie bündeln zu viel zu früh

Plugins mit gemischten Fähigkeiten sind möglich, aber erste Versionen sollten scharf bleiben. Ein Plugin, das gleichzeitig Tools registriert, eine CLI einhängt und einen Provider exponiert, gibt dir mehr Orte, an denen sich Fehler verstecken können.

Wann du gar kein Plugin bauen solltest

Noch eine unbequeme Wahrheit: Manchmal ist der richtige Plugin-Typ keiner. Wenn du nur eine wiederverwendbare externe Fähigkeit für eine einzelne Umgebung brauchst, kann ein MCP-Server oder ein einfacherer lokaler Workflow günstiger zu warten sein als ein eigenes Plugin-Paket.

Plugins lohnen sich, wenn du einen stabilen Installationsweg, klare Ownership und eine wiederverwendbare Fähigkeitsgrenze willst. Wenn du das noch nicht brauchst, erzwing die ganze Zeremonie nicht.

Wähle zuerst die kleinste wahrheitsgemäße Plugin-Form. Dein zukünftiges Ich wird weniger debuggen und mehr ausliefern.

Schnelle Entscheidungsregel

Neue Agent-Aktion nötig? -> Tool-Plugin
Neues Modell- oder Medien-Backend nötig? -> Provider-Plugin
Neue Messaging-Oberfläche nötig? -> Channel-Plugin
Lokalen AI-Command ansteuern? -> CLI-Backend-Plugin