OpenClaw Plugin-Manifest erstellen: Anleitung & Schema

Plugin-Manifest (openclaw.plugin.json)

Diese Seite beschreibt ausschließlich das native OpenClaw Plugin-Manifest.

Informationen zu kompatiblen Bundle-Layouts findest du unter Plugin bundles.

Kompatible Bundle-Formate nutzen unterschiedliche Manifest-Dateien:

• Codex bundle: .codex-plugin/plugin.json
• Claude bundle: .claude-plugin/plugin.json oder das Standard Claude Component Layout ohne Manifest
• Cursor bundle: .cursor-plugin/plugin.json

OpenClaw erkennt diese Layouts automatisch, validiert sie aber nicht gegen das hier beschriebene openclaw.plugin.json Schema.

Bei kompatiblen Bundles liest OpenClaw die Metadaten sowie Skill Roots, Claude Command Roots, Claude Bundle settings.json Defaults, Claude Bundle LSP Defaults und unterstützte Hook Packs aus, sofern das Layout den Erwartungen der OpenClaw Runtime entspricht.

Jedes native OpenClaw Plugin muss eine openclaw.plugin.json Datei im Plugin-Root enthalten. OpenClaw nutzt dieses Manifest zur Validierung der Konfiguration, ohne den Plugin-Code auszuführen. Fehlende oder ungültige Manifeste werden als Plugin-Fehler gewertet und blockieren die Validierung.

Den vollständigen Guide zum Plugin-System findest du hier: Plugins. Für das native Capability-Modell und Hinweise zur externen Kompatibilität: Capability model.

Was diese Datei macht

Die openclaw.plugin.json enthält die Metadaten, die OpenClaw liest, bevor dein Plugin-Code geladen wird.

Nutze sie für:

• Plugin-Identität
• Validierung der Konfiguration
• Metadaten für Auth und Onboarding, die ohne Start der Plugin-Runtime verfügbar sein sollen
• Alias- und Auto-Enable-Metadaten zur Auflösung vor dem Laden der Runtime
• Metadaten zur Model-Family, um das Plugin vor dem Runtime-Start automatisch zu aktivieren
• Statische Snapshots der Capabilities für Bundle-Kompatibilität und Contract-Abdeckung
• Channelspezifische Konfigurations-Metadaten für Katalog und Validierung ohne Runtime-Load
• Hinweise für die Konfigurations-UI (UI hints)

Nutze sie nicht für:

• Registrierung von Runtime-Verhalten
• Definition von Code-Entrypoints
• npm install Metadaten

Diese gehören in deinen Plugin-Code und die package.json.

Minimales Beispiel

{
  "id": "voice-call",
  "configSchema": {
    "type": "object",
    "additionalProperties": false,
    "properties": {}
  }
}

Umfangreiches Beispiel

{
  "id": "openrouter",
  "name": "OpenRouter",
  "description": "OpenRouter provider plugin",
  "version": "1.0.0",
  "providers": ["openrouter"],
  "modelSupport": {
    "modelPrefixes": ["router-"]
  },
  "cliBackends": ["openrouter-cli"],
  "providerAuthEnvVars": {
    "openrouter": ["OPENROUTER_API_KEY"]
  },
  "providerAuthAliases": {
    "openrouter-coding": "openrouter"
  },
  "channelEnvVars": {
    "openrouter-chatops": ["OPENROUTER_CHATOPS_TOKEN"]
  },
  "providerAuthChoices": [
    {
      "provider": "openrouter",
      "method": "api-key",
      "choiceId": "openrouter-api-key",
      "choiceLabel": "OpenRouter API key",
      "groupId": "openrouter",
      "groupLabel": "OpenRouter",
      "optionKey": "openrouterApiKey",
      "cliFlag": "--openrouter-api-key",
      "cliOption": "--openrouter-api-key <key>",
      "cliDescription": "OpenRouter API key",
      "onboardingScopes": ["text-inference"]
    }
  ],
  "uiHints": {
    "apiKey": {
      "label": "API key",
      "placeholder": "sk-or-v1-...",
      "sensitive": true
    }
  },
  "configSchema": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
      "apiKey": {
        "type": "string"
      }
    }
  }
}

Referenz der Top-Level-Felder

