OpenClaw Plugins nutzen und konfigurieren

Kennst du das Problem? Du arbeitest mit einem System, aber ein spezifisches Feature oder eine bestimmte Integration fehlt einfach. Den Core-Code selbst zu ändern ist meist keine gute Idee, da das zukünftige Updates erschwert.

Plugins lösen dieses Problem. Sie sind kleine Code-Module, die Commands, Tools, Channels oder komplette Integrationen hinzufügen. Ich nutze Plugins für alles Mögliche, von Voice Calls bis hin zu Custom Slack-Integrationen. Wenn du das Prinzip einmal verstanden hast, lassen sie sich extrem einfach einbauen.

Voraussetzungen

• OpenClaw installiert und gestartet
• Grundkenntnisse in TypeScript (falls du eigene Plugins schreiben willst)

Quick Start (3 Minuten)

Schritt 1: Installierte Plugins prüfen

Schau dir zuerst an, was bereits geladen ist:

openclaw plugins list

Schritt 2: Offizielles Plugin installieren

Installiere zum Beispiel das Voice-Call-Plugin:

openclaw plugins install @openclaw/voice-call

Schritt 3: Neustart und Konfiguration

Starte dein Gateway neu und füge die Konfiguration unter plugins.entries.<id>.config hinzu:

{
  plugins: {
    entries: {
      "voice-call": {
        enabled: true,
        config: {
          provider: "twilio"
        }
      }
    }
  }
}

Dein neues Plugin ist damit einsatzbereit.

Offizielle Plugins

Plugin	Package	Beschreibung
Voice Call	@openclaw/voice-call	Anrufe tätigen und empfangen
Microsoft Teams	@openclaw/msteams	Teams Channel Integration
Matrix	@openclaw/matrix	Matrix Chat Protokoll
Nostr	@openclaw/nostr	Dezentraler Nostr Chat
Zalo	@openclaw/zalo	Vietnamesische Messaging App

Bundled Plugins (standardmäßig deaktiviert):

• Memory (Core) — einfache Suche im Speicher
• Memory (LanceDB) — Langzeitgedächtnis mit Auto-Recall
• Google/Gemini/Qwen OAuth — Authentifizierung für Provider

Aktiviere Bundled Plugins so:

openclaw plugins enable memory-lancedb

Plugin Discovery

OpenClaw sucht in dieser Reihenfolge nach Plugins:

