Plugin-Manifest

Diese Seite behandelt das native OpenClaw-Plugin-Manifest, openclaw.plugin.json. Informationen zu kompatiblen Bundle-Layouts (Codex, Claude, Cursor) finden Sie unter Plugin-Bundles.

Kompatible Bundle-Formate verwenden stattdessen eigene Manifestdateien:

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

OpenClaw erkennt diese Layouts automatisch, validiert sie jedoch nicht anhand des unten aufgeführten openclaw.plugin.json-Schemas. Bei einem kompatiblen Bundle liest OpenClaw Bundle-Metadaten, deklarierte Skill-Stammverzeichnisse, Claude-Befehlsstammverzeichnisse, Claude-settings.json-Standardwerte, Claude-LSP-Standardwerte und unterstützte Hook-Pakete, sofern das Layout den Laufzeiterwartungen von OpenClaw entspricht.

Jedes native OpenClaw-Plugin muss openclaw.plugin.json im Plugin-Stammverzeichnis enthalten. OpenClaw liest diese Datei, um die Konfiguration ohne Ausführung des Plugin-Codes zu validieren. Ein fehlendes oder ungültiges Manifest verhindert die Konfigurationsvalidierung und wird als Plugin-Fehler behandelt.

Den vollständigen Leitfaden zum Plugin-System finden Sie unter Plugins, Informationen zum nativen Capability-Modell und zur aktuellen Kompatibilität mit externen Formaten unter Capability-Modell.

Zweck dieser Datei

openclaw.plugin.json enthält Metadaten, die OpenClaw vor dem Laden Ihres Plugin-Codes liest. Alle enthaltenen Informationen müssen sich ohne Starten der Plugin-Laufzeitumgebung mit geringem Aufwand prüfen lassen.

Verwenden Sie die Datei für:

• Plugin-Identität, Konfigurationsvalidierung und Hinweise für die Konfigurationsoberfläche
• Metadaten für Authentifizierung, Onboarding und Einrichtung (Alias, automatische Aktivierung, Provider-Umgebungsvariablen, Authentifizierungsoptionen)
• Aktivierungshinweise für Control-Plane-Oberflächen
• Zuordnung abgekürzter Modellfamilien
• statische Snapshots der Capability-Zuständigkeit (contracts)
• Datenbindungen und Aktionsverben für Dashboard-Widgets
• statische MCP-Server, die verfügbar sein sollen, während das Plugin aktiviert ist
• QA-Runner-Metadaten, die der gemeinsame openclaw qa-Host prüfen kann
• kanalspezifische Konfigurationsmetadaten, die in Katalog- und Validierungsoberflächen zusammengeführt werden

Verwenden Sie die Datei nicht für: die Registrierung nativer Laufzeit-Hooks, die Deklaration von Einstiegspunkten für Plugin-Code oder npm-Installationsmetadaten. Diese gehören in Ihren Plugin-Code und in 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-"]  },  "modelIdNormalization": {    "providers": {      "openrouter": {        "prefixWhenBare": "openrouter"      }    }  },  "providerEndpoints": [    {      "endpointClass": "openrouter",      "hostSuffixes": ["openrouter.ai"]    }  ],  "providerRequest": {    "providers": {      "openrouter": {        "family": "openrouter"      }    }  },  "cliBackends": ["openrouter-cli"],  "syntheticAuthRefs": ["openrouter-cli"],  "setup": {    "providers": [      {        "id": "openrouter",        "envVars": ["OPENROUTER_API_KEY"]      }    ]  },  "providerAuthAliases": {    "openrouter-coding": "openrouter"  },  "providerAuthChoices": [    {      "provider": "openrouter",      "method": "api-key",      "choiceId": "openrouter-api-key",      "choiceLabel": "OpenRouter-API-Schlüssel",      "groupId": "openrouter",      "groupLabel": "OpenRouter",      "optionKey": "openrouterApiKey",      "cliFlag": "--openrouter-api-key",      "cliOption": "--openrouter-api-key <key>",      "cliDescription": "OpenRouter-API-Schlüssel",      "onboardingScopes": ["text-inference"]    }  ],  "uiHints": {    "apiKey": {      "label": "API-Schlüssel",      "placeholder": "sk-or-v1-...",      "sensitive": true    }  },  "configSchema": {    "type": "object",    "additionalProperties": false,    "properties": {      "apiKey": {        "type": "string"      }    }  }}

Referenz der Felder auf oberster Ebene

MCP-Server-Referenz

mcpServers ermöglicht es einem nativen Plugin, einen MCP-Server einschließlich einer MCP App bereitzustellen, ohne dass Betreiber dessen statische Prozessdefinition in openclaw.json duplizieren müssen:

{  "mcpServers": {    "example": {      "transport": "stdio",      "command": "node",      "args": ["./mcp-server.js"]    }  }}

OpenClaw bindet diese Server nur ein, solange das besitzende Plugin aktiviert ist. Relative Pfade für command, args, cwd und workingDirectory werden vom Plugin-Stammverzeichnis aus aufgelöst. Die Benutzerkonfiguration bleibt maßgeblich: mcp.servers.<name> kann einen Plugin-Standardwert ersetzen oder enabled: false festlegen, um ihn auszulassen. Das Rendern von MCP Apps und Aufrufe von Server-Tools erfordern weiterhin die normale MCP-Apps-Einstellung und die wirksame Tool-Richtlinie; die Deklaration eines Servers umgeht keine dieser beiden Grenzen.

Dashboard-Referenz

dashboard ermöglicht es einem aktivierten Plugin, vorhandene Gateway-RPCs für berechtigte Dashboard-Widgets verfügbar zu machen, ohne Plugin-Richtlinien zum Kern hinzuzufügen. Datenbindungen müssen eine Methode benennen, die dasselbe Plugin mit operator.read registriert; Aktionsverben müssen eine Methode benennen, die es mit operator.write registriert. Bei einer Abweichung wird das Plugin während der Registrierung abgelehnt.

{  "dashboard": {    "dataBindings": [      {        "id": "items.list",        "method": "example.items.list",        "description": "Beispielelemente auflisten."      }    ],    "actionVerbs": [      {        "id": "refresh",        "method": "example.items.refresh",        "description": "Beispielelemente aktualisieren.",        "paramShape": {          "type": "object",          "additionalProperties": false,          "properties": {            "force": { "type": "boolean" }          }        }      }    ]  }}

Die Manifest-IDs sind Plugin-lokal. Widget-Berechtigungen verwenden <plugin-id>.<id>, beispielsweise example.items.list und example.refresh. Damit der persistierte Berechtigungsnamensraum eindeutig bleibt, maskiert OpenClaw % und . im Plugin-ID-Segment als %25 und %2E; gewöhnliche Plugin-IDs behalten die natürliche Form. paramShape ist ein optionales JSON Schema, das auf das Aktionsparameterobjekt angewendet wird, bevor OpenClaw den Plugin-RPC aufruft.

Katalogreferenz

catalog stellt optionale Anzeigehinweise für Plugin-Browser bereit. Hosts können diese Hinweise ignorieren. Sie installieren oder aktivieren das Plugin niemals und ändern weder dessen Laufzeitverhalten noch dessen Vertrauensstufe.

{  "catalog": {    "featured": true,    "order": 10  }}

Referenz für Metadaten von Generierungs-Providern

Die Metadatenfelder für Generierungs-Provider beschreiben statische Authentifizierungssignale für Provider, die in der entsprechenden Liste contracts.*GenerationProviders deklariert sind. OpenClaw liest diese Felder, bevor die Provider-Laufzeit geladen wird, sodass Kern-Tools entscheiden können, ob ein Generierungs-Provider verfügbar ist, ohne jedes Provider-Plugin zu importieren.

Verwenden Sie diese Felder nur für kostengünstig ermittelbare, deklarative Fakten. Transport, Anfragetransformationen, Token-Aktualisierung, Anmeldedatenvalidierung und das eigentliche Generierungsverhalten verbleiben in der Plugin-Laufzeit.

{  "contracts": {    "imageGenerationProviders": ["example-image"]  },  "imageGenerationProviderMetadata": {    "example-image": {      "aliases": ["example-image-oauth"],      "authProviders": ["example-image"],      "configSignals": [        {          "rootPath": "plugins.entries.example-image.config",          "overlayPath": "image",          "mode": {            "path": "mode",            "default": "local",            "allowed": ["local"]          },          "requiredAny": ["workflow", "workflowPath"],          "required": ["promptNodeId"]        }      ],      "authSignals": [        {          "provider": "example-image"        },        {          "provider": "example-image-oauth",          "providerBaseUrl": {            "provider": "example-image",            "defaultBaseUrl": "https://api.example.com/v1",            "allowedBaseUrls": ["https://api.example.com/v1"]          }        }      ]    }  }}

Jeder Metadateneintrag unterstützt:

Jeder configSignals-Eintrag unterstützt:

Jeder mode-Wächter unterstützt:

Jeder authSignals-Eintrag unterstützt:

Jeder providerBaseUrl-Wächter unterstützt:

Referenz für Tool-Metadaten

toolMetadata verwendet dieselben Strukturen configSignals und authSignals wie die Metadaten von Generierungs-Providern, jeweils nach Tool-Name indiziert. contracts.tools deklariert die Zuständigkeit. toolMetadata deklariert kostengünstig ermittelbare Verfügbarkeitsnachweise, sodass OpenClaw vermeiden kann, eine Plugin-Laufzeit nur deshalb zu importieren, damit deren Tool-Factory null zurückgibt.

{  "setup": {    "providers": [      {        "id": "example",        "envVars": ["EXAMPLE_API_KEY"]      }    ]  },  "contracts": {    "tools": ["example_search"]  },  "toolMetadata": {    "example_search": {      "authSignals": [        {          "provider": "example"        }      ],      "configSignals": [        {          "rootPath": "plugins.entries.example.config",          "overlayPath": "search",          "required": ["apiKey"]        }      ]    }  }}

toolMetadata-Einträge akzeptieren zusätzlich optional (kennzeichnet das Tool als nicht erforderlich für die Plugin-Aktivierung) und replaySafe (kennzeichnet die Tool-Ausführung als sicher wiederholbar nach einem unvollständigen Modell-Durchlauf), ergänzend zu den oben genannten gemeinsamen Feldern configSignals/authSignals.

Wenn ein Tool kein toolMetadata besitzt, behält OpenClaw das bestehende Verhalten bei und lädt das zugehörige Plugin, wenn der Tool-Vertrag der Richtlinie entspricht. Bei Tools im kritischen Ausführungspfad, deren Factory von Authentifizierung/Konfiguration abhängt, sollten Plugin-Autoren toolMetadata deklarieren, statt Core die Runtime importieren zu lassen, um sie abzufragen.

Referenz zu providerAuthChoices

Jeder providerAuthChoices-Eintrag beschreibt eine Onboarding- oder Authentifizierungsoption. OpenClaw liest diesen Eintrag, bevor die Provider-Runtime geladen wird. Listen für die Provider-Einrichtung verwenden diese Manifestoptionen, aus Deskriptoren abgeleitete Einrichtungsoptionen und Metadaten des Installationskatalogs, ohne die Provider-Runtime zu laden.

Wenn appGuidedDiscovery wahr ist, muss die entsprechende Provider-Authentifizierungsmethode appGuidedSetup.detect und appGuidedSetup.prepare bereitstellen. Die Erkennung muss schreibgeschützt sein: keine Anmeldung, kein Modellabruf, kein Download und kein Schreiben der Konfiguration. Die Vorbereitung prüft das exakt ausgewählte Modell erneut und gibt einen Konfigurationsvorschlag zurück; OpenClaw testet diesen Vorschlag isoliert im Live-Betrieb und übernimmt ihn erst nach erfolgreichem Abschluss.

Referenz zu commandAliases

Verwenden Sie commandAliases, wenn ein Plugin einen Runtime-Befehlsnamen besitzt, den Benutzer irrtümlicherweise in plugins.allow eintragen oder als Root-CLI-Befehl ausführen könnten. OpenClaw verwendet diese Metadaten für die Diagnose, ohne den Runtime-Code des Plugins zu importieren.

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

Referenz zur Aktivierung

Verwenden Sie activation, wenn das Plugin mit geringem Aufwand deklarieren kann, bei welchen Steuerungsebenenereignissen es in einen Aktivierungs-/Ladeplan aufgenommen werden soll.

Dieser Block enthält Planer-Metadaten und ist keine Lebenszyklus-API. Er registriert kein Runtime-Verhalten, ersetzt register(...) nicht und garantiert nicht, dass Plugin-Code bereits ausgeführt wurde. Der Aktivierungsplaner verwendet diese Felder, um die infrage kommenden Plugins einzugrenzen, bevor er auf bestehende Manifest-Metadaten zur Zuständigkeit wie providers, channels, commandAliases, setup.providers, contracts.tools und Hooks zurückgreift.

Bevorzugen Sie die engsten Metadaten, die die Zuständigkeit bereits beschreiben. Verwenden Sie providers, channels, commandAliases, Einrichtungsdeskriptoren oder contracts, wenn diese Felder die Beziehung ausdrücken. Verwenden Sie activation für zusätzliche Planerhinweise, die nicht durch diese Zuständigkeitsfelder dargestellt werden können. Verwenden Sie cliBackends auf oberster Ebene für CLI-Runtime-Aliasse wie claude-cli, my-cli oder google-gemini-cli; activation.onAgentHarnesses ist ausschließlich für eingebettete Agent-Harness-IDs vorgesehen, die noch kein Zuständigkeitsfeld besitzen.

Jedes Plugin sollte activation.onStartup bewusst festlegen. Setzen Sie den Wert nur dann auf true, wenn das Plugin während des Gateway-Starts ausgeführt werden muss. Setzen Sie ihn auf false, wenn das Plugin beim Start inaktiv ist und nur durch engere Auslöser geladen werden soll. Wenn onStartup fehlt, wird das Plugin nicht mehr implizit beim Start geladen; verwenden Sie explizite Aktivierungsmetadaten für Start-, Kanal-, Konfigurations-, Agent-Harness-, Speicher- oder andere engere Aktivierungsauslöser.

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

Aktuelle aktive Verbraucher:

• Die Gateway-Startplanung verwendet activation.onStartup für den expliziten Import beim Start.
• Die befehlsausgelöste CLI-Planung greift auf das veraltete commandAliases[].cliCommand oder commandAliases[].name zurück.
• Die Startplanung der Agent-Laufzeit verwendet activation.onAgentHarnesses für eingebettete Harnesses und cliBackends[] auf oberster Ebene für CLI-Laufzeit-Aliasse.
• Die kanalbezogene Einrichtungs-/Kanalplanung greift auf die veraltete Eigentümerschaft gemäß channels[] zurück, wenn explizite Metadaten zur Kanalaktivierung fehlen.
• Die Plugin-Planung beim Start verwendet activation.onConfigPaths für kanalunabhängige Stammkonfigurationsoberflächen wie den Block browser des gebündelten Browser-Plugins.
• Die providerausgelöste Einrichtungs-/Laufzeitplanung greift auf die veraltete Eigentümerschaft gemäß providers[] und cliBackends[] auf oberster Ebene zurück, wenn explizite Metadaten zur Provider-Aktivierung fehlen.

Planerdiagnosen können explizite Aktivierungshinweise von einem Rückgriff auf die Manifest-Eigentümerschaft unterscheiden. Beispielsweise bedeutet activation-command-hint, dass activation.onCommands übereinstimmte, während manifest-command-alias bedeutet, dass der Planer stattdessen die Eigentümerschaft gemäß commandAliases verwendete. Diese Begründungsbezeichnungen dienen Hostdiagnosen und Tests; Plugin-Autoren sollten weiterhin die Metadaten deklarieren, die die Eigentümerschaft am besten beschreiben.

qaRunners-Referenz