Feld	Erforderlich	Typ	Bedeutung
id	Ja	string	Kanonische Plugin-ID. Diese ID wird in plugins.entries.<id> verwendet.
configSchema	Ja	object	Inline JSON Schema für die Konfiguration dieses Plugins.
enabledByDefault	Nein	true	Markiert ein gebündeltes Plugin als standardmäßig aktiviert. Lass es weg oder setze einen Wert ungleich true, um es deaktiviert zu lassen.
legacyPluginIds	Nein	string[]	Veraltete IDs, die auf diese kanonische Plugin-ID normalisiert werden.
autoEnableWhenConfiguredProviders	Nein	string[]	Provider-IDs, die dieses Plugin automatisch aktivieren sollen, wenn Auth, Config oder Model-Refs sie erwähnen.
kind	Nein	"memory" | "context-engine"	Deklariert einen exklusiven Plugin-Typ für plugins.slots.*.
channels	Nein	string[]	Channel-IDs, die zu diesem Plugin gehören. Wird für Discovery und Validierung genutzt.
providers	Nein	string[]	Provider-IDs, die zu diesem Plugin gehören.
modelSupport	Nein	object	Metadaten zur Model-Family, um das Plugin vor der Runtime automatisch zu laden.
cliBackends	Nein	string[]	CLI Inference Backend-IDs dieses Plugins. Wird für die Auto-Aktivierung beim Start genutzt.
commandAliases	Nein	object[]	Command-Namen dieses Plugins für Plugin-aware Config und CLI-Diagnose vor dem Runtime-Load.
providerAuthEnvVars	Nein	Record<string, string[]>	Metadaten für Provider-Auth Umgebungsvariablen, die OpenClaw ohne Plugin-Code prüfen kann.
providerAuthAliases	Nein	Record<string, string>	Provider-IDs, die eine andere Provider-ID für den Auth-Lookup wiederverwenden (z. B. Coding-Provider).
channelEnvVars	Nein	Record<string, string[]>	Metadaten für Channel Umgebungsvariablen für das Setup oder Auth-Oberflächen beim Start.
providerAuthChoices	Nein	object[]	Metadaten für Auth-Optionen in Onboarding-Pickern und CLI-Flags.
contracts	Nein	object	Statischer Snapshot der Capabilities für Speech, Realtime Voice, Image-Generation, Web-Search und Tool-Ownership.
channelConfigs	Nein	Record<string, object>	Channel-Konfigurationsmetadaten, die vor dem Runtime-Load in Discovery und Validierung einfließen.
skills	Nein	string[]	Skill-Verzeichnisse, die relativ zum Plugin-Root geladen werden sollen.
name	Nein	string	Lesbarer Name des Plugins.
description	Nein	string	Kurze Zusammenfassung für Plugin-Oberflächen.
version	Nein	string	Information zur Plugin-Version.
uiHints	Nein	Record<string, object>	UI-Labels, Placeholder und Hinweise zur Vertraulichkeit für Konfigurationsfelder.

Referenz für providerAuthChoices

Jeder providerAuthChoices-Eintrag beschreibt eine Onboarding- oder Auth-Option. OpenClaw liest diese Informationen, bevor die Provider-Runtime geladen wird.

Feld	Erforderlich	Typ	Bedeutung
provider	Ja	string	Provider-ID, zu der diese Auswahl gehört.
method	Ja	string	Auth-Methoden-ID, an die weitergeleitet wird.
choiceId	Ja	string	Stabile Auth-Choice-ID für Onboarding- und CLI-Flows.
choiceLabel	Nein	string	Bezeichnung für Nutzer. Falls weggelassen, nutzt OpenClaw die choiceId.
choiceHint	Nein	string	Kurzer Hilfetext für das Auswahlmenü.
assistantPriority	Nein	number	Kleinere Werte werden in interaktiven Assistant-Pickern weiter oben sortiert.
assistantVisibility	Nein	"visible" | "manual-only"	Blendet die Auswahl in Assistant-Pickern aus, erlaubt aber weiterhin die manuelle Auswahl per CLI.
deprecatedChoiceIds	Nein	string[]	Veraltete Choice-IDs, die Nutzer zu dieser neuen Auswahl weiterleiten.
groupId	Nein	string	Optionale Gruppen-ID, um zusammengehörige Optionen zu bündeln.
groupLabel	Nein	string	Bezeichnung der Gruppe für Nutzer.
groupHint	Nein	string	Kurzer Hilfetext für die Gruppe.
optionKey	Nein	string	Interner Option-Key für einfache Auth-Flows mit nur einem Flag.
cliFlag	Nein	string	Name des CLI-Flags, zum Beispiel --openrouter-api-key.
cliOption	Nein	string	Vollständiges Format der CLI-Option, zum Beispiel --openrouter-api-key <key>.
cliDescription	Nein	string	Beschreibung für die CLI-Hilfe.
onboardingScopes	Nein	Array&lt;"text-inference" | "image-generation"&gt;	In welchen Onboarding-Bereichen diese Auswahl erscheinen soll. Falls weggelassen, wird standardmäßig ["text-inference"] verwendet.

