package.json-Metadaten), Manifeste (openclaw.plugin.json), Einrichtungseinträ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
compat- und build-Felder erforderlich. Die kanonischen Veröffentlichungssnippets befinden sich in docs/snippets/plugin-publish/.openclaw-Felder
Einstiegspunktdateien (relativ zum Paket-Root).
Leichtgewichtiger Einstieg nur für die Einrichtung (optional).
Kanalkatalog-Metadaten für Einrichtungs-, 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 schlanke Paketmetadaten für die Kanalerkennung und Einrichtungsoberflächen, bevor die Laufzeit lädt.
| Feld | Typ | Bedeutung |
|---|---|---|
id | string | Kanonische Kanal-ID. |
label | string | Primäre Kanalbezeichnung. |
selectionLabel | string | Auswahl-/Einrichtungsbezeichnung, wenn sie von label abweichen soll. |
detailLabel | string | Sekundäre Detailbezeichnung für umfangreichere Kanalkataloge und Statusoberflächen. |
docsPath | string | Dokumentationspfad für Einrichtungs- und Auswahllinks. |
docsLabel | string | Überschreibt die für Dokumentationslinks verwendete Bezeichnung, wenn sie von der Kanal-ID abweichen soll. |
blurb | string | Kurze Onboarding-/Katalogbeschreibung. |
order | number | Sortierreihenfolge in Kanalkatalogen. |
aliases | string[] | Zusätzliche Suchaliase für die Kanalauswahl. |
preferOver | string[] | Plugin-/Kanal-IDs mit niedrigerer Priorität, die dieser Kanal übertreffen soll. |
systemImage | string | Optionaler Symbol-/System-Image-Name für Kanal-UI-Kataloge. |
selectionDocsPrefix | string | Präfixtext vor Dokumentationslinks in Auswahloberflächen. |
selectionDocsOmitLabel | boolean | Zeigt den Dokumentationspfad direkt statt eines beschrifteten Dokumentationslinks im Auswahltext an. |
selectionExtras | string[] | Zusätzliche kurze Zeichenfolgen, die im Auswahltext angehängt werden. |
markdownCapable | boolean | Markiert den Kanal als Markdown-fähig für Entscheidungen zur ausgehenden Formatierung. |
exposure | object | Sichtbarkeitssteuerung des Kanals für Einrichtung, konfigurierte Listen und Dokumentationsoberflächen. |
quickstartAllowFrom | boolean | Nimmt diesen Kanal in den standardmäßigen Schnellstart-allowFrom-Einrichtungsablauf auf. |
forceAccountBinding | boolean | Erfordert eine explizite Kontobindung, auch wenn nur ein Konto vorhanden ist. |
preferSessionLookupForAnnounceTarget | boolean | Bevorzugt die Sitzungssuche beim Auflösen von Ankündigungszielen für diesen Kanal. |
exposure unterstützt:
configured: Kanal in konfigurierten/statusähnlichen Listenoberflächen einschließensetup: Kanal in interaktive Einrichtungs-/Konfigurationsauswahlen einschließendocs: Kanal in Dokumentations-/Navigationsoberflächen als öffentlich markieren
showConfigured und showInSetup werden weiterhin als Legacy-Aliase unterstützt. Bevorzugen Sie exposure.openclaw.install
openclaw.install sind Paketmetadaten, keine Manifestmetadaten.
| Feld | Typ | Bedeutung |
|---|---|---|
clawhubSpec | string | Kanonische ClawHub-Spezifikation für Installations-/Aktualisierungs- und Onboarding-Install-on-Demand-Abläufe. |
npmSpec | string | Kanonische npm-Spezifikation für Installations-/Aktualisierungs-Fallback-Abläufe. |
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 in der Form >=x.y.z oder >=x.y.z-prerelease. |
expectedIntegrity | string | Erwartete npm-Dist-Integritätszeichenfolge, normalerweise sha512-..., für angeheftete Installationen. |
allowInvalidConfigRecovery | boolean | Ermöglicht Neuinstallationsabläufen gebündelter Plugins die Wiederherstellung nach bestimmten veralteten Konfigurationsfehlern. |
requiredPlatformPackages | string[] | Erforderliche plattformspezifische npm-Aliase, die während der npm-Installation geprüft werden. |
Onboarding behavior
Onboarding behavior
Interaktives Onboarding verwendet
openclaw.install auch für Install-on-Demand-Oberflächen. Wenn Ihr Plugin Provider-Authentifizierungsoptionen oder Kanaleinrichtungs-/Katalogmetadaten verfügbar macht, bevor die Laufzeit lädt, kann das Onboarding diese Option anzeigen, zur ClawHub-, npm- oder lokalen Installation auffordern, das Plugin installieren oder aktivieren und dann mit dem ausgewählten Ablauf fortfahren. 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 Installations-/Aktualisierungsabläufe sie für npm. Bewahren Sie die „was anzeigen“-Metadaten in openclaw.plugin.json und die „wie installieren“-Metadaten in package.json auf.minHostVersion enforcement
minHostVersion enforcement
Wenn
minHostVersion gesetzt ist, erzwingen sowohl Installation als auch nicht gebündeltes Laden aus der Manifest-Registry diese Version. Ältere Hosts überspringen externe Plugins; ungültige Versionszeichenfolgen werden abgelehnt. Gebündelte Quell-Plugins gelten als mit dem Host-Checkout gleich versioniert.Pinned npm installs
Pinned npm installs
Für angeheftete npm-Installationen behalten Sie die exakte Version in
npmSpec bei und fügen die erwartete Artefaktintegrität hinzu:allowInvalidConfigRecovery scope
allowInvalidConfigRecovery scope
allowInvalidConfigRecovery ist keine allgemeine Umgehung für defekte Konfigurationen. Es ist nur für eng begrenzte Wiederherstellung gebündelter Plugins gedacht, damit Neuinstallation/Einrichtung bekannte Upgrade-Reste wie einen fehlenden gebündelten Plugin-Pfad oder einen veralteten channels.<id>-Eintrag für dasselbe Plugin reparieren kann. 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.Aufgeschobenes vollständiges Laden
Kanal-Plugins können das aufgeschobene Laden aktivieren mit:setupEntry, auch für bereits konfigurierte Kanäle. Der vollständige Einstieg wird geladen, nachdem der Gateway zu lauschen beginnt.
Wenn Ihr Einrichtungs-/vollständiger Einstieg Gateway-RPC-Methoden registriert, halten Sie sie auf 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 Paket-Root ausliefern. OpenClaw verwendet dies, um die Konfiguration zu validieren, ohne Plugin-Code auszuführen.
kind und channels hinzu:
ClawHub-Veröffentlichung
Verwenden Sie für Plugin-Pakete den paketspezifischen ClawHub-Befehl:Der Legacy-Veröffentlichungsalias nur für Skills ist für Skills gedacht. Plugin-Pakete sollten immer
clawhub package publish verwenden.Setup-Einstiegspunkt
Die Dateisetup-entry.ts ist eine schlanke 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, damit die Runtime-Verdrahtung zur Setup-Zeit schlank und explizit bleiben kann.
Wann OpenClaw setupEntry statt des vollständigen Einstiegspunkts verwendet
Wann OpenClaw setupEntry statt des vollständigen Einstiegspunkts verwendet
- Der Kanal ist deaktiviert, benötigt aber Setup-/Onboarding-Oberflächen.
- Der Kanal ist aktiviert, aber nicht konfiguriert.
- Verzögertes Laden ist aktiviert (
deferConfiguredChannelFullLoadUntilAfterListen).
Was setupEntry registrieren muss
Was setupEntry registrieren muss
- 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.Was setupEntry NICHT enthalten sollte
Was setupEntry NICHT enthalten sollte
- CLI-Registrierungen.
- Hintergrunddienste.
- Umfangreiche Runtime-Importe (Krypto, SDKs).
- Gateway-Methoden, die erst nach dem Start benötigt werden.
Schmale Setup-Hilfsimporte
Bevorzugen Sie für heiße reine Setup-Pfade die schmalen Setup-Hilfs-Seams gegenüber dem breiterenplugin-sdk/setup-Umbrella, wenn Sie nur einen Teil der Setup-Oberfläche benötigen:
| Importpfad | Verwenden für | Wichtige Exporte |
|---|---|---|
plugin-sdk/setup-runtime | Runtime-Helfer zur Setup-Zeit, die in setupEntry / beim verzögerten Kanalstart verfügbar bleiben | createSetupTranslator, createPatchedAccountSetupAdapter, createEnvPatchedAccountSetupAdapter, createSetupInputPresenceValidator, noteChannelLookupFailure, noteChannelLookupSummary, promptResolvedAllowFrom, splitSetupEntries, createAllowlistSetupWizardProxy, createDelegatedSetupWizardProxy |
plugin-sdk/setup-adapter-runtime | veralteter Kompatibilitätsalias; verwenden Sie plugin-sdk/setup-runtime | createEnvPatchedAccountSetupAdapter |
plugin-sdk/setup-tools | Setup-/Installations-CLI-/Archiv-/Dokumentationshelfer | formatCliCommand, detectBinary, extractArchive, resolveBrewExecutable, formatDocsLink, CONFIG_DIR |
plugin-sdk/setup-Seam, wenn Sie die vollständige gemeinsame Setup-Toolbox einschließlich Konfigurations-Patch-Helfern wie moveSingleAccountChannelSectionToDefaultAccount(...) benötigen.
Verwenden Sie createSetupTranslator(...) für feste Texte des Setup-Assistenten. Er folgt der
CLI-Assistenten-Locale (OPENCLAW_LOCALE, dann System-Locale-Variablen) und fällt
auf Englisch zurück. Halten Sie Plugin-spezifischen Setup-Text in Plugin-eigenem Code und verwenden Sie
gemeinsame Katalogschlüssel nur für allgemeine Setup-Labels, Statustexte und offizielle
Setup-Texte gebündelter Plugins.
Die Setup-Patch-Adapter bleiben beim Import für Hot Paths sicher. Ihre gebündelte Contract-Surface-Suche für Single-Account-Promotion ist lazy, sodass der Import von plugin-sdk/setup-runtime die gebündelte Contract-Surface-Ermittlung nicht vorab lädt, bevor der Adapter tatsächlich verwendet wird.
Kanal-eigene Single-Account-Promotion
Wenn ein Kanal von einer Single-Account-Konfiguration auf oberster Ebene aufchannels.<id>.accounts.* aktualisiert, verschiebt das gemeinsame Standardverhalten hochgestufte account-bezogene Werte nach accounts.default.
Gebündelte Kanäle können diese Promotion über ihre Setup-Contract-Surface einschränken oder überschreiben:
singleAccountKeysToMove: zusätzliche Schlüssel auf oberster Ebene, die in den hochgestuften Account verschoben werden sollennamedAccountPromotionKeys: wenn benannte Accounts bereits vorhanden sind, werden nur diese Schlüssel in den hochgestuften Account verschoben; gemeinsame Policy-/Delivery-Schlüssel bleiben am Kanal-RootresolveSingleAccountPromotionTarget(...): wählt aus, welcher vorhandene Account hochgestufte Werte erhält
Matrix ist das aktuelle gebündelte Beispiel. Wenn genau ein benannter Matrix-Account bereits existiert oder wenn
defaultAccount auf einen vorhandenen nicht-kanonischen Schlüssel wie Ops zeigt, bewahrt die Promotion diesen Account, statt 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.
Verwenden Sie für kanalspezifische Konfiguration stattdessen den Kanal-Konfigurationsabschnitt:
Kanal-Konfigurationsschemas 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 Runtime-Code 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).
Gemeinsame allowFrom-Prompts
Gemeinsame allowFrom-Prompts
Bevorzugen Sie für DM-Allowlist-Prompts, die nur den Standardablauf
note -> prompt -> parse -> merge -> patch benötigen, die gemeinsamen Setup-Helfer aus openclaw/plugin-sdk/setup: createPromptParsedAllowFromForAccount(...), createTopLevelChannelParsedAllowFromPrompt(...) und createNestedChannelParsedAllowFromPrompt(...).Standardmäßiger Kanal-Setup-Status
Standardmäßiger Kanal-Setup-Status
Bevorzugen Sie für Kanal-Setup-Statusblöcke, die sich nur nach Labels, Scores und optionalen Zusatzzeilen unterscheiden,
createStandardChannelSetupStatus(...) aus openclaw/plugin-sdk/setup, statt dasselbe status-Objekt in jedem Plugin von Hand zu erstellen.Optionale Kanal-Setup-Oberfläche
Optionale Kanal-Setup-Oberfläche
Verwenden Sie für optionale Setup-Oberflächen, die nur in bestimmten Kontexten erscheinen sollen,
createOptionalChannelSetupSurface aus openclaw/plugin-sdk/channel-setup:plugin-sdk/channel-setup stellt außerdem die niedrigeren 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 dieselbe Meldung zur erforderlichen Installation über validateInput, applyAccountConfig und finalize hinweg wieder und hängt einen Dokumentationslink an, wenn docsPath gesetzt ist.Setup-Helfer mit Binary-Unterstützung
Setup-Helfer mit Binary-Unterstützung
Bevorzugen Sie für Binary-gestützte Setup-UIs die gemeinsamen delegierten Helfer, statt denselben Binary-/Status-Code in jeden Kanal zu kopieren:
createDetectedBinaryStatus(...)für Statusblöcke, die sich nur durch Labels, Hinweise, Scores und binäre Erkennung unterscheidencreateCliPathTextInput(...)für pfadgestützte TexteingabencreateDelegatedSetupWizardStatusResolvers(...),createDelegatedPrepare(...),createDelegatedFinalize(...)undcreateDelegatedResolveConfigured(...), wennsetupEntrybei Bedarf verzögert an einen umfangreicheren vollständigen Assistenten weiterleiten musscreateDelegatedTextInputShouldPrompt(...), wennsetupEntrynur einetextInputs[*].shouldPrompt-Entscheidung delegieren muss
Veröffentlichen und Installieren
Externe Plugins: In ClawHub veröffentlichen, dann installieren:- npm
- Nur ClawHub
- npm-Paketangabe
Bei Installationen aus npm installiert
openclaw plugins install das Paket in ein Plugin-spezifisches Projekt unter ~/.openclaw/npm/projects, wobei Lifecycle-Skripte deaktiviert sind. 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. npm-/git-/ClawHub-Installationsabläufe sind für die Abhängigkeitskonvergenz zuständig; lokale Plugins müssen ihre Abhängigkeiten bereits installiert haben.
Verwandte Themen
- Plugins erstellen — Schritt-für-Schritt-Anleitung für den Einstieg
- Plugin-Manifest — vollständige Referenz zum Manifest-Schema
- SDK-Einstiegspunkte —
definePluginEntryunddefineChannelPluginEntry