1. Config paths — plugins.load.paths
2. Workspace extensions — .openclaw/extensions/*.ts
3. Global extensions — ~/.openclaw/extensions/*.ts
4. Bundled — direkt in OpenClaw enthalten

Der erste Treffer wird verwendet, spätere Kopien ignoriert OpenClaw.

Configuration

Hier siehst du ein Beispiel für eine vollständige Konfiguration:

{
  plugins: {
    enabled: true,
    allow: ["voice-call"],           // Allowlist (optional)
    deny: ["untrusted-plugin"],      // Denylist hat Priorität
    load: {
      paths: ["~/my-plugins/custom"]
    },
    entries: {
      "voice-call": {
        enabled: true,
        config: { provider: "twilio" }
      }
    }
  }
}

Wichtig: Nach Änderungen an der Konfiguration musst du das Gateway neu starten.

Plugin Slots

Einige Kategorien erlauben nur ein einziges aktives Plugin (zum Beispiel Memory Provider):

{
  plugins: {
    slots: {
      memory: "memory-lancedb"  // oder "memory-core" oder "none"
    }
  }
}

CLI Commands

Mit diesen Befehlen verwaltest du deine Plugins:

openclaw plugins list                    # Alle Plugins anzeigen
openclaw plugins info <id>               # Details zum Plugin
openclaw plugins install &lt;path|npm&gt;      # Plugin installieren
openclaw plugins install -l <path>       # Link für die Entwicklung
openclaw plugins enable <id>             # Plugin aktivieren
openclaw plugins disable <id>            # Plugin deaktivieren
openclaw plugins update <id>             # NPM-Plugin aktualisieren
openclaw plugins update --all            # Alle NPM-Plugins aktualisieren
openclaw plugins doctor                  # Probleme diagnostizieren

Fehlerbehebung

Falls ein Plugin nicht wie erwartet funktioniert, ist das der erste Schritt zur Lösung:

• Diagnose-Tool nutzen: Führe openclaw plugins doctor aus, um Konfigurationsfehler oder Ladeprobleme zu finden.
• Neustart vergessen: Prüfe, ob du das Gateway nach der Installation oder Konfigurationsänderung neu gestartet hast.

Hast du Fragen zur Einrichtung? Nutze den AI Setup Assistant.

Nächste Schritte

• Custom Plugins erstellen
• Gateway Konfiguration
• CLI Referenz
• API Dokumentation

Du hast eine Idee für eine neue Funktion, aber die vorhandenen Tools lassen sich nicht so anpassen, wie du es brauchst. Oft verbringt man mehr Zeit damit, Workarounds für starre Systeme zu finden, anstatt die eigentliche Logik zu schreiben.

Wenn du eine API anbinden oder einen spezifischen Workflow automatisieren willst, ist ein eigenes Plugin der richtige Weg. So behältst du die volle Kontrolle über die Ausführung und die Integration.

Voraussetzungen

• Eine installierte Instanz von OpenClaw
• Node.js Umgebung für die Entwicklung
• Zugriff auf das Verzeichnis ~/.openclaw/extensions/
• Grundkenntnisse in TypeScript

Schnellstart

In weniger als 5 Minuten erstellst du dein erstes Plugin.

1. Erstelle den Ordner ~/.openclaw/extensions/my-plugin/.
2. Erstelle die Datei index.ts in diesem Ordner:

export default function(api) {
  api.registerGatewayMethod("myplugin.status", ({ respond }) => {
    respond(true, { status: "running" });
  });
}

3. Erstelle die Datei openclaw.plugin.json im selben Verzeichnis:

{
  "id": "my-plugin",
  "name": "My Custom Plugin",
  "version": "1.0.0"
}

4. Starte das Gateway neu. Dein Plugin ist sofort live.

Register a Tool

Du kannst Tools registrieren, die vom AI-Modell aufgerufen werden können.

export default function(api) {
  api.registerTool({
    name: "my_tool",
    description: "Does something useful",
    parameters: {
      type: "object",
      properties: {
        input: { type: "string" }
      }
    },
    handler: async ({ input }) => {
      return { result: `Processed: ${input}` };
    }
  });
}

Register a Slash Command

Slash Commands sind ideal für schnelle Status-Checks, da sie die AI nicht involvieren.

export default function(api) {
  api.registerCommand({
    name: "mystatus",
    description: "Show plugin status",
    handler: (ctx) => ({
      text: `Plugin running on ${ctx.channel}`
    })
  });
}

Register a Channel

Wenn du Nachrichten über einen eigenen Dienst senden willst, registriere einen Channel.

const plugin = {
  id: "acmechat",
  meta: {
    label: "AcmeChat",
    docsPath: "/channels/acmechat",
    blurb: "AcmeChat messaging."
  },
  capabilities: { chatTypes: ["direct"] },
  config: {
    listAccountIds: (cfg) =>
      Object.keys(cfg.channels?.acmechat?.accounts ?? {}),
    resolveAccount: (cfg, id) =>
      cfg.channels?.acmechat?.accounts?.[id ?? "default"]
  },
  outbound: {
    deliveryMode: "direct",
    sendText: async ({ text }) => {
      // Nachricht senden
      return { ok: true };
    }
  }
};

export default function(api) {
  api.registerChannel({ plugin });
}

Plugin Hooks

Plugins können Hooks enthalten und diese zur Laufzeit registrieren. Das ermöglicht event-gesteuerte Automatisierung ohne separate Installation eines Hook-Packs.

import { registerPluginHooksFromDir } from "openclaw/plugin-sdk";

export default function register(api) {
  registerPluginHooksFromDir(api, "./hooks");
}

Hinweise:

• Hook-Verzeichnisse müssen die Struktur aus HOOK.md und handler.ts einhalten.
• Plugin-Hooks erscheinen in der Liste openclaw hooks list mit dem Präfix plugin:<id>.
• Die Eligibility Rules (OS, Binaries, Env, Config) gelten weiterhin.
• Das Aktivieren oder Deaktivieren des Plugins steuert auch dessen Hooks.

Runtime Helpers

Über api.runtime greifen Plugins auf Core-Funktionen zu, wie zum Beispiel Telephony TTS:

const result = await api.runtime.tts.textToSpeechTelephony({
  text: "Hello from OpenClaw",
  cfg: api.config,
});

Hinweise:

• Diese Funktion nutzt die messages.tts Konfiguration (OpenAI oder ElevenLabs).
• Du erhältst einen PCM Audio Buffer und die Sample Rate zurück.
• Plugins sind selbst für das Resampling oder Encoding für ihre Provider verantwortlich.
• Edge TTS wird für Telephony nicht unterstützt.

Provider Plugins (Model Auth)

Du kannst Auth-Flows für Model Provider registrieren, damit Nutzer OAuth oder API-Keys direkt in OpenClaw einrichten können.

api.registerProvider({
  id: "acme",
  label: "AcmeAI",
  auth: [
    {
      id: "oauth",
      label: "OAuth",
      kind: "oauth",
      run: async (ctx) => {
        // OAuth Flow ausführen und Profile zurückgeben
        return {
          profiles: [
            {
              profileId: "acme:default",
              credential: {
                type: "oauth",
                provider: "acme",
                access: "...",
                refresh: "...",
                expires: Date.now() + 3600 * 1000,
              },
            },
          ],
          defaultModel: "acme/opus-1",
        };
      },
    },
  ],
});

Hinweise:

• Die run Funktion erhält einen ProviderAuthContext mit Helfern wie prompter, runtime und openUrl.
• Nutze configPatch, um Standardmodelle hinzuzufügen.
• Mit defaultModel kann --set-default die Agent-Standards aktualisieren.

Nutzer authentifizieren sich dann über das CLI:

openclaw models auth login --provider acme --method oauth

Fehlerbehebung

• Hooks werden nicht geladen: Prüfe, ob alle Anforderungen in der Hook-Struktur (OS, Umgebungsvariablen) erfüllt sind.
• Audio-Probleme bei TTS: Stelle sicher, dass dein Plugin das Resampling korrekt handhabt, da nur PCM Buffer geliefert werden.
• Plugin wird nicht erkannt: Kontrolliere, ob die id in der openclaw.plugin.json exakt mit dem Verzeichnisnamen übereinstimmt.
• Fehlende Berechtigungen: Stelle sicher, dass der Prozess Schreibrechte für das Verzeichnis ~/.openclaw/extensions/ besitzt.

Falls du Hilfe bei der Konfiguration benötigst, frag den AI Setup Assistant.

Nächste Schritte

• Plugin API Reference
• Channel Configuration

Du kennst das: Ein Nutzer stellt eine simple Frage und dein AI-Agent fängt an zu grübeln, obwohl die Antwort feststeht. Das frisst unnötig Token und Zeit. Manchmal willst du einfach, dass dein Plugin sofort antwortet, ohne den Umweg über die AI zu gehen.

Eigene Slash-Commands sind der beste Weg, um diese Abkürzung zu nehmen. So reagiert dein Plugin direkt auf spezifische Eingaben, spart Ressourcen und gibt dem Nutzer sofortiges Feedback.

Voraussetzungen

• Eine bestehende OpenClaw Plugin-Struktur
• Grundverständnis von TypeScript und Node.js

Schnellstart

In 5 Minuten hast du deinen ersten eigenen Befehl am Laufen. Folge einfach diesen Schritten:

1. Nutze api.registerCommand in deiner Plugin-Hauptfunktion.
2. Definiere einen Namen und einen Handler für die Antwort.
3. Lege fest, ob der Befehl eine Autorisierung benötigt.
4. Starte dein Plugin neu und teste den Befehl im Channel.

Hier ist das minimale Code-Beispiel:

export default function(api) {
  api.registerCommand({
    name: "mystatus",
    description: "Show plugin status",
    acceptsArgs: false,
    requireAuth: true,
    handler: (ctx) => ({
      text: `Plugin running on ${ctx.channel}`
    })
  });
}

Technische Details

Command Context

Wenn ein Befehl ausgeführt wird, erhält der Handler einen Context (ctx). Diese Daten kannst du nutzen:

Feld	Beschreibung
senderId	ID des Absenders
channel	Channel, in dem der Befehl gesendet wurde
isAuthorizedSender	Ob der Absender autorisiert ist
args	Argumente (wenn acceptsArgs: true)
commandBody	Vollständiger Text des Befehls
config	Aktuelle OpenClaw-Konfiguration

Command Options

Du hast verschiedene Optionen, um das Verhalten deines Befehls zu steuern:

Option	Beschreibung
name	Name des Befehls (ohne /)
description	Hilfetext
acceptsArgs	Ob Argumente akzeptiert werden (Standard: false)
requireAuth	Erfordert autorisierten Absender (Standard: true)
handler	Funktion, die { text: string } zurückgibt

Background Services registrieren

Neben Befehlen kannst du Services starten, die im Hintergrund laufen:

export default function(api) {
  api.registerService({
    id: "my-service",
    start: () => api.logger.info("ready"),
    stop: () => api.logger.info("bye"),
  });
}

CLI Commands registrieren

Für direkte Interaktionen über das Terminal kannst du CLI-Befehle hinzufügen:

export default function(api) {
  api.registerCli(({ program }) => {
    program.command("mycmd").action(() => {
      console.log("Hello");
    });
  }, { commands: ["mycmd"] });
}

Plugin Manifest & Publishing

Jedes Plugin benötigt eine openclaw.plugin.json:

{
  "id": "my-plugin",
  "name": "My Plugin",
  "version": "1.0.0",
  "configSchema": {
    "type": "object",
    "properties": {
      "apiKey": { "type": "string" }
    }
  },
  "uiHints": {
    "apiKey": { "label": "API Key", "sensitive": true }
  }
}

Veröffentlichung auf npm

1. Füge dies zu deiner package.json hinzu:

{
  "name": "@yourscope/my-plugin",
  "openclaw": {
    "extensions": ["./index.ts"]
  }
}

2. Veröffentlichen: npm publish

3. Installation durch Nutzer:

openclaw plugins install @yourscope/my-plugin

Fehlerbehebung

• Befehl wird ignoriert: Plugin-Befehle werden verarbeitet, bevor eingebaute Befehle oder der AI-Agent greifen. Prüfe, ob der Name korrekt registriert wurde.
• Reservierte Namen: Du kannst keine reservierten Befehle wie help, status oder reset überschreiben.
• Groß-/Kleinschreibung: Befehlsnamen sind case-insensitive, es spielt also keine Rolle, ob der Nutzer /MyStatus oder /mystatus schreibt.

Benötigst du Hilfe bei der Einrichtung? Frag den AI Setup Assistant.

Nächste Schritte

• Plugin Architektur verstehen
• API Referenz
• Event Listeners nutzen
• Config Schema Guide

Kennst du das? Du hast dein Plugin fertig geschrieben, aber es taucht einfach nicht in der Liste auf. Du starrst auf den Monitor und fragst dich, ob es an einem Tippfehler in der Config oder an einer fehlenden Datei liegt. Solche Hürden kosten Zeit und nerven, wenn man eigentlich nur Features bauen will.

Oft sind es kleinteilige Validierungsfehler oder falsch gesetzte Pfade, die den Start verhindern. In diesem Guide erfährst du, wie du Plugins richtig konfigurierst und Fehler schnell behebst, damit dein Setup stabil läuft.

Voraussetzungen

• Eine installierte Instanz von OpenClaw
• Zugriff auf das Verzeichnis ~/.openclaw/extensions/
• Node.js und npm für die Verwaltung von Abhängigkeiten
• Die Datei openclaw.plugin.json oder eine package.json für dein Plugin

Schnellstart

In fünf Minuten zum funktionierenden Plugin:

1. Aktivierung prüfen: Stelle sicher, dass in deiner Config plugins.enabled auf true gesetzt ist.
2. Dateien validieren: Prüfe, ob die Datei openclaw.plugin.json im Plugin-Ordner liegt.
3. Abhängigkeiten laden: Falls dein Plugin npm-Pakete nutzt, wechsle in den Plugin-Ordner und führe npm install aus.
4. Neustart: Starte OpenClaw neu, um die Änderungen zu übernehmen.

Fehlerbehebung

Plugin lädt nicht

Prüfe diese Punkte:

1. Ist plugins.enabled in der Konfiguration auf true gesetzt?
2. Steht das Plugin versehentlich auf der deny Liste?
3. Ist die Datei openclaw.plugin.json im Verzeichnis vorhanden?
4. Sind alle Pfade in der Config korrekt angegeben?

Config Validierungsfehler

Ursache: Wenn du unbekannte Plugin-IDs in deiner Config verwendest, führt das zu strikten Fehlern.

Lösung: Entferne alle Referenzen auf Plugins, die deaktiviert oder deinstalliert wurden, aus den Abschnitten entries, allow und deny.

Plugin-Konflikte

Ursache: Es befinden sich mehrere Plugins mit derselben ID im System.

Lösung: OpenClaw lädt nur das Plugin, das zuerst entdeckt wird. Du musst Duplikate aus deinen Extension-Verzeichnissen entfernen.

Package Packs

Ein Plugin-Verzeichnis kann eine package.json enthalten, die das Feld openclaw.extensions nutzt:

{
  "name": "my-pack",
  "openclaw": {
    "extensions": ["./src/safety.ts", "./src/tools.ts"]
  }
}

Dabei wird jeder Eintrag als einzelnes Plugin behandelt. Wenn ein Pack mehrere Extensions auflistet, setzt sich die Plugin-ID aus name/<fileBase> zusammen.

Falls dein Plugin npm-Abhängigkeiten importiert, musst du diese direkt in diesem Verzeichnis installieren:

cd ~/.openclaw/extensions/my-pack
npm install

Channel Catalog Metadata

Channel-Plugins können Onboarding-Metadaten über openclaw.channel und Installationshinweise über openclaw.install bereitstellen:

{
  "name": "@openclaw/nextcloud-talk",
  "openclaw": {
    "extensions": ["./index.ts"],
    "channel": {
      "id": "nextcloud-talk",
      "label": "Nextcloud Talk",
      "selectionLabel": "Nextcloud Talk (self-hosted)",
      "docsPath": "/channels/nextcloud-talk",
      "blurb": "Self-hosted chat via Nextcloud Talk webhook bots.",
      "order": 65,
      "aliases": ["nc-talk", "nc"]
    },
    "install": {
      "npmSpec": "@openclaw/nextcloud-talk",
      "localPath": "extensions/nextcloud-talk",
      "defaultChoice": "npm"
    }
  }
}

Externe Catalogs

Du kannst JSON-Dateien für Kataloge an folgenden Orten hinterlegen:

• ~/.openclaw/mpm/plugins.json
• ~/.openclaw/mpm/catalog.json
• ~/.openclaw/plugins/catalog.json

Alternativ kannst du die Umgebungsvariable OPENCLAW_PLUGIN_CATALOG_PATHS nutzen, um eigene Pfade zu definieren.

Du kommst nicht weiter? Unser AI Setup Assistant hilft dir beim Debugging deines Plugin-Setups.

Nächste Schritte

• Plugin Architektur verstehen
• Eigene Channels entwickeln
• API Referenz
• CLI Tooling

Du hast eine großartige AI-Anwendung gebaut, aber sie steckt in einem Silo fest. Die Anbindung an neue Chat-Plattformen ist oft nervig, weil jede API ihr eigenes Süppchen kocht. Du verbringst mehr Zeit mit Boilerplate-Code für die Verbindung als mit den eigentlichen Features deines Agents.

Dieses Guide zeigt dir, wie du eine neue Chat-Oberfläche (einen Messaging Channel) baust, damit dein Agent dort erreichbar ist, wo deine Nutzer sind.

Voraussetzungen

• Eine eindeutige Channel-ID
• Eine definierte Config-Struktur
• Metadaten für das UI/CLI
• Implementierte Adapters für die Kommunikation

Schnellstart

In 5 Minuten steht das Grundgerüst für deinen eigenen Channel. Folge diesen Schritten:

Schritt 1: ID und Config Shape wählen

Die gesamte Channel-Konfiguration wird unter channels.<id> gespeichert. So sieht die Struktur in der JSON5-Datei aus:

{
  channels: {
    acmechat: {
      accounts: {
        default: { token: "TOKEN", enabled: true }
      }
    }
  }
}

Schritt 2: Channel Metadaten definieren

Die Metadaten steuern, wie dein Channel im CLI oder im UI erscheint.

Field	Purpose
meta.label	Anzeigename im CLI/UI
meta.selectionLabel	Längerer Text für die Auswahl
meta.docsPath	Link zur Dokumentation (z. B. /channels/acmechat)
meta.blurb	Kurze Beschreibung
meta.aliases	Alternative Channel-IDs
meta.preferOver	Ersetzt einen anderen Channel

Schritt 3: Erforderliche Adapters implementieren

Hier definierst du die Logik, wie Accounts aufgelöst werden und wie Nachrichten rausgehen.

const plugin = {
  id: "acmechat",
  meta: { /* ... */ },
  capabilities: { chatTypes: ["direct"] },
  config: {
    listAccountIds: (cfg) => Object.keys(cfg.channels?.acmechat?.accounts ?? {}),
    resolveAccount: (cfg, id) => cfg.channels?.acmechat?.accounts?.[id ?? "default"]
  },
  outbound: {
    deliveryMode: "direct",
    sendText: async ({ text }) => ({ ok: true })
  }
};

Schritt 4: Optionale Adapters hinzufügen

Je nachdem, was dein Channel unterstützen soll, kannst du diese Adapters ergänzen:

Adapter	Purpose
setup	Integration in den Setup-Wizard
security	Richtlinien für Direct Messages (DM)
status	Status-Checks und Diagnosen
gateway	Start/Stop/Login Aktionen
mentions	Handhabung von @mentions
threading	Unterstützung für Threads
streaming	Antworten per Streaming übertragen
actions	Nachrichten-Aktionen
commands	Natives Verhalten für Befehle

Schritt 5: Registrieren

Exportiere die Funktion, um das Plugin im System anzumelden:

export default function(api) {
  api.registerChannel({ plugin });
}

Naming Conventions

Halte dich an diese Konventionen, um Konflikte mit Core-Befehlen zu vermeiden:

Type	Convention	Example
Gateway methods	pluginId.action	voicecall.status
Tools	snake_case	voice_call
CLI commands	kebab-case	voicecall-start

Skills in Plugins

Deine Plugins können eigene Skills mitliefern. Erstelle dafür einfach ein skills/ Verzeichnis in deiner Plugin-Struktur:

my-plugin/
├── index.ts
├── openclaw.plugin.json
└── skills/
    └── my-skill/
        └── SKILL.md

