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 einfache Paketmetadaten für Kanalerkennung und Setup-Oberflächen, bevor die Laufzeit geladen wird.

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: nimmt den Kanal in konfigurierte/statusartige Listenoberflächen auf
• setup: nimmt den Kanal in interaktive Setup-/Konfigurationsauswahlen auf
• docs: markiert den Kanal als öffentlich sichtbar in Dokumentations-/Navigationsoberflächen

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"    }  }}

Verzögertes vollständiges Laden

Kanal-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, selbst für bereits konfigurierte Kanäle. Der vollständige Einstieg wird geladen, nachdem der Gateway begonnen hat zu lauschen.

Wenn Ihr Setup-/vollständiger Einstieg Gateway-RPC-Methoden registriert, behalten Sie sie unter einem Plugin-spezifischen Präfix. Reservierte Core-Admin-Namensräume (config.*, exec.approvals.*, wizard.*, update.*) bleiben Core-eigen und werden immer zu operator.admin aufgelöst.

Plugin-Manifest

Jedes native Plugin muss eine openclaw.plugin.json in der Paketwurzel ausliefern. OpenClaw verwendet diese Datei, 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 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-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, Inspektion deaktivierter Kanäle).

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

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

Gebündelte Workspace-Kanäle, die setup-sichere Exporte in Sidecar-Modulen halten, können defineBundledChannelSetupEntry(...) aus openclaw/plugin-sdk/channel-entry-contract statt defineSetupPluginEntry(...) verwenden. Dieser gebündelte Vertrag unterstützt außerdem einen optionalen runtime-Export, damit die Laufzeitverdrahtung zur Setup-Zeit leichtgewichtig und explizit bleiben kann.

Schmale Setup-Helper-Importe

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

Verwenden Sie den breiteren Seam plugin-sdk/setup, wenn Sie die vollständige gemeinsame Setup-Toolbox einschließlich Konfigurations-Patch-Helpern wie moveSingleAccountChannelSectionToDefaultAccount(...) benötigen.

Verwenden Sie createSetupTranslator(...) für feste Texte des Setup-Assistenten. Es folgt der CLI-Assistenten-Locale (OPENCLAW_LOCALE, dann System-Locale-Variablen) und fällt auf Englisch zurück. Halten Sie Plugin-spezifische Setup-Texte 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. Ihr gebündelter Single-Account-Promotion-Vertragsoberflächen-Lookup ist lazy, daher lädt der Import von plugin-sdk/setup-runtime die gebündelte Vertragsoberflächen-Erkennung nicht sofort, bevor der Adapter tatsächlich verwendet wird.

Kanalgesteuerte Single-Account-Promotion

Wenn ein Kanal von einer Single-Account-Konfiguration auf oberster Ebene auf channels.<id>.accounts.* aktualisiert wird, besteht das standardmäßige gemeinsame Verhalten darin, heraufgestufte kontospezifische Werte nach accounts.default zu verschieben.

Gebündelte Kanäle können diese Promotion über ihre Setup-Vertragsoberfläche einschränken oder überschreiben:

• singleAccountKeysToMove: zusätzliche Schlüssel auf oberster Ebene, die in das heraufgestufte Konto verschoben werden sollen
• namedAccountPromotionKeys: wenn benannte Konten bereits existieren, werden nur diese Schlüssel in das heraufgestufte Konto verschoben; gemeinsame Richtlinien-/Auslieferungsschlüssel bleiben im Kanal-Root
• resolveSingleAccountPromotionTarget(...): wählt aus, welches vorhandene Konto heraufgestufte Werte erhält

Konfigurationsschema

Plugin-Konfiguration wird anhand des 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 umzuwandeln, 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 Helper, damit OpenClaw auf Metadatenpfaden die Zod-zu-JSON-Schema-Konvertierung ü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> inspizieren 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 in ClawHub, installieren Sie dann:

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 im Workspace-Baum der gebündelten Plugins ab; sie werden beim Build 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 eines paketierten OpenClaw repariert oder spiegelt Plugin-Abhängigkeiten niemals.

Verwandte Themen

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