Verwenden Sie qaRunners, wenn ein Plugin einen oder mehrere Transport-Runner unterhalb des gemeinsamen Stamms openclaw qa bereitstellt. Halten Sie diese Metadaten schlank und statisch; die Plugin- Laufzeit ist weiterhin für die eigentliche CLI-Registrierung über eine leichtgewichtige runtime-api.ts-Oberfläche zuständig, die passende qaRunnerCliRegistrations exportiert. Ein optionales adapterFactory stellt den Transport gemeinsamen QA-Szenarien bereit, ohne den Runner des registrierten Befehls zu ändern.

{  "qaRunners": [    {      "commandName": "matrix",      "description": "Die Docker-gestützte Matrix-Live-QA-Spur gegen einen temporären Homeserver ausführen"    }  ]}

Die ID adapterFactory muss mit commandName übereinstimmen. Exportieren Sie keine Registrierungen für Befehle, die nicht im Manifest enthalten sind.

setup-Referenz

Verwenden Sie setup, wenn Einrichtungs- und Onboarding-Oberflächen schlanke Plugin-eigene Metadaten benötigen, bevor die Laufzeit geladen wird.

{  "setup": {    "providers": [      {        "id": "openai",        "authMethods": ["api-key"],        "envVars": ["OPENAI_API_KEY"],        "authEvidence": [          {            "type": "local-file-with-env",            "fileEnvVar": "OPENAI_CREDENTIALS_FILE",            "requiresAllEnv": ["OPENAI_PROJECT"],            "credentialMarker": "openai-local-credentials",            "source": "lokale OpenAI-Anmeldedaten"          }        ]      }    ],    "cliBackends": ["openai-cli"],    "configMigrations": ["legacy-openai-auth"],    "requiresRuntime": false  }}

cliBackends auf oberster Ebene bleibt gültig und beschreibt weiterhin CLI-Inferenz-Backends. setup.cliBackends ist die einrichtungsspezifische Deskriptoroberfläche für Steuerungsebenen-/Einrichtungsabläufe, die ausschließlich auf Metadaten basieren sollten.

Sofern vorhanden, sind setup.providers und setup.cliBackends die bevorzugte Deskriptor-zuerst-Nachschlageoberfläche für die Einrichtungserkennung. Wenn der Deskriptor lediglich das infrage kommende Plugin eingrenzt und die Einrichtung weiterhin umfangreichere Laufzeit-Hooks zur Einrichtungszeit benötigt, legen Sie requiresRuntime: true fest und behalten Sie setup-api als Ausweich-Ausführungspfad bei.

OpenClaw bezieht setup.providers[].envVars in generische Nachschlagevorgänge für Provider-Authentifizierung und Umgebungsvariablen ein. Hinterlegen Sie dort Umgebungsmetadaten für Einrichtung und Status.

Verwenden Sie providerUsageAuthEnvVars, wenn Anmeldedaten auf Abrechnungs- oder Organisationsebene resolveUsageAuth aktivieren müssen, ohne zu Inferenz-Anmeldedaten zu werden. Diese Namen werden in die Blockierung von Workspace-Dotenv-Werten, die Bereinigung von ACP-Unterprozessen, die Sandbox-Filterung von Geheimnissen und die allgemeine Bereinigung von Geheimnissen aufgenommen. Die Provider-Laufzeit liest und klassifiziert den Wert weiterhin innerhalb von resolveUsageAuth.

OpenClaw kann außerdem einfache Einrichtungsoptionen aus setup.providers[].authMethods ableiten, wenn kein Einrichtungseintrag verfügbar ist oder wenn setup.requiresRuntime: false angibt, dass keine Einrichtungslaufzeit erforderlich ist. Explizite providerAuthChoices-Einträge werden weiterhin für benutzerdefinierte Bezeichnungen, CLI-Flags, den Onboarding-Umfang und Assistentenmetadaten bevorzugt.

Legen Sie requiresRuntime: false nur fest, wenn diese Deskriptoren für die Einrichtungsoberfläche ausreichen. OpenClaw behandelt ein explizites false als ausschließlich deskriptorbasierten Vertrag und führt setup-api oder openclaw.setupEntry nicht für die Einrichtungssuche aus. Wenn ein ausschließlich deskriptorbasiertes Plugin dennoch einen dieser Einrichtungslaufzeit-Einträge bereitstellt, meldet OpenClaw eine zusätzliche Diagnose und ignoriert ihn weiterhin. Wird requiresRuntime weggelassen, bleibt das veraltete Rückgriffverhalten erhalten, damit vorhandene Plugins, die Deskriptoren ohne das Flag hinzugefügt haben, nicht beeinträchtigt werden.

Da die Einrichtungssuche Plugin-eigenen setup-api-Code ausführen kann, müssen normalisierte setup.providers[].id- und setup.cliBackends[]-Werte über alle erkannten Plugins hinweg eindeutig bleiben. Bei mehrdeutiger Eigentümerschaft wird der Vorgang sicher abgebrochen, anstatt anhand der Erkennungsreihenfolge einen Gewinner auszuwählen.

Wenn die Einrichtungslaufzeit ausgeführt wird, melden die Diagnosen der Einrichtungsregistrierung Deskriptorabweichungen, falls setup-api einen Provider oder ein CLI-Backend registriert, den beziehungsweise das die Manifest-Deskriptoren nicht deklarieren, oder falls für einen Deskriptor keine passende Laufzeitregistrierung vorhanden ist. Diese Diagnosen sind ergänzend und weisen veraltete Plugins nicht zurück.

setup.providers-Referenz

authEvidence ist für Provider-eigene Marker lokaler Anmeldedaten vorgesehen, die ohne Laden von Laufzeitcode überprüft werden können. Diese Prüfungen müssen schlank und lokal bleiben: keine Netzwerkaufrufe, keine Zugriffe auf Schlüsselbund oder Geheimnisverwaltung, keine Shell-Befehle und keine Abfragen der Provider-API.

Unterstützte Nachweiseinträge:

setup-Felder

Referenz zu uiHints

uiHints ist eine Zuordnung von Namen der Konfigurationsfelder zu kleinen Darstellungshinweisen. Schlüssel können Punkte für verschachtelte Konfigurationsfelder verwenden, aber kein Pfadsegment darf __proto__, constructor oder prototype lauten; die Einrichtung weist diese Namen zurück.

{  "uiHints": {    "apiKey": {      "label": "API-Schlüssel",      "help": "Wird für OpenRouter-Anfragen verwendet",      "placeholder": "sk-or-v1-...",      "sensitive": true    }  }}

Jeder Feldhinweis kann Folgendes enthalten:

Referenz zu contracts

Verwenden Sie contracts ausschließlich für statische Metadaten zur Zuständigkeit für Fähigkeiten, die OpenClaw lesen kann, ohne die Plugin-Laufzeit zu importieren.

{  "contracts": {    "agentToolResultMiddleware": ["openclaw", "codex"],    "trustedToolPolicies": ["workflow-budget"],    "externalAuthProviders": ["acme-ai"],    "embeddingProviders": ["openai-compatible"],    "speechProviders": ["openai"],    "realtimeTranscriptionProviders": ["openai"],    "realtimeVoiceProviders": ["openai"],    "memoryEmbeddingProviders": ["local"],    "mediaUnderstandingProviders": ["openai"],    "imageGenerationProviders": ["openai"],    "videoGenerationProviders": ["qwen"],    "musicGenerationProviders": ["stability-audio"],    "documentExtractors": ["example-docs"],    "webContentExtractors": ["firecrawl"],    "webFetchProviders": ["firecrawl"],    "webSearchProviders": ["gemini"],    "workerProviders": ["example-worker"],    "usageProviders": ["acme-ai"],    "migrationProviders": ["hermes"],    "gatewayMethodDispatch": ["authenticated-request"],    "tools": ["firecrawl_search", "firecrawl_scrape"]  }}

Jede Liste ist optional:

contracts.embeddedExtensionFactories bleibt für mitgelieferte Erweiterungs-Factorys erhalten, die ausschließlich für den Codex-App-Server bestimmt sind. Mitgelieferte Transformationen von Tool-Ergebnissen sollten stattdessen contracts.agentToolResultMiddleware deklarieren und sich mit api.registerAgentToolResultMiddleware(...) registrieren. Installierte Plugins dürfen dieselbe Middleware-Schnittstelle nur verwenden, wenn sie ausdrücklich aktiviert wurde, und nur für Laufzeiten, die sie in contracts.agentToolResultMiddleware deklarieren.

