Referentie voor Plugin-verpakking (Documentation Index
Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt
Use this file to discover all available pages before exploring further.
package.json-metadata), manifests (openclaw.plugin.json), setupvermeldingen en configuratieschema’s.
Pakketmetadata
Jepackage.json heeft een openclaw-veld nodig dat het Plugin-systeem vertelt wat je Plugin levert:
- Kanaal-plugin
- Provider-plugin / ClawHub-baseline
Als je de Plugin extern op ClawHub publiceert, 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).
Metadata voor de kanaalcatalogus 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 kanaalontdekking en setupoppervlakken voordat de runtime laadt.
| Veld | Type | Wat het betekent |
|---|---|---|
id | string | Canonieke kanaal-id. |
label | string | Primair kanaallabel. |
selectionLabel | string | Kiezer-/setuplabel wanneer dit moet verschillen van label. |
detailLabel | string | Secundair detaillabel voor rijkere kanaalcatalogi en statusoppervlakken. |
docsPath | string | Documentatiepad voor setup- en selectielinks. |
docsLabel | string | Overschrijft het label dat voor documentatielinks wordt gebruikt wanneer dit moet verschillen van de kanaal-id. |
blurb | string | Korte beschrijving voor onboarding/catalogus. |
order | number | Sorteervolgorde in kanaalcatalogi. |
aliases | string[] | Extra opzoekaliassen voor kanaalselectie. |
preferOver | string[] | Plugin-/kanaal-id’s met lagere prioriteit waar dit kanaal boven moet staan. |
systemImage | string | Optionele pictogram-/systeemafbeeldingsnaam voor kanaal-UI-catalogi. |
selectionDocsPrefix | string | Prefixtekst vóór documentatielinks in selectieoppervlakken. |
selectionDocsOmitLabel | boolean | Toon het documentatiepad direct in plaats van een gelabelde documentatielink 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 het kanaal voor setup-, geconfigureerde lijst- en documentatieoppervlakken. |
quickstartAllowFrom | boolean | Laat dit kanaal meedoen aan de standaard quickstart-setupflow allowFrom. |
forceAccountBinding | boolean | Vereis expliciete accountkoppeling, zelfs wanneer er maar één account bestaat. |
preferSessionLookupForAnnounceTarget | boolean | Geef de voorkeur aan sessie-opzoeking 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 documentatie-/navigatieoppervlakken
showConfigured en showInSetup blijven ondersteund als legacy-aliassen. Geef de voorkeur aan exposure.openclaw.install
openclaw.install is pakketmetadata, geen manifestmetadata.
| Veld | Type | Wat het betekent |
|---|---|---|
clawhubSpec | string | Canonieke ClawHub-specificatie voor installatie/update en onboardingflows voor installeren 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 er 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-dist-integriteitsstring, meestal sha512-..., voor vastgepinde installaties. |
allowInvalidConfigRecovery | boolean | Laat herinstallatieflows voor gebundelde Plugins herstellen van specifieke fouten door verouderde configuratie. |
Onboardinggedrag
Onboardinggedrag
Interactieve onboarding gebruikt ook
openclaw.install voor oppervlakken voor installeren op aanvraag. Als je Plugin provider-authenticatiekeuzes of metadata voor kanaalsetup/catalogus blootstelt voordat de runtime laadt, kan onboarding die keuze tonen, vragen om installatie via ClawHub, npm of lokaal, de Plugin installeren of inschakelen en daarna doorgaan met de geselecteerde flow. ClawHub-onboardingkeuzes gebruiken clawhubSpec en krijgen de voorkeur wanneer aanwezig; 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.Afdwinging van minHostVersion
Afdwinging van minHostVersion
Als
minHostVersion is ingesteld, dwingen zowel installatie als het laden van niet-gebundelde manifestregistries dit af. Oudere hosts slaan externe Plugins over; ongeldige versiestrings worden geweigerd. Gebundelde bron-Plugins worden geacht dezelfde versie te hebben als de hostcheckout.Vastgepinde npm-installaties
Vastgepinde npm-installaties
Houd voor vastgepinde npm-installaties de exacte versie in
npmSpec en voeg de verwachte artefactintegriteit toe:Scope van allowInvalidConfigRecovery
Scope van allowInvalidConfigRecovery
allowInvalidConfigRecovery is geen algemene omzeiling voor kapotte configuraties. Het is alleen bedoeld voor beperkt 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>-vermelding voor diezelfde Plugin. Als de configuratie om niet-gerelateerde redenen kapot is, mislukt de installatie nog steeds gesloten en krijgt de operator de opdracht openclaw doctor --fix uit te voeren.Uitgestelde volledige laadactie
Kanaal-Plugins kunnen kiezen voor uitgesteld laden met:setupEntry, zelfs voor al geconfigureerde kanalen. De volledige entry laadt 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 in de pakketroot meeleveren. OpenClaw gebruikt dit om configuratie te valideren zonder Plugin-code uit te voeren.
kind en channels toe:
Publiceren op ClawHub
Gebruik voor Plugin-pakketten de pakketspecifieke ClawHub-opdracht:De verouderde publicatiealias alleen voor skills is bedoeld voor skills. Pluginpakketten 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, config-reparatie, 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-bedrading 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 luistert.
- Alle Gateway-methoden die tijdens het opstarten nodig zijn.
config.* of update.* vermijden.Wat setupEntry NIET moet bevatten
Wat setupEntry NIET moet bevatten
- CLI-registraties.
- Achtergrondservices.
- Zware runtime-imports (crypto, SDK’s).
- Gateway-methoden die alleen na het opstarten nodig zijn.
Smalle setup-helperimports
Gebruik voor hete paden die alleen setup nodig hebben liever de smalle setup-helperseams dan de bredereplugin-sdk/setup-paraplu wanneer je slechts een deel van het setup-oppervlak nodig hebt:
| Importpad | Gebruik dit voor | Belangrijkste exports |
|---|---|---|
plugin-sdk/setup-runtime | runtimehelpers tijdens setup die beschikbaar blijven in setupEntry / uitgestelde kanaalstart | createPatchedAccountSetupAdapter, createEnvPatchedAccountSetupAdapter, createSetupInputPresenceValidator, noteChannelLookupFailure, noteChannelLookupSummary, promptResolvedAllowFrom, splitSetupEntries, createAllowlistSetupWizardProxy, createDelegatedSetupWizardProxy |
plugin-sdk/setup-adapter-runtime | omgevingsbewuste adapters voor accountsetup | createEnvPatchedAccountSetupAdapter |
plugin-sdk/setup-tools | helpers voor setup-/installatie-CLI/archieven/docs | formatCliCommand, detectBinary, extractArchive, resolveBrewExecutable, formatDocsLink, CONFIG_DIR |
plugin-sdk/setup-seam wanneer je de volledige gedeelde setup-toolbox wilt, inclusief config-patchhelpers zoals moveSingleAccountChannelSectionToDefaultAccount(...).
De setup-patchadapters blijven veilig voor het hete pad bij import. Hun gebundelde contract-oppervlaklookup voor promotie van één account is lazy, dus het importeren van plugin-sdk/setup-runtime laadt de gebundelde contract-oppervlakontdekking niet gretig voordat de adapter daadwerkelijk wordt gebruikt.
Kanaal-eigen promotie van één account
Wanneer een kanaal wordt geüpgraded van een top-level config voor één account naarchannels.<id>.accounts.*, is het standaard gedeelde gedrag dat gepromoveerde account-scoped waarden naar accounts.default worden verplaatst.
Gebundelde kanalen kunnen die promotie beperken 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 policy-/delivery-keys blijven op de kanaalrootresolveSingleAccountPromotionTarget(...): kies welk bestaand account gepromoveerde waarden ontvangt
Matrix is het huidige gebundelde voorbeeld. Als er al precies één benoemd Matrix-account bestaat, of als
defaultAccount naar een bestaande niet-canonieke key zoals Ops wijst, behoudt promotie dat account in plaats van een nieuwe accounts.default-entry te maken.Config-schema
Pluginconfiguratie 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 Plugin-eigen configuratieartefacten:
openclaw.plugin.json#channelConfigs, zodat configuratieschema-, setup- en UI-oppervlakken channels.<id> kunnen inspecteren zonder runtimecode te laden.
Setupwizards
Kanaalplugins kunnen interactieve setupwizards bieden vooropenclaw onboard. De wizard is een ChannelSetupWizard-object op de ChannelPlugin:
ChannelSetupWizard ondersteunt credentials, textInputs, dmPolicy, allowFrom, groupAccess, prepare, finalize en meer. Zie gebundelde Pluginpakketten (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 setuphelpers uit openclaw/plugin-sdk/setup: createPromptParsedAllowFromForAccount(...), createTopLevelChannelParsedAllowFromPrompt(...) en createNestedChannelParsedAllowFromPrompt(...).Standaardstatus voor kanaalsetup
Standaardstatus voor kanaalsetup
Geef voor statusblokken voor kanaalsetup 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 lower-level builders createOptionalChannelSetupAdapter(...) en createOptionalChannelSetupWizard(...) wanneer je slechts één helft van dat optionele installatieoppervlak nodig hebt.De gegenereerde optionele adapter/wizard faalt gesloten bij echte configuratieschrijfacties. Ze hergebruiken één installatie-vereist-bericht in validateInput, applyAccountConfig en finalize, en voegen een docs-link toe wanneer docsPath is ingesteld.Binary-backed setuphelpers
Binary-backed setuphelpers
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 tekstinvoer met padbackingcreateDelegatedSetupWizardStatusResolvers(...),createDelegatedPrepare(...),createDelegatedFinalize(...)encreateDelegatedResolveConfigured(...)wanneersetupEntrylazy naar een zwaardere volledige wizard moet doorsturencreateDelegatedTextInputShouldPrompt(...)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 afhankelijkheidsbomen van Plugins puur 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 afhankelijkheidsconvergentie; lokale Plugins moeten hun afhankelijkheden al geïnstalleerd hebben.
Gerelateerd
- Plugins bouwen — stapsgewijze gids om aan de slag te gaan
- Plugin-manifest — volledige referentie voor het manifestschema
- SDK-entrypoints —
definePluginEntryendefineChannelPluginEntry