Referenz für commandAliases

Verwende commandAliases, wenn ein Plugin einen Runtime-Befehlsnamen besitzt, den Nutzer versehentlich in plugins.allow eintragen oder als Root-CLI-Befehl ausführen könnten. OpenClaw nutzt diese Metadaten für Diagnosen, ohne den Plugin-Runtime-Code zu importieren.

{
  "channelConfigs": {
    "matrix": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "homeserverUrl": { "type": "string" }
        }
      },
      "uiHints": {
        "homeserverUrl": {
          "label": "Homeserver URL",
          "placeholder": "https://matrix.example.com"
        }
      },
      "label": "Matrix",
      "description": "Matrix homeserver connection",
      "preferOver": ["matrix-legacy"]
    }
  }
}

Jeder Channel-Eintrag kann folgende Felder enthalten:

Feld	Typ	Bedeutung
schema	object	JSON Schema für channels.<id>. Erforderlich für jeden deklarierten Channel-Config-Eintrag.
uiHints	Record<string, object>	Optionale UI-Labels, Platzhalter oder Hinweise für sensible Daten in diesem Abschnitt.
label	string	Channel-Label für den Picker und die Inspect-Oberfläche, falls Runtime-Metadaten noch nicht bereit sind.
description	string	Kurze Channel-Beschreibung für Inspect- und Katalog-Oberflächen.
preferOver	string[]	IDs von Legacy-Plugins oder Plugins mit niedrigerer Priorität, die dieser Channel übertreffen soll.

modelSupport Referenz

Verwende modelSupport, damit OpenClaw dein Provider-Plugin aus Kurz-IDs wie gpt-5.4 oder claude-sonnet-4.6 ableiten kann, noch bevor die Plugin-Runtime geladen wird.

{
  "modelSupport": {
    "modelPrefixes": ["gpt-", "o1", "o3", "o4"],
    "modelPatterns": ["^computer-use-preview"]
  }
}

OpenClaw wendet dabei diese Rangfolge an:

• Explizite provider/model Referenzen nutzen die Metadaten des besitzenden providers Manifests.
• modelPatterns haben Vorrang vor modelPrefixes.
• Wenn ein externes Plugin und ein integriertes (bundled) Plugin beide passen, gewinnt das externe Plugin.
• Verbleibende Unklarheiten werden ignoriert, bis du oder die Konfiguration einen Provider festlegen.

Felder:

Feld	Typ	Bedeutung
modelPrefixes	string[]	Präfixe, die per startsWith mit Modell-Kurz-IDs abgeglichen werden.
modelPatterns	string[]	Regex-Quellen, die nach dem Entfernen von Profil-Suffixen gegen Kurz-IDs geprüft werden.

Alte Capability-Keys auf oberster Ebene sind veraltet. Nutze openclaw doctor --fix, um speechProviders, realtimeTranscriptionProviders, realtimeVoiceProviders, mediaUnderstandingProviders, imageGenerationProviders, videoGenerationProviders, webFetchProviders und webSearchProviders unter contracts zu verschieben. Das normale Laden des Manifests behandelt diese Felder auf oberster Ebene nicht mehr als Capability-Besitz.

AI Setup Assistant

Nächste Schritte

• Plugin Manifest Übersicht
• Contracts Guide

Manifest im Vergleich zu package.json

Die beiden Dateien haben unterschiedliche Aufgaben:

Datei	Verwendung
openclaw.plugin.json	Discovery, Validierung der Konfiguration, Metadaten für die Auth-Auswahl und UI-Hints, die vorhanden sein müssen, bevor der Plugin-Code läuft.
package.json	npm-Metadaten und die Installation von Abhängigkeiten sowie der openclaw-Block für Entrypoints, Install-Gating, Setup oder Katalog-Metadaten.