Aktiviere Skills über plugins.entries.<id>.enabled und stelle sicher, dass sie in deinen verwalteten Skill-Verzeichnissen liegen.

Troubleshooting & Safety

Plugins laufen in-process direkt mit dem Gateway. Behandle sie daher als vertrauenswürdigen Code.

• Problem: Änderungen am Plugin werden nicht übernommen. Lösung: Starte das Gateway nach jeder Code-Änderung neu.
• Problem: Sicherheitsbedenken bei Drittanbieter-Plugins. Lösung: Nutze plugins.allow Whitelists und prüfe den Source Code, bevor du ein Plugin aktivierst.
• Problem: Plugin verhält sich instabil. Lösung: Stelle sicher, dass du Tests mitlieferst. In-Repo Plugins nutzen Vitest unter src/** (z. B. src/plugins/voice-call.plugin.test.ts).

Für veröffentlichte Plugins solltest du eine eigene CI nutzen und validieren, dass openclaw.extensions auf den korrekten Entrypoint zeigt.

# Plugin-Tests ausführen
cd ~/.openclaw/extensions/my-plugin
npm test

---

Du brauchst Hilfe bei der Umsetzung? Frage den AI Setup Assistant oder besuche uns auf Discord.

Nächste Schritte

• Plugin Agent Tools → — Baue Tools, die deine AI aufrufen kann.
• Plugin Manifest → — Die vollständige Referenz für das Manifest.
• Voice Call Plugin → — Ein Beispiel-Plugin im Detail.