Referentie voor pluginverpakking (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.
package.json-metadata), manifests (openclaw.plugin.json), setup-items en configuratieschema’s.
Pakketmetadata
Jepackage.json heeft een openclaw-veld nodig dat het pluginsysteem vertelt wat je plugin biedt:
- Channel plugin
- Provider plugin / ClawHub baseline
Als je de plugin extern publiceert op ClawHub, zijn die
compat- en build-velden vereist. De canonieke publicatiesnippets staan in docs/snippets/plugin-publish/.openclaw-velden
Entry-pointbestanden (relatief ten opzichte van de pakketroot).
Lichtgewicht entry alleen voor setup (optioneel).
Kanaalcatalogusmetadata voor setup, kiezer, quickstart en statusoppervlakken.
Provider-id’s die door deze plugin worden geregistreerd.
Installatiehints:
npmSpec, localPath, defaultChoice, minHostVersion, expectedIntegrity, allowInvalidConfigRecovery.Vlaggen voor opstartgedrag.
openclaw.channel
openclaw.channel is goedkope pakketmetadata voor kanaaldetectie en setup-oppervlakken voordat de runtime wordt geladen.
| Veld | Type | Betekenis |
|---|---|---|
id | string | Canoniek kanaal-id. |
label | string | Primair kanaallabel. |
selectionLabel | string | Kiezer-/setuplabel wanneer dit moet afwijken van label. |
detailLabel | string | Secundair detaillabel voor rijkere kanaalcatalogi en statusoppervlakken. |
docsPath | string | Docspad voor setup- en selectielinks. |
docsLabel | string | Overschrijft het label dat voor docslinks wordt gebruikt wanneer dit moet afwijken van het kanaal-id. |
blurb | string | Korte onboarding-/catalogusbeschrijving. |
order | number | Sorteervolgorde in kanaalcatalogi. |
aliases | string[] | Extra opzoekaliassen voor kanaalselectie. |
preferOver | string[] | Plugin-/kanaal-id’s met lagere prioriteit waar dit kanaal voor moet gaan. |
systemImage | string | Optionele pictogram-/systeemafbeeldingsnaam voor kanaal-UI-catalogi. |
selectionDocsPrefix | string | Prefixtekst vóór docslinks in selectieoppervlakken. |
selectionDocsOmitLabel | boolean | Toon het docspad direct in plaats van een gelabelde docslink in selectietekst. |
selectionExtras | string[] | Extra korte strings die aan selectietekst worden toegevoegd. |
markdownCapable | boolean | Markeert het kanaal als markdown-geschikt voor beslissingen over uitgaande opmaak. |
exposure | object | Zichtbaarheidsinstellingen voor kanalen voor setup, geconfigureerde lijsten en docsoppervlakken. |
quickstartAllowFrom | boolean | Schakelt dit kanaal in voor de standaard quickstart-setupflow allowFrom. |
forceAccountBinding | boolean | Vereist expliciete accountkoppeling, zelfs wanneer er maar één account bestaat. |
preferSessionLookupForAnnounceTarget | boolean | Geef de voorkeur aan sessieopzoeking bij het oplossen van aankondigingsdoelen voor dit kanaal. |
exposure ondersteunt:
configured: neem het kanaal op in geconfigureerde/statusachtige lijstoppervlakkensetup: neem het kanaal op in interactieve setup-/configuratiekiezersdocs: markeer het kanaal als publiek zichtbaar in docs-/navigatieoppervlakken
showConfigured en showInSetup blijven ondersteund als legacy aliassen. Geef de voorkeur aan exposure.openclaw.install
openclaw.install is pakketmetadata, geen manifestmetadata.
| Veld | Type | Betekenis |
|---|---|---|
clawhubSpec | string | Canonieke ClawHub-specificatie voor installatie/update en onboardingflows voor installatie op aanvraag. |
npmSpec | string | Canonieke npm-specificatie voor fallbackflows voor installatie/update. |
localPath | string | Lokaal ontwikkelpad of gebundeld installatiepad. |
defaultChoice | "clawhub" | "npm" | "local" | Voorkeursinstallatiebron wanneer meerdere bronnen beschikbaar zijn. |
minHostVersion | string | Minimaal ondersteunde OpenClaw-versie in de vorm >=x.y.z of >=x.y.z-prerelease. |
expectedIntegrity | string | Verwachte npm-distintegriteitsstring, meestal sha512-..., voor gepinde installaties. |
allowInvalidConfigRecovery | boolean | Laat herinstallatieflows voor gebundelde plugins herstellen van specifieke fouten door verouderde configuratie. |
Onboarding behavior
Onboarding behavior
Interactieve onboarding gebruikt ook
openclaw.install voor oppervlakken voor installatie op aanvraag. Als je plugin provider-authkeuzes of kanaalsetup-/catalogusmetadata blootstelt voordat de runtime wordt geladen, kan onboarding die keuze tonen, vragen om ClawHub-, npm- of lokale installatie, de plugin installeren of inschakelen en daarna doorgaan met de geselecteerde flow. ClawHub-onboardingkeuzes gebruiken clawhubSpec en hebben de voorkeur wanneer ze aanwezig zijn; npm-keuzes vereisen vertrouwde catalogusmetadata met een registry-npmSpec; exacte versies en expectedIntegrity zijn optionele npm-pins. Als expectedIntegrity aanwezig is, dwingen installatie-/updateflows dit af voor npm. Bewaar de metadata voor “wat te tonen” in openclaw.plugin.json en de metadata voor “hoe het te installeren” in package.json.minHostVersion enforcement
minHostVersion enforcement
Als
minHostVersion is ingesteld, dwingen zowel installatie als laden van niet-gebundelde manifestregisters dit af. Oudere hosts slaan externe plugins over; ongeldige versiestrings worden geweigerd. Aangenomen wordt dat gebundelde bronplugins dezelfde versie hebben als de host-checkout.Pinned npm installs
Pinned npm installs
Voor gepinde npm-installaties bewaar je de exacte versie in
npmSpec en voeg je de verwachte artifactintegriteit toe:allowInvalidConfigRecovery scope
allowInvalidConfigRecovery scope
allowInvalidConfigRecovery is geen algemene omzeiling voor kapotte configuraties. Het is alleen bedoeld voor smal herstel van gebundelde plugins, zodat herinstallatie/setup bekende restanten van upgrades kan repareren, zoals een ontbrekend pad naar een gebundelde plugin of een verouderde channels.<id>-entry voor diezelfde plugin. Als de configuratie om niet-gerelateerde redenen kapot is, faalt de installatie nog steeds gesloten en wordt de operator gevraagd openclaw doctor --fix uit te voeren.Uitgesteld volledig laden
Kanaalplugins kunnen kiezen voor uitgesteld laden met:setupEntry tijdens de opstartfase vóór luisteren, zelfs voor al geconfigureerde kanalen. De volledige entry wordt geladen nadat de Gateway begint te luisteren.
Als je setup-/volledige entry Gateway-RPC-methoden registreert, houd ze dan op een plugin-specifieke prefix. Gereserveerde core-adminnamespaces (config.*, exec.approvals.*, wizard.*, update.*) blijven eigendom van core en worden altijd opgelost naar operator.admin.
Pluginmanifest
Elke native plugin moet eenopenclaw.plugin.json meeleveren in de pakketroot. OpenClaw gebruikt dit om configuratie te valideren zonder plugincode uit te voeren.
kind en channels toe:
Publiceren op ClawHub
Gebruik voor pluginpakketten de pakketspecifieke ClawHub-opdracht:De verouderde publicatie-alias alleen voor skills is bedoeld voor skills. Plugin-pakketten moeten altijd
clawhub package publish gebruiken.Setup-entry
Het bestandsetup-entry.ts is een lichtgewicht alternatief voor index.ts dat OpenClaw laadt wanneer het alleen setup-oppervlakken nodig heeft (onboarding, configuratiereparatie, inspectie van uitgeschakelde kanalen).
defineBundledChannelSetupEntry(...) uit openclaw/plugin-sdk/channel-entry-contract gebruiken in plaats van defineSetupPluginEntry(...). Dat gebundelde contract ondersteunt ook een optionele runtime-export, zodat runtime-bekabeling tijdens setup lichtgewicht en expliciet kan blijven.
Wanneer OpenClaw setupEntry gebruikt in plaats van de volledige entry
Wanneer OpenClaw setupEntry gebruikt in plaats van de volledige entry
- Het kanaal is uitgeschakeld maar heeft setup-/onboarding-oppervlakken nodig.
- Het kanaal is ingeschakeld maar niet geconfigureerd.
- Uitgesteld laden is ingeschakeld (
deferConfiguredChannelFullLoadUntilAfterListen).
Wat setupEntry moet registreren
Wat setupEntry moet registreren
- Het kanaal-Plugin-object (via
defineSetupPluginEntry). - Alle HTTP-routes die nodig zijn voordat de gateway gaat luisteren.
- Alle gateway-methoden die nodig zijn tijdens het opstarten.
config.* of update.* vermijden.Wat setupEntry NIET mag bevatten
Wat setupEntry NIET mag bevatten
- CLI-registraties.
- Achtergrondservices.
- Zware runtime-imports (crypto, SDK’s).
- Gateway-methoden die pas na het opstarten nodig zijn.
Smalle setup-helperimports
Gebruik voor snelle paden die alleen voor setup zijn de smalle setup-helperkoppelingen in plaats van de bredereplugin-sdk/setup-paraplu wanneer je slechts een deel van het setup-oppervlak nodig hebt:
| Importpad | Gebruik het voor | Belangrijkste exports |
|---|---|---|
plugin-sdk/setup-runtime | runtime-helpers voor setup die beschikbaar blijven in setupEntry / uitgestelde kanaalstart | createPatchedAccountSetupAdapter, createEnvPatchedAccountSetupAdapter, createSetupInputPresenceValidator, noteChannelLookupFailure, noteChannelLookupSummary, promptResolvedAllowFrom, splitSetupEntries, createAllowlistSetupWizardProxy, createDelegatedSetupWizardProxy |
plugin-sdk/setup-adapter-runtime | verouderde compatibiliteitsalias; gebruik plugin-sdk/setup-runtime | createEnvPatchedAccountSetupAdapter |
plugin-sdk/setup-tools | helpers voor setup-/installatie-CLI, archieven en docs | formatCliCommand, detectBinary, extractArchive, resolveBrewExecutable, formatDocsLink, CONFIG_DIR |
plugin-sdk/setup-koppeling wanneer je de volledige gedeelde setup-toolbox wilt, inclusief configuratiepatch-helpers zoals moveSingleAccountChannelSectionToDefaultAccount(...).
De setup-patchadapters blijven veilig om te importeren op hot paths. Hun gebundelde single-account-promotiecontract-oppervlaklookup is lazy, dus het importeren van plugin-sdk/setup-runtime laadt gebundelde contract-oppervlakdetectie niet meteen voordat de adapter daadwerkelijk wordt gebruikt.
Kanaal-eigen single-account-promotie
Wanneer een kanaal upgradet van een top-level configuratie met één account naarchannels.<id>.accounts.*, is het standaard gedeelde gedrag om gepromoveerde account-scoped waarden naar accounts.default te verplaatsen.
Gebundelde kanalen kunnen die promotie verfijnen of overschrijven via hun setup-contractoppervlak:
singleAccountKeysToMove: extra top-level keys die naar het gepromoveerde account moeten worden verplaatstnamedAccountPromotionKeys: wanneer benoemde accounts al bestaan, worden alleen deze keys naar het gepromoveerde account verplaatst; gedeelde beleids-/delivery-keys blijven op de kanaalrootresolveSingleAccountPromotionTarget(...): kies welk bestaand account gepromoveerde waarden ontvangt
Matrix is het huidige gebundelde voorbeeld. Als er precies één benoemd Matrix-account al bestaat, of als
defaultAccount naar een bestaande niet-canonieke key zoals Ops wijst, behoudt de promotie dat account in plaats van een nieuwe accounts.default-vermelding te maken.Configuratieschema
Plugin-configuratie wordt gevalideerd tegen het JSON Schema in je manifest. Gebruikers configureren plugins via:api.pluginConfig tijdens registratie.
Gebruik voor kanaalspecifieke configuratie in plaats daarvan de kanaalconfiguratiesectie:
Kanaalconfiguratieschema’s bouwen
GebruikbuildChannelConfigSchema om een Zod-schema om te zetten naar de ChannelConfigSchema-wrapper die wordt gebruikt door configuratieartefacten die eigendom zijn van plugins:
openclaw.plugin.json#channelConfigs, zodat configuratieschema-, setup- en UI-oppervlakken channels.<id> kunnen inspecteren zonder runtime-code te laden.
Setup-wizards
Kanaalplugins kunnen interactieve setup-wizards bieden vooropenclaw onboard. De wizard is een ChannelSetupWizard-object op de ChannelPlugin:
ChannelSetupWizard ondersteunt credentials, textInputs, dmPolicy, allowFrom, groupAccess, prepare, finalize en meer. Bekijk gebundelde Plugin-pakketten (bijvoorbeeld de Discord-Plugin src/channel.setup.ts) voor volledige voorbeelden.
Gedeelde allowFrom-prompts
Gedeelde allowFrom-prompts
Geef voor DM-allowlistprompts die alleen de standaardflow
note -> prompt -> parse -> merge -> patch nodig hebben de voorkeur aan de gedeelde setup-helpers uit openclaw/plugin-sdk/setup: createPromptParsedAllowFromForAccount(...), createTopLevelChannelParsedAllowFromPrompt(...) en createNestedChannelParsedAllowFromPrompt(...).Standaard kanaalsetupstatus
Standaard kanaalsetupstatus
Geef voor kanaalsetupstatusblokken die alleen verschillen in labels, scores en optionele extra regels de voorkeur aan
createStandardChannelSetupStatus(...) uit openclaw/plugin-sdk/setup in plaats van hetzelfde status-object in elke Plugin handmatig te schrijven.Optioneel kanaalsetup-oppervlak
Optioneel kanaalsetup-oppervlak
Gebruik voor optionele setup-oppervlakken die alleen in bepaalde contexten moeten verschijnen
createOptionalChannelSetupSurface uit openclaw/plugin-sdk/channel-setup:plugin-sdk/channel-setup exposeert ook de lagere-niveau builders createOptionalChannelSetupAdapter(...) en createOptionalChannelSetupWizard(...) wanneer je slechts één helft van dat optionele installatie-oppervlak nodig hebt.De gegenereerde optionele adapter/wizard faalt gesloten bij echte configuratieschrijfacties. Ze hergebruiken één installatie-vereistbericht voor validateInput, applyAccountConfig en finalize, en voegen een docs-link toe wanneer docsPath is ingesteld.Binary-backed setup-helpers
Binary-backed setup-helpers
Geef voor binary-backed setup-UI’s de voorkeur aan de gedeelde gedelegeerde helpers in plaats van dezelfde binary-/statuslijm naar elk kanaal te kopiëren:
createDetectedBinaryStatus(...)voor statusblokken die alleen verschillen in labels, hints, scores en binary-detectiecreateCliPathTextInput(...)voor pad-backed tekstinvoercreateDelegatedSetupWizardStatusResolvers(...),createDelegatedPrepare(...),createDelegatedFinalize(...)encreateDelegatedResolveConfigured(...)wanneersetupEntrylazy moet doorsturen naar een zwaardere volledige wizardcreateDelegatedTextInputShouldPrompt(...)wanneersetupEntryalleen een beslissing voortextInputs[*].shouldPrompthoeft te delegeren
Publiceren en installeren
Externe plugins: publiceer naar ClawHub en installeer daarna:- npm
- Alleen ClawHub
- npm-pakketspecificatie
Voor installaties vanuit npm installeert
openclaw plugins install het pakket onder ~/.openclaw/npm met lifecycle-scripts uitgeschakeld. Houd afhankelijkheidsstructuren van Plugins zuiver JS/TS en vermijd pakketten die postinstall-builds vereisen.Het opstarten van de Gateway installeert geen Plugin-afhankelijkheden. npm/git/ClawHub-installatiestromen zijn eigenaar van convergentie van afhankelijkheden; lokale Plugins moeten hun afhankelijkheden al geinstalleerd hebben.
Gerelateerd
- Plugins bouwen — stapsgewijze gids om aan de slag te gaan
- Plugin-manifest — volledige referentie voor het manifestschema
- SDK-entrypoints —
definePluginEntryendefineChannelPluginEntry