Plugins erstellen

Plugins erweitern OpenClaw, ohne den Kern zu verändern. Ein Plugin kann einen Messaging-Kanal, Modell-Provider, ein lokales CLI-Backend, Agenten-Tool, einen Hook, Medien-Provider oder eine andere Plugin-eigene Funktion hinzufügen.

Sie müssen dem OpenClaw-Repository kein externes Plugin hinzufügen. Veröffentlichen Sie das Paket auf ClawHub; Benutzer installieren es mit:

openclaw plugins install clawhub:<package-name>

Reine Paketspezifikationen werden während der Einführungsumstellung weiterhin von npm installiert. Verwenden Sie das Präfix clawhub:, wenn Sie die Auflösung über ClawHub wünschen.

Anforderungen

• Node 22.22.3+, Node 24.15+ oder Node 25.9+ sowie npm oder pnpm.
• TypeScript-ESM-Module.
• Klonen Sie für die Arbeit an gebündelten Plugins im Repository das Repository und führen Sie pnpm install aus. Die Plugin-Entwicklung im Quellcode-Checkout erfolgt ausschließlich mit pnpm, da OpenClaw gebündelte Plugins aus extensions/*-Workspace-Paketen erkennt.

Plugin-Struktur auswählen

Schnellstart

Erstellen Sie ein minimales Tool-Plugin, indem Sie ein erforderliches Agenten-Tool registrieren. Dies ist die kürzeste nützliche Plugin-Struktur und deckt Paket, Manifest, Einstiegspunkt und lokalen Nachweis ab.

{"name": "@myorg/openclaw-my-plugin","version": "1.0.0","type": "module","dependencies": {"typebox": "1.1.39"},"peerDependencies": {"openclaw": ">=2026.3.24-beta.2"},"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"}}}

{"id": "my-plugin","name": "My Plugin","description": "Adds a custom tool to OpenClaw","contracts": {"tools": ["my_tool"]},"activation": {"onStartup": true},"configSchema": {"type": "object","additionalProperties": false}}

import { Type } from "typebox";import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry"; export default definePluginEntry({  id: "my-plugin",  name: "My Plugin",  description: "Adds a custom tool to OpenClaw",  register(api) {    api.registerTool({      name: "my_tool",      description: "Echo one input value",      parameters: Type.Object({ input: Type.String() }),      outputSchema: Type.Object(        { input: Type.String() },        { additionalProperties: false },      ),      async execute(_id, params) {        const details = { input: params.input };        return {          content: [{ type: "text", text: `Got: ${params.input}` }],          details,        };      },    });  },});

openclaw plugins inspect my-plugin --runtime --json

pnpm test extensions/my-plugin/pnpm check

npm pack --pack-destination /tmpopenclaw plugins install npm-pack:/tmp/<plugin-package>.tgz --forceopenclaw plugins inspect my-plugin --runtime --json

clawhub package publish your-org/your-plugin --dry-runclawhub package publish your-org/your-plugin

openclaw plugins install clawhub:your-org/your-plugin

Tools registrieren

Tools können erforderlich oder optional sein. Erforderliche Tools sind immer verfügbar, wenn das Plugin aktiviert ist. Optionale Tools erfordern die ausdrückliche Zustimmung des Benutzers, bevor OpenClaw die zugehörige Plugin-Laufzeit lädt.

Tool-Factories erhalten einen vertrauenswürdigen Laufzeitkontext, einschließlich deliveryContext, nativeChannelId für die aktive Plattformkonversation, sofern verfügbar, und requesterSenderId.

register(api) {  api.registerTool(    {      name: "workflow_tool",      description: "Run a workflow",      parameters: Type.Object({ pipeline: Type.String() }),      outputSchema: Type.Object(        { pipeline: Type.String() },        { additionalProperties: false },      ),      async execute(_id, params) {        return {          content: [{ type: "text", text: params.pipeline }],          details: { pipeline: params.pipeline },        };      },    },    { optional: true },  );}

outputSchema ist optional. Es beschreibt den strukturierten details-Wert, der von Code Mode und Tool-Suche verwendet wird. Katalog- Aufrufe lehnen ungültige Schemas vor der Ausführung ab und validieren den endgültigen Wert nach Tool-Hooks. Lassen Sie es bei Tools ohne stabiles JSON-Ergebnis weg. Den vollständigen Vertrag finden Sie unter Tool-Plugins.

Jedes mit api.registerTool(...) registrierte Tool muss außerdem im Plugin-Manifest deklariert werden:

{  "contracts": {    "tools": ["workflow_tool"]  },  "toolMetadata": {    "workflow_tool": {      "optional": true    }  }}

Benutzer stimmen mit tools.allow zu:

{  tools: { allow: ["workflow_tool"] }, // or ["my-plugin"] for every tool from one plugin}

Optionale Tools steuern, ob ein Tool dem Modell bereitgestellt wird. Verwenden Sie Plugin-Berechtigungsanfragen, wenn ein Tool oder Hook nach der Auswahl durch das Modell und vor der Ausführung der Aktion eine Genehmigung anfordern soll.

Verwenden Sie optionale Tools für Nebeneffekte, ungewöhnliche Binärdateien oder Funktionen, die standardmäßig nicht bereitgestellt werden sollten. Tool-Namen dürfen nicht mit Namen von Kern-Tools kollidieren; Konflikte werden übersprungen und in der Plugin-Diagnose gemeldet. Fehlerhafte Registrierungen werden übersprungen und auf dieselbe Weise gemeldet: ein fehlendes, nicht leeres name, ein execute, das keine Funktion ist, oder ein Tool-Deskriptor ohne ein parameters- Objekt.

Tool-Factories erhalten ein von der Laufzeit bereitgestelltes Kontextobjekt. Verwenden Sie ctx.activeModel, wenn ein Tool das aktive Modell für den aktuellen Durchlauf protokollieren, anzeigen oder sich daran anpassen muss; es kann provider, modelId und modelRef enthalten. Behandeln Sie es als informative Laufzeitmetadaten und nicht als Sicherheitsgrenze gegenüber dem lokalen Betreiber, installiertem Plugin-Code oder einer modifizierten OpenClaw-Laufzeit. Sensible lokale Tools sollten weiterhin eine ausdrückliche Zustimmung für das Plugin oder durch den Betreiber erfordern und geschlossen fehlschlagen, wenn Metadaten zum aktiven Modell fehlen oder ungeeignet sind.

Das Manifest deklariert Zuständigkeit und Erkennung; die Ausführung ruft weiterhin die aktive registrierte Tool-Implementierung auf. Halten Sie toolMetadata.<tool>.optional: true mit api.registerTool(..., { optional: true }) konsistent, damit OpenClaw das Laden dieser Plugin-Laufzeit vermeiden kann, bis das Tool ausdrücklich in die Zulassungsliste aufgenommen wird.

Importkonventionen

Importieren Sie aus spezifischen SDK-Unterpfaden:

Verwenden Sie innerhalb Ihres Plugin-Pakets lokale Barrel-Dateien wie api.ts und runtime-api.ts für interne Importe. Importieren Sie Ihr eigenes Plugin nicht über einen SDK-Pfad. Provider-spezifische Hilfsfunktionen sollten im Provider-Paket verbleiben, sofern die Schnittstelle nicht wirklich generisch ist.

Benutzerdefinierte Gateway-RPC-Methoden sind ein erweiterter Einstiegspunkt. Verwenden Sie dafür ein Plugin-spezifisches Präfix; zentrale Admin-Namespaces wie config.*, exec.approvals.*, operator.admin.*, wizard.* und update.* bleiben reserviert und werden zu operator.admin aufgelöst. Die openclaw/plugin-sdk/gateway-method-runtime-Bridge ist für Plugin-HTTP- Routen reserviert, die contracts.gatewayMethodDispatch: ["authenticated-request"] deklarieren.

Die vollständige Importübersicht finden Sie unter Plugin-SDK-Übersicht.

Die OpenClaw-SDK-Kompatibilitätsfelder enthalten TypeScript-@deprecated-Annotationen, die Editoren als Migrationswarnungen anzeigen. Um sie während des Builds durchzusetzen, aktivieren Sie eine typbewusste Regel wie @typescript-eslint/no-deprecated. Oxlint ist nicht typbewusst und kann diese Annotationen daher nicht durchsetzen.

Checkliste vor der Einreichung

OPENCLAW_DOCS_MARKER:calloutOpen:Q2hlY2s package.json enthält korrekte openclaw-Metadaten OPENCLAW_DOCS_MARKER:calloutClose:

OPENCLAW_DOCS_MARKER:calloutOpen:Q2hlY2s Das openclaw.plugin.json-Manifest ist vorhanden und gültig OPENCLAW_DOCS_MARKER:calloutClose:

OPENCLAW_DOCS_MARKER:calloutOpen:Q2hlY2s Der Einstiegspunkt verwendet defineChannelPluginEntry oder definePluginEntry OPENCLAW_DOCS_MARKER:calloutClose:

OPENCLAW_DOCS_MARKER:calloutOpen:Q2hlY2s Alle Importe verwenden spezifische plugin-sdk/<subpath>-Pfade OPENCLAW_DOCS_MARKER:calloutClose: