Plugin-Einrichtung und -Konfiguration

Referenz für Plugin-Paketierung (package.json-Metadaten), Manifeste (openclaw.plugin.json), Einrichtungseinträge und Konfigurationsschemas.

Paketmetadaten

Ihre package.json benötigt ein openclaw-Feld, das dem Plugin-System mitteilt, was Ihr Plugin bereitstellt:

{  "name": "@myorg/openclaw-my-channel",  "version": "1.0.0",  "type": "module",  "openclaw": {    "extensions": ["./index.ts"],    "setupEntry": "./setup-entry.ts",    "channel": {      "id": "my-channel",      "label": "My Channel",      "blurb": "Short description of the channel."    }  }}

{  "name": "@myorg/openclaw-my-plugin",  "version": "1.0.0",  "type": "module",  "dependencies": {    "typebox": "1.1.39"  },  "peerDependencies": {    "openclaw": ">=2026.3.24-beta.2"  },  "openclaw": {    "extensions": ["./index.ts"],    "compat": {      "pluginApi": ">=2026.3.24-beta.2",      "minGatewayVersion": "2026.3.24-beta.2"    },    "build": {      "openclawVersion": "2026.3.24-beta.2",      "pluginSdkVersion": "2026.3.24-beta.2"    }  }}

openclaw-Felder

openclaw.channel

openclaw.channel sind schlanke Paketmetadaten für die Kanalerkennung und Einrichtungsoberflächen, bevor die Laufzeit lädt.

Beispiel:

{  "openclaw": {    "channel": {      "id": "my-channel",      "label": "My Channel",      "selectionLabel": "My Channel (self-hosted)",      "detailLabel": "My Channel Bot",      "docsPath": "/channels/my-channel",      "docsLabel": "my-channel",      "blurb": "Webhook-based self-hosted chat integration.",      "order": 80,      "aliases": ["mc"],      "preferOver": ["my-channel-legacy"],      "selectionDocsPrefix": "Guide:",      "selectionExtras": ["Markdown"],      "markdownCapable": true,      "exposure": {        "configured": true,        "setup": true,        "docs": true      },      "quickstartAllowFrom": true    }  }}

exposure unterstützt:

• configured: Kanal in konfigurierten/statusähnlichen Listenoberflächen einschließen
• setup: Kanal in interaktive Einrichtungs-/Konfigurationsauswahlen einschließen
• docs: Kanal in Dokumentations-/Navigationsoberflächen als öffentlich markieren

openclaw.install

openclaw.install sind Paketmetadaten, keine Manifestmetadaten.

{  "openclaw": {    "install": {      "npmSpec": "@wecom/wecom-openclaw-plugin@1.2.3",      "expectedIntegrity": "sha512-REPLACE_WITH_NPM_DIST_INTEGRITY",      "defaultChoice": "npm"    }  }}

Aufgeschobenes vollständiges Laden

Kanal-Plugins können das aufgeschobene Laden aktivieren mit:

{  "openclaw": {    "extensions": ["./index.ts"],    "setupEntry": "./setup-entry.ts",    "startup": {      "deferConfiguredChannelFullLoadUntilAfterListen": true    }  }}

Wenn aktiviert, lädt OpenClaw während der Startphase vor dem Listen nur 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 ein openclaw.plugin.json im Paket-Root ausliefern. OpenClaw verwendet dies, um die Konfiguration zu validieren, ohne Plugin-Code auszuführen.

{  "id": "my-plugin",  "name": "My Plugin",  "description": "Adds My Plugin capabilities to OpenClaw",  "configSchema": {    "type": "object",    "additionalProperties": false,    "properties": {      "webhookSecret": {        "type": "string",        "description": "Webhook verification secret"      }    }  }}

Fügen Sie für Kanal-Plugins kind und channels hinzu:

{  "id": "my-channel",  "kind": "channel",  "channels": ["my-channel"],  "configSchema": {    "type": "object",    "additionalProperties": false,    "properties": {}  }}

Auch Plugins ohne Konfiguration müssen ein Schema ausliefern. Ein leeres Schema ist gültig:

{  "id": "my-plugin",  "configSchema": {    "type": "object",    "additionalProperties": false  }}

Siehe Plugin-Manifest für die vollständige Schema-Referenz.

ClawHub-Veröffentlichung

Verwenden Sie für Plugin-Pakete den paketspezifischen ClawHub-Befehl:

clawhub package publish your-org/your-plugin --dry-runclawhub package publish your-org/your-plugin

Setup-Einstiegspunkt

Die Datei setup-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).

// setup-entry.ts  export default defineSetupPluginEntry(myChannelPlugin);

Dadurch wird vermieden, dass umfangreicher Runtime-Code (Kryptobibliotheken, CLI-Registrierungen, Hintergrunddienste) während Setup-Abläufen geladen wird.

Gebündelte Workspace-Kanäle, die setup-sichere Exporte in Sidecar-Modulen halten, können statt 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.

Schmale Setup-Hilfsimporte

