Plugin-Entwicklung

OpenClaw Plugins sind der Punkt, an dem die Plattform aufhört, ein starres Produkt zu sein, und anfängt, Infrastruktur zu werden. Sie können Tools, Channels, Provider, Hooks, Commands und Hintergrund-Services ergänzen. Wenn Prompts dem Agenten sagen, wie er denken soll, entscheiden Plugins, was er tatsächlich tun kann.

Das nützliche mentale Modell ist dieses: Ein Plugin ist kein zufälliges Script, das man seitlich anschraubt. Es ist eher wie ein neuer Stromkreis im Sicherungskasten. Wenn es sauber gemacht ist, ist alles beschriftet, isoliert und leicht zu debuggen. Wenn nicht, kostet dich ein loses Kabel schnell einen halben Tag.

Starte mit dem passenden Plugin-Typ

OpenClaw unterstützt mehrere Plugin-Formen. Die offizielle Plugin-Dokumentation nennt vier typische Einstiege: Channel-Plugins, Provider-Plugins, CLI-Backend-Plugins und Tool- oder Hook-Plugins.

• Tool- oder Hook-Plugin: Ideal, wenn du ein neues Agent-Tool, Command, einen Service oder Workflow-Hook ergänzen willst.
• Provider-Plugin: Ideal, wenn OpenClaw mit einem neuen Modell-, Speech-, Medien- oder Search-Backend sprechen soll.
• Channel-Plugin: Ideal, wenn du OpenClaw mit einer Messaging-Oberfläche verbindest.
• CLI-Backend-Plugin: Ideal, wenn du eine lokale Coding- oder Inference-CLI in OpenClaw einhängst.

Die meisten ersten Plugins sollten einfache Tool-Plugins sein. Sie sind leichter zu verstehen, leichter zu testen und zwingen dich, das SDK sauber zu lernen, ohne gleichzeitig eine komplette Transport-Schicht zu besitzen.

Das Manifest ist dein Reisepass

Bevor OpenClaw deinem Runtime-Code vertraut, liest es openclaw.plugin.json. Denk an diese Datei wie an einen Reisepass plus Frachtetikett. Sie sagt dem Gateway, wer du bist, welche Config-Form du erwartest, welche Fähigkeiten du beanspruchst und ob du bewusst beim Start geladen werden willst.

Das ist keine Bürokratie um der Bürokratie willen. Die Geschichte von Browser-Erweiterungen hat der Software-Welt dieselbe Lektion beigebracht: Erweiterbarkeit ohne deklarierte Berechtigungen kippt schnell ins Chaos. OpenClaw vermeidet das, indem Plugin-Metadaten geprüft werden, bevor Runtime-Code ausgeführt wird.

Für das genaue Feld-Referenzwerk ist die offizielle Manifest-Referenz die richtige Quelle. In der Praxis zählen zuerst diese Felder:

• id für die kanonische Plugin-Id
• configSchema für Validierung und Setup-UX
• contracts.tools, wenn dein Plugin Runtime-Tools registriert
• activation.onStartup, wenn das Plugin bewusst beim Boot laden soll

Minimale Form eines Tool-Plugins

Ein einfaches Tool-Plugin braucht drei bewegliche Teile: Paket-Metadaten, ein Manifest und eine Entry-Datei, die die SDK-Registrierung nutzt.

// index.ts
import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
import { Type } from "@sinclair/typebox";

export default definePluginEntry({
  id: "my-plugin",
  name: "My Plugin",
  description: "Adds one focused tool",
  register(api) {
    api.registerTool({
      name: "my_tool",
      description: "Do a thing",
      parameters: Type.Object({
        input: Type.String(),
      }),
      async execute(_id, params) {
        return {
          content: [{ type: "text", text: "Got: ${params.input}" }],
        };
      },
    });
  },
});

Auffällig ist, was fehlt: keine riesige Framework-Schicht, kein magisches Ordnerscanning und keine losen Runtime-Side-Effects. Deine Aufgabe ist, eine Fähigkeit sauber zu registrieren und ihre Grenze offensichtlich zu halten.

