Pluginmanifest

Deze pagina is alleen voor het native OpenClaw-Pluginmanifest.

Zie Plugin-bundels voor compatibele bundelindelingen.

Compatibele bundelindelingen gebruiken andere manifestbestanden:

• Codex-bundel: .codex-plugin/plugin.json
• Claude-bundel: .claude-plugin/plugin.json of de standaard Claude-componentindeling zonder manifest
• Cursor-bundel: .cursor-plugin/plugin.json

OpenClaw detecteert die bundelindelingen ook automatisch, maar ze worden niet gevalideerd tegen het hier beschreven openclaw.plugin.json-schema.

Voor compatibele bundels leest OpenClaw momenteel bundelmetadata plus gedeclareerde skill-roots, Claude-commandoroots, standaardwaarden uit Claude-bundel settings.json, standaardwaarden voor Claude-bundel-LSP en ondersteunde hookpakketten wanneer de indeling overeenkomt met de runtimeverwachtingen van OpenClaw.

Elke native OpenClaw-Plugin moet een openclaw.plugin.json-bestand leveren in de Plugin-root. OpenClaw gebruikt dit manifest om configuratie te valideren zonder Plugin-code uit te voeren. Ontbrekende of ongeldige manifesten worden behandeld als Plugin-fouten en blokkeren configuratievalidatie.

Zie de volledige gids voor het Pluginsysteem: Plugins. Voor het native capaciteitsmodel en de huidige richtlijnen voor externe compatibiliteit: Capaciteitsmodel.

Wat dit bestand doet

openclaw.plugin.json is de metadata die OpenClaw leest voordat het je Plugin-code laadt. Alles hieronder moet goedkoop genoeg zijn om te inspecteren zonder de Plugin-runtime te starten.

Gebruik het voor:

• Plugin-identiteit, configuratievalidatie en hints voor de configuratie-UI
• metadata voor auth, onboarding en installatie (alias, automatisch inschakelen, provider-env-vars, auth-keuzes)
• activeringshints voor control-plane-oppervlakken
• eigenaarschap van verkorte modelfamilies
• statische momentopnamen van capaciteits-eigenaarschap (contracts)
• metadata voor de QA-runner die de gedeelde openclaw qa-host kan inspecteren
• kanaalspecifieke configuratiemetadata samengevoegd in catalogus- en validatieoppervlakken

Gebruik het niet voor: het registreren van runtimegedrag, het declareren van code-entrypoints, of npm-installatiemetadata. Die horen thuis in je Plugin-code en package.json.

Minimaal voorbeeld

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

Uitgebreid voorbeeld

{  "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"],  "providerAuthEnvVars": {    "openrouter": ["OPENROUTER_API_KEY"]  },  "providerAuthAliases": {    "openrouter-coding": "openrouter"  },  "channelEnvVars": {    "openrouter-chatops": ["OPENROUTER_CHATOPS_TOKEN"]  },  "providerAuthChoices": [    {      "provider": "openrouter",      "method": "api-key",      "choiceId": "openrouter-api-key",      "choiceLabel": "OpenRouter API key",      "groupId": "openrouter",      "groupLabel": "OpenRouter",      "optionKey": "openrouterApiKey",      "cliFlag": "--openrouter-api-key",      "cliOption": "--openrouter-api-key <key>",      "cliDescription": "OpenRouter API key",      "onboardingScopes": ["text-inference"]    }  ],  "uiHints": {    "apiKey": {      "label": "API key",      "placeholder": "sk-or-v1-...",      "sensitive": true    }  },  "configSchema": {    "type": "object",    "additionalProperties": false,    "properties": {      "apiKey": {        "type": "string"      }    }  }}

Referentie voor velden op topniveau

Referentie voor metagegevens van generatieproviders

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

Gebruik deze velden alleen voor goedkope, declaratieve feiten. Transport, aanvraag- transformaties, tokenvernieuwing, validatie van inloggegevens en daadwerkelijk 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 configSignals-vermelding ondersteunt:

Elke mode-guard ondersteunt:

Elke authSignals-vermelding ondersteunt:

Elke providerBaseUrl-guard ondersteunt:

Referentie voor toolmetagegevens

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

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

Als een tool geen toolMetadata heeft, behoudt OpenClaw het bestaande gedrag en laadt het de eigenaarplugin wanneer het toolcontract overeenkomt met beleid. Voor hot-path tools waarvan de factory afhankelijk is van auth/configuratie, moeten pluginauteurs toolMetadata declareren in plaats van core runtime te laten importeren om het te vragen.

Referentie voor providerAuthChoices

Elke providerAuthChoices-vermelding beschrijft één onboarding- of auth-keuze. OpenClaw leest dit voordat de runtime van de provider wordt geladen. Providerinstallatielijsten gebruiken deze manifestkeuzes, uit descriptors afgeleide installatiekeuzes en metagegevens uit de installatiecatalogus zonder de runtime van de provider te laden.

Referentie voor commandAliases

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

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

activatiereferentie

Gebruik activation wanneer de plugin goedkoop kan declareren welke control-plane-gebeurtenissen deze moeten opnemen in een activatie-/laadplan.

Dit blok is planner-metadata, geen levenscyclus-API. Het registreert geen runtimegedrag, vervangt register(...) niet en belooft niet dat plugincode al is uitgevoerd. De activatieplanner gebruikt deze velden om kandidaat-plugins te beperken voordat wordt teruggevallen op bestaande manifest-eigenaarschapsmetadata zoals providers, channels, commandAliases, setup.providers, contracts.tools en hooks.

Geef de voorkeur aan de smalste metadata die eigenaarschap al beschrijft. Gebruik providers, channels, commandAliases, setup-descriptors of contracts wanneer die velden de relatie uitdrukken. Gebruik activation voor extra planner-hints die niet door die eigenaarschapsvelden kunnen worden weergegeven. Gebruik top-level cliBackends voor CLI-runtimealiases zoals claude-cli, codex-cli of google-gemini-cli; activation.onAgentHarnesses is alleen voor ingebedde agent-harness-id's die nog geen eigenaarschapsveld hebben.

Dit blok is alleen metadata. Het registreert geen runtimegedrag en vervangt register(...), setupEntry of andere runtime-/plugin-entrypoints niet. Huidige consumers gebruiken het als een beperkende hint vóór breder laden van plugins, dus ontbrekende niet-opstartactivatiemetadata kost meestal alleen prestaties; het zou de correctheid niet moeten veranderen zolang manifest-eigenaarschapsfallbacks nog bestaan.

Elke plugin moet activation.onStartup bewust instellen. Stel dit alleen in op true wanneer de plugin tijdens het opstarten van de Gateway moet draaien. Stel dit in op false wanneer de plugin inert is bij het opstarten en alleen via smallere triggers moet laden. Het weglaten van onStartup laadt de plugin niet langer impliciet bij het opstarten; gebruik expliciete activatiemetadata voor opstart-, kanaal-, config-, agent-harness-, geheugen- of andere smallere activatietriggers.

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

Huidige live consumers:

• Gateway-opstartplanning gebruikt activation.onStartup voor expliciete opstartimport
• door opdrachten getriggerde CLI-planning valt terug op legacy commandAliases[].cliCommand of commandAliases[].name
• agent-runtime-opstartplanning gebruikt activation.onAgentHarnesses voor ingebedde harnesses en top-level cliBackends[] voor CLI-runtimealiases
• door kanalen getriggerde setup-/kanaalplanning valt terug op legacy channels[]-eigenaarschap wanneer expliciete kanaalactivatiemetadata ontbreekt
• pluginplanning bij opstarten gebruikt activation.onConfigPaths voor niet-kanaal-root config-oppervlakken zoals het browser-blok van de gebundelde browserplugin
• door providers getriggerde setup-/runtimeplanning valt terug op legacy providers[] en top-level cliBackends[]-eigenaarschap wanneer expliciete provideractivatiemetadata ontbreekt

Planner-diagnostiek kan expliciete activatiehints onderscheiden van manifest-eigenaarschapsfallback. Bijvoorbeeld, activation-command-hint betekent dat activation.onCommands overeenkwam, terwijl manifest-command-alias betekent dat de planner in plaats daarvan commandAliases-eigenaarschap gebruikte. Deze redenlabels zijn voor hostdiagnostiek en tests; plugin-auteurs moeten de metadata blijven declareren die eigenaarschap het best beschrijft.

