Plugins erstellen

Plugins erweitern OpenClaw um neue Fähigkeiten: Kanäle, Modell-Provider, Speech, Realtime-Transkription, Realtime-Voice, Media Understanding, Image Generation, Video Generation, Web Fetch, Web Search, Agent-Tools oder eine beliebige Kombination davon. Sie müssen Ihr Plugin nicht zum OpenClaw-Repository hinzufügen. Veröffentlichen Sie es auf ClawHub oder npm, und Benutzer installieren es mit openclaw plugins install <package-name>. OpenClaw versucht zuerst ClawHub und fällt dann automatisch auf npm zurück.

Voraussetzungen

Node >= 22 und ein Paketmanager (npm oder pnpm)
Vertrautheit mit TypeScript (ESM)
Für In-Repo-Plugins: Repository geklont und pnpm install ausgeführt

Welche Art von Plugin?

Kanal-Plugin

Verbinden Sie OpenClaw mit einer Messaging-Plattform (Discord, IRC usw.)

Provider-Plugin

Fügen Sie einen Modell-Provider hinzu (LLM, Proxy oder benutzerdefinierter Endpunkt)

Tool-/Hook-Plugin

Registrieren Sie Agent-Tools, Event-Hooks oder Services — unten weiterlesen

Wenn ein Kanal-Plugin optional ist und beim Ausführen von Onboarding/Setup möglicherweise nicht installiert ist, verwenden Sie createOptionalChannelSetupSurface(...) aus openclaw/plugin-sdk/channel-setup. Es erzeugt ein Setup-Adapter-/Wizard-Paar, das die Installationsanforderung bekannt gibt und bei echten Konfigurationsschreibvorgängen fehlschlägt, bis das Plugin installiert ist.

Schnellstart: Tool-Plugin

Diese Anleitung erstellt ein minimales Plugin, das ein Agent-Tool registriert. Kanal- und Provider-Plugins haben eigene Leitfäden, die oben verlinkt sind.

Paket und Manifest erstellen

{
  "name": "@myorg/openclaw-my-plugin",
  "version": "1.0.0",
  "type": "module",
  "openclaw": {
    "extensions": ["./index.ts"],
    "compat": {
      "pluginApi": ">=2026.3.24-beta.2",
      "minGatewayVersion": "2026.3.24-beta.2"
    },
    "build": {
      "openclawVersion": "2026.3.24-beta.2",
      "pluginSdkVersion": "2026.3.24-beta.2"
    }
  }
}

Jedes Plugin benötigt ein Manifest, auch ohne Konfiguration. Siehe Manifest für das vollständige Schema. Die kanonischen ClawHub- Publish-Snippets befinden sich unter docs/snippets/plugin-publish/.

Einstiegspunkt schreiben