Installierte Plugins, die die vom Host als vertrauenswürdig eingestufte Richtlinienebene vor der Tool-Ausführung benötigen, müssen jede registrierte lokale ID in contracts.trustedToolPolicies deklarieren und ausdrücklich aktiviert werden. Mitgelieferte Plugins behalten den bestehenden Pfad für vertrauenswürdige Richtlinien bei, installierte Plugins mit nicht deklarierten Richtlinien-IDs werden jedoch vor der Registrierung zurückgewiesen. Richtlinien-IDs sind auf das registrierende Plugin beschränkt, sodass zwei Plugins jeweils workflow-budget deklarieren und registrieren dürfen; ein einzelnes Plugin darf dieselbe lokale ID nicht zweimal registrieren.

Laufzeitregistrierungen von api.registerTool(...) müssen mit contracts.tools übereinstimmen. Die Tool-Ermittlung verwendet diese Liste, um nur die Plugin-Laufzeiten zu laden, denen die angeforderten Tools gehören können.

Provider-Plugins, die resolveExternalAuthProfiles implementieren, sollten contracts.externalAuthProviders deklarieren; nicht deklarierte Hooks für externe Authentifizierung werden ignoriert.

Provider-Plugins, die sowohl resolveUsageAuth als auch fetchUsageSnapshot implementieren, sollten jede automatisch ermittelte Provider-ID in contracts.usageProviders deklarieren. Die Nutzungsermittlung liest diesen Vertrag vor dem Laden des Laufzeitcodes und überprüft anschließend beide Hooks, nachdem nur die deklarierten zuständigen Plugins geladen wurden.

Allgemeine Embedding-Provider sollten contracts.embeddingProviders für jeden mit api.registerEmbeddingProvider(...) registrierten Adapter deklarieren. Verwenden Sie den allgemeinen Vertrag für die wiederverwendbare Vektorerzeugung, einschließlich Providern, die von der Memory-Suche verwendet werden. contracts.memoryEmbeddingProviders ist eine veraltete Memory-spezifische Kompatibilität und bleibt nur bestehen, solange vorhandene Provider zur generischen Schnittstelle für Embedding-Provider migrieren.

Worker-Provider müssen jede api.registerWorkerProvider(...)-ID in contracts.workerProviders deklarieren. Core speichert die dauerhafte Absicht, bevor provision aufgerufen wird; Provider validieren ihre Einstellungen vor der externen Zuweisung, und wiederholte Aufrufe mit derselben Vorgangs-ID müssen denselben Lease übernehmen. Core speichert außerdem diese Momentaufnahme der validierten Einstellungen und übergibt sie zusammen mit leaseId an inspect({ leaseId, profile }) und destroy({ leaseId, profile }), auch nachdem das benannte Profil geändert oder entfernt wurde. Die Zerstörung ist idempotent, die Inspektion gibt die geschlossene Statusvereinigung aus active / destroyed / unknown zurück, und auf privates SSH-Schlüsselmaterial wird ausschließlich über SecretRef verwiesen. Bereitgestellte SSH-Endpunkte müssen außerdem einen öffentlichen hostKey aus einer vertrauenswürdigen Bereitstellungsausgabe exakt als algorithm base64 enthalten, ohne Hostnamen oder Kommentar, damit Core den Host vor dem Verbindungsaufbau anheften kann. Provider, die dynamische Identitätsreferenzen erzeugen, können das maßgebliche resolveSshIdentity({ leaseId, profile, keyRef }) implementieren; Provider ohne diese Implementierung verwenden den generischen Secret-Resolver von Core. Ein maßgebliches unknown verwaist einen aktiven lokalen Datensatz; nach einer gespeicherten Zerstörungsanforderung bestätigt es den Abbau.

contracts.gatewayMethodDispatch akzeptiert derzeit "authenticated-request". Es handelt sich um eine API-Hygiene-Schranke für native Plugin-HTTP-Routen, die absichtlich Gateway-Control-Plane-Methoden prozessintern aufrufen, nicht um eine Sandbox gegen bösartige native Plugins. Verwenden Sie sie nur für streng geprüfte gebündelte bzw. Operator-Oberflächen, die bereits eine Gateway-HTTP-Authentifizierung erfordern. Eine berechtigte Route bleibt bei geschlossener Gateway-Zulassung für Root-Arbeit nur erreichbar, wenn sie zusätzlich auth: "gateway" und das routenspezifische gatewayRuntimeScopeSurface: "trusted-operator" deklariert; gewöhnliche benachbarte Routen desselben Plugins bleiben hinter der Zulassungsgrenze. Dadurch bleiben der Sperrstatus und das Fortsetzen erreichbar, ohne dem gesamten Plugin eine Umgehung der Zulassung zu gewähren. Halten Sie das Parsen und die Antwortaufbereitung außerhalb des Dispatches begrenzt; wesentliche oder verändernde Arbeit muss über den Gateway-Methoden-Dispatch erfolgen, der die Zulassungs- und Bereichsdurchsetzung verantwortet.

Referenz zu configContracts

Verwenden Sie configContracts für manifestgesteuertes Konfigurationsverhalten, das generische Core-Hilfsfunktionen benötigen, ohne die Plugin-Laufzeit zu importieren: Erkennung gefährlicher Flags, SecretRef-Migrationsziele und Eingrenzung veralteter Konfigurationspfade.

{  "configContracts": {    "compatibilityMigrationPaths": ["legacyProvider"],    "compatibilityRuntimePaths": ["legacyProvider.webhook"],    "dangerousFlags": [      {        "path": "accounts.*.allowUnverifiedSenders",        "equals": true      }    ],    "secretInputs": {      "bundledDefaultEnabled": false,      "paths": [        {          "path": "routes.*.secret",          "expected": "string",          "ownerKind": "route"        }      ]    }  }}

Jeder dangerousFlags-Eintrag unterstützt:

secretInputs unterstützt:

Referenz zu mediaUnderstandingProviderMetadata

Verwenden Sie mediaUnderstandingProviderMetadata, wenn ein Provider für Medienverständnis Standardmodelle, eine Priorität für den automatischen Authentifizierungs-Fallback oder native Dokumentunterstützung besitzt, die generische Core-Hilfsfunktionen vor dem Laden der Laufzeit benötigen. Schlüssel müssen außerdem in contracts.mediaUnderstandingProviders deklariert werden.

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

Jeder Provider-Eintrag kann Folgendes enthalten:

Referenz zu channelConfigs

Verwenden Sie channelConfigs, wenn ein Kanal-Plugin kostengünstig verfügbare Konfigurationsmetadaten benötigt, bevor die Laufzeit geladen wird. Die schreibgeschützte Ermittlung von Kanaleinrichtung und -status kann diese Metadaten direkt für konfigurierte externe Kanäle verwenden, wenn kein Einrichtungseintrag verfügbar ist oder wenn setup.requiresRuntime: false erklärt, dass keine Einrichtungslaufzeit erforderlich ist.

channelConfigs sind Plugin-Manifest-Metadaten und kein neuer Konfigurationsabschnitt auf oberster Ebene für Benutzer. Benutzer konfigurieren Kanalinstanzen weiterhin unter channels.<channel-id>. OpenClaw liest die Manifest-Metadaten, um zu bestimmen, welches Plugin den konfigurierten Kanal besitzt, bevor der Plugin-Laufzeitcode ausgeführt wird.

Für ein Kanal-Plugin beschreiben configSchema und channelConfigs unterschiedliche Pfade:

• configSchema validiert plugins.entries.<plugin-id>.config
• channelConfigs.<channel-id>.schema validiert channels.<channel-id>

Nicht gebündelte Plugins, die channels[] deklarieren, sollten außerdem passende channelConfigs-Einträge deklarieren. Ohne sie kann OpenClaw das Plugin weiterhin laden, aber Konfigurationsschema-, Einrichtungs- und Control-UI-Oberflächen für den Kaltpfad können die Form der kanaleigenen Optionen oder ausschließlich zur Anzeige bestimmten UI-Hinweise erst erkennen, nachdem die Plugin-Laufzeit ausgeführt wurde.

