Pluginmanifest

Deze pagina behandelt het native OpenClaw-pluginmanifest, openclaw.plugin.json. Zie Pluginbundels voor compatibele bundelindelingen (Codex, Claude, Cursor).

Compatibele bundelindelingen gebruiken in plaats daarvan hun eigen manifestbestanden:

• Codex-bundel: .codex-plugin/plugin.json
• Claude-bundel: .claude-plugin/plugin.json, of de standaardindeling voor Claude-componenten zonder manifest
• Cursor-bundel: .cursor-plugin/plugin.json

OpenClaw detecteert deze indelingen automatisch, maar valideert ze niet aan de hand van het onderstaande openclaw.plugin.json-schema. Voor een compatibele bundel leest OpenClaw bundelmetadata, gedeclareerde skill-hoofdmappen, Claude-opdrachthoofdmappen, standaardwaarden voor Claude settings.json, standaardwaarden voor Claude LSP en ondersteunde hookpakketten, wanneer de indeling overeenkomt met de runtimeverwachtingen van OpenClaw.

Elke native OpenClaw-plugin moet openclaw.plugin.json in de hoofdmap van de plugin meeleveren. OpenClaw leest dit om de configuratie te valideren zonder plugincode uit te voeren. Een ontbrekend of ongeldig manifest blokkeert de configuratievalidatie en wordt als een pluginfout beschouwd.

Zie Plugins voor de volledige handleiding van het pluginsysteem en Capaciteitsmodel voor het native capaciteitsmodel en de huidige richtlijnen voor externe compatibiliteit.

Wat dit bestand doet

openclaw.plugin.json bevat metadata die OpenClaw leest voordat je plugincode wordt geladen. Alles daarin moet eenvoudig genoeg zijn om te inspecteren zonder de pluginruntime op te starten.

Gebruik het voor:

• pluginidentiteit, configuratievalidatie en aanwijzingen voor de configuratie-UI
• metadata voor authenticatie, onboarding en installatie (alias, automatisch inschakelen, omgevingsvariabelen van providers, authenticatiekeuzes)
• activeringsaanwijzingen voor control-plane-oppervlakken
• eigenaarschap van modelreeksen in verkorte notatie
• statische momentopnamen van capaciteitseigenaarschap (contracts)
• gegevenskoppelingen en actiewerkwoorden voor dashboardwidgets
• statische MCP-servers die beschikbaar moeten zijn zolang de plugin is ingeschakeld
• metadata van de QA-runner die de gedeelde openclaw qa-host kan inspecteren
• kanaalspecifieke configuratiemetadata die in catalogus- en validatieoppervlakken worden samengevoegd

Gebruik het niet voor: het registreren van native runtimehooks, het declareren van toegangspunten voor plugincode of installatiemetadata voor npm. Die horen thuis in je plugincode en package.json.

Minimaal voorbeeld

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

Uitgebreid voorbeeld

{  "id": "openrouter",  "name": "OpenRouter",  "description": "OpenRouter-providerplugin",  "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-sleutel",      "groupId": "openrouter",      "groupLabel": "OpenRouter",      "optionKey": "openrouterApiKey",      "cliFlag": "--openrouter-api-key",      "cliOption": "--openrouter-api-key <key>",      "cliDescription": "OpenRouter-API-sleutel",      "onboardingScopes": ["text-inference"]    }  ],  "uiHints": {    "apiKey": {      "label": "API-sleutel",      "placeholder": "sk-or-v1-...",      "sensitive": true    }  },  "configSchema": {    "type": "object",    "additionalProperties": false,    "properties": {      "apiKey": {        "type": "string"      }    }  }}

Overzicht van velden op het hoogste niveau

Naslaginformatie voor MCP-servers

mcpServers laat een native plugin een MCP-server leveren, inclusief een MCP App, zonder dat beheerders de statische procesdefinitie ervan hoeven te dupliceren in openclaw.json:

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

OpenClaw neemt deze servers alleen op zolang de bijbehorende plugin is ingeschakeld. Relatieve paden voor command, args, cwd en workingDirectory worden herleid vanaf de hoofdmap van de plugin. De gebruikersconfiguratie blijft leidend: mcp.servers.<name> kan een standaardwaarde van een plugin vervangen of enabled: false instellen om deze weg te laten. Voor het renderen van MCP Apps en het aanroepen van servertools zijn nog steeds de normale instelling voor MCP Apps en het geldende toolbeleid vereist; het declareren van een server omzeilt geen van beide grenzen.

Naslaginformatie voor het dashboard

dashboard laat een ingeschakelde plugin bestaande Gateway-RPC's beschikbaar stellen aan dashboardwidgets met de juiste rechten, zonder pluginbeleid aan de kern toe te voegen. Gegevensbindingen moeten een methode noemen die dezelfde plugin registreert met operator.read; actiewerkwoorden moeten een methode noemen die de plugin registreert met operator.write. Bij een verschil wordt de plugin tijdens de registratie geweigerd.

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

De manifest-id's zijn lokaal voor de plugin. Widgetrechten gebruiken <plugin-id>.<id>, zoals example.items.list en example.refresh. Om de persistente naamruimte voor rechten ondubbelzinnig te houden, escapt OpenClaw % en . in het plugin-id-segment als %25 en %2E; gewone plugin-id's behouden de natuurlijke vorm. paramShape is een optioneel JSON Schema dat wordt toegepast op het object met actieparameters voordat OpenClaw de RPC van de plugin aanroept.

Naslaginformatie voor de catalogus

catalog biedt optionele weergaveaanwijzingen voor pluginbrowsers. Hosts mogen deze aanwijzingen negeren. Ze installeren of activeren de plugin nooit en veranderen het runtimegedrag of vertrouwensniveau ervan niet.

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

Naslaginformatie voor metagegevens van generatieproviders

De metagegevensvelden voor generatieproviders beschrijven statische authenticatiesignalen voor providers die zijn gedeclareerd in de bijbehorende lijst contracts.*GenerationProviders. OpenClaw leest deze velden voordat de providerruntime wordt geladen, zodat kerntools kunnen bepalen of een generatieprovider beschikbaar is zonder elke providerplugin te importeren.

Gebruik deze velden alleen voor eenvoudige, declaratieve feiten. Transport, aanvraagtransformaties, tokenvernieuwing, validatie van aanmeldgegevens en het daadwerkelijke generatiegedrag blijven in de pluginruntime.

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

Elke metagegevensvermelding ondersteunt:

Elke vermelding in configSignals ondersteunt:

Elke beperking in mode ondersteunt:

Elke vermelding in authSignals ondersteunt:

Elke beperking in providerBaseUrl ondersteunt:

Naslaginformatie voor toolmetagegevens

toolMetadata gebruikt dezelfde vormen configSignals en authSignals als de metagegevens voor generatieproviders, geïndexeerd op toolnaam. contracts.tools declareert het eigenaarschap. toolMetadata declareert eenvoudig beschikbaarheidsbewijs, zodat OpenClaw kan voorkomen dat een pluginruntime alleen wordt geïmporteerd om de toolfactory null te laten retourneren.

{  "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-vermeldingen accepteren naast de gedeelde velden configSignals/authSignals hierboven ook optional (markeert de tool als niet vereist voor activering van de plugin) en replaySafe (markeert de uitvoering van de tool als veilig om te herhalen na een onvolledige modelbeurt).

Als een tool geen toolMetadata heeft, behoudt OpenClaw het bestaande gedrag en laadt het de bijbehorende plugin wanneer het toolcontract overeenkomt met het beleid. Voor tools in het kritieke pad waarvan de factory afhankelijk is van authenticatie/configuratie, moeten pluginauteurs toolMetadata declareren in plaats van core runtime te laten importeren om dit op te vragen.

Naslaginformatie voor providerAuthChoices

Elke providerAuthChoices-vermelding beschrijft één keuze voor onboarding of authenticatie. OpenClaw leest deze voordat de provider-runtime wordt geladen. Lijsten voor providerconfiguratie gebruiken deze manifestkeuzes, uit descriptors afgeleide configuratiekeuzes en metadata uit de installatiecatalogus zonder de provider-runtime te laden.

Wanneer appGuidedDiscovery waar is, moet de overeenkomende authenticatiemethode van de provider appGuidedSetup.detect en appGuidedSetup.prepare beschikbaar stellen. Detectie moet alleen-lezen zijn: geen aanmelding, ophalen van modellen, download of schrijven van configuratie. De voorbereiding controleert het exact geselecteerde model opnieuw en retourneert een configuratievoorstel; OpenClaw test dat voorstel afzonderlijk live en legt het pas na succes vast.

Naslaginformatie voor commandAliases

Gebruik commandAliases wanneer een plugin eigenaar is van een runtime-opdrachtnaam die gebruikers per ongeluk in plugins.allow kunnen opnemen of als root-CLI-opdracht kunnen proberen uit te voeren. OpenClaw gebruikt deze metadata voor diagnostiek zonder de runtimecode van de plugin te importeren.

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

Naslaginformatie voor activation

Gebruik activation wanneer de plugin op efficiënte wijze kan declareren bij welke gebeurtenissen in het besturingsvlak deze in een activerings-/laadplan moet worden opgenomen.

Dit blok bevat metadata voor de planner en is geen levenscyclus-API. Het registreert geen runtimegedrag, vervangt register(...) niet en garandeert niet dat plugincode al is uitgevoerd. De activeringsplanner gebruikt deze velden om kandidaat-plugins te beperken voordat wordt teruggevallen op bestaande metadata over eigenaarschap in het manifest, zoals providers, channels, commandAliases, setup.providers, contracts.tools en hooks.

Geef de voorkeur aan de meest specifieke metadata die het eigenaarschap al beschrijft. Gebruik providers, channels, commandAliases, configuratiedescriptors of contracts wanneer deze velden de relatie uitdrukken. Gebruik activation voor aanvullende plannerhints die niet door die eigenaarschapsvelden kunnen worden weergegeven. Gebruik cliBackends op het hoogste niveau voor CLI-runtime-aliassen zoals claude-cli, my-cli of google-gemini-cli; activation.onAgentHarnesses is alleen bestemd voor ids van ingebedde agentharnassen die nog geen eigenaarschapsveld hebben.

Elke plugin moet activation.onStartup bewust instellen. Stel dit alleen in op true wanneer de plugin tijdens het opstarten van de Gateway moet worden uitgevoerd. Stel het in op false wanneer de plugin bij het opstarten inactief is en alleen door specifiekere triggers moet worden geladen. Het weglaten van onStartup zorgt er niet langer impliciet voor dat de plugin bij het opstarten wordt geladen; gebruik expliciete activeringsmetadata voor activeringstriggers bij het opstarten, voor kanalen, configuratie, agentharnassen, geheugen of andere specifiekere triggers.

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

Huidige actieve gebruikers:

• De opstartplanning van de Gateway gebruikt activation.onStartup voor expliciete import bij het starten.
• Door opdrachten geactiveerde CLI-planning valt terug op de verouderde commandAliases[].cliCommand of commandAliases[].name.
• De opstartplanning van de agentruntime gebruikt activation.onAgentHarnesses voor ingebedde harnassen en cliBackends[] op het hoogste niveau voor aliassen van CLI-runtimes.
• Door kanalen geactiveerde installatie-/kanaalplanning valt terug op het verouderde eigenaarschap van channels[] wanneer expliciete activeringsmetadata voor kanalen ontbreken.
• De planning van plugins bij het starten gebruikt activation.onConfigPaths voor hoofdconfiguratieoppervlakken die niet kanaalspecifiek zijn, zoals het browser-blok van de meegeleverde browserplugin.
• Door providers geactiveerde installatie-/runtimeplanning valt terug op het verouderde eigenaarschap van providers[] en cliBackends[] op het hoogste niveau wanneer expliciete activeringsmetadata voor providers ontbreken.

Plannerdiagnostiek kan expliciete activeringshints onderscheiden van terugval op manifesteigenaarschap. activation-command-hint betekent bijvoorbeeld dat activation.onCommands overeenkwam, terwijl manifest-command-alias betekent dat de planner in plaats daarvan het eigenaarschap van commandAliases gebruikte. Deze redenlabels zijn bedoeld voor hostdiagnostiek en tests; pluginauteurs moeten de metadata blijven declareren die het eigenaarschap het beste beschrijven.

Naslag voor qaRunners

Gebruik qaRunners wanneer een plugin een of meer transportrunners toevoegt onder de gedeelde hoofdmap openclaw qa. Houd deze metadata goedkoop en statisch; de pluginruntime blijft verantwoordelijk voor de daadwerkelijke CLI-registratie via een lichtgewicht runtime-api.ts-oppervlak dat overeenkomende qaRunnerCliRegistrations exporteert. Een optionele adapterFactory stelt het transport beschikbaar aan gedeelde QA-scenario's zonder de runner van de geregistreerde opdracht te wijzigen.

{  "qaRunners": [    {      "commandName": "matrix",      "description": "Voer de door Docker ondersteunde actieve QA-lane voor Matrix uit tegen een tijdelijke homeserver"    }  ]}

De adapterFactory-id moet overeenkomen met commandName. Exporteer geen registraties voor opdrachten die niet in het manifest staan.

Naslag voor setup

Gebruik setup wanneer installatie- en onboardingoppervlakken goedkope, door de plugin beheerde metadata nodig hebben voordat de runtime wordt geladen.

{  "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-referenties"          }        ]      }    ],    "cliBackends": ["openai-cli"],    "configMigrations": ["legacy-openai-auth"],    "requiresRuntime": false  }}

cliBackends op het hoogste niveau blijft geldig en blijft CLI-inferentiebackends beschrijven. setup.cliBackends is het installatiespecifieke descriptoroppervlak voor besturingsvlak-/installatiestromen die uitsluitend uit metadata moeten blijven bestaan.

Wanneer aanwezig, vormen setup.providers en setup.cliBackends het voorkeursoppervlak voor descriptorgerichte opzoekacties tijdens installatiedetectie. Als de descriptor alleen de kandidaat-plugin beperkt en de installatie nog uitgebreidere runtimehooks voor de installatiefase nodig heeft, stel je requiresRuntime: true in en behoud je setup-api als terugvalpad voor uitvoering.

OpenClaw neemt setup.providers[].envVars op in generieke opzoekacties voor providerauthenticatie en omgevingsvariabelen. Plaats daar omgevingsmetadata voor installatie en status.

Gebruik providerUsageAuthEnvVars wanneer referenties op facturerings- of organisatieniveau resolveUsageAuth moeten activeren zonder inferentiereferenties te worden. Deze namen worden opgenomen in het blokkeren van dotenv-waarden voor werkruimten, het verwijderen van waarden uit ACP-subprocessen, het filteren van geheimen in de sandbox en het breed opschonen van geheimen. De providerruntime leest en classificeert de waarde nog steeds binnen resolveUsageAuth.

OpenClaw kan ook eenvoudige installatiekeuzes afleiden uit setup.providers[].authMethods wanneer geen installatie-item beschikbaar is of wanneer setup.requiresRuntime: false aangeeft dat een installatieruntime niet nodig is. Expliciete providerAuthChoices-items blijven de voorkeur genieten voor aangepaste labels, CLI-vlaggen, onboardingsbereik en assistentmetadata.

Stel requiresRuntime: false alleen in wanneer deze descriptors voldoende zijn voor het installatieoppervlak. OpenClaw behandelt een expliciete false als een contract dat uitsluitend uit descriptors bestaat en voert setup-api of openclaw.setupEntry niet uit voor opzoekacties tijdens de installatie. Als een plugin die uitsluitend descriptors gebruikt toch een van deze runtime-items voor installatie levert, rapporteert OpenClaw aanvullende diagnostiek en blijft het item negeren. Wanneer requiresRuntime is weggelaten, blijft het verouderde terugvalgedrag behouden, zodat bestaande plugins die descriptors zonder de vlag hebben toegevoegd niet defect raken.

Omdat de installatieopzoekactie door de plugin beheerde setup-api-code kan uitvoeren, moeten genormaliseerde waarden voor setup.providers[].id en setup.cliBackends[] uniek blijven voor alle gedetecteerde plugins. Bij dubbelzinnig eigenaarschap wordt de bewerking veilig geweigerd in plaats van een winnaar te kiezen op basis van de detectievolgorde.

Wanneer de installatieruntime wel wordt uitgevoerd, rapporteert de diagnostiek van het installatieregister descriptorafwijkingen als setup-api een provider of CLI-backend registreert die niet door de manifestdescriptors wordt gedeclareerd, of als een descriptor geen overeenkomende runtimeregistratie heeft. Deze diagnostiek is aanvullend en wijst verouderde plugins niet af.

Naslag voor setup.providers

authEvidence is bedoeld voor lokale, door providers beheerde referentiemarkeringen die kunnen worden geverifieerd zonder runtimecode te laden. Deze controles moeten goedkoop en lokaal blijven: geen netwerkoproepen, geen leesacties uit een sleutelhanger of geheimenbeheerder, geen shellopdrachten en geen controles via de provider-API.

Ondersteunde bewijsitems:

Installatievelden

Referentie voor uiHints

uiHints is een toewijzing van namen van configuratievelden naar kleine renderhints. Sleutels kunnen punten gebruiken voor geneste configuratievelden, maar geen enkel padsegment mag __proto__, constructor of prototype zijn; de configuratie weigert deze namen.

{  "uiHints": {    "apiKey": {      "label": "API-sleutel",      "help": "Gebruikt voor OpenRouter-verzoeken",      "placeholder": "sk-or-v1-...",      "sensitive": true    }  }}

Elke veldhint kan het volgende bevatten:

Referentie voor contracts

Gebruik contracts alleen voor statische metadata over eigendom van mogelijkheden die OpenClaw kan lezen zonder de runtime van de plugin te importeren.

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

Elke lijst is optioneel:

contracts.embeddedExtensionFactories blijft behouden voor gebundelde extensiefabrieken die uitsluitend voor de Codex-app-server zijn bedoeld. Gebundelde transformaties van toolresultaten moeten in plaats daarvan contracts.agentToolResultMiddleware declareren en zich bij api.registerAgentToolResultMiddleware(...) registreren. Geïnstalleerde plugins mogen dezelfde middlewarekoppeling alleen gebruiken wanneer deze expliciet is ingeschakeld en uitsluitend voor runtimes die zij in contracts.agentToolResultMiddleware declareren.

Geïnstalleerde plugins die het door de host vertrouwde beleidsniveau vóór tooluitvoering nodig hebben, moeten elke geregistreerde lokale id in contracts.trustedToolPolicies declareren en expliciet zijn ingeschakeld. Gebundelde plugins behouden het bestaande pad voor vertrouwd beleid, maar geïnstalleerde plugins met niet-gedeclareerde beleids-id's worden vóór registratie geweigerd. Beleids-id's vallen binnen het bereik van de registrerende plugin, zodat twee plugins beide workflow-budget mogen declareren en registreren; één plugin mag dezelfde lokale id niet twee keer registreren.

Runtime-registraties van api.registerTool(...) moeten overeenkomen met contracts.tools. Tooldetectie gebruikt deze lijst om uitsluitend de pluginruntimes te laden die eigenaar kunnen zijn van de aangevraagde tools.

Providerplugins die resolveExternalAuthProfiles implementeren, moeten contracts.externalAuthProviders declareren; niet-gedeclareerde hooks voor externe authenticatie worden genegeerd.

Providerplugins die zowel resolveUsageAuth als fetchUsageSnapshot implementeren, moeten elke automatisch gedetecteerde provider-id in contracts.usageProviders declareren. Gebruiksdetectie leest dit contract voordat runtimecode wordt geladen en verifieert vervolgens beide hooks nadat alleen de gedeclareerde eigenaren zijn geladen.

Algemene embeddingproviders moeten contracts.embeddingProviders declareren voor elke adapter die bij api.registerEmbeddingProvider(...) is geregistreerd. Gebruik het algemene contract voor herbruikbare vectorgeneratie, inclusief providers die door geheugenzoekopdrachten worden gebruikt. contracts.memoryEmbeddingProviders is verouderde, geheugenspecifieke compatibiliteit en blijft alleen bestaan terwijl bestaande providers naar de generieke koppeling voor embeddingproviders migreren.

Workerproviders moeten elke api.registerWorkerProvider(...)-id in contracts.workerProviders declareren. Core slaat duurzame intentie op voordat provision wordt aangeroepen; providers valideren hun instellingen vóór externe toewijzing en herhaalde aanroepen met dezelfde bewerkings-id moeten dezelfde lease overnemen. Core slaat ook die gevalideerde momentopname van instellingen op en geeft deze met leaseId door aan inspect({ leaseId, profile }) en destroy({ leaseId, profile }), ook nadat het benoemde profiel is gewijzigd of verwijderd. Vernietiging is idempotent, inspectie retourneert de gesloten status-unie active / destroyed / unknown, en materiaal van privésleutels voor SSH wordt uitsluitend via SecretRef verwezen. Ingerichte SSH-eindpunten moeten ook een openbare hostKey uit vertrouwde inrichtingsuitvoer bevatten als exact algorithm base64, zonder hostnaam of opmerking, zodat Core de host vóór het verbinden kan vastzetten. Providers die dynamische identiteitsreferenties aanmaken, mogen een gezaghebbende resolveSshIdentity({ leaseId, profile, keyRef }) implementeren; providers zonder deze implementatie gebruiken de generieke geheimresolver van Core. Een gezaghebbende unknown maakt een actieve lokale record verweesd; na een opgeslagen vernietigingsaanvraag bevestigt deze de ontmanteling.

contracts.gatewayMethodDispatch accepteert momenteel "authenticated-request". Het is een API-hygiënepoort voor native HTTP-routes van plugins die opzettelijk Gateway-besturingsvlakmethoden in-process aanroepen, geen sandbox tegen kwaadaardige native plugins. Gebruik dit alleen voor grondig beoordeelde gebundelde/operatoroppervlakken die al HTTP-authenticatie van de Gateway vereisen. Een geautoriseerde route blijft bereikbaar terwijl de toelating van rootwerk door de Gateway is gesloten, maar alleen wanneer deze ook auth: "gateway" en de routespecifieke gatewayRuntimeScopeSurface: "trusted-operator" declareert; gewone zusterroutes van dezelfde plugin blijven achter de toelatingsgrens. Hierdoor blijven de opschortingsstatus en hervatting bereikbaar zonder de hele plugin een omzeiling van de toelating te verlenen. Houd parsering en vormgeving van reacties begrensd buiten de aanroep; inhoudelijk of muterend werk moet via de methodedispatch van de Gateway verlopen, die de toelating en scopehandhaving beheert.

Naslaginformatie voor configContracts

Gebruik configContracts voor configuratiegedrag dat eigendom is van het manifest en dat generieke kernhelpers nodig hebben zonder de pluginruntime te importeren: detectie van gevaarlijke vlaggen, migratiedoelen voor SecretRef en beperking van verouderde configuratiepaden.

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

Elke dangerousFlags-vermelding ondersteunt:

secretInputs ondersteunt:

Naslaginformatie voor mediaUnderstandingProviderMetadata

Gebruik mediaUnderstandingProviderMetadata wanneer een provider voor mediabegrip standaardmodellen, prioriteit voor automatische authenticatieterugval of native documentondersteuning heeft die generieke kernhelpers nodig hebben voordat de runtime wordt geladen. Sleutels moeten ook in contracts.mediaUnderstandingProviders worden gedeclareerd.

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

Elke providervermelding kan het volgende bevatten:

Naslaginformatie voor channelConfigs

Gebruik channelConfigs wanneer een kanaalplugin goedkope configuratiemetadata nodig heeft voordat de runtime wordt geladen. Alleen-lezen ontdekking van kanaalinstallatie/-status kan deze metadata rechtstreeks gebruiken voor geconfigureerde externe kanalen wanneer geen installatievermelding beschikbaar is, of wanneer setup.requiresRuntime: false verklaart dat een installatieruntime niet nodig is.

channelConfigs is metadata van het pluginmanifest, geen nieuwe configuratiesectie op het hoogste niveau voor gebruikers. Gebruikers configureren kanaalinstanties nog steeds onder channels.<channel-id>. OpenClaw leest manifestmetadata om te bepalen welke plugin eigenaar is van dat geconfigureerde kanaal voordat de pluginruntimecode wordt uitgevoerd.

Voor een kanaalplugin beschrijven configSchema en channelConfigs verschillende paden:

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

Niet-gebundelde plugins die channels[] declareren, moeten ook overeenkomende channelConfigs-vermeldingen declareren. Zonder deze vermeldingen kan OpenClaw de plugin nog steeds laden, maar kunnen configuratieschema's voor koude paden, installatie- en Control UI-oppervlakken de vorm van kanaaleigen opties of uitsluitend voor weergave bedoelde UI-hints niet kennen totdat de pluginruntime wordt uitgevoerd.

channelConfigs.<channel-id>.commands.nativeCommandsAutoEnabled en nativeSkillsAutoEnabled kunnen statische standaardwaarden voor auto declareren voor controles van opdrachtconfiguratie die worden uitgevoerd voordat de kanaalruntime wordt geladen. Gebundelde kanalen kunnen dezelfde standaardwaarden ook publiceren via package.json#openclaw.channel.commands, naast hun andere kanaalcatalogusmetadata waarvan het pakket eigenaar is.

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

Elke kanaalvermelding kan het volgende bevatten:

Een andere kanaalplugin vervangen

Gebruik preferOver wanneer jouw plugin de voorkeurseigenaar is voor een kanaal-id dat ook door een andere plugin kan worden geleverd. Veelvoorkomende gevallen zijn een hernoemde plugin-id, een zelfstandige plugin die een gebundelde plugin vervangt, of een onderhouden fork die dezelfde kanaal-id behoudt voor configuratiecompatibiliteit.

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

Wanneer channels.chat is geconfigureerd, houdt OpenClaw rekening met zowel de kanaal-id als de voorkeurs-Plugin-id. Als de Plugin met lagere prioriteit alleen is geselecteerd omdat deze is meegeleverd of standaard is ingeschakeld, schakelt OpenClaw deze uit in de effectieve runtimeconfiguratie, zodat één Plugin eigenaar is van het kanaal en de bijbehorende tools. Expliciete selectie door de gebruiker heeft nog steeds voorrang: als de gebruiker beide Plugins expliciet inschakelt (via plugins.allow of een materiële plugins.entries-configuratie), behoudt OpenClaw die keuze en rapporteert het diagnostische gegevens over dubbele kanalen/tools in plaats van de aangevraagde Plugin-set stilzwijgend te wijzigen.

Beperk preferOver tot Plugin-id's die daadwerkelijk hetzelfde kanaal kunnen leveren. Het is geen algemeen prioriteitsveld en het hernoemt geen configuratiesleutels van gebruikers.

Naslaginformatie voor modelSupport

Gebruik modelSupport wanneer OpenClaw je provider-Plugin moet afleiden uit verkorte model-id's zoals gpt-5.6-sol of claude-sonnet-4.6 voordat de Plugin-runtime wordt geladen.

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

OpenClaw past deze voorrangsvolgorde toe:

• expliciete provider/model-verwijzingen gebruiken de manifestmetagegevens van de bijbehorende providers
• modelPatterns hebben voorrang op modelPrefixes
• als één niet-meegeleverde Plugin en één meegeleverde Plugin beide overeenkomen, heeft de niet-meegeleverde Plugin voorrang
• resterende ambiguïteit wordt genegeerd totdat de gebruiker of configuratie een provider opgeeft

Velden:

modelPatterns-vermeldingen worden gecompileerd via compileSafeRegex, dat patronen met geneste herhaling afwijst (bijvoorbeeld (a+)+$). Patronen die niet door de veiligheidscontrole komen, worden stilzwijgend overgeslagen, net als syntactisch ongeldige regex. Houd patronen eenvoudig en vermijd geneste kwantoren.

Naslaginformatie voor modelCatalog

Gebruik modelCatalog wanneer OpenClaw vóór het laden van de Plugin-runtime metagegevens over providermodellen moet kennen. Dit is de bron in eigendom van het manifest voor vaste catalogusrijen, provideraliassen, onderdrukkingsregels en de detectiemodus. Runtimevernieuwing blijft de verantwoordelijkheid van de providerruntimecode, maar het manifest vertelt de core wanneer runtime vereist is.

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

Velden op het hoogste niveau:

aliases neemt deel aan het opzoeken van providereigendom voor modelcatalogusplanning. Aliasdoelen moeten providers op het hoogste niveau zijn die eigendom zijn van dezelfde Plugin. Wanneer een op provider gefilterde lijst een alias gebruikt, kan OpenClaw het bijbehorende manifest lezen en API-/basis-URL-overschrijvingen van de alias toepassen zonder de providerruntime te laden. Aliassen breiden ongefilterde catalogusvermeldingen niet uit; brede lijsten geven alleen de canonieke provider-rijen van de eigenaar weer.

suppressions vervangt de oude providerruntime-hook suppressBuiltInModel. Onderdrukkingsvermeldingen worden alleen gehonoreerd wanneer de provider eigendom is van de Plugin of is gedeclareerd als een modelCatalog.aliases-sleutel die naar een provider in eigendom verwijst. Runtime-hooks voor onderdrukking worden niet langer aangeroepen tijdens modelresolutie.

Providervelden:

Modelvelden:

Onderdrukkingsvelden:

Plaats geen gegevens die alleen tijdens runtime beschikbaar zijn in modelCatalog. Gebruik static alleen wanneer de manifestrijen volledig genoeg zijn zodat op provider gefilterde lijst- en kiezeroppervlakken register-/runtime-ontdekking kunnen overslaan. Gebruik refreshable wanneer manifestrijen nuttige vermeldbare beginwaarden of aanvullingen zijn, maar een vernieuwing/cache later meer rijen kan toevoegen; vernieuwbare rijen zijn op zichzelf niet gezaghebbend. Gebruik runtime wanneer OpenClaw de providerruntime moet laden om de lijst te kennen.

Naslag voor modelIdNormalization

Gebruik modelIdNormalization voor goedkope, door de provider beheerde opschoning van model-id's die moet plaatsvinden voordat de providerruntime wordt geladen. Hierdoor blijven aliassen zoals korte modelnamen, verouderde providerlokale id's en regels voor proxyprefixen in het manifest van de beherende plugin in plaats van in modelselectietabellen van de kern.

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

Providervelden:

Naslag voor providerEndpoints

Gebruik providerEndpoints voor eindpuntclassificatie die het algemene aanvraagbeleid moet kennen voordat de providerruntime wordt geladen. De kern bepaalt nog steeds de betekenis van elke endpointClass; pluginmanifesten beheren de host- en basis-URL-metagegevens.

Officieel geëxternaliseerde providerplugins zijn uitgesloten van de kerndistributie, zodat hun manifesten onzichtbaar zijn totdat ze zijn geïnstalleerd. Hun providerEndpoints moet ook worden gespiegeld in scripts/lib/official-external-provider-catalog.json, zodat eindpuntclassificatie zonder de plugin blijft werken; een contracttest dwingt deze spiegeling af.

Eindpuntvelden:

Naslag voor providerRequest

Gebruik providerRequest voor goedkope metagegevens over aanvraagcompatibiliteit die het algemene aanvraagbeleid nodig heeft zonder de providerruntime te laden. Houd gedragsspecifieke herschrijving van payloads in providerruntimehooks of gedeelde helpers voor providerfamilies.

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

Providervelden:

Naslag voor secretProviderIntegrations

Gebruik secretProviderIntegrations wanneer een plugin een herbruikbare voorinstelling voor een SecretRef-exec-provider kan publiceren. OpenClaw leest deze metagegevens voordat de pluginruntime wordt geladen, slaat het plugineigendom op in secrets.providers.<alias>.pluginIntegration en laat de daadwerkelijke oplossing van geheimen over aan de SecretRef-runtime. Voorinstellingen worden alleen beschikbaar gesteld voor gebundelde plugins en geïnstalleerde plugins die zijn ontdekt vanuit de beheerde installatieroots voor plugins, zoals git- en ClawHub-installaties.

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

De mapsleutel is de integratie-id. Als providerAlias wordt weggelaten, gebruikt OpenClaw de integratie-id als de provideralias voor SecretRef. Provideraliassen moeten overeenkomen met het normale patroon voor SecretRef-provideraliassen, bijvoorbeeld team-secrets of onepassword-work.

Wanneer een beheerder de voorinstelling selecteert, schrijft OpenClaw een providerverwijzing zoals:

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

Bij het opstarten/opnieuw laden lost OpenClaw die provider op door de huidige metagegevens van het pluginmanifest te laden, te controleren of de beherende plugin is geïnstalleerd en actief is, en de exec-opdracht uit het manifest te materialiseren. Het uitschakelen of verwijderen van de plugin trekt de provider voor actieve SecretRefs in. Beheerders die een zelfstandige exec-configuratie willen, kunnen nog steeds rechtstreeks handmatige command/args-providers schrijven.

Momenteel worden alleen source: "exec"-voorinstellingen ondersteund. command moet ${node} zijn en args[0] moet een ./-resolverscript relatief aan de pluginroot zijn. OpenClaw materialiseert dit bij het opstarten/opnieuw laden naar het huidige uitvoerbare Node-bestand en het absolute scriptpad binnen de plugin. Node-opties zoals --require, --import, --loader, --env-file, --eval en --print maken geen deel uit van het manifestcontract voor voorinstellingen. Beheerders die niet-Node-opdrachten nodig hebben, kunnen rechtstreeks zelfstandige handmatige exec-providers configureren.

OpenClaw leidt trustedDirs voor manifestvoorinstellingen af van de pluginroot en, voor ${node}-voorinstellingen, van de map van het huidige uitvoerbare Node-bestand. In het manifest opgegeven trustedDirs worden genegeerd. Andere exec-provideropties zoals timeoutMs, noOutputTimeoutMs, maxOutputBytes, jsonOnly, env, passEnv en allowInsecurePath worden doorgegeven aan de normale SecretRef-configuratie voor exec-providers.

Naslag voor modelPricing

Gebruik modelPricing wanneer een provider prijsstellingsgedrag op het besturingsvlak nodig heeft voordat de runtime wordt geladen. De prijsstellingscache van de Gateway leest deze metagegevens zonder providerruntimecode te importeren.

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

Providervelden:

Bronvelden:

OpenClaw-providerindex

De OpenClaw-providerindex bestaat uit door OpenClaw beheerde voorbeeldmetagegevens voor providers waarvan de plugins mogelijk nog niet zijn geïnstalleerd. Deze maakt geen deel uit van een pluginmanifest. Pluginmanifesten blijven de gezaghebbende bron voor geïnstalleerde plugins. De providerindex is het interne terugvalcontract dat toekomstige oppervlakken voor installeerbare providers en modelkiezers vóór installatie gebruiken wanneer een providerplugin niet is geïnstalleerd.

Volgorde van catalogusautoriteit:

1. Gebruikersconfiguratie.
2. Manifest van geïnstalleerde plugin modelCatalog.
3. Modelcataloguscache na expliciet vernieuwen.
4. Voorbeeldrijen van de OpenClaw-providerindex.

De Provider Index mag geen secrets, ingeschakelde status, runtime-hooks of live accountspecifieke modelgegevens bevatten. De voorbeeldcatalogi gebruiken dezelfde modelCatalog-provider-rijstructuur als Plugin-manifesten, maar moeten beperkt blijven tot stabiele weergavemetadata, tenzij runtime-adaptervelden zoals api, baseUrl, prijzen of compatibiliteitsvlaggen bewust worden afgestemd op het geïnstalleerde Plugin-manifest. Providers met live /models-detectie moeten vernieuwde rijen via het expliciete cachepad voor de modelcatalogus schrijven, in plaats van provider-API's aan te roepen tijdens normale vermeldingen of onboarding.

Provider Index-vermeldingen kunnen ook metadata voor installeerbare Plugins bevatten voor providers waarvan de Plugin uit de kern is verplaatst of anderszins nog niet is geïnstalleerd. Deze metadata volgt het patroon van de kanaalcatalogus: pakketnaam, npm-installatiespecificatie, verwachte integriteit en eenvoudige labels voor authenticatiekeuzes volstaan om een installeerbare configuratieoptie te tonen. Zodra de Plugin is geïnstalleerd, heeft het manifest daarvan voorrang en wordt de Provider Index-vermelding voor die provider genegeerd.

openclaw doctor --fix migreert een kleine, gesloten set verouderde manifest-capaciteitssleutels op het hoogste niveau naar contracts.*: speechProviders, mediaUnderstandingProviders, imageGenerationProviders en tools. Geen van deze sleutels (of enige andere capaciteitenlijst) wordt nog als manifestveld op het hoogste niveau gelezen; bij normaal laden van manifesten worden ze alleen onder contracts herkend.

Manifest versus package.json

De twee bestanden hebben verschillende functies:

Als je niet zeker weet waar bepaalde metadata thuishoort, gebruik je deze regel:

• als OpenClaw deze moet kennen voordat Plugin-code wordt geladen, plaats je deze in openclaw.plugin.json
• als deze betrekking heeft op pakkettering, toegangsbestanden of npm-installatiegedrag, plaats je deze in package.json

package.json-velden die detectie beïnvloeden

Sommige Plugin-metadata van vóór de runtime staat bewust in package.json onder het openclaw-blok in plaats van in openclaw.plugin.json. openclaw.bundle en openclaw.bundle.json zijn geen OpenClaw-Plugin-contracten; native Plugins moeten openclaw.plugin.json gebruiken, samen met de ondersteunde package.json#openclaw-velden hieronder.

Belangrijke voorbeelden:

Manifestmetadata bepaalt welke provider-, kanaal- en configuratiekeuzes tijdens onboarding worden weergegeven voordat de runtime wordt geladen. package.json#openclaw.install vertelt onboarding hoe die Plugin moet worden opgehaald of ingeschakeld wanneer de gebruiker een van die keuzes selecteert. Verplaats installatieaanwijzingen niet naar openclaw.plugin.json.

Gebruik voor openclaw.channel.cliAddOptions de syntaxis van Commander voor lange opties, zoals --initial-sync-limit <n>. Stel valueType: "int" in om een niet-negatief geheel getal te parseren of valueType: "list" om invoer die door komma's, puntkomma's of nieuwe regels wordt gescheiden op te splitsen in tekenreeksen voordat de configuratieadapter van de Plugin deze ontvangt. Laat valueType weg om de geparste Commander-waarde ongewijzigd door te geven.

openclaw.install.minHostVersion wordt tijdens installatie en het laden van het manifestregister afgedwongen voor niet-gebundelde Plugin-bronnen. Ongeldige waarden worden geweigerd; nieuwere maar geldige waarden zorgen ervoor dat externe Plugins op oudere hosts worden overgeslagen. Er wordt aangenomen dat gebundelde bron-Plugins dezelfde versie hebben als de host-checkout.

openclaw.install.requiredPlatformPackages is bedoeld voor npm-pakketten die vereiste native binaire bestanden beschikbaar stellen via optionele, platformspecifieke aliassen. Vermeld voor elke ondersteunde platformalias de kale npm-pakketnaam. Tijdens de npm-installatie verifieert OpenClaw alleen de gedeclareerde alias waarvan de lockbestandbeperkingen overeenkomen met de huidige host. Als npm succes meldt maar die alias weglaat, probeert OpenClaw het eenmaal opnieuw met een nieuwe cache en draait het de installatie terug als de alias nog steeds ontbreekt.

openclaw.compat.pluginApi wordt tijdens pakketinstallatie afgedwongen voor niet-gebundelde Plugin-bronnen. Gebruik dit voor de ondergrens van de OpenClaw-Plugin-SDK/runtime-API waartegen het pakket is gebouwd. Dit kan strenger zijn dan minHostVersion wanneer een Plugin-pakket een nieuwere API nodig heeft, maar voor andere flows toch een lagere installatieaanwijzing behoudt. Officiële OpenClaw-releasesynchronisatie verhoogt bestaande officiële ondergrenzen voor Plugin-API's standaard naar de OpenClaw-releaseversie, maar releases die alleen Plugins bevatten kunnen een lagere ondergrens behouden wanneer het pakket bewust oudere hosts ondersteunt. Gebruik niet alleen de pakketversie als compatibiliteitscontract. peerDependencies.openclaw blijft npm-pakketmetadata; OpenClaw gebruikt het openclaw.compat.pluginApi-contract voor beslissingen over installatiecompatibiliteit.

Officiële metadata voor installatie op aanvraag moet clawhubSpec gebruiken wanneer de Plugin op ClawHub wordt gepubliceerd; onboarding behandelt dit als de externe voorkeursbron en registreert na installatie de feiten over het ClawHub-artefact. npmSpec blijft de compatibiliteitsterugval voor pakketten die nog niet naar ClawHub zijn verplaatst.

Exacte vastlegging van npm-versies staat al in npmSpec, bijvoorbeeld "npmSpec": "@wecom/wecom-openclaw-plugin@1.2.3". Officiële externe catalogusvermeldingen moeten exacte specificaties combineren met expectedIntegrity, zodat updateflows veilig stoppen als het opgehaalde npm-artefact niet langer overeenkomt met de vastgelegde release. Interactieve onboarding biedt voor compatibiliteit nog steeds vertrouwde npm-registerspecificaties aan, waaronder kale pakketnamen en dist-tags. Catalogusdiagnostiek kan onderscheid maken tussen exacte, zwevende, op integriteit vastgelegde, zonder integriteit vastgelegde, qua pakketnaam niet-overeenkomende en ongeldige standaardkeuzebronnen. Ook wordt gewaarschuwd wanneer expectedIntegrity aanwezig is, maar er geen geldige npm-bron is die ermee kan worden vastgelegd. Wanneer expectedIntegrity aanwezig is, dwingen installatie- en updateflows deze af; wanneer deze is weggelaten, wordt de registerresolutie zonder integriteitsvastlegging geregistreerd.

Kanaal-Plugins moeten openclaw.setupEntry aanbieden wanneer status-, kanaallijst- of SecretRef-scans geconfigureerde accounts moeten identificeren zonder de volledige runtime te laden. Het configuratietoegangspunt moet kanaalmetadata plus configuratie-, status- en secrets-adapters bevatten die veilig tijdens de configuratie kunnen worden gebruikt; bewaar netwerkclients, Gateway-listeners en transportruntimes in het hoofdtoegangspunt van de extensie.

Runtime-entrypointvelden overschrijven pakketgrenscontroles voor bron-entrypointvelden niet. Zo kan openclaw.runtimeExtensions een ontsnappend openclaw.extensions-pad niet laadbaar maken.

openclaw.install.allowInvalidConfigRecovery is bewust beperkt. Het maakt niet willekeurige defecte configuraties installeerbaar. Momenteel staat het alleen toe dat installatieflows herstellen van specifieke verouderde upgradefouten van gebundelde plugins, zoals een ontbrekend pad naar een gebundelde plugin of een verouderde channels.<id>-vermelding voor diezelfde gebundelde plugin. Niet-gerelateerde configuratiefouten blokkeren de installatie nog steeds en verwijzen beheerders naar openclaw doctor --fix.

openclaw.channel.persistedAuthState is pakketmetadata voor een kleine controlemodule:

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

Gebruik dit wanneer installatie-, doctor-, status- of alleen-lezen-aanwezigheidsflows een goedkope ja/nee-controle van authenticatie nodig hebben voordat de volledige kanaalplugin wordt geladen. Persistente authenticatiestatus is geen geconfigureerde kanaalstatus: gebruik deze metadata niet om plugins automatisch in te schakelen, runtime-afhankelijkheden te repareren of te bepalen of een kanaalruntime moet worden geladen. De doelexport moet een kleine functie zijn die alleen persistente status leest; leid deze niet via de volledige runtime-barrel van het kanaal.

openclaw.channel.configuredState ondersteunt goedkope controles op configuratie. Geef de voorkeur aan declaratieve omgevingsmetadata wanneer omgevingsvariabelen voldoende zijn:

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

Gebruik env.allOf wanneer elke vermelde variabele vereist is en env.anyOf wanneer één niet-lege variabele voldoende is. Als een kleine niet-runtimecontrole meer nodig heeft dan omgevingsmetadata, gebruik dan specifier plus exportName, zoals weergegeven voor persistedAuthState; wanneer env aanwezig is, gebruikt OpenClaw dit zonder die module te laden. Als de controle volledige configuratieresolutie of de echte kanaalruntime nodig heeft, houd die logica dan in de config.hasConfiguredState-hook van de plugin.

