Referenz für Plugin-Paketierung (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-Metadaten), Manifeste (openclaw.plugin.json), Setup-Einträge und Konfigurationsschemas.
Paketmetadaten
Ihrepackage.json benötigt ein openclaw-Feld, das dem Plugin-System mitteilt, was Ihr Plugin bereitstellt:
- Channel plugin
- Provider plugin / ClawHub baseline
Wenn Sie das Plugin extern auf ClawHub veröffentlichen, sind diese Felder
compat und build erforderlich. Die kanonischen Veröffentlichungssnippets befinden sich in docs/snippets/plugin-publish/.openclaw-Felder
Einstiegspunktdateien (relativ zum Paketstamm).
Leichtgewichtiger reiner Setup-Eintrag (optional).
Channel-Katalogmetadaten für Setup, Auswahl, Schnellstart und Statusoberflächen.
Von diesem Plugin registrierte Provider-IDs.
Installationshinweise:
npmSpec, localPath, defaultChoice, minHostVersion, expectedIntegrity, allowInvalidConfigRecovery.Flags für das Startverhalten.
openclaw.channel
openclaw.channel sind günstige Paketmetadaten für Channel-Erkennung und Setup-Oberflächen, bevor die Runtime lädt.
| Feld | Typ | Bedeutung |
|---|---|---|
id | string | Kanonische Channel-ID. |
label | string | Primäres Channel-Label. |
selectionLabel | string | Auswahl-/Setup-Label, wenn es sich von label unterscheiden soll. |
detailLabel | string | Sekundäres Detail-Label für umfangreichere Channel-Kataloge und Statusoberflächen. |
docsPath | string | Dokumentationspfad für Setup- und Auswahllinks. |
docsLabel | string | Überschreibungs-Label für Dokumentationslinks, wenn es sich von der Channel-ID unterscheiden soll. |
blurb | string | Kurze Onboarding-/Katalogbeschreibung. |
order | number | Sortierreihenfolge in Channel-Katalogen. |
aliases | string[] | Zusätzliche Lookup-Aliasse für die Channel-Auswahl. |
preferOver | string[] | Plugin-/Channel-IDs mit niedrigerer Priorität, die dieser Channel übertreffen soll. |
systemImage | string | Optionaler Icon-/System-Image-Name für Channel-UI-Kataloge. |
selectionDocsPrefix | string | Präfixtext vor Dokumentationslinks in Auswahloberflächen. |
selectionDocsOmitLabel | boolean | Den Dokumentationspfad direkt anzeigen statt eines beschrifteten Dokumentationslinks im Auswahltext. |
selectionExtras | string[] | Zusätzliche kurze Strings, die im Auswahltext angehängt werden. |
markdownCapable | boolean | Markiert den Channel als Markdown-fähig für Entscheidungen zur ausgehenden Formatierung. |
exposure | object | Sichtbarkeitssteuerung des Channels für Setup, konfigurierte Listen und Dokumentationsoberflächen. |
quickstartAllowFrom | boolean | Nimmt diesen Channel in den standardmäßigen Schnellstart-Setup-Flow allowFrom auf. |
forceAccountBinding | boolean | Erfordert explizite Konto-Bindung, selbst wenn nur ein Konto existiert. |
preferSessionLookupForAnnounceTarget | boolean | Bevorzugt die Sitzungssuche beim Auflösen von Ankündigungszielen für diesen Channel. |
exposure unterstützt:
configured: Channel in konfigurierte bzw. statusartige Listenoberflächen aufnehmensetup: Channel in interaktive Setup-/Konfigurationsauswahlen aufnehmendocs: Channel in Dokumentations-/Navigationsoberflächen als öffentlich sichtbar markieren
showConfigured und showInSetup bleiben als Legacy-Aliasse unterstützt. Bevorzugen Sie exposure.openclaw.install
openclaw.install sind Paketmetadaten, keine Manifestmetadaten.
| Feld | Typ | Bedeutung |
|---|---|---|
clawhubSpec | string | Kanonische ClawHub-Spezifikation für Install-/Update- und Onboarding-Install-on-Demand-Flows. |
npmSpec | string | Kanonische npm-Spezifikation für Install-/Update-Fallback-Flows. |
localPath | string | Lokaler Entwicklungs- oder gebündelter Installationspfad. |
defaultChoice | "clawhub" | "npm" | "local" | Bevorzugte Installationsquelle, wenn mehrere Quellen verfügbar sind. |
minHostVersion | string | Minimal unterstützte OpenClaw-Version im Format >=x.y.z oder >=x.y.z-prerelease. |
expectedIntegrity | string | Erwarteter npm-Dist-Integritätsstring, üblicherweise sha512-..., für gepinnte Installationen. |
allowInvalidConfigRecovery | boolean | Ermöglicht Neuinstallations-Flows gebündelter Plugins die Wiederherstellung nach bestimmten veralteten Konfigurationsfehlern. |
Onboarding behavior
Onboarding behavior
Interaktives Onboarding verwendet
openclaw.install auch für Install-on-Demand-Oberflächen. Wenn Ihr Plugin vor dem Laden der Runtime Provider-Auth-Optionen oder Channel-Setup-/Katalogmetadaten bereitstellt, kann das Onboarding diese Option anzeigen, nach ClawHub, npm oder lokaler Installation fragen, das Plugin installieren oder aktivieren und anschließend den ausgewählten Flow fortsetzen. ClawHub-Onboarding-Optionen verwenden clawhubSpec und werden bevorzugt, wenn vorhanden; npm-Optionen erfordern vertrauenswürdige Katalogmetadaten mit einer Registry-npmSpec; exakte Versionen und expectedIntegrity sind optionale npm-Pins. Wenn expectedIntegrity vorhanden ist, erzwingen Install-/Update-Flows diesen Wert für npm. Bewahren Sie die Metadaten dazu, „was angezeigt werden soll“, in openclaw.plugin.json und die Metadaten dazu, „wie es installiert wird“, in package.json auf.minHostVersion enforcement
minHostVersion enforcement
Wenn
minHostVersion gesetzt ist, erzwingen sowohl die Installation als auch das Laden der nicht gebündelten Manifest-Registry diesen Wert. Ältere Hosts überspringen externe Plugins; ungültige Versionsstrings werden abgelehnt. Gebündelte Source-Plugins werden als mit dem Host-Checkout versionsgleich angenommen.Pinned npm installs
Pinned npm installs
Behalten Sie für gepinnte npm-Installationen die exakte Version in
npmSpec bei und fügen Sie die erwartete Artefaktintegrität hinzu:allowInvalidConfigRecovery scope
allowInvalidConfigRecovery scope
allowInvalidConfigRecovery ist keine allgemeine Umgehung für defekte Konfigurationen. Es dient nur der eng begrenzten Wiederherstellung gebündelter Plugins, damit Neuinstallation/Setup bekannte Upgrade-Überreste reparieren können, etwa einen fehlenden gebündelten Plugin-Pfad oder einen veralteten Eintrag channels.<id> für dasselbe Plugin. Wenn die Konfiguration aus anderen Gründen defekt ist, schlägt die Installation weiterhin geschlossen fehl und weist den Operator an, openclaw doctor --fix auszuführen.Verzögertes vollständiges Laden
Channel-Plugins können verzögertes Laden aktivieren mit:setupEntry, auch für bereits konfigurierte Channels. Der vollständige Eintrag lädt, nachdem das Gateway zu lauschen beginnt.
Wenn Ihr Setup-/vollständiger Eintrag Gateway-RPC-Methoden registriert, behalten Sie diese unter einem Plugin-spezifischen Präfix. Reservierte Core-Admin-Namespaces (config.*, exec.approvals.*, wizard.*, update.*) bleiben Core-eigen und werden immer zu operator.admin aufgelöst.
Plugin-Manifest
Jedes native Plugin muss einopenclaw.plugin.json im Paketstamm ausliefern. OpenClaw verwendet dies, um Konfiguration zu validieren, ohne Plugin-Code auszuführen.
kind und channels hinzu:
ClawHub-Veröffentlichung
Verwenden Sie für Plugin-Pakete den paketbezogenen ClawHub-Befehl:Der veraltete Publish-Alias nur für Skills ist für Skills vorgesehen. Plugin-Pakete sollten immer
clawhub package publish verwenden.Setup-Einstieg
Die Dateisetup-entry.ts ist eine leichtgewichtige Alternative zu index.ts, die OpenClaw lädt, wenn nur Setup-Oberflächen benötigt werden (Onboarding, Konfigurationsreparatur, Prüfung deaktivierter Kanäle).
defineSetupPluginEntry(...) defineBundledChannelSetupEntry(...) aus openclaw/plugin-sdk/channel-entry-contract verwenden. Dieser gebündelte Vertrag unterstützt außerdem einen optionalen runtime-Export, sodass die Laufzeitverdrahtung zur Setup-Zeit leichtgewichtig und explizit bleiben kann.
When OpenClaw uses setupEntry instead of the full entry
When OpenClaw uses setupEntry instead of the full entry
- Der Kanal ist deaktiviert, benötigt aber Setup-/Onboarding-Oberflächen.
- Der Kanal ist aktiviert, aber nicht konfiguriert.
- Verzögertes Laden ist aktiviert (
deferConfiguredChannelFullLoadUntilAfterListen).
What setupEntry must register
What setupEntry must register
- Das Kanal-Plugin-Objekt (über
defineSetupPluginEntry). - Alle HTTP-Routen, die vor dem Gateway-Listen erforderlich sind.
- Alle Gateway-Methoden, die während des Starts benötigt werden.
config.* oder update.* vermeiden.What setupEntry should NOT include
What setupEntry should NOT include
- CLI-Registrierungen.
- Hintergrunddienste.
- Schwergewichtige Laufzeit-Imports (Krypto, SDKs).
- Gateway-Methoden, die erst nach dem Start benötigt werden.
Schmale Setup-Hilfs-Imports
Für heiße reine Setup-Pfade sollten Sie die schmalen Setup-Hilfs-Seams gegenüber dem breiteren Umbrellaplugin-sdk/setup bevorzugen, wenn Sie nur einen Teil der Setup-Oberfläche benötigen:
| Importpfad | Verwendung | Wichtige Exporte |
|---|---|---|
plugin-sdk/setup-runtime | Laufzeit-Helfer zur Setup-Zeit, die in setupEntry / beim verzögerten Kanalstart verfügbar bleiben | createPatchedAccountSetupAdapter, createEnvPatchedAccountSetupAdapter, createSetupInputPresenceValidator, noteChannelLookupFailure, noteChannelLookupSummary, promptResolvedAllowFrom, splitSetupEntries, createAllowlistSetupWizardProxy, createDelegatedSetupWizardProxy |
plugin-sdk/setup-adapter-runtime | veralteter Kompatibilitäts-Alias; verwenden Sie plugin-sdk/setup-runtime | createEnvPatchedAccountSetupAdapter |
plugin-sdk/setup-tools | Setup-/Installations-CLI-/Archiv-/Dokumentations-Helfer | formatCliCommand, detectBinary, extractArchive, resolveBrewExecutable, formatDocsLink, CONFIG_DIR |
plugin-sdk/setup, wenn Sie die vollständige gemeinsam genutzte Setup-Toolbox wünschen, einschließlich Konfigurations-Patch-Helfern wie moveSingleAccountChannelSectionToDefaultAccount(...).
Die Setup-Patch-Adapter bleiben beim Import für Hot Paths sicher. Ihre gebündelte Contract-Surface-Suche für die Einzelkonto-Promotion ist lazy, sodass der Import von plugin-sdk/setup-runtime die gebündelte Contract-Surface-Erkennung nicht eifrig lädt, bevor der Adapter tatsächlich verwendet wird.
Kanaleigene Einzelkonto-Promotion
Wenn ein Kanal von einer Einzelkonto-Konfiguration auf oberster Ebene aufchannels.<id>.accounts.* aktualisiert, verschiebt das standardmäßige gemeinsame Verhalten die hochgestuften kontobezogenen Werte nach accounts.default.
Gebündelte Kanäle können diese Promotion über ihre Setup-Contract-Surface eingrenzen oder überschreiben:
singleAccountKeysToMove: zusätzliche Schlüssel auf oberster Ebene, die in das hochgestufte Konto verschoben werden sollennamedAccountPromotionKeys: wenn benannte Konten bereits existieren, werden nur diese Schlüssel in das hochgestufte Konto verschoben; gemeinsame Policy-/Delivery-Schlüssel bleiben im KanalstammresolveSingleAccountPromotionTarget(...): wählt, welches vorhandene Konto hochgestufte Werte erhält
Matrix ist das aktuelle gebündelte Beispiel. Wenn genau ein benanntes Matrix-Konto bereits existiert oder wenn
defaultAccount auf einen vorhandenen nicht-kanonischen Schlüssel wie Ops zeigt, behält die Promotion dieses Konto bei, anstatt einen neuen Eintrag accounts.default zu erstellen.Konfigurationsschema
Die Plugin-Konfiguration wird gegen das JSON Schema in Ihrem Manifest validiert. Benutzer konfigurieren Plugins über:api.pluginConfig.
Für kanalspezifische Konfiguration verwenden Sie stattdessen den Abschnitt für die Kanalkonfiguration:
Kanalkonfigurationsschemata erstellen
Verwenden SiebuildChannelConfigSchema, um ein Zod-Schema in den ChannelConfigSchema-Wrapper zu konvertieren, der von Plugin-eigenen Konfigurationsartefakten verwendet wird:
openclaw.plugin.json#channelConfigs, damit Konfigurationsschema, Setup und UI-Oberflächen channels.<id> prüfen können, ohne Laufzeitcode zu laden.
Setup-Assistenten
Kanal-Plugins können interaktive Setup-Assistenten füropenclaw onboard bereitstellen. Der Assistent ist ein ChannelSetupWizard-Objekt auf dem ChannelPlugin:
ChannelSetupWizard unterstützt credentials, textInputs, dmPolicy, allowFrom, groupAccess, prepare, finalize und mehr. Vollständige Beispiele finden Sie in gebündelten Plugin-Paketen, zum Beispiel im Discord-Plugin src/channel.setup.ts.
Shared allowFrom prompts
Shared allowFrom prompts
Standard channel setup status
Standard channel setup status
Für Statusblöcke der Kanal-Einrichtung, die nur nach Labels, Scores und optionalen zusätzlichen Zeilen variieren, bevorzugen Sie
createStandardChannelSetupStatus(...) aus openclaw/plugin-sdk/setup, statt in jedem Plugin dasselbe status-Objekt von Hand zu erstellen.Optional channel setup surface
Optional channel setup surface
Für optionale Setup-Oberflächen, die nur in bestimmten Kontexten erscheinen sollen, verwenden Sie
createOptionalChannelSetupSurface aus openclaw/plugin-sdk/channel-setup:plugin-sdk/channel-setup stellt außerdem die Low-Level-Builder createOptionalChannelSetupAdapter(...) und createOptionalChannelSetupWizard(...) bereit, wenn Sie nur eine Hälfte dieser optionalen Installationsoberfläche benötigen.Der generierte optionale Adapter/Assistent schlägt bei echten Konfigurationsschreibvorgängen geschlossen fehl. Er verwendet eine Installations-erforderlich-Meldung für validateInput, applyAccountConfig und finalize wieder und hängt einen Dokumentationslink an, wenn docsPath gesetzt ist.Binary-backed setup helpers
Binary-backed setup helpers
Für binary-gestützte Setup-UIs bevorzugen Sie die gemeinsamen delegierten Helfer, statt denselben Binary-/Status-Glue in jeden Kanal zu kopieren:
createDetectedBinaryStatus(...)für Statusblöcke, die nur nach Labels, Hinweisen, Scores und Binary-Erkennung variierencreateCliPathTextInput(...)für pfadgestützte TexteingabencreateDelegatedSetupWizardStatusResolvers(...),createDelegatedPrepare(...),createDelegatedFinalize(...)undcreateDelegatedResolveConfigured(...), wennsetupEntrylazy an einen schwergewichtigeren vollständigen Assistenten weiterleiten musscreateDelegatedTextInputShouldPrompt(...), wennsetupEntrynur eine Entscheidung fürtextInputs[*].shouldPromptdelegieren muss
Veröffentlichen und Installieren
Externe Plugins: Veröffentlichen Sie auf ClawHub, dann installieren Sie:- npm
- ClawHub only
- npm package spec
Bei Installationen aus npm installiert
openclaw plugins install das Paket unter ~/.openclaw/npm mit deaktivierten Lifecycle-Skripten. Halten Sie Plugin-Abhängigkeitsbäume rein JS/TS-basiert und vermeiden Sie Pakete, die postinstall-Builds erfordern.Der Gateway-Start installiert keine Plugin-Abhängigkeiten. Installationsabläufe über npm/git/ClawHub sind für den Abgleich der Abhängigkeiten verantwortlich; bei lokalen Plugins müssen die Abhängigkeiten bereits installiert sein.
Verwandt
- Plugins erstellen — Schritt-für-Schritt-Anleitung für den Einstieg
- Plugin-Manifest — vollständige Referenz zum Manifest-Schema
- SDK-Einstiegspunkte —
definePluginEntryunddefineChannelPluginEntry