Plugin-Einrichtung und -Konfiguration

Referenz für Plugin-Paketierung (package.json-Metadaten), Manifeste (openclaw.plugin.json), Setup-Einträ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",  "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 günstige Paketmetadaten für Channel-Erkennung und Setup-Oberflächen, bevor die Runtime 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: Channel in konfigurierte bzw. statusartige Listenoberflächen aufnehmen
• setup: Channel in interaktive Setup-/Konfigurationsauswahlen aufnehmen
• docs: Channel in Dokumentations-/Navigationsoberflächen als öffentlich sichtbar markieren

openclaw.install

openclaw.install sind Paketmetadaten, keine Manifestmetadaten.

{  "openclaw": {    "install": {      "npmSpec": "@wecom/[email protected]",      "expectedIntegrity": "sha512-REPLACE_WITH_NPM_DIST_INTEGRITY",      "defaultChoice": "npm"    }  }}

Verzögertes vollständiges Laden

Channel-Plugins können verzögertes 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 Lauschen nur 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 ein openclaw.plugin.json im Paketstamm ausliefern. OpenClaw verwendet dies, um 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 Channel-Plugins kind und channels hinzu:

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

Selbst 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 Schemareferenz.

ClawHub-Veröffentlichung

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

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

Setup-Einstieg

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

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

Dadurch wird vermieden, dass während Setup-Abläufen schwergewichtiger Laufzeitcode geladen wird (Krypto-Bibliotheken, CLI-Registrierungen, Hintergrunddienste).

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, sodass die Laufzeitverdrahtung zur Setup-Zeit leichtgewichtig und explizit bleiben kann.

Schmale Setup-Hilfs-Imports

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

Verwenden Sie den breiteren Seam 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 auf channels.<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 sollen
• namedAccountPromotionKeys: wenn benannte Konten bereits existieren, werden nur diese Schlüssel in das hochgestufte Konto verschoben; gemeinsame Policy-/Delivery-Schlüssel bleiben im Kanalstamm
• resolveSingleAccountPromotionTarget(...): wählt, welches vorhandene Konto 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.

Für kanalspezifische Konfiguration verwenden Sie stattdessen den Abschnitt für die Kanalkonfiguration:

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

Kanalkonfigurationsschemata 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 nach 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ü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: Veröffentlichen Sie auf ClawHub, dann installieren Sie:

openclaw plugins install @myorg/openclaw-my-plugin

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

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

Repo-interne Plugins: Legen Sie sie unter der gebündelten Plugin-Workspace-Struktur 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. Runtime-Abhängigkeiten gehören in das Plugin-Paket, dem sie gehören; der Start eines paketierten OpenClaw repariert oder spiegelt Plugin-Abhängigkeiten niemals.

Verwandt

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