Bevorzugen Sie für heiße reine Setup-Pfade die schmalen Setup-Hilfs-Seams gegenüber dem breiteren plugin-sdk/setup-Umbrella, wenn Sie nur einen Teil der Setup-Oberfläche benötigen:

Verwenden Sie den breiteren 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 auf channels.<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 sollen
• namedAccountPromotionKeys: wenn benannte Accounts bereits vorhanden sind, werden nur diese Schlüssel in den hochgestuften Account verschoben; gemeinsame Policy-/Delivery-Schlüssel bleiben am Kanal-Root
• resolveSingleAccountPromotionTarget(...): wählt aus, welcher vorhandene Account hochgestufte Werte erhält

Konfigurationsschema

Die Plugin-Konfiguration wird gegen das JSON Schema in Ihrem Manifest validiert. Benutzer konfigurieren Plugins über:

{  plugins: {    entries: {      "my-plugin": {        config: {          webhookSecret: "abc123",        },      },    },  },}

Ihr Plugin erhält diese Konfiguration während der Registrierung als api.pluginConfig.

Verwenden Sie für kanalspezifische Konfiguration stattdessen den Kanal-Konfigurationsabschnitt:

{  channels: {    "my-channel": {      token: "bot-token",      allowFrom: ["user1", "user2"],    },  },}

Kanal-Konfigurationsschemas erstellen

Verwenden Sie buildChannelConfigSchema, um ein Zod-Schema in den ChannelConfigSchema-Wrapper zu konvertieren, der von Plugin-eigenen Konfigurationsartefakten verwendet wird:

  const accountSchema = z.object({  token: z.string().optional(),  allowFrom: z.array(z.string()).optional(),  accounts: z.object({}).catchall(z.any()).optional(),  defaultAccount: z.string().optional(),}); const configSchema = buildChannelConfigSchema(accountSchema);

Wenn Sie den Vertrag bereits als JSON Schema oder TypeBox verfassen, verwenden Sie den direkten Helfer, damit OpenClaw die Zod-zu-JSON-Schema-Konvertierung auf Metadatenpfaden überspringen kann:

  const configSchema = buildJsonChannelConfigSchema(  Type.Object({    token: Type.Optional(Type.String()),    allowFrom: Type.Optional(Type.Array(Type.String())),  }),);

Für Drittanbieter-Plugins bleibt der Cold-Path-Vertrag weiterhin das Plugin-Manifest: Spiegeln Sie das generierte JSON Schema in 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ür openclaw onboard bereitstellen. Der Assistent ist ein ChannelSetupWizard-Objekt auf dem ChannelPlugin:

 const setupWizard: ChannelSetupWizard = {  channel: "my-channel",  status: {    configuredLabel: "Connected",    unconfiguredLabel: "Not configured",    resolveConfigured: ({ cfg }) => Boolean((cfg.channels as any)?.["my-channel"]?.token),  },  credentials: [    {      inputKey: "token",      providerHint: "my-channel",      credentialLabel: "Bot token",      preferredEnvVar: "MY_CHANNEL_BOT_TOKEN",      envPrompt: "Use MY_CHANNEL_BOT_TOKEN from environment?",      keepPrompt: "Keep current token?",      inputPrompt: "Enter your bot token:",      inspect: ({ cfg, accountId }) => {        const token = (cfg.channels as any)?.["my-channel"]?.token;        return {          accountConfigured: Boolean(token),          hasConfiguredValue: Boolean(token),        };      },    },  ],};

Der Typ 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).

import { createOptionalChannelSetupSurface } from "openclaw/plugin-sdk/channel-setup"; const setupSurface = createOptionalChannelSetupSurface({  channel: "my-channel",  label: "My Channel",  npmSpec: "@myorg/openclaw-my-channel",  docsPath: "/channels/my-channel",});// Returns { setupAdapter, setupWizard }

Veröffentlichen und Installieren

Externe Plugins: In ClawHub veröffentlichen, dann installieren:

openclaw plugins install @myorg/openclaw-my-plugin

openclaw plugins install clawhub:@myorg/openclaw-my-plugin

openclaw plugins install npm:@myorg/openclaw-my-plugin

Plugins im Repository: Legen Sie sie unter dem gebündelten Plugin-Workspace-Baum ab; sie werden während des Builds automatisch erkannt.

Benutzer können installieren:

openclaw plugins install <package-name>

Gebündelte Paketmetadaten sind explizit und werden beim Gateway-Start nicht aus gebautem JavaScript abgeleitet. Laufzeitabhängigkeiten gehören in das Plugin-Paket, dem sie gehören; der Start des paketierten OpenClaw repariert oder spiegelt Plugin-Abhängigkeiten nie.

Verwandte Themen

• Plugins erstellen — Schritt-für-Schritt-Anleitung für den Einstieg
• Plugin-Manifest — vollständige Referenz zum Manifest-Schema
• SDK-Einstiegspunkte — definePluginEntry und defineChannelPluginEntry