package.json-metadata), manifesten (openclaw.plugin.json), setup-items en configuratieschema’s.
Pakketmetadata
Jepackage.json heeft een openclaw-veld nodig dat het Plugin-systeem vertelt wat je Plugin biedt:
- Channel 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 aan de pakketroot).
Lichtgewicht item alleen voor setup (optioneel).
Kanaalcatalogusmetadata voor setup-, kiezer-, quickstart- en statusoppervlakken.
Provider-id’s die door deze Plugin worden geregistreerd.
Installatietips:
npmSpec, localPath, defaultChoice, minHostVersion, expectedIntegrity, allowInvalidConfigRecovery.Opstartgedragsvlaggen.
openclaw.channel
openclaw.channel is goedkope pakketmetadata voor kanaalontdekking en setup-oppervlakken 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 afwijken van label. |
detailLabel | string | Secundair detaillabel voor rijkere kanaalcatalogi en statusoppervlakken. |
docsPath | string | Documentatiepad voor setup- en selectielinks. |
docsLabel | string | Overschrijvend label voor documentatielinks wanneer dit moet afwijken van de kanaal-id. |
blurb | string | Korte onboarding-/catalogusbeschrijving. |
order | number | Sorteervolgorde in kanaalcatalogi. |
aliases | string[] | Extra lookup-aliassen 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 | Voorvoegseltekst 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 kanalen voor setup, geconfigureerde lijsten 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-lookup 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 install-on-demandflows tijdens onboarding. |
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-dist-integriteitsstring, meestal sha512-..., voor vastgepinde installaties. |
allowInvalidConfigRecovery | boolean | Laat herinstallatieflows van gebundelde Plugins herstellen van specifieke stale-configfouten. |
requiredPlatformPackages | string[] | Vereiste platformspecifieke npm-aliassen die tijdens npm-installatie worden geverifieerd. |
Onboarding behavior
Onboarding behavior
Interactieve onboarding gebruikt ook
openclaw.install voor install-on-demand-oppervlakken. Als je Plugin provider-authkeuzes of kanaalsetup-/catalogusmetadata blootstelt voordat de runtime laadt, kan onboarding die keuze tonen, om ClawHub-, npm- of lokale installatie vragen, de Plugin installeren of inschakelen en daarna doorgaan met de geselecteerde flow. ClawHub-onboardingkeuzes gebruiken clawhubSpec en hebben 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 dit te installeren” in package.json.minHostVersion enforcement
minHostVersion enforcement
Als
minHostVersion is ingesteld, dwingen installatie en niet-gebundelde manifest-registry-loading dit allebei af. Oudere hosts slaan externe Plugins over; ongeldige versiestrings worden geweigerd. Gebundelde bron-Plugins worden geacht mee geversioneerd te zijn met de host-checkout.Pinned npm installs
Pinned npm installs
Houd voor vastgepinde npm-installaties de exacte versie in
npmSpec en voeg de verwachte artefactintegriteit toe:allowInvalidConfigRecovery scope
allowInvalidConfigRecovery scope
allowInvalidConfigRecovery is geen algemene bypass voor kapotte configuraties. Het is alleen bedoeld voor nauw herstel van gebundelde Plugins, zodat herinstallatie/setup bekende upgrade-restanten kan repareren, zoals een ontbrekend pad naar een gebundelde Plugin of een stale channels.<id>-item voor diezelfde Plugin. Als de configuratie om niet-gerelateerde redenen kapot is, faalt installatie nog steeds gesloten en vertelt dit de operator om openclaw doctor --fix uit te voeren.Uitgestelde volledige load
Kanaalplugins kunnen zich aanmelden voor uitgesteld laden met:setupEntry tijdens de pre-listen-opstartfase, zelfs voor al geconfigureerde kanalen. Het volledige item laadt nadat de gateway begint te luisteren.
Als je setup-/volledige item Gateway-RPC-methoden registreert, houd ze dan op een Plugin-specifiek prefix. Gereserveerde core-adminnamespaces (config.*, exec.approvals.*, wizard.*, update.*) blijven eigendom van core en worden altijd opgelost naar operator.admin.
Plugin-manifest
Elke native Plugin moet eenopenclaw.plugin.json in de pakketroot leveren. OpenClaw gebruikt dit om configuratie te valideren zonder Plugin-code uit te voeren.
kind en channels toe:
ClawHub-publicatie
Gebruik voor Plugin-pakketten de pakketspecifieke ClawHub-opdracht:De verouderde publicatie-alias alleen voor skills is bedoeld voor Skills. Plugin-pakketten moeten altijd
clawhub package publish gebruiken.Setup-item
Het bestandsetup-entry.ts is een lichtgewicht alternatief voor index.ts dat OpenClaw laadt wanneer het alleen setup-oppervlakken nodig heeft (onboarding, configuratieherstel, 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 het volledige item
Wanneer OpenClaw setupEntry gebruikt in plaats van het volledige item
- 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 vóór gateway-listen vereist zijn.
- 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 pas na het opstarten nodig zijn.
Smalle imports voor setup-helpers
Gebruik voor hete paden die alleen setup nodig hebben liever de smalle setup-helpernaden dan de bredereplugin-sdk/setup-paraplu wanneer je maar een deel van het setup-oppervlak nodig hebt:
| Importpad | Gebruik het voor | Belangrijke exports |
|---|---|---|
plugin-sdk/setup-runtime | runtime-helpers tijdens setup die beschikbaar blijven in setupEntry / uitgestelde kanaalstart | createSetupTranslator, 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/archief/docs | formatCliCommand, detectBinary, extractArchive, resolveBrewExecutable, formatDocsLink, CONFIG_DIR |
plugin-sdk/setup-naad wanneer je de volledige gedeelde setup-toolbox wilt, inclusief configuratiepatch-helpers zoals moveSingleAccountChannelSectionToDefaultAccount(...).
Gebruik createSetupTranslator(...) voor vaste setup-wizardtekst. Deze volgt de
CLI-wizardlocale (OPENCLAW_LOCALE, daarna systeemlocalevariabelen) en valt
terug op Engels. Houd Plugin-specifieke setuptekst in code die eigendom is van de Plugin en gebruik
gedeelde catalogussleutels alleen voor algemene setuplabels, statustekst en officiële
gebundelde Plugin-setuptekst.
De setup-patchadapters blijven veilig voor hete paden 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.
Kanaaleigen promotie van één account
Wanneer een kanaal opwaardeert 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 beperken of overschrijven via hun setup-contractoppervlak:
singleAccountKeysToMove: extra top-level sleutels die naar het gepromoveerde account moeten worden verplaatstnamedAccountPromotionKeys: wanneer benoemde accounts al bestaan, worden alleen deze sleutels naar het gepromoveerde account verplaatst; gedeelde beleids-/bezorgsleutels blijven in 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 sleutel zoals Ops verwijst, behoudt promotie dat account in plaats van een nieuw accounts.default-item 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
Kanaal-Plugins 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. Zie 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 statusblokken voor kanaalsetup die alleen verschillen per labels, scores en optionele extra regels de voorkeur aan
createStandardChannelSetupStatus(...) uit openclaw/plugin-sdk/setup in plaats van hetzelfde status-object handmatig in elke Plugin te maken.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 stelt ook de lagere createOptionalChannelSetupAdapter(...)- en createOptionalChannelSetupWizard(...)-builders beschikbaar 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 voor validateInput, applyAccountConfig en finalize, en voegen een docs-link toe wanneer docsPath is ingesteld.Setup-helpers met binaire ondersteuning
Setup-helpers met binaire ondersteuning
Geef voor setup-UI’s met binaire ondersteuning de voorkeur aan de gedeelde gedelegeerde helpers in plaats van dezelfde binaire/statuslijm naar elk kanaal te kopiëren:
createDetectedBinaryStatus(...)voor statusblokken die alleen verschillen in labels, hints, scores en binaire detectiecreateCliPathTextInput(...)voor tekstinvoer op basis van padencreateDelegatedSetupWizardStatusResolvers(...),createDelegatedPrepare(...),createDelegatedFinalize(...)encreateDelegatedResolveConfigured(...)wanneersetupEntrylui moet doorsturen naar een zwaardere volledige wizardcreateDelegatedTextInputShouldPrompt(...)wanneersetupEntryalleen eentextInputs[*].shouldPrompt-beslissing hoeft te delegeren
Publiceren en installeren
Externe plugins: publiceer naar ClawHub en installeer daarna:- npm
- ClawHub only
- npm package spec
Voor installaties vanuit npm installeert
openclaw plugins install het pakket in een project per plugin onder ~/.openclaw/npm/projects, met lifecycle-scripts uitgeschakeld. Houd afhankelijkheidsbomen van plugins zuiver JS/TS en vermijd pakketten die postinstall-builds vereisen.Gateway-start installeert geen plugin-afhankelijkheden. npm/git/ClawHub-installatiestromen zijn verantwoordelijk voor afhankelijkheidsconvergentie; lokale plugins moeten hun afhankelijkheden al geïnstalleerd hebben.
Gerelateerd
- Plugins bouwen — stapsgewijze handleiding om aan de slag te gaan
- Plugin-manifest — volledige referentie voor het manifestschema
- SDK-entrypoints —
definePluginEntryendefineChannelPluginEntry