channelConfigs.<channel-id>.commands.nativeCommandsAutoEnabled und nativeSkillsAutoEnabled können statische auto-Standardwerte für Prüfungen der Befehlskonfiguration deklarieren, die vor dem Laden der Kanallaufzeit ausgeführt werden. Gebündelte Kanäle können dieselben Standardwerte außerdem über package.json#openclaw.channel.commands zusammen mit ihren übrigen paketeigenen Kanalkatalog-Metadaten veröffentlichen.

{  "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-Verbindung",      "commands": {        "nativeCommandsAutoEnabled": true,        "nativeSkillsAutoEnabled": true      },      "preferOver": ["matrix-legacy"]    }  }}

Jeder Kanaleintrag kann Folgendes enthalten:

Ersetzen eines anderen Kanal-Plugins

Verwenden Sie preferOver, wenn Ihr Plugin der bevorzugte Eigentümer einer Kanal-ID ist, die auch von einem anderen Plugin bereitgestellt werden kann. Häufige Fälle sind eine umbenannte Plugin-ID, ein eigenständiges Plugin, das ein gebündeltes Plugin ersetzt, oder ein gepflegter Fork, der zur Konfigurationskompatibilität dieselbe Kanal-ID beibehält.

{  "id": "acme-chat",  "channels": ["chat"],  "channelConfigs": {    "chat": {      "schema": {        "type": "object",        "additionalProperties": false,        "properties": {          "webhookUrl": { "type": "string" }        }      },      "preferOver": ["chat"]    }  }}

Wenn channels.chat konfiguriert ist, berücksichtigt OpenClaw sowohl die Kanal-ID als auch die bevorzugte Plugin-ID. Wenn das Plugin mit niedrigerer Priorität nur ausgewählt wurde, weil es gebündelt oder standardmäßig aktiviert ist, deaktiviert OpenClaw es in der effektiven Laufzeitkonfiguration, sodass ein Plugin für den Kanal und dessen Tools zuständig ist. Eine explizite Benutzerauswahl hat weiterhin Vorrang: Wenn beide Plugins explizit aktiviert werden (über plugins.allow oder eine maßgebliche plugins.entries-Konfiguration), behält OpenClaw diese Auswahl bei und meldet Diagnosen zu doppelten Kanälen oder Tools, anstatt die angeforderte Plugin-Gruppe stillschweigend zu ändern.

Beschränken Sie preferOver auf Plugin-IDs, die tatsächlich denselben Kanal bereitstellen können. Es ist kein allgemeines Prioritätsfeld und benennt keine Benutzerkonfigurationsschlüssel um.

Referenz zu modelSupport

Verwenden Sie modelSupport, wenn OpenClaw Ihr Provider-Plugin anhand verkürzter Modell-IDs wie gpt-5.6-sol oder claude-sonnet-4.6 ableiten soll, bevor die Plugin-Laufzeit geladen wird.

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

OpenClaw wendet folgende Rangfolge an:

• Explizite provider/model-Referenzen verwenden die Manifest-Metadaten der zugehörigen providers
• modelPatterns haben Vorrang vor modelPrefixes
• Wenn sowohl ein nicht gebündeltes als auch ein gebündeltes Plugin übereinstimmen, hat das nicht gebündelte Plugin Vorrang
• Verbleibende Mehrdeutigkeiten werden ignoriert, bis eine Provider-Angabe durch den Benutzer oder die Konfiguration erfolgt

Felder:

modelPatterns-Einträge werden über compileSafeRegex kompiliert, wobei Muster mit verschachtelten Wiederholungen (zum Beispiel (a+)+$) abgelehnt werden. Muster, welche die Sicherheitsprüfung nicht bestehen, werden ebenso wie syntaktisch ungültige reguläre Ausdrücke stillschweigend übersprungen. Halten Sie Muster einfach und vermeiden Sie verschachtelte Quantifizierer.

Referenz zu modelCatalog

Verwenden Sie modelCatalog, wenn OpenClaw die Modellmetadaten des Providers kennen soll, bevor die Plugin-Laufzeit geladen wird. Dies ist die vom Manifest verwaltete Quelle für feste Katalogzeilen, Provider-Aliasse, Unterdrückungsregeln und den Ermittlungsmodus. Die Aktualisierung zur Laufzeit verbleibt im Laufzeitcode des Providers, das Manifest teilt dem Kern jedoch mit, wann die Laufzeit erforderlich ist.

{  "providers": ["openai"],  "modelCatalog": {    "providers": {      "openai": {        "baseUrl": "https://api.openai.com/v1",        "api": "openai-responses",        "models": [          {            "id": "gpt-5.4",            "name": "GPT-5.4",            "input": ["text", "image"],            "reasoning": true,            "contextWindow": 256000,            "maxTokens": 128000,            "cost": {              "input": 1.25,              "output": 10,              "cacheRead": 0.125            },            "status": "available",            "tags": ["default"]          }        ]      }    },    "aliases": {      "azure-openai-responses": {        "provider": "openai",        "api": "azure-openai-responses"      }    },    "suppressions": [      {        "provider": "azure-openai-responses",        "model": "gpt-5.3-codex-spark",        "reason": "not available on Azure OpenAI Responses"      }    ],    "discovery": {      "openai": "static"    }  }}

Felder der obersten Ebene:

aliases ist an der Ermittlung der Provider-Zuständigkeit für die Modellkatalogplanung beteiligt. Aliasziele müssen Provider der obersten Ebene sein, die demselben Plugin gehören. Wenn eine nach Provider gefilterte Liste einen Alias verwendet, kann OpenClaw das zugehörige Manifest lesen und die API-/Basis-URL-Überschreibungen des Alias anwenden, ohne die Provider-Laufzeit zu laden. Aliasse erweitern ungefilterte Katalogauflistungen nicht; umfassende Listen geben nur die Zeilen des zugehörigen kanonischen Providers aus.

suppressions ersetzt den alten suppressBuiltInModel-Hook der Provider-Laufzeit. Unterdrückungseinträge werden nur berücksichtigt, wenn der Provider dem Plugin gehört oder als modelCatalog.aliases-Schlüssel deklariert ist, der auf einen zugehörigen Provider verweist. Laufzeit-Hooks zur Unterdrückung werden bei der Modellauflösung nicht mehr aufgerufen.

Provider-Felder:

Modellfelder:

Unterdrückungsfelder:

Legen Sie keine reinen Laufzeitdaten in modelCatalog ab. Verwenden Sie static nur, wenn die Manifestzeilen vollständig genug sind, damit nach Provider gefilterte Listen- und Auswahloberflächen die Registry-/Laufzeitermittlung überspringen können. Verwenden Sie refreshable, wenn Manifestzeilen als auflistbare Ausgangsdaten oder Ergänzungen nützlich sind, aber eine Aktualisierung bzw. ein Cache später weitere Zeilen hinzufügen kann; aktualisierbare Zeilen sind für sich genommen nicht maßgeblich. Verwenden Sie runtime, wenn OpenClaw die Provider-Laufzeit laden muss, um die Liste zu ermitteln.

Referenz zu modelIdNormalization

Verwenden Sie modelIdNormalization für einfache, dem Provider zugehörige Bereinigungen von Modell-IDs, die erfolgen müssen, bevor die Provider-Laufzeit geladen wird. Dadurch verbleiben Aliasse wie kurze Modellnamen, ältere Provider-lokale IDs und Regeln für Proxy-Präfixe im Manifest des zuständigen Plugins statt in den zentralen Tabellen zur Modellauswahl.

{  "providers": ["anthropic", "openrouter"],  "modelIdNormalization": {    "providers": {      "anthropic": {        "aliases": {          "sonnet-4.6": "claude-sonnet-4-6"        }      },      "openrouter": {        "prefixWhenBare": "openrouter"      }    }  }}

Provider-Felder:

Referenz zu providerEndpoints