Detectieprioriteit (dubbele plugin-id's)

OpenClaw detecteert plugins vanuit drie hoofdmappen, die in deze volgorde worden gecontroleerd: gebundelde plugins die met OpenClaw worden geleverd, de globale installatiehoofdmap (~/.openclaw/extensions) en de huidige werkruimtehoofdmap (<workspace>/.openclaw/extensions), plus eventuele expliciete plugins.load.paths-vermeldingen.

Als twee detecties dezelfde id delen, wordt alleen het manifest met de hoogste prioriteit behouden; duplicaten met een lagere prioriteit worden verwijderd in plaats van ernaast geladen. Prioriteit, van hoog naar laag:

1. Door configuratie geselecteerd — een pad dat expliciet is vastgezet in plugins.entries.<id>
2. Globale installatie die overeenkomt met een bijgehouden installatierecord — een plugin die via openclaw plugin install/openclaw plugin update is geïnstalleerd en die door de installatieregistratie van OpenClaw voor diezelfde id wordt herkend, zelfs wanneer de id ook bij een gebundelde plugin hoort
3. Gebundeld — plugins die met OpenClaw worden geleverd
4. Werkruimte — plugins die relatief aan de huidige werkruimte worden gedetecteerd
5. Elke andere gedetecteerde kandidaat

Gevolgen:

• Een geforkte of verouderde kopie van een gebundelde plugin die niet wordt bijgehouden en zich in de werkruimte of globale hoofdmap bevindt, overschaduwt de gebundelde build niet.
• Om een gebundelde plugin te overschrijven, voer je openclaw plugin install uit voor die id, zodat de bijgehouden globale installatie een hogere prioriteit krijgt dan de gebundelde kopie, of zet je een specifiek pad vast via plugins.entries.<id>, zodat dit wint op basis van door configuratie geselecteerde prioriteit.
• Het verwijderen van duplicaten wordt gelogd, zodat Doctor en diagnostiek bij het opstarten naar de verworpen kopie kunnen verwijzen.
• Door configuratie geselecteerde overschrijvingen van duplicaten worden in de diagnostiek als expliciete overschrijvingen beschreven, maar genereren nog steeds een waarschuwing, zodat verouderde forks en onbedoelde overschaduwingen zichtbaar blijven.

Vereisten voor JSON Schema

• Elke plugin moet een JSON Schema meeleveren, zelfs als deze geen configuratie accepteert.
• Een leeg schema is toegestaan (bijvoorbeeld { "type": "object", "additionalProperties": false }).
• Schema's worden gevalideerd wanneer configuratie wordt gelezen of geschreven, niet tijdens runtime.
• Wanneer je een gebundelde plugin uitbreidt of forkt met nieuwe configuratiesleutels, werk dan tegelijkertijd de openclaw.plugin.json configSchema van die plugin bij. Schema's van gebundelde plugins zijn strikt, dus het toevoegen van plugins.entries.<id>.config.myNewKey aan de gebruikersconfiguratie zonder myNewKey aan configSchema.properties toe te voegen, wordt geweigerd voordat de runtime van de plugin wordt geladen.

Voorbeeld van een schema-uitbreiding:

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

Validatiegedrag

• Onbekende channels.*-sleutels zijn fouten, tenzij de kanaal-id door een pluginmanifest wordt gedeclareerd. Als dezelfde id ook voorkomt in plugins.allow, plugins.entries of plugins.installs (een plugin waarnaar wordt verwezen maar die momenteel niet kan worden gedetecteerd), verlaagt OpenClaw dit in plaats daarvan tot een waarschuwing.
• plugins.entries.<id>, plugins.allow en plugins.deny die naar onbekende plugin-id's verwijzen, zijn waarschuwingen ("verouderde configuratievermelding genegeerd"), geen fouten, zodat upgrades en verwijderde of hernoemde plugins het starten van de Gateway niet blokkeren.
• plugins.slots.memory die naar een onbekende plugin-id verwijst, is een fout, behalve voor de bekende officiële externe plugin memory-lancedb, waarvoor in plaats daarvan een waarschuwing wordt gegeven.
• Als een plugin is geïnstalleerd maar een defect of ontbrekend manifest of schema heeft, mislukt de validatie en rapporteert Doctor de pluginfout.
• Als er pluginconfiguratie bestaat maar de plugin uitgeschakeld is, wordt de configuratie behouden en verschijnt er een waarschuwing in Doctor en de logboeken.

Zie Configuratiereferentie voor het volledige plugins.*-schema.

Opmerkingen

• Het manifest is vereist voor systeemeigen OpenClaw-plugins, inclusief laden vanuit het lokale bestandssysteem. De runtime laadt de pluginmodule nog steeds afzonderlijk; het manifest dient alleen voor detectie en validatie.
• Systeemeigen manifesten worden geparseerd met JSON5, zodat opmerkingen, afsluitende komma's en sleutels zonder aanhalingstekens worden geaccepteerd zolang de uiteindelijke waarde nog steeds een object is.
• Alleen gedocumenteerde manifestvelden worden door de manifestlader gelezen. Vermijd aangepaste sleutels op het hoogste niveau.
• channels, providers, cliBackends en skills kunnen allemaal worden weggelaten wanneer een plugin ze niet nodig heeft.
• providerCatalogEntry moet lichtgewicht blijven en mag geen brede runtimecode importeren; gebruik dit voor statische metadata van de providercatalogus of beperkte detectiedescriptors, niet voor uitvoering tijdens aanvragen.
• Exclusieve plugintypen worden geselecteerd via plugins.slots.*: kind: "memory" via plugins.slots.memory (standaard memory-core), kind: "context-engine" via plugins.slots.contextEngine (standaard legacy).
• Declareer het exclusieve plugintype in dit manifest. Runtime-entry OpenClawPluginDefinition.kind is verouderd en blijft alleen bestaan als compatibiliteitsfallback voor oudere plugins.
• Metadata voor omgevingsvariabelen in setup.providers[].envVars is alleen declaratief. Status, audit, validatie van Cron-bezorging en andere alleen-lezen-oppervlakken passen nog steeds het pluginvertrouwen en het effectieve activeringsbeleid toe voordat een omgevingsvariabele als geconfigureerd wordt beschouwd.
• Zie Runtime-hooks voor providers voor runtimewizardmetadata waarvoor providercode vereist is.
• Als je plugin afhankelijk is van systeemeigen modules, documenteer dan de buildstappen en eventuele vereisten voor de toelatingslijst van de pakketbeheerder (bijvoorbeeld pnpm allow-build-scripts + pnpm rebuild <package>).

Gerelateerd