OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

Building plugins

Plugins erstellen

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

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

bash
openclaw plugins install clawhub:<package-name>

Während der Umstellung beim Launch werden einfache Paketspezifikationen weiterhin von npm installiert. Verwenden Sie das Präfix clawhub:, wenn die Auflösung über ClawHub erfolgen soll.

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 in einem Quellcode-Checkout ist ausschließlich mit pnpm möglich, da OpenClaw gebündelte Plugins aus extensions/*-Workspace-Paketen erkennt.

Plugin-Form auswählen

Kanal-Plugin

Verbinden Sie OpenClaw mit einer Messaging-Plattform.
Provider-Plugin

Fügen Sie einen Provider für Modelle, Medien, Suche, Abruf, Sprache oder Echtzeit hinzu.
CLI-Backend-Plugin

Führen Sie eine lokale KI-CLI über den Modell-Fallback von OpenClaw aus.
Werkzeug-Plugin

Registrieren Sie Agentenwerkzeuge.

Schnellstart

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

  • Paketmetadaten erstellen

    package.json
    {"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"}}}
    openclaw.plugin.json
    {"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}}

    Veröffentlichte externe Plugins sollten Laufzeiteinträge auf erstellte JavaScript- Dateien verweisen lassen. Den vollständigen Vertrag für Einstiegspunkte finden Sie unter SDK-Einstiegspunkte.

    Jedes Plugin benötigt ein Manifest, auch wenn es keine Konfiguration hat. Laufzeitwerkzeuge müssen in contracts.tools aufgeführt sein, damit OpenClaw die Eigentümerschaft erkennen kann, ohne jede Plugin-Laufzeit vorzeitig zu laden. Legen Sie activation.onStartup bewusst fest; dieses Beispiel wird beim Start des Gateways geladen.

    Vom Host als vertrauenswürdig eingestufte Plugin-Oberflächen sind ebenfalls durch das Manifest beschränkt und erfordern für installierte Plugins eine ausdrückliche Deklaration: api.registerAgentToolResultMiddleware(...) benötigt jede Ziellaufzeit in contracts.agentToolResultMiddleware, und api.registerTrustedToolPolicy(...) benötigt jede Richtlinien-ID in contracts.trustedToolPolicies. Diese Deklarationen sorgen dafür, dass die Prüfung zur Installationszeit und die Laufzeitregistrierung übereinstimmen.

    Informationen zu allen Manifestfeldern finden Sie unter Plugin-Manifest.

  • Werkzeug registrieren

    index.ts
    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,        };      },    });  },});

    Verwenden Sie definePluginEntry für Plugins, die keine Kanal-Plugins sind. Kanal-Plugins verwenden stattdessen defineChannelPluginEntry aus openclaw/plugin-sdk/core.

  • Laufzeit testen

    Prüfen Sie bei einem installierten oder externen Plugin die geladene Laufzeit:

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

    Wenn das Plugin einen CLI-Befehl registriert, führen Sie auch diesen Befehl aus und bestätigen Sie die Ausgabe, beispielsweise openclaw demo-plugin ping.

    Bei einem gebündelten Plugin in diesem Repository erkennt OpenClaw Plugin-Pakete aus dem Quellcode-Checkout über den extensions/*-Workspace. Führen Sie den am besten passenden gezielten Test aus:

    bash
    pnpm test extensions/my-plugin/pnpm check

  • Paketinstallation testen

    Testen Sie vor der Veröffentlichung eines paketfertigen Plugins dieselbe Installationsform, die Benutzer erhalten werden. Fügen Sie zunächst einen Build-Schritt hinzu, lassen Sie Laufzeiteinträge wie openclaw.extensions auf erstelltes JavaScript wie ./dist/index.js verweisen und stellen Sie sicher, dass npm pack diese dist/-Ausgabe enthält. TypeScript-Quellcodeeinträge sind ausschließlich für Quellcode-Checkouts und lokale Entwicklungspfade vorgesehen.

    Packen Sie anschließend das Plugin und installieren Sie das Tarball mit npm-pack::

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

    npm-pack: verwendet das von OpenClaw verwaltete npm-Projekt pro Plugin und erkennt daher Fehler bei Laufzeitabhängigkeiten, die Tests im Quellcode-Checkout verbergen können. Damit werden die Paket- und Abhängigkeitsstruktur nachgewiesen, nicht das mit einem Katalog verknüpfte offizielle Vertrauen. Laufzeitimporte müssen in dependencies oder optionalDependencies enthalten sein; Abhängigkeiten, die nur in devDependencies verbleiben, werden für das verwaltete Laufzeitprojekt nicht installiert.

    Verwenden Sie eine direkte Archiv-/Pfadinstallation nicht als abschließenden Nachweis für offizielles oder privilegiertes Plugin-Verhalten. Direkte Quellen sind für die lokale Fehlerbehebung nützlich, weisen jedoch nicht denselben Abhängigkeitspfad wie Installationen über npm oder ClawHub nach. Wenn Ihr Plugin auf dem Status als vertrauenswürdiges offizielles Plugin beruht, fügen Sie einen zweiten Nachweis über eine kataloggestützte offizielle Installation oder einen veröffentlichten Paketpfad hinzu, der offizielles Vertrauen verzeichnet. Einzelheiten zum Installationsstamm und zur Eigentümerschaft von Abhängigkeiten finden Sie unter Auflösung von Plugin-Abhängigkeiten.

  • Veröffentlichen

    Validieren Sie das Paket vor der Veröffentlichung:

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

    Kanonische ClawHub-Paketausschnitte befinden sich in docs/snippets/plugin-publish/.

  • Installieren

    Installieren Sie das veröffentlichte Paket über ClawHub:

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

    • Werkzeuge registrieren

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

    Werkzeug-Factorys erhalten einen vertrauenswürdigen Laufzeitkontext, einschließlich deliveryContext, nativeChannelId für die aktive Plattformkonversation, sofern verfügbar, sowie requesterSenderId.

    typescript
    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 Werkzeugsuche verwendet wird. Katalog- aufrufe lehnen ungültige Schemas vor der Ausführung ab und validieren den endgültigen Wert nach Werkzeug-Hooks. Lassen Sie es bei Werkzeugen ohne stabiles JSON-Ergebnis weg. Den vollständigen Vertrag finden Sie unter Werkzeug-Plugins.

    Jedes mit api.registerTool(...) registrierte Werkzeug muss auch im Plugin-Manifest deklariert werden:

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

    Benutzer stimmen mit tools.allow zu:

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

    Optionale Werkzeuge steuern, ob ein Werkzeug dem Modell zur Verfügung gestellt wird. Verwenden Sie Plugin-Berechtigungsanfragen, wenn ein Werkzeug oder Hook nach der Auswahl durch das Modell und vor der Ausführung der Aktion eine Genehmigung anfordern soll.

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

    Werkzeug-Factorys erhalten ein von der Laufzeit bereitgestelltes Kontextobjekt. Verwenden Sie ctx.activeModel, wenn ein Werkzeug das für den aktuellen Turn aktive Modell protokollieren, anzeigen oder sich daran anpassen muss; es kann provider, modelId und modelRef enthalten. Behandeln Sie es als informative Laufzeitmetadaten, nicht als Sicherheitsgrenze gegenüber dem lokalen Betreiber, installiertem Plugin-Code oder einer modifizierten OpenClaw-Laufzeit. Sensible lokale Werkzeuge 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 Eigentümerschaft und Erkennung; bei der Ausführung wird weiterhin die aktive registrierte Werkzeugimplementierung aufgerufen. Halten Sie toolMetadata.<tool>.optional: true und api.registerTool(..., { optional: true }) aufeinander abgestimmt, damit OpenClaw das Laden dieser Plugin-Laufzeit vermeiden kann, bis das Werkzeug ausdrücklich in die Zulassungsliste aufgenommen wurde.

    Importkonventionen

    Importieren Sie aus fokussierten SDK-Unterpfaden:

    typescript

    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 fortgeschrittener Einstiegspunkt. Verwenden Sie dafür ein Plugin-spezifisches Präfix; administrative Kern-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 Übersicht über das Plugin SDK.

    Die SDK-Kompatibilitätsfelder von OpenClaw tragen TypeScript-@deprecated-Annotationen, die Editoren als Migrationswarnungen anzeigen. Um sie zur Build-Zeit 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 gezielte plugin-sdk/<subpath>-Pfade OPENCLAW_DOCS_MARKER:calloutClose:

    Was this useful?
    On this page

    On this page