​

Plugin-Manifest (openclaw.plugin.json)

• Codex-Bundle: .codex-plugin/plugin.json
• Claude-Bundle: .claude-plugin/plugin.json oder das standardmäßige Claude-Komponenten- Layout ohne Manifest
• Cursor-Bundle: .cursor-plugin/plugin.json

​

Was diese Datei macht

• Plugin-Identität
• Konfigurationsvalidierung
• Auth- und Onboarding-Metadaten, die verfügbar sein sollen, ohne die Plugin- Runtime zu starten
• kostengünstige Aktivierungshinweise, die Control-Plane-Oberflächen vor dem Laden der Runtime prüfen können
• kostengünstige Setup-Deskriptoren, die Setup-/Onboarding-Oberflächen vor dem Laden der Runtime prüfen können
• Alias- und Auto-Enable-Metadaten, die aufgelöst werden sollen, bevor die Plugin-Runtime lädt
• Kurzform-Metadaten zur Eigentümerschaft von Modellfamilien, die das Plugin vor dem Laden der Runtime automatisch aktivieren sollen
• statische Snapshots der Fähigkeits-Eigentümerschaft, die für gebündelte Compat- Verdrahtung und Vertragsabdeckung verwendet werden
• kostengünstige QA-Runner-Metadaten, die der gemeinsame Host openclaw qa vor dem Laden der Plugin-Runtime prüfen kann
• channelspezifische Konfigurationsmetadaten, die in Katalog- und Validierungsoberflächen zusammengeführt werden sollen, ohne die Runtime zu laden
• Hinweise für die Konfigurations-UI

• das Registrieren von Runtime-Verhalten
• das Deklarieren von Code-Einstiegspunkten
• npm-Installationsmetadaten

​

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-"]
  },
  "providerEndpoints": [
    {
      "endpointClass": "xai-native",
      "hosts": ["api.x.ai"]
    }
  ],
  "cliBackends": ["openrouter-cli"],
  "syntheticAuthRefs": ["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 Felder auf oberster Ebene

​

Referenz für providerAuthChoices

​

Referenz für commandAliases

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

​

Referenz für activation

​

Referenz für qaRunners

{
  "qaRunners": [
    {
      "commandName": "matrix",
      "description": "Run the Docker-backed Matrix live QA lane against a disposable homeserver"
    }
  ]
}

{
  "activation": {
    "onProviders": ["openai"],
    "onCommands": ["models"],
    "onChannels": ["web"],
    "onRoutes": ["gateway-webhook"],
    "onCapabilities": ["provider", "tool"]
  }
}

• CLI-Planung, die durch Befehle ausgelöst wird, greift als Fallback auf commandAliases[].cliCommand oder commandAliases[].name zurück
• setup-/channel-Planung, die durch Channels ausgelöst wird, greift als Fallback auf die veraltete Eigentümerschaft channels[] zurück, wenn explizite Channel-Aktivierungsmetadaten fehlen
• setup-/runtime-Planung, die durch Provider ausgelöst wird, greift als Fallback auf die veraltete Eigentümerschaft providers[] und die Top-Level-Eigentümerschaft cliBackends[] zurück, wenn explizite Provider-Aktivierungsmetadaten fehlen

​

Referenz für setup

{
  "setup": {
    "providers": [
      {
        "id": "openai",
        "authMethods": ["api-key"],
        "envVars": ["OPENAI_API_KEY"]
      }
    ],
    "cliBackends": ["openai-cli"],
    "configMigrations": ["legacy-openai-auth"],
    "requiresRuntime": false
  }
}

​

Referenz für setup.providers

​

setup-Felder

​

Referenz für uiHints

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

​

Referenz für contracts

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

​

Referenz für mediaUnderstandingProviderMetadata

{
  "contracts": {
    "mediaUnderstandingProviders": ["example"]
  },
  "mediaUnderstandingProviderMetadata": {
    "example": {
      "capabilities": ["image", "audio"],
      "defaultModels": {
        "image": "example-vision-latest",
        "audio": "example-transcribe-latest"
      },
      "autoPriority": {
        "image": 40
      },
      "nativeDocumentInputs": ["pdf"]
    }
  }
}

​

Referenz für channelConfigs

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

​

Referenz für modelSupport

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

• explizite Referenzen provider/model verwenden die Manifest-Metadaten der zugehörigen providers
• modelPatterns haben Vorrang vor modelPrefixes
• wenn sowohl ein nicht gebündeltes Plugin als auch ein gebündeltes Plugin übereinstimmen, gewinnt das nicht gebündelte Plugin
• verbleibende Mehrdeutigkeit wird ignoriert, bis der Nutzer oder die Konfiguration einen Provider angibt

​

Manifest im Vergleich zu package.json

• wenn OpenClaw es kennen muss, bevor Plugin-Code geladen wird, gehört es in openclaw.plugin.json
• wenn es um Packaging, Entry-Dateien oder das npm-Installationsverhalten geht, gehört es in package.json

​

package.json-Felder, die Discovery beeinflussen

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

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

​

Discovery-Priorität (doppelte Plugin-IDs)

1. Per Konfiguration ausgewählt — ein Pfad, der explizit in plugins.entries.<id> festgelegt ist
2. Gebündelt — Plugins, die mit OpenClaw ausgeliefert werden
3. Globale Installation — Plugins, die in den globalen OpenClaw-Plugin-Root installiert sind
4. Workspace — Plugins, die relativ zum aktuellen Workspace erkannt werden

• Eine geforkte oder veraltete Kopie eines gebündelten Plugins im Workspace überschattet den gebündelten Build nicht.
• Um ein gebündeltes Plugin tatsächlich mit einem lokalen zu überschreiben, pinne es über plugins.entries.<id>, damit es über die Priorität gewinnt, statt dich auf Workspace-Discovery zu verlassen.
• Verworfene Duplikate werden protokolliert, damit Doctor und Startdiagnosen auf die verworfene Kopie hinweisen können.

​

JSON-Schema-Anforderungen

• Jedes Plugin muss ein JSON-Schema bereitstellen, auch wenn es keine Konfiguration akzeptiert.
• Ein leeres Schema ist zulässig (zum Beispiel { "type": "object", "additionalProperties": false }).
• Schemata werden beim Lesen/Schreiben der Konfiguration validiert, nicht zur Runtime.

​

Validierungsverhalten

• Unbekannte Schlüssel in channels.* sind Fehler, außer die Channel-ID wird von einem Plugin-Manifest deklariert.
• plugins.entries.<id>, plugins.allow, plugins.deny und plugins.slots.* müssen auf erkennbare Plugin-IDs verweisen. Unbekannte IDs sind Fehler.
• Wenn ein Plugin installiert ist, aber ein defektes 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 in Doctor + Logs wird eine Warnung angezeigt.

​

Hinweise

• Das Manifest ist für native OpenClaw Plugins erforderlich, einschließlich lokaler Dateisystem-Ladevorgänge.
• Die Runtime lädt das Plugin-Modul weiterhin separat; das Manifest ist nur für Discovery + Validierung vorgesehen.
• Native Manifeste werden mit JSON5 geparst, daher sind Kommentare, nachgestellte Kommas und nicht in Anführungszeichen gesetzte Schlüssel zulässig, solange der endgültige Wert weiterhin ein Objekt ist.
• Nur dokumentierte Manifest-Felder werden vom Manifest-Loader gelesen. Vermeide es, hier benutzerdefinierte Top-Level-Schlüssel hinzuzufügen.
• providerAuthEnvVars ist der kostengünstige Metadatenpfad für Auth-Prüfungen, Env-Marker-Validierung und ähnliche Provider-Auth-Oberflächen, die die Plugin- Runtime nicht starten sollten, nur um env-Namen zu prüfen.
• providerAuthAliases erlaubt Provider-Varianten, die Auth-Umgebungsvariablen, Auth-Profile, konfigurationsgestützte Authentifizierung und die API-Key- Onboarding-Auswahl eines anderen Providers wiederzuverwenden, ohne diese Beziehung im Core fest zu codieren.
• providerEndpoints erlaubt Provider-Plugins, einfache Matching-Metadaten für Endpoint-Hosts/baseUrl zu besitzen. Verwende es nur für Endpoint-Klassen, die der Core bereits unterstützt; das Plugin besitzt weiterhin das Runtime-Verhalten.
• syntheticAuthRefs ist der kostengünstige Metadatenpfad für Plugin-eigene Synthetic-Auth-Hooks, die für kalte Modell-Discovery sichtbar sein müssen, bevor die Runtime-Registry existiert. Führe nur Referenzen auf, deren Runtime- Provider oder CLI-Backend tatsächlich resolveSyntheticAuth implementiert.
• nonSecretAuthMarkers ist der kostengünstige Metadatenpfad für Platzhalter- API-Keys, die gebündelten Plugins gehören, wie Marker für lokale, OAuth- oder ambiente Zugangsdaten. Der Core behandelt diese für die Auth-Anzeige und Secret-Audits als nicht geheim, ohne den zugehörigen Provider fest zu codieren.
• channelEnvVars ist der kostengünstige Metadatenpfad für Shell-env-Fallback, Setup-Prompts und ähnliche Channel-Oberflächen, die die Plugin-Runtime nicht starten sollten, nur um env-Namen zu prüfen. Env-Namen sind Metadaten, nicht selbst eine Aktivierung: Status, Audit, Cron-Zustellungsvalidierung und andere schreibgeschützte Oberflächen wenden weiterhin Plugin-Vertrauen und effektive Aktivierungsrichtlinien an, bevor sie eine env-Variable als konfigurierten Channel behandeln.
• providerAuthChoices ist der kostengünstige Metadatenpfad für Auth-Auswahlfelder, die Auflösung von --auth-choice, bevorzugte Provider-Zuordnung und einfache Registrierung von CLI-Flags für das Onboarding, bevor die Provider-Runtime lädt. Für Metadaten von Runtime-Assistenten, die Provider-Code erfordern, siehe Provider-Runtime-Hooks.
• Exklusive Plugin-Arten werden über plugins.slots.* ausgewählt.
  • kind: "memory" wird über plugins.slots.memory ausgewählt.
  • kind: "context-engine" wird über plugins.slots.contextEngine ausgewählt (Standard: eingebautes legacy).
• channels, providers, cliBackends und skills können weggelassen werden, wenn ein Plugin sie nicht benötigt.
• Wenn dein Plugin von nativen Modulen abhängt, dokumentiere die Build-Schritte und alle Anforderungen an Allowlists des Paketmanagers (zum Beispiel pnpm allow-build-scripts
  • pnpm rebuild <package>).

​

Verwandt

• Plugins erstellen — Einstieg in Plugins
• Plugin-Architektur — interne Architektur
• SDK-Überblick — Referenz zum Plugin SDK