Falls du dir unsicher bist, wo bestimmte Metadaten hingehören, hilft dir diese Regel:

• Wenn OpenClaw die Info braucht, bevor der Plugin-Code geladen wird, pack sie in die openclaw.plugin.json.
• Wenn es um das Packaging, Entry-Dateien oder das Verhalten bei npm install geht, gehört es in die package.json.

package.json Felder, die die Discovery beeinflussen

Einige Metadaten für die Zeit vor der Runtime liegen absichtlich in der package.json im openclaw-Block statt in der openclaw.plugin.json.

Wichtige Beispiele:

Feld	Bedeutung
openclaw.extensions	Deklariert native Plugin-Entrypoints.
openclaw.setupEntry	Leichtgewichtiger Entrypoint nur für das Setup, der beim Onboarding und verzögerten Channel-Start genutzt wird.
openclaw.channel	Einfache Metadaten für den Channel-Katalog wie Labels, Docs-Pfade, Aliase und Texte für die Auswahl.
openclaw.channel.configuredState	Metadaten für einen leichtgewichtigen Checker, der prüft, ob eine Umgebungskonfiguration existiert, ohne die volle Runtime zu laden.
openclaw.channel.persistedAuthState	Metadaten für einen leichtgewichtigen Checker, der prüft, ob jemand angemeldet ist, ohne die volle Runtime zu laden.
openclaw.install.npmSpec / openclaw.install.localPath	Hinweise für Installation und Updates von gebündelten oder extern veröffentlichten Plugins.
openclaw.install.defaultChoice	Bevorzugter Installationspfad, wenn mehrere Quellen verfügbar sind.
openclaw.install.minHostVersion	Minimale unterstützte OpenClaw-Host-Version (Semver-Format wie >=2026.3.22).
openclaw.install.allowInvalidConfigRecovery	Ermöglicht eine Wiederherstellung bei der Neuinstallation von gebündelten Plugins, wenn die Konfiguration ungültig ist.
openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen	Erlaubt es, Setup-Oberflächen vor dem eigentlichen Channel-Plugin beim Start zu laden.

Das Feld openclaw.install.minHostVersion wird während der Installation und beim Laden der Manifest-Registry geprüft. Ungültige Werte werden abgelehnt. Wenn ein Wert gültig, aber zu neu ist, wird das Plugin auf älteren Hosts übersprungen.

Die Option openclaw.install.allowInvalidConfigRecovery ist bewusst eng gefasst. Sie macht kaputte Konfigurationen nicht einfach installierbar. Aktuell hilft sie nur dabei, Fehler bei Upgrades von gebündelten Plugins zu beheben, etwa bei fehlenden Pfaden oder veralteten channels.<id> Einträgen für dasselbe Plugin. Andere Konfigurationsfehler blockieren weiterhin die Installation und verweisen auf openclaw doctor --fix.

openclaw.channel.persistedAuthState sind Paket-Metadaten für ein winziges Checker-Modul:

{
  "openclaw": {
    "channel": {
      "id": "whatsapp",
      "persistedAuthState": {
        "specifier": "./auth-presence",
        "exportName": "hasAnyWhatsAppAuth"
      }
    }
  }
}

Nutze das, wenn Setup- und Doctor-Flows oder Abfragen zum Configured-State eine schnelle Ja/Nein-Abfrage zum Auth-Status brauchen, bevor das komplette Channel-Plugin geladen wird. Der Export sollte eine kleine Funktion sein, die nur den gespeicherten Status liest. Leite das nicht durch die gesamte Runtime des Channels.

openclaw.channel.configuredState funktioniert nach dem gleichen Prinzip für schnelle Checks der Umgebung:

{
  "openclaw": {
    "channel": {
      "id": "telegram",
      "configuredState": {
        "specifier": "./configured-state",
        "exportName": "hasTelegramConfiguredState"
      }
    }
  }
}

Verwende dies, wenn ein Channel den Status aus Umgebungsvariablen oder anderen kleinen Inputs ohne Runtime ermitteln kann. Falls der Check eine vollständige Konfigurationsauflösung oder die echte Channel-Runtime benötigt, behalte die Logik stattdessen im config.hasConfiguredState Hook des Plugins.

JSON Schema Anforderungen