Ein praktischer Build-Workflow

1. Starte mit genau einer Aufgabe. Wenn deine erste Idee gleichzeitig Tools, Hooks, Background-Services und einen Channel braucht, trenne sie auf.
2. Erstelle Paket-Metadaten. Deklariere den OpenClaw Extension Entry in package.json.
3. Schreibe das Manifest. Halte das Config-Schema strikt. Lockere Schemata werden später Support-Schulden.
4. Registriere genau eine Fähigkeit. Ein einzelnes Tool reicht, um den End-to-End-Weg zu beweisen.
5. Teste lokal. Verifiziere die Runtime-Registrierung, bevor du ans Publishing denkst.
6. Veröffentliche mit Absicht. Externe Plugins gehören in ClawHub oder in einen Installationspfad, den du wirklich supporten kannst.

Erfahrene Plugin-Autoren arbeiten aus gutem Grund so. Es folgt der alten Handwerker-Regel: zweimal messen, einmal schneiden. In der Plugin-Entwicklung heißen diese Messungen Config-Schema, Contracts und Runtime-Grenzen.

Gebündeltes Plugin oder externes Plugin?

Häufige Fehler, die Plugins fragil machen

Statische Contracts vergessen

Wenn du ein Tool zur Laufzeit registrierst, es aber nicht in contracts.tools deklarierst, wird Discovery unklar und Debugging unnötig seltsam. OpenClaw ist hier absichtlich explizit.

Das SDK zu breit importieren

Das SDK-Overview empfiehlt gezielte Subpath-Imports. Das hält den Start leichter und vermeidet versehentliche Dependency-Knoten. Wenn du aus Bequemlichkeit riesige Barrel-Imports nimmst, leihst du dir zukünftige Schmerzen.

TypeScript ohne Runtime-Output veröffentlichen

Lokale Source Checkouts sind oft gnädig. Veröffentlichte Pakete nicht. Wenn dein npm-Paket nur Source-Dateien, aber kein kompiliertes Runtime-Output enthält, kann die Installation gelingen, während das Runtime-Laden später trotzdem scheitert.

Policy nur mit Code lösen wollen

Plugins können stark genug sein, um externe Systeme, Freigaben und sensible Daten zu berühren. Wenn sich etwas riskant anfühlt, lautet die bessere Antwort meist: engerer Contract, klarere Config oder kleinere Tool-Oberfläche, nicht nur clevererer Code.

Wann du kein Plugin bauen solltest

Nicht jede Erweiterungsidee braucht eins. Wenn du nur einen einmaligen Workflow in einer einzelnen Umgebung brauchst, sind ein Skill, eine stehende Anweisung oder ein MCP-Server oft günstiger in der Wartung. Ein Plugin lohnt sich, wenn du eine wiederverwendbare Fähigkeit mit sauberem Installationsweg und stabiler Grenze brauchst.

Sicherheitsdenken für Plugin-Autoren

• Halte die Oberfläche klein. Schmale Tools sind leichter zu vertrauen als Schweizer-Taschenmesser-Tools.
• Validiere Eingaben hart. Config-Schema und Tool-Parameter sind Teil des Produkts, keine Büroarbeit.
• Deklariere Ownership klar. Channels, Provider, Tools und Commands sollten aus den Metadaten eindeutig hervorgehen.
• Fail closed. Wenn Config fehlt oder ungültig ist, tu nicht so, als würde das Plugin halb funktionieren.
• Behandle Packaging als Teil der Zuverlässigkeit. Installation, Updates und Inspection sind genauso wichtig wie die Happy-Path-Demo.

Gute Plugin-Entwicklung in OpenClaw ist im besten Sinn langweilig. Das Paket installiert sauber, das Manifest erklärt sich selbst, die Runtime registriert genau das, was sie besitzt, und der Betreiber braucht keine Detektivarbeit, um dem Ganzen zu vertrauen.