Plugin-Einrichtung und -Konfiguration

Referenz für die Plugin-Paketierung (package.json-Metadaten), Manifeste (openclaw.plugin.json), Einrichtungseinstiegspunkte 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 enthält leichtgewichtige Paketmetadaten für die Kanalerkennung und Einrichtungsansichten, 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 Auflistungsansichten für konfigurierte Kanäle und Status auf
• setup: nimmt den Kanal in interaktive Auswahlansichten für Einrichtung und Konfiguration auf
• docs: kennzeichnet den Kanal in Dokumentations- und Navigationsansichten als öffentlich sichtbar

openclaw.install

openclaw.install enthält 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 das verzögerte Laden mit folgender Konfiguration aktivieren:

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

Wenn diese Option aktiviert ist, lädt OpenClaw während der Startphase vor dem Lauschen ausschließlich setupEntry, auch bei bereits konfigurierten Kanälen. Der vollständige Einstiegspunkt wird geladen, nachdem das Gateway mit dem Lauschen begonnen hat.

Wenn Ihr Einrichtungs- oder vollständiger Einstiegspunkt Gateway-RPC-Methoden registriert, verwenden Sie dafür ein Plugin-spezifisches Präfix. Reservierte administrative Kern-Namensräume (config.*, exec.approvals.*, wizard.*, update.*) bleiben Eigentum des Kerns und werden immer zu operator.admin normalisiert.

Plugin-Manifest

Jedes native Plugin muss eine openclaw.plugin.json im Stammverzeichnis des Pakets mitliefern. OpenClaw verwendet diese Datei, 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 channels hinzu (Provider-Plugins entsprechend providers):

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

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

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

Die vollständige Schemareferenz finden Sie unter Plugin-Manifest.

Veröffentlichung auf ClawHub

Skills und Plugin-Pakete verwenden separate ClawHub-Befehle zur Veröffentlichung. Verwenden Sie für Plugin-Pakete den paketspezifischen Befehl:

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

Setup-Einstiegspunkt

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 Laufzeitcode (Kryptografiebibliotheken, CLI-Registrierungen, Hintergrunddienste) während der Setup-Abläufe geladen wird.

Gebündelte Workspace-Kanäle, die Setup-sichere Exporte in Sidecar-Modulen vorhalten, können defineBundledChannelSetupEntry(...) aus openclaw/plugin-sdk/channel-entry-contract anstelle von defineSetupPluginEntry(...) verwenden. Dieser Vertrag für gebündelte Plugins unterstützt außerdem einen optionalen runtime-Export, sodass die Laufzeitverdrahtung während des Setups schlank und explizit bleiben kann.

Schmale Importe für Setup-Hilfsfunktionen

Bevorzugen Sie für häufig durchlaufene, ausschließlich dem Setup dienende Pfade die schmalen Schnittstellen für Setup-Hilfsfunktionen gegenüber dem umfassenderen plugin-sdk/setup, wenn Sie nur einen Teil der Setup-Oberfläche benötigen:

Verwenden Sie die umfassendere Schnittstelle plugin-sdk/setup, wenn Sie den vollständigen gemeinsamen Setup-Werkzeugkasten einschließlich Hilfsfunktionen für Konfigurationsänderungen wie moveSingleAccountChannelSectionToDefaultAccount(...) benötigen.

Verwenden Sie createSetupTranslator(...) für feste Texte des Setup-Assistenten. Die Funktion richtet sich nach dem Gebietsschema des CLI-Assistenten (OPENCLAW_LOCALE, danach die Gebietsschemavariablen des Systems) und greift ersatzweise auf Englisch zurück. Belassen Sie Plugin-spezifische Setup-Texte im Plugin-eigenen Code und verwenden Sie gemeinsame Katalogschlüssel nur für allgemeine Setup-Bezeichnungen, Statustexte und Setup-Texte offizieller gebündelter Plugins.

Die Adapter für Setup-Änderungen bleiben beim Import für häufig durchlaufene Pfade geeignet. Die Suche nach der Vertragsoberfläche für die gebündelte Überführung eines Einzelkontos erfolgt verzögert. Daher lädt der Import von plugin-sdk/setup-runtime die Erkennung gebündelter Vertragsoberflächen nicht vorzeitig, bevor der Adapter tatsächlich verwendet wird.

Kanaleigene Überführung eines Einzelkontos

Wenn ein Kanal von einer Einzelkonto-Konfiguration auf oberster Ebene auf channels.<id>.accounts.* aktualisiert wird, verschiebt das gemeinsame Standardverhalten die überführten kontobezogenen Werte nach accounts.default.

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

• singleAccountKeysToMove: zusätzliche Schlüssel auf oberster Ebene, die in das überführte Konto verschoben werden sollen
• namedAccountPromotionKeys: Wenn bereits benannte Konten vorhanden sind, werden nur diese Schlüssel in das überführte Konto verschoben; gemeinsame Richtlinien-/Zustellungsschlüssel verbleiben im Stamm des Kanals
• resolveSingleAccountPromotionTarget(...): legt fest, welches vorhandene Konto die überführten Werte erhält

Konfigurationsschema

Die Plugin-Konfiguration wird anhand des JSON-Schemas 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 Konfigurationen stattdessen den Abschnitt für die Kanalkonfiguration:

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

Kanalkonfigurationsschemas erstellen

Verwenden Sie buildChannelConfigSchema, um ein Zod-Schema in den von Plugin-eigenen Konfigurationsartefakten verwendeten Wrapper ChannelConfigSchema umzuwandeln:

  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 definieren, verwenden Sie die direkte Hilfsfunktion, damit OpenClaw die Konvertierung von Zod in JSON-Schema in Metadatenpfaden überspringen kann:

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

Für Plugins von Drittanbietern bleibt das Plugin-Manifest der Vertrag für selten durchlaufene Pfade: Übernehmen 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 im 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),        };      },    },  ],};

ChannelSetupWizard unterstützt außerdem textInputs, dmPolicy, allowFrom, groupAccess, prepare, finalize und weitere Eigenschaften. Ein vollständiges gebündeltes Beispiel finden Sie in src/setup-core.ts des Discord-Plugins.

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 sie auf ClawHub und installieren Sie sie anschließend:

openclaw plugins install @myorg/openclaw-my-plugin

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

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

Repository-interne Plugins: Legen Sie sie im Workspace-Baum der mitgelieferten Plugins ab; sie werden während des Builds automatisch erkannt.

Die Metadaten mitgelieferter Pakete werden explizit angegeben und beim Start des Gateways nicht aus dem erstellten JavaScript abgeleitet. Laufzeitabhängigkeiten gehören in das Plugin-Paket, das für sie zuständig ist; der Start einer paketierten OpenClaw-Installation repariert oder spiegelt niemals Plugin-Abhängigkeiten.

Verwandte Themen

• Plugins erstellen – Schritt-für-Schritt-Anleitung für den Einstieg
• Plugin-Manifest – vollständige Referenz des Manifest-Schemas
• SDK-Einstiegspunkte – definePluginEntry und defineChannelPluginEntry