• Jedes Plugin muss ein JSON Schema mitliefern (auch leere Schemas wie { "type": "object", "additionalProperties": false } sind erlaubt).
• Die Validierung der Schemas erfolgt beim Lesen oder Schreiben der Konfiguration, nicht erst zur Runtime.

Validierungsverhalten

• Unbekannte channels.* Keys werden als Fehler gewertet, es sei denn, die Plugin-ID ist in einem Plugin-Manifest deklariert.
• plugins.entries.<id>, plugins.allow, plugins.deny und plugins.slots.* müssen auf auffindbare Plugin-IDs verweisen. Unbekannte IDs führen zu Fehlern.
• Falls ein Plugin installiert ist, aber ein fehlerhaftes oder fehlendes Manifest oder Schema hat, schlägt die Validierung fehl und Doctor meldet den Plugin-Fehler.
• Wenn eine Plugin-Konfiguration existiert, das Plugin aber deaktiviert ist, bleibt die Konfiguration erhalten und eine Warnung wird in Doctor und den Logs ausgegeben.

Schau dir die Konfigurations-Referenz für das vollständige plugins.* Schema an.

Hinweise

• Das Manifest ist für native OpenClaw-Plugins erforderlich, das gilt auch für das Laden aus dem lokalen Dateisystem.
• Die Runtime lädt das Plugin-Modul weiterhin separat; das Manifest dient nur der Discovery und Validierung.
• Native Manifeste werden mit JSON5 geparst. Kommentare, Trailing Commas und Keys ohne Anführungszeichen sind also erlaubt, solange das Endergebnis ein Objekt ist.
• Nur dokumentierte Manifest-Felder werden vom Manifest-Loader gelesen. Du solltest hier keine eigenen Top-Level-Keys hinzufügen.
• providerAuthEnvVars ist der effiziente Metadaten-Pfad für Auth-Probes, Env-Marker-Validierung und ähnliche Oberflächen. So muss die Plugin-Runtime nicht extra starten, nur um Env-Namen zu prüfen.
• providerAuthAliases erlaubt es Provider-Varianten, Auth-Env-Variablen, Profile oder Konfigurationen eines anderen Providers zu nutzen, ohne diese Verbindung im Core fest zu verdrahten.
• channelEnvVars ist der Metadaten-Pfad für Shell-Env-Fallbacks, Setup-Prompts und ähnliche Channel-Bereiche, damit die Plugin-Runtime nicht für einfache Namens-Checks booten muss.
• providerAuthChoices dient als Metadaten-Pfad für Auth-Auswahllisten, die --auth-choice Auflösung und das Mapping bevorzugter Provider vor dem Laden der Runtime. Für Metadaten, die Provider-Code benötigen, schau dir die Provider-Runtime-Hooks an.
• Exklusive Plugin-Typen werden über plugins.slots.* ausgewählt.
  • kind: "memory" wird durch plugins.slots.memory bestimmt.
  • kind: "context-engine" wird durch plugins.slots.contextEngine bestimmt (Standard: built-in legacy).
• channels, providers, cliBackends und skills kannst du weglassen, wenn dein Plugin diese nicht benötigt.
• Falls dein Plugin von nativen Modulen abhängt, dokumentiere die Build-Schritte und Anforderungen an die Allowlist des Package-Managers (zum Beispiel pnpm allow-build-scripts - pnpm rebuild <package>).

Verwandte Themen

• Plugins erstellen – Erste Schritte mit Plugins
• Plugin-Architektur – Interne Architektur
• SDK-Übersicht – Plugin-SDK-Referenz
• AI Setup Assistant

{
  "commandAliases": [
    {
      "name": "dreaming",
      "kind": "runtime-slash",
      "cliCommand": "memory"
    }
  ]
}

{
  "uiHints": {
    "apiKey": {
      "label": "API key",
      "help": "Used for OpenRouter requests",
      "placeholder": "sk-or-v1-...",
      "sensitive": true
    }
  }
}

{
  "contracts": {
    "speechProviders": ["openai"],
    "realtimeTranscriptionProviders": ["openai"],
    "realtimeVoiceProviders": ["openai"],
    "mediaUnderstandingProviders": ["openai", "openai-codex"],
    "imageGenerationProviders": ["openai"],
    "videoGenerationProviders": ["qwen"],
    "webFetchProviders": ["firecrawl"],
    "webSearchProviders": ["gemini"],
    "tools": ["firecrawl_search", "firecrawl_scrape"]
  }
}