​

Building Plugins

​

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?

​

Schnellstart: Tool-Plugin

{
  "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"
    }
  }
}

// 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}` }] };
      },
    });
  },
});

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

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

​

Plugin-Fähigkeiten

• before_tool_call: { block: true } ist endgültig 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 Freigabe über das Overlay für Ausführungsfreigaben, Telegram-Schaltflächen, Discord-Interaktionen oder den Befehl /approve auf jedem Kanal auf.
• before_install: { block: true } ist endgültig und stoppt Handler mit niedrigerer Priorität.
• before_install: { block: false } wird als keine Entscheidung behandelt.
• message_sending: { cancel: true } ist endgültig und stoppt Handler mit niedrigerer Priorität.
• message_sending: { cancel: false } wird als keine Entscheidung behandelt.

​

Agent-Tools registrieren

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

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

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

​

Importkonventionen

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

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

• Anthropic: Claude-Stream-Wrapper und Hilfsfunktionen für service_tier / Beta
• OpenAI: Provider-Builder, Hilfsfunktionen für Standardmodelle, Echtzeit-Provider
• OpenRouter: Provider-Builder plus Hilfsfunktionen für Onboarding/Konfiguration

​

Checkliste vor der Einreichung

​

Beta-Release-Tests

1. Achten Sie auf GitHub-Release-Tags auf openclaw/openclaw und abonnieren Sie sie über Watch > Releases. Beta-Tags sehen etwa so aus: v2026.3.N-beta.1. Sie können auch Benachrichtigungen für das offizielle OpenClaw-X-Konto @openclaw aktivieren, um Release-Ankündigungen zu erhalten.
2. Testen Sie Ihr Plugin gegen das Beta-Tag, sobald es erscheint. Das Zeitfenster bis zum Stable-Release beträgt typischerweise nur wenige Stunden.
3. Posten Sie nach dem Testen im Thread Ihres Plugins im Discord-Kanal plugin-forum entweder all good oder was nicht funktioniert hat. Wenn Sie noch keinen Thread haben, erstellen Sie einen.
4. Wenn etwas nicht funktioniert, ö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.
5. Ö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. Beitragende können PRs nicht labeln, daher ist der Titel das PR-seitige Signal für Maintainer und Automatisierung. Blocker mit einem PR werden zusammengeführt; Blocker ohne PR könnten trotzdem ausgeliefert werden. Maintainer beobachten diese Threads während der Beta-Tests.
6. Schweigen bedeutet grün. Wenn Sie das Zeitfenster verpassen, landet Ihr Fix wahrscheinlich im nächsten Zyklus.

​

Nächste Schritte

​

Verwandt

• Plugin-Architektur — tiefer Einblick in die interne Architektur
• SDK Overview — Referenz zum Plugin SDK
• Manifest — Format des Plugin-Manifests
• Kanal-Plugins — Kanal-Plugins erstellen
• Provider-Plugins — Provider-Plugins erstellen