// 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 a custom tool to OpenClaw",
  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}` }] };
      },
    });
  },
});

definePluginEntry ist für Nicht-Kanal-Plugins gedacht. Für Kanäle verwenden Sie defineChannelPluginEntry — siehe Kanal-Plugins. Vollständige Optionen für Einstiegspunkte finden Sie unter Einstiegspunkte.

Testen und veröffentlichen

Externe Plugins: mit ClawHub validieren und veröffentlichen, dann installieren:

clawhub package publish your-org/your-plugin --dry-run
clawhub package publish your-org/your-plugin
openclaw plugins install clawhub:@myorg/openclaw-my-plugin

OpenClaw prüft auch ClawHub vor npm bei reinen Paketspezifikationen wie @myorg/openclaw-my-plugin.In-Repo-Plugins: unter dem gebündelten Plugin-Workspace-Baum ablegen — werden automatisch erkannt.

pnpm test -- <bundled-plugin-root>/my-plugin/

Plugin-Fähigkeiten

Ein einzelnes Plugin kann über das api-Objekt beliebig viele Fähigkeiten registrieren:

Fähigkeit	Registrierungsmethode	Detaillierter Leitfaden
Text-Inferenz (LLM)	`api.registerProvider(...)`	Provider-Plugins
CLI-Inferenz-Backend	`api.registerCliBackend(...)`	CLI-Backends
Kanal / Messaging	`api.registerChannel(...)`	Kanal-Plugins
Speech (TTS/STT)	`api.registerSpeechProvider(...)`	Provider-Plugins
Realtime-Transkription	`api.registerRealtimeTranscriptionProvider(...)`	Provider-Plugins
Realtime-Voice	`api.registerRealtimeVoiceProvider(...)`	Provider-Plugins
Media Understanding	`api.registerMediaUnderstandingProvider(...)`	Provider-Plugins
Image Generation	`api.registerImageGenerationProvider(...)`	Provider-Plugins
Music Generation	`api.registerMusicGenerationProvider(...)`	Provider-Plugins
Video Generation	`api.registerVideoGenerationProvider(...)`	Provider-Plugins
Web Fetch	`api.registerWebFetchProvider(...)`	Provider-Plugins
Web Search	`api.registerWebSearchProvider(...)`	Provider-Plugins
Agent-Tools	`api.registerTool(...)`	Unten
Benutzerdefinierte Befehle	`api.registerCommand(...)`	Einstiegspunkte
Event-Hooks	`api.registerHook(...)`	Einstiegspunkte
HTTP-Routen	`api.registerHttpRoute(...)`	Internals
CLI-Unterbefehle	`api.registerCli(...)`	Einstiegspunkte

Die vollständige Registrierungs-API finden Sie unter SDK Overview. Wenn Ihr Plugin benutzerdefinierte Gateway-RPC-Methoden registriert, behalten Sie sie unter einem pluginspezifischen Präfix. Core-Admin-Namespaces (config.*, exec.approvals.*, wizard.*, update.*) bleiben reserviert und werden immer zu operator.admin aufgelöst, selbst wenn ein Plugin einen engeren Scope anfordert. Hook-Guard-Semantik, die Sie beachten sollten:

before_tool_call: { block: true } ist terminal und stoppt Handler mit niedrigerer Priorität.
before_tool_call: { block: false } wird als keine Entscheidung behandelt.
before_tool_call: { requireApproval: true } pausiert die Agent-Ausführung und fordert den Benutzer zur Genehmigung über das Exec-Genehmigungs-Overlay, Telegram-Schaltflächen, Discord-Interaktionen oder den Befehl /approve auf jedem Kanal auf.
before_install: { block: true } ist terminal und stoppt Handler mit niedrigerer Priorität.
before_install: { block: false } wird als keine Entscheidung behandelt.
message_sending: { cancel: true } ist terminal und stoppt Handler mit niedrigerer Priorität.
message_sending: { cancel: false } wird als keine Entscheidung behandelt.

Der Befehl /approve verarbeitet sowohl Exec- als auch Plugin-Genehmigungen mit begrenztem Fallback: Wenn eine Exec-Genehmigungs-ID nicht gefunden wird, versucht OpenClaw dieselbe ID erneut über Plugin-Genehmigungen. Die Weiterleitung von Plugin-Genehmigungen kann unabhängig über approvals.plugin in der Konfiguration konfiguriert werden. Wenn eine benutzerdefinierte Genehmigungsverkabelung denselben begrenzten Fallback-Fall erkennen muss, verwenden Sie bevorzugt isApprovalNotFoundError aus openclaw/plugin-sdk/error-runtime, anstatt Ablaufstrings für Genehmigungen manuell abzugleichen. Details finden Sie unter SDK Overview hook decision semantics.

Agent-Tools registrieren

Tools sind typisierte Funktionen, die das LLM aufrufen kann. Sie können erforderlich (immer verfügbar) oder optional (Opt-in durch den Benutzer) sein:

register(api) {
  // Erforderliches Tool — immer verfügbar
  api.registerTool({
    name: "my_tool",
    description: "Do a thing",
    parameters: Type.Object({ input: Type.String() }),
    async execute(_id, params) {
      return { content: [{ type: "text", text: params.input }] };
    },
  });

  // Optionales Tool — Benutzer muss es zur Allowlist hinzufügen
  api.registerTool(
    {
      name: "workflow_tool",
      description: "Run a workflow",
      parameters: Type.Object({ pipeline: Type.String() }),
      async execute(_id, params) {
        return { content: [{ type: "text", text: params.pipeline }] };
      },
    },
    { optional: true },
  );
}

Benutzer aktivieren optionale Tools in der Konfiguration:

{
  tools: { allow: ["workflow_tool"] },
}

Tool-Namen dürfen nicht mit Core-Tools kollidieren (Konflikte werden übersprungen)
Verwenden Sie optional: true für Tools mit Nebeneffekten oder zusätzlichen Binäranforderungen
Benutzer können alle Tools eines Plugins aktivieren, indem sie die Plugin-ID zu tools.allow hinzufügen

Import-Konventionen

Importieren Sie immer aus gezielten openclaw/plugin-sdk/<subpath>-Pfaden:

import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store";

// Falsch: monolithische Root-Ebene (veraltet, wird entfernt)
import { ... } from "openclaw/plugin-sdk";

Die vollständige Referenz der Unterpfade finden Sie unter SDK Overview. Verwenden Sie innerhalb Ihres Plugins lokale Barrel-Dateien (api.ts, runtime-api.ts) für interne Importe — importieren Sie niemals Ihr eigenes Plugin über seinen SDK-Pfad. Für Provider-Plugins sollten providerspezifische Hilfsfunktionen in diesen package-root- Barrels bleiben, sofern die Schnittstelle nicht wirklich generisch ist. Aktuelle gebündelte Beispiele:

Anthropic: Claude-Stream-Wrapper und service_tier- / Beta-Hilfsfunktionen
OpenAI: Provider-Builder, Hilfsfunktionen für Standardmodelle, Realtime-Provider
OpenRouter: Provider-Builder sowie Onboarding-/Konfigurationshilfen

Wenn eine Hilfsfunktion nur innerhalb eines gebündelten Provider-Pakets nützlich ist, belassen Sie sie an dieser package-root-Schnittstelle, anstatt sie in openclaw/plugin-sdk/* hochzustufen. Einige generierte Hilfsschnittstellen unter openclaw/plugin-sdk/<bundled-id> existieren weiterhin für die Wartung gebündelter Plugins und zur Kompatibilität, zum Beispiel plugin-sdk/feishu-setup oder plugin-sdk/zalo-setup. Behandeln Sie diese als reservierte Oberflächen, nicht als Standardmuster für neue Drittanbieter-Plugins.

Checkliste vor der Einreichung

package.json hat korrekte openclaw-Metadaten

openclaw.plugin.json-Manifest ist vorhanden und gültig

Der Einstiegspunkt verwendet defineChannelPluginEntry oder definePluginEntry

Alle Importe verwenden gezielte plugin-sdk/<subpath>-Pfade

Interne Importe verwenden lokale Module, keine SDK-Selbstimporte

Tests bestehen (pnpm test -- <bundled-plugin-root>/my-plugin/)

pnpm check besteht (In-Repo-Plugins)

Beta-Release-Tests

Achten Sie auf GitHub-Release-Tags auf openclaw/openclaw und abonnieren Sie sie über Watch > Releases. Beta-Tags sehen aus wie v2026.3.N-beta.1. Sie können auch Benachrichtigungen für das offizielle OpenClaw-X-Konto @openclaw für Release-Ankündigungen aktivieren.
Testen Sie Ihr Plugin gegen das Beta-Tag, sobald es erscheint. Das Zeitfenster vor dem stabilen Release beträgt typischerweise nur wenige Stunden.
Schreiben Sie nach dem Testen im plugin-forum-Discord-Kanal im Thread Ihres Plugins entweder all good oder was nicht funktioniert hat. Falls Sie noch keinen Thread haben, erstellen Sie einen.
Wenn etwas kaputtgeht, eröffnen oder aktualisieren Sie ein Issue mit dem Titel Beta blocker: <plugin-name> - <summary> und versehen Sie es mit dem Label beta-blocker. Fügen Sie den Issue-Link in Ihren Thread ein.
Eröffnen Sie einen PR gegen main mit dem Titel fix(<plugin-id>): beta blocker - <summary> und verlinken Sie das Issue sowohl im PR als auch in Ihrem Discord-Thread. Mitwirkende können PRs nicht labeln, daher ist der Titel das PR-seitige Signal für Maintainer und Automatisierung. Blocker mit PR werden zusammengeführt; Blocker ohne PR werden möglicherweise trotzdem ausgeliefert. Maintainer beobachten diese Threads während der Beta-Tests.
Schweigen bedeutet grün. Wenn Sie das Zeitfenster verpassen, landet Ihr Fix wahrscheinlich im nächsten Zyklus.

Nächste Schritte

Kanal-Plugins

Erstellen Sie ein Messaging-Kanal-Plugin

Provider-Plugins

Erstellen Sie ein Modell-Provider-Plugin

SDK Overview

Referenz für Importzuordnung und Registrierungs-API

Runtime Helpers

TTS, Suche, Subagent über api.runtime

Testing

Testhilfen und Muster

Plugin Manifest

Vollständige Referenz des Manifest-Schemas

Verwandt

Plugin-Architektur — tiefgehender Einblick in die interne Architektur
SDK Overview — Referenz zum Plugin SDK
Manifest — Plugin-Manifestformat
Kanal-Plugins — Kanal-Plugins erstellen
Provider-Plugins — Provider-Plugins erstellen

Overview

Plugins

Skills

Automation & Tasks

Tools

Agent coordination

Plugins erstellen

Plugins erstellen

Voraussetzungen

Welche Art von Plugin?

Kanal-Plugin

Provider-Plugin

Tool-/Hook-Plugin

Schnellstart: Tool-Plugin

Plugin-Fähigkeiten

Agent-Tools registrieren

Import-Konventionen

Checkliste vor der Einreichung

Beta-Release-Tests

Nächste Schritte

Kanal-Plugins

Provider-Plugins

SDK Overview

Runtime Helpers

Testing

Plugin Manifest

Verwandt

Overview

Plugins

Skills

Automation & Tasks

Tools

Agent coordination

​Plugins erstellen

​Voraussetzungen

​Welche Art von Plugin?

Kanal-Plugin

Provider-Plugin

Tool-/Hook-Plugin

​Schnellstart: Tool-Plugin

​Plugin-Fähigkeiten

​Agent-Tools registrieren

​Import-Konventionen

​Checkliste vor der Einreichung

​Beta-Release-Tests

​Nächste Schritte

Kanal-Plugins

Provider-Plugins

SDK Overview

Runtime Helpers

Testing

Plugin Manifest

​Verwandt

Plugins erstellen

Voraussetzungen

Welche Art von Plugin?

Schnellstart: Tool-Plugin

Plugin-Fähigkeiten

Agent-Tools registrieren

Import-Konventionen

Checkliste vor der Einreichung

Beta-Release-Tests

Nächste Schritte

Verwandt