Plugins erstellen

Plugins erweitern OpenClaw, ohne den Kern zu ändern. Ein Plugin kann einen Messaging- Kanal, Modell-Provider, lokalen CLI-Backend, Agent-Tool, Hook, Medien-Provider oder eine andere Plugin-eigene Fähigkeit hinzufügen.

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

openclaw plugins install clawhub:<package-name>

Nackte Paketspezifikationen werden während der Launch-Umstellung weiterhin von npm installiert. Verwenden Sie das Präfix clawhub:, wenn Sie die ClawHub-Auflösung wünschen.

Anforderungen

• Verwenden Sie Node 22.19+, Node 23.11+ oder Node 24+ und einen Paketmanager wie npm oder pnpm.
• Machen Sie sich mit TypeScript-ESM-Modulen vertraut.
• Klonen Sie für im Repository gebündelte Plugin-Arbeit das Repository und führen Sie pnpm install aus. Die Plugin-Entwicklung aus einem Source-Checkout ist nur mit pnpm möglich, weil OpenClaw gebündelte Plugins aus Workspace-Paketen unter extensions/* lädt.

Plugin-Form auswählen

Schnellstart

Erstellen Sie ein minimales Tool-Plugin, indem Sie ein erforderliches Agent-Tool registrieren. Dies ist die kürzeste nützliche Plugin-Form und zeigt Paket, Manifest, Einstiegspunkt und lokalen Nachweis.

{"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() }),      async execute(_id, params) {        return {          content: [{ type: "text", text: `Got: ${params.input}` }],        };      },    });  },});

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 eine Zustimmung durch den Benutzer.

register(api) {  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 },  );}

Jedes mit api.registerTool(...) registrierte Tool muss auch 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 all tools from one plugin}

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

Verwenden Sie optionale Tools für Seiteneffekte, ungewöhnliche Binärdateien oder Fähigkeiten, die standardmäßig nicht offengelegt werden sollten. Tool-Namen dürfen nicht mit Core-Tools kollidieren; Konflikte werden übersprungen und in den Plugin-Diagnosen gemeldet. Fehlerhafte Registrierungen, einschließlich Tool-Deskriptoren ohne parameters, werden übersprungen und auf dieselbe Weise gemeldet. Registrierte Tools sind typisierte Funktionen, die das Modell aufrufen kann, nachdem Policy- und Allowlist-Prüfungen bestanden wurden.

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

Das Manifest deklariert Zuständigkeit und Discovery; die Ausführung ruft weiterhin die live registrierte Tool-Implementierung auf. Halten Sie toolMetadata.<tool>.optional: true mit api.registerTool(..., { optional: true }) abgestimmt, damit OpenClaw vermeiden kann, diese Plugin-Laufzeit zu laden, bis das Tool explizit in die Allowlist aufgenommen wurde.

Importkonventionen

Importieren Sie aus fokussierten SDK-Unterpfaden:

Importieren Sie nicht aus dem veralteten Root-Barrel:

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

Benutzerdefinierte Gateway-RPC-Methoden sind ein fortgeschrittener Einstiegspunkt. Belassen Sie sie unter einem Plugin-spezifischen Präfix; Core-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-Map finden Sie in der Plugin-SDK-Übersicht.

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 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 Imports verwenden fokussierte plugin-sdk/<subpath>-Pfade OPENCLAW_DOCS_MARKER:calloutClose: