De Plugin SDK is het getypeerde contract tussen Plugins en core. Deze pagina is de referentie voor wat je importeert en wat je kunt registreren.Documentation Index
Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt
Use this file to discover all available pages before exploring further.
Deze pagina is voor Plugin-auteurs die
openclaw/plugin-sdk/* binnen
OpenClaw gebruiken. Voor externe apps, scripts, dashboards, CI-taken en IDE-extensies
die agents via de Gateway willen uitvoeren, gebruik je in plaats daarvan de
OpenClaw App SDK en het pakket @openclaw/sdk.Importconventie
Importeer altijd vanuit een specifiek subpad:openclaw/plugin-sdk/channel-core de voorkeur; houd openclaw/plugin-sdk/core voor
het bredere overkoepelende oppervlak en gedeelde helpers zoals
buildChannelConfigSchema.
Voor channel-configuratie publiceer je het JSON Schema dat eigendom is van de channel via
openclaw.plugin.json#channelConfigs. Het subpad plugin-sdk/channel-config-schema
is bedoeld voor gedeelde schemaprimitieven en de generieke builder. De gebundelde
Plugins van OpenClaw gebruiken plugin-sdk/bundled-channel-config-schema voor behouden
gebundelde-channel-schema’s. Verouderde compatibiliteitsexports blijven beschikbaar op
plugin-sdk/channel-config-schema-legacy; geen van beide gebundelde schemasubpaden is een
patroon voor nieuwe Plugins.
Subpadreferentie
De Plugin SDK wordt beschikbaar gesteld als een set smalle subpaden, gegroepeerd per gebied (Plugin entry, channel, provider, auth, runtime, capability, memory en gereserveerde gebundelde-Plugin-helpers). Zie voor de volledige catalogus, gegroepeerd en gelinkt, Plugin SDK-subpaden. De compiler-entrypoint-inventaris staat inscripts/lib/plugin-sdk-entrypoints.json; package-exports worden gegenereerd uit
de publieke subset na aftrek van repo-lokale test/interne subpaden die staan vermeld in
scripts/lib/plugin-sdk-private-local-only-subpaths.json. Voer
pnpm plugin-sdk:surface uit om het aantal publieke exports te controleren. Verouderde publieke
subpaden die oud genoeg zijn en niet worden gebruikt door productiecode van gebundelde extensies worden
bijgehouden in scripts/lib/plugin-sdk-deprecated-public-subpaths.json; brede
verouderde re-export-barrels worden bijgehouden in
scripts/lib/plugin-sdk-deprecated-barrel-subpaths.json.
Registratie-API
De callbackregister(api) ontvangt een OpenClawPluginApi-object met deze
methoden:
Capability-registratie
| Methode | Wat deze registreert |
|---|---|
api.registerProvider(...) | Tekstinferentie (LLM) |
api.registerAgentHarness(...) | Experimentele low-level agent executor |
api.registerCliBackend(...) | Lokale CLI-inferentiebackend |
api.registerChannel(...) | Messaging-channel |
api.registerSpeechProvider(...) | Tekst-naar-spraak / STT-synthese |
api.registerRealtimeTranscriptionProvider(...) | Streaming realtime-transcriptie |
api.registerRealtimeVoiceProvider(...) | Duplex realtime-spraaksessies |
api.registerMediaUnderstandingProvider(...) | Beeld-/audio-/videoanalyse |
api.registerImageGenerationProvider(...) | Beeldgeneratie |
api.registerMusicGenerationProvider(...) | Muziekgeneratie |
api.registerVideoGenerationProvider(...) | Videogeneratie |
api.registerWebFetchProvider(...) | Webfetch-/scrape-provider |
api.registerWebSearchProvider(...) | Webzoekfunctie |
Tools en opdrachten
| Methode | Wat deze registreert |
|---|---|
api.registerTool(tool, opts?) | Agent-tool (vereist of { optional: true }) |
api.registerCommand(def) | Aangepaste opdracht (omzeilt de LLM) |
agentPromptGuidance instellen wanneer de agent een korte,
opdracht-eigen routinghint nodig heeft. Houd die tekst gericht op de opdracht zelf; voeg geen
provider- of Plugin-specifiek beleid toe aan core-promptbuilders.
Infrastructuur
| Methode | Wat deze registreert |
|---|---|
api.registerHook(events, handler, opts?) | Event-hook |
api.registerHttpRoute(params) | Gateway HTTP-eindpunt |
api.registerGatewayMethod(name, handler) | Gateway RPC-methode |
api.registerGatewayDiscoveryService(service) | Lokale Gateway-discovery-adverteerder |
api.registerCli(registrar, opts?) | CLI-subopdracht |
api.registerNodeCliFeature(registrar, opts?) | Node-feature-CLI onder openclaw nodes |
api.registerService(service) | Achtergrondservice |
api.registerInteractiveHandler(registration) | Interactieve handler |
api.registerAgentToolResultMiddleware(...) | Runtime-toolresultaatmiddleware |
api.registerMemoryPromptSupplement(builder) | Additieve memory-aangrenzende promptsectie |
api.registerMemoryCorpusSupplement(adapter) | Additief memory-zoek-/leescorpus |
Host-hooks voor workflow-Plugins
Host-hooks zijn de SDK-seams voor Plugins die moeten deelnemen aan de host- lifecycle in plaats van alleen een provider, channel of tool toe te voegen. Het zijn generieke contracten; Plan Mode kan ze gebruiken, maar dat geldt ook voor approval-workflows, workspace-policy-gates, achtergrondmonitors, setupwizards en UI-companion- Plugins.| Methode | Contract waarvan deze eigenaar is |
|---|---|
api.session.state.registerSessionExtension(...) | Plugin-eigen, JSON-compatibele sessiestatus geprojecteerd via Gateway-sessies |
api.session.workflow.enqueueNextTurnInjection(...) | Duurzame exactly-once-context geïnjecteerd in de volgende agent-turn voor één sessie |
api.registerTrustedToolPolicy(...) | Gebundeld/vertrouwd pre-Plugin-toolbeleid dat toolparameters kan blokkeren of herschrijven |
api.registerToolMetadata(...) | Weergavemetadata voor de toolcatalogus zonder de toolimplementatie te wijzigen |
api.registerCommand(...) | Scoped Plugin-opdrachten; opdrachtresultaten kunnen continueAgent: true instellen; Discord-native opdrachten ondersteunen descriptionLocalizations |
api.session.controls.registerControlUiDescriptor(...) | Control-UI-contributiedescriptors voor sessie-, tool-, run- of instellingenoppervlakken |
api.lifecycle.registerRuntimeLifecycle(...) | Cleanup-callbacks voor Plugin-eigen runtime-resources op reset-/delete-/reload-paden |
api.agent.events.registerAgentEventSubscription(...) | Gesaniteerde event-abonnementen voor workflowstatus en monitors |
api.runContext.setRunContext(...) / getRunContext(...) / clearRunContext(...) | Plugin-scratchstatus per run, opgeschoond bij terminale run-lifecycle |
api.session.workflow.registerSessionSchedulerJob(...) | Cleanupmetadata voor Plugin-eigen scheduler-jobs; plant geen werk en maakt geen taakrecords aan |
api.session.workflow.sendSessionAttachment(...) | Alleen gebundeld: door de host bemiddelde bestandsbijlagelevering aan de actieve direct-outbound-sessieroute |
api.session.workflow.scheduleSessionTurn(...) / unscheduleSessionTurnsByTag(...) | Alleen gebundeld: door Cron ondersteunde geplande sessie-turns plus taggebaseerde cleanup |
api.session.controls.registerSessionAction(...) | Getypeerde sessieacties die clients via de Gateway kunnen dispatchen |
api.session.state.registerSessionExtension(...)api.session.workflow.enqueueNextTurnInjection(...)api.session.workflow.registerSessionSchedulerJob(...)api.session.workflow.sendSessionAttachment(...)api.session.workflow.scheduleSessionTurn(...)api.session.workflow.unscheduleSessionTurnsByTag(...)api.session.controls.registerSessionAction(...)api.session.controls.registerControlUiDescriptor(...)api.agent.events.registerAgentEventSubscription(...)api.agent.events.emitAgentEvent(...)api.runContext.setRunContext(...)/getRunContext(...)/clearRunContext(...)api.lifecycle.registerRuntimeLifecycle(...)
api.registerSessionExtension, api.enqueueNextTurnInjection,
api.registerControlUiDescriptor, api.registerRuntimeLifecycle,
api.registerAgentEventSubscription, api.emitAgentEvent,
api.setRunContext, api.getRunContext, api.clearRunContext,
api.registerSessionSchedulerJob, api.registerSessionAction,
api.sendSessionAttachment, api.scheduleSessionTurn of
api.unscheduleSessionTurnsByTag rechtstreeks aanroept.
scheduleSessionTurn(...) is een sessiegebonden gemakslaag boven de Gateway
Cron-planner. Cron beheert de timing en maakt de achtergrondtaakrecord aan
wanneer de beurt wordt uitgevoerd; de Plugin SDK beperkt alleen de doelsessie,
Plugin-eigen naamgeving en opschoning. Gebruik api.runtime.tasks.managedFlows
binnen de geplande beurt wanneer het werk zelf duurzame meerstaps-Task Flow-status
nodig heeft.
De contracten splitsen de bevoegdheid bewust op:
- Externe plugins kunnen sessie-uitbreidingen, UI-descriptors, commando’s, toolmetadata, injecties voor de volgende beurt en normale hooks beheren.
- Vertrouwde toolbeleidsregels worden uitgevoerd vóór gewone
before_tool_call-hooks en zijn alleen gebundeld omdat ze deelnemen aan het veiligheidsbeleid van de host. - Gereserveerd commando-eigenaarschap is alleen gebundeld. Externe plugins moeten hun eigen commandonamen of aliassen gebruiken.
allowPromptInjection=falseschakelt promptwijzigende hooks uit, waaronderagent_turn_prepare,before_prompt_build,heartbeat_prompt_contribution, promptvelden van de verouderdebefore_agent_startenenqueueNextTurnInjection.
| Plugin-archetype | Gebruikte hooks |
|---|---|
| Goedkeuringsworkflow | Sessie-uitbreiding, commandovoortzetting, injectie voor volgende beurt, UI-descriptor |
| Beleidsgrens voor budget/werkruimte | Vertrouwd toolbeleid, toolmetadata, sessieprojectie |
| Achtergrondmonitor voor levenscyclus | Opschoning van runtimelevenscyclus, abonnement op agentevents, eigenaarschap/opschoning van sessieplanner, bijdrage aan heartbeat-prompt, UI-descriptor |
| Installatie- of onboardingwizard | Sessie-uitbreiding, gescopete commando’s, Control-UI-descriptor |
Gereserveerde kernbeheernamespaces (
config.*, exec.approvals.*, wizard.*,
update.*) blijven altijd operator.admin, zelfs als een plugin probeert een
nauwere Gateway-methodescope toe te wijzen. Geef de voorkeur aan pluginspecifieke
voorvoegsels voor Plugin-eigen methoden.Wanneer toolresultaat-middleware gebruiken
Wanneer toolresultaat-middleware gebruiken
Gebundelde plugins kunnen
api.registerAgentToolResultMiddleware(...) gebruiken
wanneer ze een toolresultaat na uitvoering en voordat de runtime dat resultaat
terugvoert naar het model moeten herschrijven. Dit is de vertrouwde runtime-neutrale
naad voor asynchrone uitvoerreducers zoals tokenjuice.Gebundelde plugins moeten contracts.agentToolResultMiddleware declareren voor elke
gerichte runtime, bijvoorbeeld ["pi", "codex"]. Externe plugins
kunnen deze middleware niet registreren; houd normale OpenClaw-pluginhooks aan voor werk
waarvoor geen timing van toolresultaten vóór het model nodig is. Het oude, alleen voor Pi
bedoelde registratiepad voor ingebedde uitbreidingsfabrieken is verwijderd.Gateway-discoveryregistratie
api.registerGatewayDiscoveryService(...) laat een plugin de actieve
Gateway adverteren op een lokaal discoverytransport zoals mDNS/Bonjour. OpenClaw roept de
service aan tijdens het opstarten van de Gateway wanneer lokale discovery is ingeschakeld, geeft de
huidige Gateway-poorten en niet-geheime TXT-hintgegevens door, en roept de geretourneerde
stop-handler aan tijdens het afsluiten van de Gateway.
CLI-registratiemetadata
api.registerCli(registrar, opts?) accepteert twee soorten commandometadata:
commands: expliciete commandonamen die eigendom zijn van de registrardescriptors: commandodescriptors tijdens het parsen die worden gebruikt voor CLI-help, routering en luie CLI-registratie van pluginsparentPath: optioneel bovenliggend commandopad voor geneste commandogroepen, zoals["nodes"]
api.registerNodeCliFeature(registrar, opts?) de voorkeur. Dit is een kleine wrapper rond
api.registerCli(..., { parentPath: ["nodes"] }) en maakt commando’s zoals
openclaw nodes canvas expliciete Plugin-eigen node-functies.
Als je wilt dat een plugincommando lui geladen blijft in het normale root-CLI-pad,
geef dan descriptors op die elke root van een topniveaucommando dekken die door die
registrar wordt blootgesteld.
program:
commands op zichzelf alleen wanneer je geen luie root-CLI-registratie nodig hebt.
Dat gretige compatibiliteitspad blijft ondersteund, maar het installeert geen
door descriptors ondersteunde placeholders voor lui laden tijdens het parsen.
CLI-backendregistratie
api.registerCliBackend(...) laat een plugin de standaardconfiguratie beheren voor een lokale
AI-CLI-backend zoals codex-cli.
- De backend-
idwordt het providervoorvoegsel in modelrefs zoalscodex-cli/gpt-5. - De backend-
configgebruikt dezelfde vorm alsagents.defaults.cliBackends.<id>. - Gebruikersconfiguratie wint nog steeds. OpenClaw voegt
agents.defaults.cliBackends.<id>samen boven op de Plugin-standaard voordat de CLI wordt uitgevoerd. - Gebruik
normalizeConfigwanneer een backend compatibiliteitsherschrijvingen na het samenvoegen nodig heeft (bijvoorbeeld het normaliseren van oude flagvormen). - Gebruik
resolveExecutionArgsvoor aanvraaggebonden argv-herschrijvingen die bij het CLI-dialect horen, zoals het mappen van OpenClaw-denkniveaus naar een native effort-flag.
Exclusieve slots
| Methode | Wat deze registreert |
|---|---|
api.registerContextEngine(id, factory) | Contextengine (één tegelijk actief). De callback assemble() ontvangt availableTools en citationsMode, zodat de engine prompttoevoegingen kan afstemmen. |
api.registerMemoryCapability(capability) | Uniforme geheugencapability |
api.registerMemoryPromptSection(builder) | Bouwer voor geheugenpromptsecties |
api.registerMemoryFlushPlan(resolver) | Resolver voor geheugenflushplan |
api.registerMemoryRuntime(runtime) | Geheugenruntime-adapter |
Adapters voor geheugenembeddings
| Methode | Wat deze registreert |
|---|---|
api.registerMemoryEmbeddingProvider(adapter) | Geheugenembeddingadapter voor de actieve plugin |
registerMemoryCapabilityis de voorkeurs-API voor exclusieve geheugenplugins.registerMemoryCapabilitykan ookpublicArtifacts.listArtifacts(...)blootstellen, zodat begeleidende plugins geëxporteerde geheugenartefacten kunnen consumeren viaopenclaw/plugin-sdk/memory-host-corein plaats van in de privé-indeling van een specifieke geheugenplugin te reiken.registerMemoryPromptSection,registerMemoryFlushPlanenregisterMemoryRuntimezijn legacy-compatibele API’s voor exclusieve geheugenplugins.MemoryFlushPlan.modelkan de flushbeurt vastpinnen op een exacteprovider/model-referentie, zoalsollama/qwen3:8b, zonder de actieve fallbackketen te erven.registerMemoryEmbeddingProviderlaat de actieve geheugenplugin één of meer embeddingadapter-id’s registreren (bijvoorbeeldopenai,geminiof een aangepaste door een plugin gedefinieerde id).- Gebruikersconfiguratie zoals
agents.defaults.memorySearch.providerenagents.defaults.memorySearch.fallbackwordt opgelost tegen die geregistreerde adapter-id’s.
Events en levenscyclus
| Methode | Wat deze doet |
|---|---|
api.on(hookName, handler, opts?) | Getypeerde levenscyclushook |
api.onConversationBindingResolved(handler) | Callback voor gespreksbinding |
Semantiek van hookbeslissingen
before_tool_call: het retourneren van{ block: true }is terminaal. Zodra een handler dit instelt, worden handlers met lagere prioriteit overgeslagen.before_tool_call: het retourneren van{ block: false }wordt behandeld als geen beslissing (hetzelfde alsblockweglaten), niet als een overschrijving.before_install: het retourneren van{ block: true }is terminaal. Zodra een handler dit instelt, worden handlers met lagere prioriteit overgeslagen.before_install: het retourneren van{ block: false }wordt behandeld als geen beslissing (hetzelfde alsblockweglaten), niet als een overschrijving.reply_dispatch: het retourneren van{ handled: true, ... }is terminaal. Zodra een handler dispatch claimt, worden handlers met lagere prioriteit en het standaarddispatchpad van het model overgeslagen.message_sending: het retourneren van{ cancel: true }is terminaal. Zodra een handler dit instelt, worden handlers met lagere prioriteit overgeslagen.message_sending: het retourneren van{ cancel: false }wordt behandeld als geen beslissing (hetzelfde alscancelweglaten), niet als een overschrijving.message_received: gebruik het getypeerde veldthreadIdwanneer je routering van inkomende threads/onderwerpen nodig hebt. Bewaarmetadatavoor kanaalspecifieke extra’s.message_sending: gebruik getypeerde routeringsveldenreplyToId/threadIdvoordat je terugvalt op kanaalspecifiekemetadata.gateway_start: gebruikctx.config,ctx.workspaceDirenctx.getCron?.()voor Gateway-eigen opstartstatus in plaats van te vertrouwen op internegateway:startup-hooks.cron_changed: observeer wijzigingen in de Gateway-eigen Cron-levenscyclus. Gebruikevent.job?.state?.nextRunAtMsenctx.getCron?.()bij het synchroniseren van externe wekkerschedulers, en houd OpenClaw als de bron van waarheid voor vervalcontroles en uitvoering.
API-objectvelden
| Veld | Type | Beschrijving |
|---|---|---|
api.id | string | Plugin-id |
api.name | string | Weergavenaam |
api.version | string? | Plugin-versie (optioneel) |
api.description | string? | Plugin-beschrijving (optioneel) |
api.source | string | Bronpad van Plugin |
api.rootDir | string? | Hoofdmap van Plugin (optioneel) |
api.config | OpenClawConfig | Huidige config-snapshot (actieve runtime-snapshot in het geheugen wanneer beschikbaar) |
api.pluginConfig | Record<string, unknown> | Plugin-specifieke config uit plugins.entries.<id>.config |
api.runtime | PluginRuntime | Runtimehelpers |
api.logger | PluginLogger | Scoped logger (debug, info, warn, error) |
api.registrationMode | PluginRegistrationMode | Huidige laadmodus; "setup-runtime" is het lichte opstart-/setupvenster vóór volledige entry |
api.resolvePath(input) | (string) => string | Pad relatief aan de Plugin-root oplossen |
Conventie voor interne modules
Gebruik binnen je Plugin lokale barrel-bestanden voor interne imports:api.ts, runtime-api.ts,
index.ts, setup-entry.ts en vergelijkbare publieke entrybestanden) geven de voorkeur aan de
actieve runtime-configsnapshot wanneer OpenClaw al draait. Als er nog geen runtime-
snapshot bestaat, vallen ze terug op het opgeloste configbestand op schijf.
Verpakte facades van gebundelde Plugins moeten worden geladen via OpenClaw’s Plugin-
facadeladers; directe imports uit dist/extensions/... omzeilen de manifest-
en runtime-sidecarcontroles die verpakte installaties gebruiken voor code die eigendom is van de Plugin.
Provider-Plugins kunnen een smalle, Plugin-lokale contract-barrel blootstellen wanneer een
helper bewust provider-specifiek is en nog niet thuishoort in een generiek SDK-
subpad. Gebundelde voorbeelden:
- Anthropic: publieke
api.ts/contract-api.ts-seam voor Claude beta-header- enservice_tier-streamhelpers. @openclaw/openai-provider:api.tsexporteert provider-builders, helpers voor standaardmodellen en realtime provider-builders.@openclaw/openrouter-provider:api.tsexporteert de provider-builder plus onboarding-/confighelpers.
Gerelateerd
Entry points
Opties voor
definePluginEntry en defineChannelPluginEntry.Runtime helpers
Volledige referentie voor de
api.runtime-namespace.Setup and config
Packaging, manifests en config-schema’s.
Testing
Testhulpmiddelen en lintregels.
SDK migration
Migreren vanaf verouderde oppervlakken.
Plugin internals
Diepgaande architectuur en capability-model.