Verwenden Sie providerEndpoints für die Endpunktklassifizierung, die allgemeine Anfragerichtlinien kennen müssen, bevor die Provider-Laufzeit geladen wird. Der Kern bestimmt weiterhin die Bedeutung jeder endpointClass; Plugin-Manifeste enthalten die Host- und Basis-URL-Metadaten.

Offiziell externalisierte Provider-Plugins sind von der Kern-Distribution ausgeschlossen, sodass ihre Manifeste bis zur Installation nicht sichtbar sind. Ihre providerEndpoints müssen auch in scripts/lib/official-external-provider-catalog.json gespiegelt werden, damit die Endpunktklassifizierung ohne das Plugin weiterhin funktioniert; ein Vertragstest erzwingt diese Spiegelung.

Endpunktfelder:

Referenz zu providerRequest

Verwenden Sie providerRequest für einfache Metadaten zur Anfragekompatibilität, die allgemeine Anfragerichtlinien benötigen, ohne die Provider-Laufzeit zu laden. Verhalten-spezifische Umschreibungen der Nutzlast gehören in Laufzeit-Hooks des Providers oder gemeinsame Hilfsfunktionen der Provider-Familie.

{  "providerRequest": {    "providers": {      "vllm": {        "family": "vllm",        "openAICompletions": {          "supportsStreamingUsage": true        }      }    }  }}

Provider-Felder:

Referenz zu secretProviderIntegrations

Verwenden Sie secretProviderIntegrations, wenn ein Plugin eine wiederverwendbare Voreinstellung für einen SecretRef-Exec-Provider veröffentlichen kann. OpenClaw liest diese Metadaten, bevor die Plugin-Laufzeit geladen wird, speichert die Plugin-Zuständigkeit in secrets.providers.<alias>.pluginIntegration und überlässt die eigentliche Auflösung von Geheimnissen der SecretRef-Laufzeit. Voreinstellungen werden nur für gebündelte Plugins und installierte Plugins angeboten, die in den verwalteten Plugin-Installationsverzeichnissen gefunden wurden, beispielsweise Installationen über Git und ClawHub.

{  "secretProviderIntegrations": {    "secret-store": {      "providerAlias": "team-secrets",      "displayName": "Team secrets",      "source": "exec",      "command": "${node}",      "args": ["./bin/resolve-secrets.mjs"]    }  }}

Der Map-Schlüssel ist die Integrations-ID. Wenn providerAlias weggelassen wird, verwendet OpenClaw die Integrations-ID als SecretRef-Provider-Alias. Provider-Aliasse müssen dem üblichen Muster für SecretRef-Provider-Aliasse entsprechen, beispielsweise team-secrets oder onepassword-work.

Wenn eine zuständige Person die Voreinstellung auswählt, schreibt OpenClaw eine Provider-Referenz wie diese:

{  "secrets": {    "providers": {      "team-secrets": {        "source": "exec",        "pluginIntegration": {          "pluginId": "acme-secrets",          "integrationId": "secret-store"        }      }    }  }}

Beim Start bzw. Neuladen löst OpenClaw diesen Provider auf, indem es die aktuellen Metadaten des Plugin-Manifests lädt, prüft, ob das zuständige Plugin installiert und aktiv ist, und den Exec-Befehl aus dem Manifest erzeugt. Wird das Plugin deaktiviert oder entfernt, wird der Provider für aktive SecretRefs widerrufen. Zuständige Personen, die eine eigenständige Exec-Konfiguration wünschen, können weiterhin manuelle command-/args-Provider direkt angeben.

Derzeit werden nur source: "exec"-Voreinstellungen unterstützt. command muss ${node} sein und args[0] muss ein ./-Auflösungsskript relativ zum Plugin-Stammverzeichnis sein. OpenClaw setzt dies beim Start bzw. Neuladen in die aktuelle ausführbare Node-Datei und den absoluten Skriptpfad innerhalb des Plugins um. Node-Optionen wie --require, --import, --loader, --env-file, --eval und --print sind nicht Teil des Vertrags für Manifest-Voreinstellungen. Zuständige Personen, die Nicht-Node-Befehle benötigen, können eigenständige manuelle Exec-Provider direkt konfigurieren.

OpenClaw leitet trustedDirs für Manifest-Voreinstellungen aus dem Plugin-Stammverzeichnis und bei ${node}-Voreinstellungen aus dem Verzeichnis der aktuellen ausführbaren Node-Datei ab. Im Manifest definierte trustedDirs werden ignoriert. Andere Optionen des Exec-Providers wie timeoutMs, noOutputTimeoutMs, maxOutputBytes, jsonOnly, env, passEnv und allowInsecurePath werden an die normale Konfiguration des SecretRef-Exec-Providers weitergereicht.

Referenz zu modelPricing

Verwenden Sie modelPricing, wenn ein Provider das Preisverhalten der Steuerungsebene festlegen muss, bevor die Laufzeit geladen wird. Der Preis-Cache des Gateways liest diese Metadaten, ohne den Laufzeitcode des Providers zu importieren.

{  "providers": ["ollama", "openrouter"],  "modelPricing": {    "providers": {      "ollama": {        "external": false      },      "openrouter": {        "openRouter": {          "passthroughProviderModel": true        },        "liteLLM": false      }    }  }}

Provider-Felder:

Quellfelder:

OpenClaw-Provider-Index

Der OpenClaw-Provider-Index besteht aus OpenClaw-eigenen Vorschau-Metadaten für Provider, deren Plugins möglicherweise noch nicht installiert sind. Er ist nicht Teil eines Plugin-Manifests. Plugin-Manifeste bleiben die maßgebliche Quelle für installierte Plugins. Der Provider-Index ist der interne Rückfallvertrag, den künftige Oberflächen für installierbare Provider und die Modellauswahl vor der Installation verwenden, wenn ein Provider-Plugin nicht installiert ist.

Reihenfolge der Katalogautorität:

1. Benutzerkonfiguration.
2. Installiertes Plugin-Manifest modelCatalog.
3. Modellkatalog-Cache aus einer expliziten Aktualisierung.
4. Vorschauzeilen des OpenClaw-Provider-Index.

Der Provider-Index darf keine Geheimnisse, Aktivierungszustände, Runtime-Hooks oder Live-Modelldaten enthalten, die für ein bestimmtes Konto gelten. Seine Vorschaukataloge verwenden dieselbe modelCatalog-Provider-Zeilenstruktur wie Plugin-Manifeste, sollten jedoch auf stabile Anzeigemetadaten beschränkt bleiben, sofern Runtime-Adapterfelder wie api, baseUrl, Preise oder Kompatibilitäts-Flags nicht absichtlich mit dem installierten Plugin-Manifest synchron gehalten werden. Provider mit Live-Erkennung über /models sollten aktualisierte Zeilen über den expliziten Cache-Pfad des Modellkatalogs schreiben, statt bei der normalen Auflistung oder beim Onboarding Provider-APIs aufzurufen.

Einträge im Provider-Index können außerdem Metadaten für installierbare Plugins enthalten, wenn das Plugin eines Providers aus dem Kern verlagert wurde oder aus anderen Gründen noch nicht installiert ist. Diese Metadaten entsprechen dem Muster des Kanalkatalogs: Paketname, npm-Installationsspezifikation, erwartete Integrität und einfache Bezeichnungen für Authentifizierungsoptionen reichen aus, um eine installierbare Einrichtungsoption anzuzeigen. Sobald das Plugin installiert ist, hat sein Manifest Vorrang, und der Eintrag im Provider-Index wird für diesen Provider ignoriert.

openclaw doctor --fix migriert eine kleine, abgeschlossene Menge veralteter Manifest-Fähigkeitsschlüssel der obersten Ebene nach contracts.*: speechProviders, mediaUnderstandingProviders, imageGenerationProviders und tools. Keiner dieser Schlüssel – und auch keine andere Fähigkeitsliste – wird weiterhin als Manifestfeld der obersten Ebene gelesen; das normale Laden von Manifesten erkennt sie nur unter contracts.

Manifest im Vergleich zu package.json

Die beiden Dateien erfüllen unterschiedliche Aufgaben:

Wenn unklar ist, wohin bestimmte Metadaten gehören, gilt folgende Regel:

• wenn OpenClaw sie vor dem Laden des Plugin-Codes kennen muss, gehören sie in openclaw.plugin.json
• wenn sie die Paketierung, Einstiegsdateien oder das npm-Installationsverhalten betreffen, gehören sie in package.json

package.json-Felder, die die Erkennung beeinflussen

Einige Plugin-Metadaten, die vor der Runtime benötigt werden, befinden sich absichtlich in package.json unter dem openclaw-Block statt in openclaw.plugin.json. openclaw.bundle und openclaw.bundle.json sind keine OpenClaw-Plugin-Verträge; native Plugins müssen openclaw.plugin.json zusammen mit den nachfolgend unterstützten package.json#openclaw-Feldern verwenden.

Wichtige Beispiele:

Manifestmetadaten bestimmen, welche Provider-, Kanal- und Einrichtungsoptionen beim Onboarding angezeigt werden, bevor die Runtime geladen wird. package.json#openclaw.install teilt dem Onboarding mit, wie dieses Plugin abgerufen oder aktiviert werden soll, wenn eine dieser Optionen ausgewählt wird. Verschieben Sie Installationshinweise nicht nach openclaw.plugin.json.

Verwenden Sie für openclaw.channel.cliAddOptions die Langoptionssyntax von Commander, beispielsweise --initial-sync-limit <n>. Setzen Sie valueType: "int", um eine nicht negative Ganzzahl zu parsen, oder valueType: "list", um durch Kommas, Semikolons oder Zeilenumbrüche getrennte Eingaben in Zeichenfolgen aufzuteilen, bevor der Plugin-Einrichtungsadapter sie empfängt. Lassen Sie valueType weg, um den von Commander geparsten Wert unverändert weiterzugeben.

openclaw.install.minHostVersion wird während der Installation und beim Laden der Manifestregistrierung für nicht gebündelte Plugin-Quellen durchgesetzt. Ungültige Werte werden abgelehnt; neuere, aber gültige Werte führen dazu, dass externe Plugins auf älteren Hosts übersprungen werden. Bei gebündelten Quell-Plugins wird davon ausgegangen, dass sie dieselbe Version wie der Host-Checkout aufweisen.

openclaw.install.requiredPlatformPackages ist für npm-Pakete vorgesehen, die erforderliche native Binärdateien über optionale, plattformspezifische Aliasse bereitstellen. Geben Sie für jeden unterstützten Plattformalias den reinen npm-Paketnamen an. Während der npm-Installation überprüft OpenClaw nur den deklarierten Alias, dessen Lockfile-Beschränkungen mit dem aktuellen Host übereinstimmen. Wenn npm Erfolg meldet, diesen Alias jedoch auslässt, wiederholt OpenClaw den Vorgang einmal mit einem frischen Cache und setzt die Installation zurück, falls der Alias weiterhin fehlt.

openclaw.compat.pluginApi wird während der Paketinstallation für nicht gebündelte Plugin-Quellen durchgesetzt. Verwenden Sie es für die Mindestversion der OpenClaw-Plugin-SDK-/Runtime-API, gegen die das Paket erstellt wurde. Sie kann strenger als minHostVersion sein, wenn ein Plugin-Paket eine neuere API benötigt, aber für andere Abläufe weiterhin einen niedrigeren Installationshinweis beibehält. Die offizielle OpenClaw-Release-Synchronisierung hebt vorhandene offizielle Plugin-API-Mindestversionen standardmäßig auf die OpenClaw-Release-Version an. Reine Plugin-Releases können jedoch eine niedrigere Mindestversion beibehalten, wenn das Paket absichtlich ältere Hosts unterstützt. Verwenden Sie nicht allein die Paketversion als Kompatibilitätsvertrag. peerDependencies.openclaw bleibt npm-Paketmetadatum; OpenClaw verwendet den openclaw.compat.pluginApi-Vertrag für Entscheidungen zur Installationskompatibilität.

Offizielle Metadaten für die Installation bei Bedarf sollten clawhubSpec verwenden, wenn das Plugin auf ClawHub veröffentlicht ist; das Onboarding behandelt dies als bevorzugte Remote-Quelle und zeichnet nach der Installation Fakten zum ClawHub-Artefakt auf. npmSpec bleibt der Kompatibilitäts-Fallback für Pakete, die noch nicht zu ClawHub verschoben wurden.

Die exakte Fixierung der npm-Version befindet sich bereits in npmSpec, beispielsweise "npmSpec": "@wecom/wecom-openclaw-plugin@1.2.3". Offizielle externe Katalogeinträge sollten exakte Spezifikationen mit expectedIntegrity kombinieren, damit Aktualisierungsabläufe sicher abbrechen, wenn das abgerufene npm-Artefakt nicht mehr dem fixierten Release entspricht. Das interaktive Onboarding bietet aus Kompatibilitätsgründen weiterhin vertrauenswürdige npm-Spezifikationen aus der Registry an, einschließlich reiner Paketnamen und Dist-Tags. Katalogdiagnosen können zwischen exakten, variablen, integritätsfixierten, ohne Integritätsangabe versehenen, durch abweichende Paketnamen gekennzeichneten und ungültigen Standardauswahlquellen unterscheiden. Sie warnen außerdem, wenn expectedIntegrity vorhanden ist, aber keine gültige npm-Quelle existiert, die damit fixiert werden kann. Wenn expectedIntegrity vorhanden ist, setzen Installations- und Aktualisierungsabläufe es durch; wenn es weggelassen wird, wird die Registry-Auflösung ohne Integritätsfixierung aufgezeichnet.

Kanal-Plugins sollten openclaw.setupEntry bereitstellen, wenn Status-, Kanallisten- oder SecretRef-Prüfungen konfigurierte Konten identifizieren müssen, ohne die vollständige Runtime zu laden. Der Einrichtungseinstiegspunkt sollte Kanalmetadaten sowie einrichtungssichere Adapter für Konfiguration, Status und Geheimnisse bereitstellen; Netzwerkclients, Gateway-Listener und Transport-Runtimes gehören in den Haupteinstiegspunkt der Erweiterung.

Laufzeit-Einstiegspunktfelder setzen die Paketgrenzenprüfungen für Quell-Einstiegspunktfelder nicht außer Kraft. Beispielsweise kann openclaw.runtimeExtensions einen ausbrechenden openclaw.extensions-Pfad nicht ladbar machen.

openclaw.install.allowInvalidConfigRecovery ist absichtlich eng begrenzt. Dadurch werden nicht beliebige fehlerhafte Konfigurationen installierbar. Derzeit können Installationsabläufe damit nur bestimmte veraltete Fehler bei Upgrades gebündelter Plugins beheben, etwa einen fehlenden Pfad eines gebündelten Plugins oder einen veralteten channels.<id>-Eintrag für dasselbe gebündelte Plugin. Nicht damit zusammenhängende Konfigurationsfehler blockieren die Installation weiterhin und verweisen Betreiber auf openclaw doctor --fix.

openclaw.channel.persistedAuthState enthält Paketmetadaten für ein kleines Prüfmodul:

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

Verwenden Sie dies, wenn Einrichtung, Doctor, Status oder schreibgeschützte Anwesenheitsabläufe eine kostengünstige Ja/Nein-Authentifizierungsprüfung benötigen, bevor das vollständige Kanal-Plugin geladen wird. Persistierter Authentifizierungsstatus ist kein konfigurierter Kanalstatus: Verwenden Sie diese Metadaten nicht, um Plugins automatisch zu aktivieren, Laufzeitabhängigkeiten zu reparieren oder zu entscheiden, ob eine Kanallaufzeit geladen werden soll. Der Zielexport sollte eine kleine Funktion sein, die ausschließlich den persistierten Status liest; leiten Sie ihn nicht durch das vollständige Kanallaufzeit-Barrel.

openclaw.channel.configuredState unterstützt kostengünstige Prüfungen des Konfigurationsstatus. Bevorzugen Sie deklarative Umgebungsmetadaten, wenn Umgebungsvariablen ausreichen:

{  "openclaw": {    "channel": {      "id": "telegram",      "configuredState": {        "env": {          "allOf": ["TELEGRAM_BOT_TOKEN"]        }      }    }  }}

Verwenden Sie env.allOf, wenn jede aufgeführte Variable erforderlich ist, und env.anyOf, wenn eine beliebige nicht leere Variable ausreicht. Wenn eine kleine, laufzeitunabhängige Prüfung mehr als Umgebungsmetadaten benötigt, verwenden Sie specifier zusammen mit exportName, wie für persistedAuthState gezeigt; wenn env vorhanden ist, verwendet OpenClaw dies, ohne das betreffende Modul zu laden. Wenn die Prüfung eine vollständige Konfigurationsauflösung oder die tatsächliche Kanallaufzeit benötigt, belassen Sie diese Logik stattdessen im config.hasConfiguredState-Hook des Plugins.

Ermittlungspriorität (doppelte Plugin-IDs)

OpenClaw ermittelt Plugins aus drei Stammverzeichnissen, die in dieser Reihenfolge geprüft werden: mit OpenClaw ausgelieferte gebündelte Plugins, das globale Installationsstammverzeichnis (~/.openclaw/extensions) und das aktuelle Arbeitsbereichsstammverzeichnis (<workspace>/.openclaw/extensions) sowie alle expliziten plugins.load.paths-Einträge.

Wenn zwei Ermittlungen dieselbe id aufweisen, wird nur das Manifest mit der höchsten Priorität beibehalten; Duplikate mit niedrigerer Priorität werden verworfen, statt parallel dazu geladen zu werden. Priorität, von der höchsten zur niedrigsten:

1. Durch Konfiguration ausgewählt — ein explizit in plugins.entries.<id> festgelegter Pfad
2. Globale Installation mit passendem nachverfolgtem Installationsdatensatz — ein über openclaw plugin install/openclaw plugin update installiertes Plugin, das von OpenClaws Installationsverfolgung für dieselbe ID erkannt wird, selbst wenn die ID auch zu einem gebündelten Plugin gehört
3. Gebündelt — mit OpenClaw ausgelieferte Plugins
4. Arbeitsbereich — relativ zum aktuellen Arbeitsbereich ermittelte Plugins
5. Alle anderen ermittelten Kandidaten

Auswirkungen:

• Eine geforkte oder veraltete Kopie eines gebündelten Plugins, die sich nicht nachverfolgt im Arbeitsbereich oder globalen Stammverzeichnis befindet, überschattet den gebündelten Build nicht.
• Um ein gebündeltes Plugin zu überschreiben, führen Sie entweder openclaw plugin install für diese ID aus, sodass die nachverfolgte globale Installation eine höhere Priorität als die gebündelte Kopie erhält, oder legen Sie über plugins.entries.<id> einen bestimmten Pfad fest, damit dieser aufgrund der konfigurationsgesteuerten Priorität Vorrang erhält.
• Das Verwerfen von Duplikaten wird protokolliert, damit Doctor und die Startdiagnose auf die verworfene Kopie verweisen können.
• Durch Konfiguration ausgewählte Überschreibungen von Duplikaten werden in der Diagnose als explizite Überschreibungen bezeichnet, lösen aber weiterhin eine Warnung aus, damit veraltete Forks und versehentliche Überschattungen sichtbar bleiben.

Anforderungen an das JSON-Schema

• Jedes Plugin muss ein JSON-Schema ausliefern, auch wenn es keine Konfiguration akzeptiert.
• Ein leeres Schema ist zulässig (beispielsweise { "type": "object", "additionalProperties": false }).
• Schemas werden beim Lesen und Schreiben der Konfiguration validiert, nicht zur Laufzeit.
• Wenn Sie ein gebündeltes Plugin um neue Konfigurationsschlüssel erweitern oder forken, aktualisieren Sie gleichzeitig dessen openclaw.plugin.json configSchema. Schemas gebündelter Plugins sind strikt. Daher wird das Hinzufügen von plugins.entries.<id>.config.myNewKey zur Benutzerkonfiguration ohne gleichzeitiges Hinzufügen von myNewKey zu configSchema.properties abgelehnt, bevor die Plugin-Laufzeit geladen wird.

Beispiel für eine Schemaerweiterung:

{  "configSchema": {    "type": "object",    "additionalProperties": false,    "properties": {      "myNewKey": {        "type": "string"      }    }  }}

Validierungsverhalten

• Unbekannte channels.*-Schlüssel sind Fehler, sofern die Kanal-ID nicht durch ein Plugin-Manifest deklariert wird. Wenn dieselbe ID auch in plugins.allow, plugins.entries oder plugins.installs erscheint (ein referenziertes, aber derzeit nicht ermittelbares Plugin), stuft OpenClaw dies stattdessen zu einer Warnung herab.
• plugins.entries.<id>, plugins.allow und plugins.deny, die auf unbekannte Plugin-IDs verweisen, sind Warnungen („veralteter Konfigurationseintrag ignoriert“) und keine Fehler, damit Upgrades sowie entfernte oder umbenannte Plugins den Start des Gateways nicht blockieren.
• plugins.slots.memory, das auf eine unbekannte Plugin-ID verweist, ist ein Fehler. Eine Ausnahme bildet das bekannte offizielle externe Plugin memory-lancedb, für das stattdessen eine Warnung ausgegeben wird.
• Wenn ein Plugin installiert ist, aber ein fehlerhaftes oder fehlendes Manifest oder Schema aufweist, schlägt die Validierung fehl und Doctor meldet den Plugin-Fehler.
• Wenn eine Plugin-Konfiguration vorhanden, das Plugin jedoch deaktiviert ist, wird die Konfiguration beibehalten und in Doctor und den Protokollen eine Warnung angezeigt.

Das vollständige plugins.*-Schema finden Sie in der Konfigurationsreferenz.

Hinweise

• Das Manifest ist für native OpenClaw-Plugins erforderlich, einschließlich Ladevorgängen aus dem lokalen Dateisystem. Die Laufzeit lädt das Plugin-Modul weiterhin separat; das Manifest dient ausschließlich der Ermittlung und Validierung.
• Native Manifeste werden mit JSON5 geparst. Daher werden Kommentare, abschließende Kommata und Schlüssel ohne Anführungszeichen akzeptiert, solange der endgültige Wert weiterhin ein Objekt ist.
• Der Manifest-Loader liest ausschließlich dokumentierte Manifestfelder. Vermeiden Sie benutzerdefinierte Schlüssel auf oberster Ebene.
• channels, providers, cliBackends und skills können alle weggelassen werden, wenn ein Plugin sie nicht benötigt.
• providerCatalogEntry muss leichtgewichtig bleiben und sollte keinen umfangreichen Laufzeitcode importieren; verwenden Sie es für statische Metadaten des Provider-Katalogs oder eng begrenzte Ermittlungsdeskriptoren, nicht für die Ausführung während einer Anfrage.
• Exklusive Plugin-Arten werden über plugins.slots.* ausgewählt: kind: "memory" über plugins.slots.memory (Standardwert memory-core), kind: "context-engine" über plugins.slots.contextEngine (Standardwert legacy).
• Deklarieren Sie die exklusive Plugin-Art in diesem Manifest. Der Laufzeiteintrag OpenClawPluginDefinition.kind ist veraltet und bleibt nur als Kompatibilitäts-Fallback für ältere Plugins bestehen.
• Metadaten für Umgebungsvariablen in setup.providers[].envVars sind rein deklarativ. Status, Audit, Validierung der Cron-Zustellung und andere schreibgeschützte Oberflächen wenden weiterhin die Plugin-Vertrauens- und effektiven Aktivierungsrichtlinien an, bevor sie eine Umgebungsvariable als konfiguriert behandeln.
• Laufzeitmetadaten für Assistenten, die Provider-Code benötigen, werden unter Provider-Laufzeit-Hooks beschrieben.
• Wenn Ihr Plugin von nativen Modulen abhängt, dokumentieren Sie die Build-Schritte und alle Anforderungen an die Zulassungsliste des Paketmanagers (beispielsweise pnpm allow-build-scripts + pnpm rebuild <package>).

Verwandte Themen