qaRunners-referentie

Gebruik qaRunners wanneer een plugin een of meer transportrunners toevoegt onder de gedeelde openclaw qa-root. Houd deze metadata goedkoop en statisch; de plugin-runtime blijft eigenaar van de daadwerkelijke CLI-registratie via een lichtgewicht runtime-api.ts-oppervlak dat qaRunnerCliRegistrations exporteert.

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

setup-referentie

Gebruik setup wanneer setup- en onboardingoppervlakken goedkope plugin-eigen metadata nodig hebben voordat runtimes laden.

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

Top-level cliBackends blijft geldig en blijft CLI-inferentiebackends beschrijven. setup.cliBackends is het setup-specifieke descriptoroppervlak voor control-plane-/setupflows die metadata-only moeten blijven.

Wanneer aanwezig, zijn setup.providers en setup.cliBackends het voorkeursoppervlak voor descriptor-first lookup bij setupdetectie. Als de descriptor alleen de kandidaat-plugin beperkt en setup nog rijkere runtimehooks voor setup nodig heeft, stel dan requiresRuntime: true in en houd setup-api op zijn plaats als het fallback-uitvoeringspad.

OpenClaw neemt ook setup.providers[].envVars op in generieke provider-authenticatie- en env-var-lookups. providerAuthEnvVars blijft ondersteund via een compatibiliteitsadapter tijdens de deprecatieperiode, maar niet-gebundelde plugins die dit nog gebruiken ontvangen een manifestdiagnose. Nieuwe plugins moeten setup-/status-env-metadata op setup.providers[].envVars zetten.

OpenClaw kan ook eenvoudige setupkeuzes afleiden uit setup.providers[].authMethods wanneer er geen setup-entry beschikbaar is, of wanneer setup.requiresRuntime: false declareert dat setup-runtime niet nodig is. Expliciete providerAuthChoices-entries blijven de voorkeur houden voor aangepaste labels, CLI-flags, onboardingbereik en assistentmetadata.

Stel requiresRuntime: false alleen in wanneer die descriptors voldoende zijn voor het setupoppervlak. OpenClaw behandelt expliciet false als een descriptor-only contract en voert setup-api of openclaw.setupEntry niet uit voor setup-lookup. Als een descriptor-only plugin nog steeds een van die setup-runtime-entries levert, rapporteert OpenClaw een additieve diagnose en blijft die negeren. Een weggelaten requiresRuntime behoudt legacy fallbackgedrag zodat bestaande plugins die descriptors zonder de vlag hebben toegevoegd niet breken.

Omdat setup-lookup plugin-eigen setup-api-code kan uitvoeren, moeten genormaliseerde waarden voor setup.providers[].id en setup.cliBackends[] uniek blijven in alle ontdekte plugins. Ambigu eigenaarschap faalt gesloten in plaats van een winnaar uit ontdekkingsvolgorde te kiezen.

Wanneer setup-runtime wel wordt uitgevoerd, rapporteert setupregistry-diagnostiek descriptorafwijking als setup-api een provider of CLI-backend registreert die de manifestdescriptors niet declareren, of als een descriptor geen overeenkomende runtimeregistratie heeft. Deze diagnoses zijn additief en wijzen legacy plugins niet af.

setup.providers-referentie

authEvidence is voor lokale credentialmarkers die eigendom zijn van de provider en kunnen worden geverifieerd zonder runtimecode te laden. Deze controles moeten goedkoop en lokaal blijven: geen netwerkaanroepen, geen leesbewerkingen uit keychains of secretmanagers, geen shellopdrachten en geen provider-API-probes.

Ondersteunde bewijsvermeldingen:

setup-velden

uiHints-referentie

uiHints is een map van configveldnamen naar kleine rendering-hints.

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

Elke veldhint kan bevatten:

contracts-referentie

Gebruik contracts alleen voor statische metadata over capability-eigendom die OpenClaw kan lezen zonder de pluginruntime te importeren.

{  "contracts": {    "agentToolResultMiddleware": ["pi", "codex"],    "externalAuthProviders": ["acme-ai"],    "speechProviders": ["openai"],    "realtimeTranscriptionProviders": ["openai"],    "realtimeVoiceProviders": ["openai"],    "memoryEmbeddingProviders": ["local"],    "mediaUnderstandingProviders": ["openai", "openai-codex"],    "imageGenerationProviders": ["openai"],    "videoGenerationProviders": ["qwen"],    "webFetchProviders": ["firecrawl"],    "webSearchProviders": ["gemini"],    "migrationProviders": ["hermes"],    "tools": ["firecrawl_search", "firecrawl_scrape"]  }}

Elke lijst is optioneel:

contracts.embeddedExtensionFactories blijft behouden voor gebundelde Codex app-server-only extensiefactories. Gebundelde tool-result-transformaties moeten in plaats daarvan contracts.agentToolResultMiddleware declareren en registreren met api.registerAgentToolResultMiddleware(...). Externe plugins kunnen geen tool-result-middleware registreren omdat de seam tooluitvoer met veel vertrouwen kan herschrijven voordat het model die ziet.

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

Providerplugins die resolveExternalAuthProfiles implementeren, moeten contracts.externalAuthProviders declareren. Plugins zonder de declaratie lopen nog steeds via een verouderde compatibiliteitsfallback, maar die fallback is trager en wordt na de migratieperiode verwijderd.

Gebundelde memory-embeddingproviders moeten contracts.memoryEmbeddingProviders declareren voor elk adapter-id dat ze beschikbaar maken, inclusief ingebouwde adapters zoals local. Zelfstandige CLI-paden gebruiken dit manifestcontract om alleen de eigenaar-plugin te laden voordat de volledige Gateway-runtime providers heeft geregistreerd.

mediaUnderstandingProviderMetadata-referentie

Gebruik mediaUnderstandingProviderMetadata wanneer een media-understandingprovider standaardmodellen, fallback-prioriteit voor auto-auth of native documentondersteuning heeft die generieke core-helpers nodig hebben voordat runtimes laden. Sleutels moeten ook worden gedeclareerd in contracts.mediaUnderstandingProviders.

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

Elke providervermelding kan bevatten:

channelConfigs-referentie

Gebruik channelConfigs wanneer een kanaalplugin goedkope configmetadata nodig heeft voordat runtime laadt. Alleen-lezen discovery voor kanaalsetup/status kan deze metadata direct gebruiken voor geconfigureerde externe kanalen wanneer er geen setupvermelding beschikbaar is, of wanneer setup.requiresRuntime: false verklaart dat setupruntime overbodig is.

channelConfigs is pluginmanifestmetadata, geen nieuwe top-level gebruikersconfigsectie. Gebruikers configureren kanaalinstanties nog steeds onder channels.<channel-id>. OpenClaw leest manifestmetadata om te bepalen welke plugin eigenaar is van dat geconfigureerde kanaal voordat 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 kan OpenClaw de plugin nog steeds laden, maar cold-path configschema-, setup- en Control UI-oppervlakken kunnen de kanaaleigen optiestructuur pas kennen wanneer pluginruntime wordt uitgevoerd.

channelConfigs.<channel-id>.commands.nativeCommandsAutoEnabled en nativeSkillsAutoEnabled kunnen statische auto-standaarden declareren voor command-config checks die worden uitgevoerd voordat de kanaalruntime laadt. Gebundelde kanalen kunnen ook dezelfde standaarden publiceren via package.json#openclaw.channel.commands naast hun andere package-eigen kanaalcatalogusmetadata.

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

Elke kanaalvermelding kan bevatten:

Een andere kanaalplugin vervangen

Gebruik preferOver wanneer je plugin de voorkeurs-eigenaar is voor een kanaal-id dat een andere plugin ook kan leveren. 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 lager geprioriteerde plugin alleen was geselecteerd omdat deze gebundeld is of standaard is ingeschakeld, schakelt OpenClaw deze uit in de effectieve runtimeconfiguratie zodat één plugin eigenaar is van het kanaal en de tools ervan. Expliciete gebruikersselectie wint nog steeds: als de gebruiker beide plugins expliciet inschakelt, behoudt OpenClaw die keuze en meldt het dubbele kanaal-/tooldiagnostiek in plaats van de aangevraagde pluginset stilzwijgend te wijzigen.

Houd preferOver beperkt tot plugin-id's die echt hetzelfde kanaal kunnen leveren. Het is geen algemeen prioriteitsveld en het hernoemt geen gebruikersconfiguratiesleutels.

modelSupport-referentie

Gebruik modelSupport wanneer OpenClaw je providerplugin moet afleiden uit verkorte model-id's zoals gpt-5.5 of claude-sonnet-4.6 voordat de pluginruntime wordt geladen.

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

OpenClaw past deze volgorde toe:

• expliciete provider/model-referenties gebruiken de metadata van het eigenaar-providers-manifest
• modelPatterns gaan vóór modelPrefixes
• als één niet-gebundelde plugin en één gebundelde plugin beide overeenkomen, wint de niet-gebundelde plugin
• resterende ambiguïteit wordt genegeerd totdat de gebruiker of configuratie een provider specificeert

Velden:

modelCatalog-referentie

Gebruik modelCatalog wanneer OpenClaw provider-modelmetadata moet kennen voordat de pluginruntime wordt geladen. Dit is de door het manifest beheerde bron voor vaste catalogusrijen, provideraliassen, onderdrukkingsregels en ontdekkingsmodus. Runtimeverversing hoort nog steeds thuis in providerruntimecode, maar het manifest vertelt 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"    }  }}

Topnivelevelden:

aliases neemt deel aan provider-eigenaarschaplookup voor modelcatalogusplanning. Aliasdoelen moeten providers op topniveau zijn waarvan dezelfde plugin eigenaar is. Wanneer een op provider gefilterde lijst een alias gebruikt, kan OpenClaw het eigenaarmanifest lezen en alias-API-/basis-URL-overschrijvingen toepassen zonder providerruntime te laden. Aliassen breiden ongefilterde catalogusvermeldingen niet uit; brede lijsten geven alleen de canonieke providerrijen van de eigenaar weer.

suppressions vervangt de oude providerruntime-hook suppressBuiltInModel. Onderdrukkingsitems worden alleen gerespecteerd wanneer de provider eigendom is van de plugin of is gedeclareerd als een modelCatalog.aliases-sleutel die verwijst naar een provider in eigendom. Runtime- onderdrukkingshooks worden niet langer aangeroepen tijdens modelresolutie.

Providervelden:

Modelvelden:

Onderdrukkingsvelden:

Plaats geen gegevens die alleen runtime zijn in modelCatalog. Gebruik static alleen wanneer manifest rijen volledig genoeg zijn zodat op provider gefilterde lijst- en kiezeroppervlakken registry-/runtime-detectie kunnen overslaan. Gebruik refreshable wanneer manifestrijen nuttige lijstbare zaden of aanvullingen zijn, maar een refresh/cache later meer rijen kan toevoegen; refreshable-rijen zijn op zichzelf niet gezaghebbend. Gebruik runtime wanneer OpenClaw de provider-runtime moet laden om de lijst te kennen.

modelIdNormalization-referentie

Gebruik modelIdNormalization voor goedkope, door de provider beheerde opschoning van model-id's die moet gebeuren voordat de provider-runtime wordt geladen. Dit houdt aliassen zoals korte modelnamen, provider-lokale verouderde id's en proxy-prefixregels in het manifest van de eigenaar-Plugin in plaats van in kern-tabellen voor modelselectie.

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

Providervelden:

providerEndpoints-referentie

Gebruik providerEndpoints voor endpointclassificatie die generiek aanvraagbeleid moet kennen voordat de provider-runtime wordt geladen. De kern blijft eigenaar van de betekenis van elke endpointClass; pluginmanifests bezitten de host- en basis-URL-metadata.

Endpointvelden:

providerRequest-referentie

Gebruik providerRequest voor goedkope metadata voor aanvraagcompatibiliteit die generiek aanvraagbeleid nodig heeft zonder de provider-runtime te laden. Houd gedragsspecifieke payload-herschrijving in provider-runtimehooks of gedeelde helpers voor providerfamilies.

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

Providervelden:

modelPricing-referentie

Gebruik modelPricing wanneer een provider control-plane-prijsgedrag nodig heeft voordat de runtime wordt geladen. De Gateway-prijscache leest deze metadata zonder provider-runtimecode te importeren.

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

Providervelden:

Bronvelden:

OpenClaw Provider Index

De OpenClaw Provider Index is door OpenClaw beheerde previewmetadata voor providers waarvan de plugins mogelijk nog niet zijn geïnstalleerd. Het maakt geen deel uit van een pluginmanifest. Pluginmanifests blijven de autoriteit voor geïnstalleerde plugins. De Provider Index is het interne fallbackcontract dat toekomstige oppervlakken voor installeerbare providers en pre-install modelkiezers zullen gebruiken wanneer een providerplugin niet is geïnstalleerd.

Volgorde van catalogusautoriteit:

1. Gebruikersconfiguratie.
2. Geïnstalleerd pluginmanifest modelCatalog.
3. Modelcataloguscache van expliciete refresh.
4. Previewrijen van OpenClaw Provider Index.

De Provider Index mag geen geheimen, ingeschakelde status, runtimehooks of live accountspecifieke modelgegevens bevatten. De previewcatalogi gebruiken dezelfde modelCatalog-provider-rijvorm als pluginmanifests, maar moeten beperkt blijven tot stabiele weergavemetadata tenzij runtime-adaptervelden zoals api, baseUrl, prijzen of compatibiliteitsvlaggen bewust afgestemd blijven op het geïnstalleerde pluginmanifest. Providers met live /models-detectie moeten ververste rijen schrijven via het expliciete cachepad voor de modelcatalogus in plaats van normale lijst- of onboarding-aanroepen provider-API's te laten aanroepen.

Provider Index-items kunnen ook metadata voor installeerbare plugins bevatten voor providers waarvan de plugin uit de kern is verplaatst of anders nog niet is geïnstalleerd. Deze metadata weerspiegelt het kanaalcataloguspatroon: pakketnaam, npm-installatiespecificatie, verwachte integriteit en goedkope labels voor auth-keuzes zijn genoeg om een installeerbare setupoptie te tonen. Zodra de plugin is geïnstalleerd, wint het manifest ervan en wordt het Provider Index-item voor die provider genegeerd.

Verouderde capability-sleutels op topniveau zijn verouderd. Gebruik openclaw doctor --fix om speechProviders, realtimeTranscriptionProviders, realtimeVoiceProviders, mediaUnderstandingProviders, imageGenerationProviders, videoGenerationProviders, webFetchProviders en webSearchProviders onder contracts te plaatsen; normaal laden van manifests behandelt die velden op topniveau niet langer als capability-eigenaarschap.

Manifest versus package.json

De twee bestanden dienen verschillende doelen:

Als je niet zeker weet waar een stuk metadata thuishoort, gebruik dan deze regel:

• als OpenClaw het moet weten voordat plugincode wordt geladen, zet het dan in openclaw.plugin.json
• als het gaat over packaging, entrybestanden of npm-installatiegedrag, zet het dan in package.json

package.json-velden die detectie beïnvloeden

Sommige pre-runtime pluginmetadata leeft bewust in package.json onder het openclaw-blok in plaats van in openclaw.plugin.json. openclaw.bundle en openclaw.bundle.json zijn geen OpenClaw-plugincontracten; native plugins moeten openclaw.plugin.json plus de ondersteunde package.json#openclaw-velden hieronder gebruiken.

Belangrijke voorbeelden:

Manifestmetadata bepaalt welke provider-/kanaal-/installatiekeuzes in onboarding verschijnen voordat runtimes laden. package.json#openclaw.install vertelt onboarding hoe die plugin moet worden opgehaald of ingeschakeld wanneer de gebruiker een van die keuzes selecteert. Verplaats installatiehints niet naar openclaw.plugin.json.

openclaw.install.minHostVersion wordt afgedwongen tijdens installatie en bij het laden van het manifestregister voor niet-meegeleverde plugin-bronnen. Ongeldige waarden worden geweigerd; nieuwere-maar-geldige waarden slaan externe plugins over op oudere hosts. Meegeleverde bronplugins worden geacht mee-geversioneerd te zijn met de host-checkout.

Officiële metadata voor installatie op aanvraag moet clawhubSpec gebruiken wanneer de plugin op ClawHub is gepubliceerd; onboarding behandelt dat als de voorkeursbron op afstand en registreert ClawHub-artefactfeiten na installatie. npmSpec blijft de compatibiliteitsfallback voor pakketten die nog niet naar ClawHub zijn verhuisd.

Exacte npm-versiepinnen staan al in npmSpec, bijvoorbeeld "npmSpec": "@wecom/[email protected]". Officiële externe catalogusitems moeten exacte specs combineren met expectedIntegrity, zodat updateflows gesloten falen als het opgehaalde npm-artefact niet langer overeenkomt met de gepinde release. Interactieve onboarding biedt voor compatibiliteit nog steeds vertrouwde registry-npm-specs, waaronder kale pakketnamen en dist-tags. Catalogusdiagnostiek kan onderscheid maken tussen exacte, zwevende, integriteit-gepinde, ontbrekende-integriteit, pakketnaam-mismatch en ongeldige default-choice-bronnen. Ze waarschuwt ook wanneer expectedIntegrity aanwezig is maar er geen geldige npm-bron is die ermee kan worden gepind. Wanneer expectedIntegrity aanwezig is, dwingen installatie-/updateflows dit af; wanneer het ontbreekt, wordt de registry-resolutie geregistreerd zonder integriteitspin.

Kanaalplugins moeten openclaw.setupEntry leveren wanneer status, kanaallijst of SecretRef-scans geconfigureerde accounts moeten identificeren zonder de volledige runtime te laden. Het installatie-ingangspunt moet kanaalmetadata plus installatieveilige config-, status- en secrets-adapters beschikbaar maken; houd netwerkclients, gateway-listeners en transportruntimes in het hoofd-ingangspunt van de extensie.

Runtime-ingangspuntvelden overschrijven pakketgrenscontroles voor bron-ingangspuntvelden niet. Bijvoorbeeld: openclaw.runtimeExtensions kan een ontsnappend openclaw.extensions-pad niet laadbaar maken.

openclaw.install.allowInvalidConfigRecovery is bewust smal. Het maakt niet willekeurige kapotte configs installeerbaar. Vandaag staat het alleen installatieflows toe te herstellen van specifieke verouderde upgradefouten van meegeleverde plugins, zoals een ontbrekend pad naar een meegeleverde plugin of een verouderde channels.<id>-entry voor diezelfde meegeleverde plugin. Niet-gerelateerde configfouten blokkeren installatie nog steeds en sturen operators naar openclaw doctor --fix.

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

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

Gebruik dit wanneer installatie-, doctor-, status- of alleen-lezen presenceflows een goedkope ja/nee-authenticatieprobe nodig hebben voordat de volledige kanaalplugin laadt. Persistente authenticatiestatus is geen geconfigureerde kanaalstatus: gebruik deze metadata niet om plugins automatisch in te schakelen, runtimedependencies te repareren of te beslissen of een kanaalruntime moet laden. De doel-export moet een kleine functie zijn die alleen persistente status leest; routeer deze niet via de volledige kanaalruntime-barrel.

openclaw.channel.configuredState volgt dezelfde vorm voor goedkope env-only geconfigureerde checks:

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

Gebruik dit wanneer een kanaal geconfigureerde status kan beantwoorden vanuit env of andere kleine niet-runtime-inputs. Als de check volledige configresolutie of de echte kanaalruntime nodig heeft, houd die logica dan in de plugin-config.hasConfiguredState- hook.

Ontdekkingsvoorrang (dubbele plugin-id's)

OpenClaw ontdekt plugins vanuit meerdere roots (meegeleverd, globale installatie, workspace, expliciete door configuratie geselecteerde paden). Als twee ontdekkingen dezelfde id delen, wordt alleen het manifest met de hoogste voorrang behouden; duplicaten met lagere voorrang worden weggelaten in plaats van ernaast te laden.

Voorrang, van hoog naar laag:

1. Door configuratie geselecteerd — een pad dat expliciet is vastgepind in plugins.entries.<id>
2. Meegeleverd — plugins die met OpenClaw worden meegeleverd
3. Globale installatie — plugins die in de globale OpenClaw-pluginroot zijn geïnstalleerd
4. Workspace — plugins die relatief ten opzichte van de huidige workspace worden ontdekt

Gevolgen:

• Een geforkte of verouderde kopie van een meegeleverde plugin in de workspace overschaduwt de meegeleverde build niet.
• Om een meegeleverde plugin daadwerkelijk met een lokale plugin te overschrijven, pin je die via plugins.entries.<id>, zodat die op basis van voorrang wint in plaats van te vertrouwen op workspace-ontdekking.
• Weggelaten duplicaten worden gelogd zodat Doctor en opstartdiagnostiek naar de weggegooide kopie kunnen verwijzen.
• Door configuratie geselecteerde duplicate overrides worden in diagnostiek geformuleerd als expliciete overrides, maar waarschuwen nog steeds zodat verouderde forks en onbedoelde overschaduwingen zichtbaar blijven.

JSON Schema-vereisten

• Elke plugin moet een JSON Schema meeleveren, zelfs als deze geen config accepteert.
• Een leeg schema is acceptabel (bijvoorbeeld { "type": "object", "additionalProperties": false }).
• Schema's worden gevalideerd bij het lezen/schrijven van config, niet tijdens runtime.
• Wanneer je een meegeleverde plugin uitbreidt of forkt met nieuwe configkeys, werk dan tegelijk de configSchema van die plugin in openclaw.plugin.json bij. Schema's van meegeleverde plugins zijn strikt, dus het toevoegen van plugins.entries.<id>.config.myNewKey aan gebruikersconfig zonder myNewKey toe te voegen aan configSchema.properties wordt geweigerd voordat de pluginruntime laadt.

Voorbeeld van schema-uitbreiding:

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

Validatiegedrag

• Onbekende channels.*-keys zijn fouten, tenzij de kanaal-id door een pluginmanifest is gedeclareerd.
• plugins.entries.<id>, plugins.allow, plugins.deny en plugins.slots.* moeten verwijzen naar ontdekbare plugin-id's. Onbekende id's zijn fouten.
• Als een plugin is geïnstalleerd maar een kapot of ontbrekend manifest of schema heeft, mislukt validatie en rapporteert Doctor de pluginfout.
• Als pluginconfig bestaat maar de plugin uitgeschakeld is, wordt de config bewaard en verschijnt er een waarschuwing in Doctor + logs.

Zie Configuratiereferentie voor het volledige plugins.*-schema.

Notities

• Het manifest is vereist voor native OpenClaw-plugins, inclusief laden vanuit het lokale bestandssysteem. Runtime laadt de pluginmodule nog steeds afzonderlijk; het manifest is alleen bedoeld voor ontdekking + validatie.
• Native manifests worden geparseerd met JSON5, dus opmerkingen, afsluitende komma's en niet-geciteerde sleutels worden geaccepteerd zolang de uiteindelijke waarde nog steeds een object is.
• Alleen gedocumenteerde manifestvelden worden gelezen door de manifestloader. 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 het voor statische provider-catalogusmetadata of smalle ontdekkingsdescriptors, niet voor uitvoering tijdens verzoeken. providerDiscoveryEntry is de verouderde spelling en werkt nog steeds voor bestaande plugins.
• Exclusieve plugintypen worden geselecteerd via plugins.slots.*: kind: "memory" via plugins.slots.memory, 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.
• Env-var-metadata (setup.providers[].envVars, verouderd providerAuthEnvVars en channelEnvVars) is alleen declaratief. Status, audit, cron-bezorgvalidatie en andere alleen-lezen-oppervlakken passen nog steeds pluginvertrouwen en effectief activatiebeleid toe voordat ze een env var als geconfigureerd behandelen.
• Voor runtime-wizardmetadata waarvoor providercode vereist is, zie Provider-runtimehooks.
• Als je plugin afhankelijk is van native modules, documenteer dan de buildstappen en eventuele allowlistvereisten voor pakketbeheerders (bijvoorbeeld pnpm allow-build-scripts + pnpm rebuild <package>).

Gerelateerd