Plugin-Einrichtung und -Konfiguration

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

Paketmetadaten

Ihr 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": "Mein Kanal",      "blurb": "Kurzbeschreibung des Kanals."    }  }}

{  "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 leichtgewichtige Paketmetadaten für die Kanalerkennung und Einrichtungsoberflächen, bevor die Laufzeit geladen wird.

Kanaleigene Einrichtungsfelder

Kanal-Plugins sollten Einrichtungsfelder einmalig im Laufzeitcode mit defineChannelSetupContract(...) definieren und die entsprechende serialisierbare Projektion unter openclaw.channel.setup.fields veröffentlichen. Die Laufzeitdefinition leitet den Plugin-lokalen Eingabetyp ab, analysiert sowohl geführte als auch nicht interaktive Werte und hält kanalspezifische Schlüssel aus den Kerntypen heraus. Mithilfe der Paketmetadaten können openclaw channels add <channel-id> --help und openclaw channels add --channel <channel-id> --help ausschließlich die Optionen des ausgewählten Kanals ermitteln, ohne das Plugin zu laden.

 export const setupContract = defineChannelSetupContract({  fields: {    endpoint: {      kind: "string",      cli: { flags: "--endpoint <url>", description: "Dienstendpunkt" },    },    transport: {      kind: "choice",      choices: ["native", "container"],      cli: { flags: "--transport <kind>", description: "Transportverantwortlicher" },    },  },  adapter: {    applyAccountConfig: ({ cfg, input }) => ({      ...cfg,      channels: { ...cfg.channels, example: input },    }),  },});

{  "openclaw": {    "channel": {      "id": "example",      "setup": {        "fields": [          {            "key": "endpoint",            "kind": "string",            "cli": { "flags": "--endpoint <url>", "description": "Dienstendpunkt" }          },          {            "key": "transport",            "kind": "choice",            "choices": ["native", "container"],            "cli": { "flags": "--transport <kind>", "description": "Transportverantwortlicher" }          }        ]      }    }  }}

Unterstützte Feldarten sind string, boolean, integer, string-list und choice. Verwenden Sie sensitive: true für Anmeldedaten. Jeder Feldschlüssel muss dem in camelCase geschriebenen Attributnamen seines langen CLI-Flags entsprechen, einschließlich einer etwaigen negierten Form, beispielsweise apiToken für --api-token. Boolesche Felder können cli.negatedFlags hinzufügen, wenn sowohl positive als auch --no-*-Formen benötigt werden. channel, account und die Kontoanzeige name bleiben die gemeinsame Steuerungshülle.

Der veröffentlichte setup/ChannelSetupInput-Adapter bleibt für bestehende externe Plugins verfügbar. Neue Plugins sollten setupContract bereitstellen; OpenClaw bevorzugt diesen immer, wenn beide vorhanden sind.

Beispiel:

{  "openclaw": {    "channel": {      "id": "my-channel",      "label": "Mein Kanal",      "selectionLabel": "Mein Kanal (selbst gehostet)",      "detailLabel": "Bot für meinen Kanal",      "docsPath": "/channels/my-channel",      "docsLabel": "my-channel",      "blurb": "Webhook-basierte, selbst gehostete Chat-Integration.",      "order": 80,      "aliases": ["mc"],      "preferOver": ["my-channel-legacy"],      "selectionDocsPrefix": "Anleitung:",      "selectionExtras": ["Markdown"],      "markdownCapable": true,      "exposure": {        "configured": true,        "setup": true,        "docs": true      },      "quickstartAllowFrom": true    }  }}

exposure unterstützt:

• configured: den Kanal in konfigurierten/statusähnlichen Auflistungsoberflächen einschließen
• setup: den Kanal in interaktiven Einrichtungs-/Konfigurationsauswahlen einschließen
• docs: den Kanal in Dokumentations-/Navigationsoberflächen als öffentlich sichtbar kennzeichnen

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 das verzögerte Laden wie folgt 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 nur setupEntry, auch bei bereits konfigurierten Kanälen. Der vollständige Einstiegspunkt wird geladen, nachdem der Gateway mit dem Lauschen begonnen hat.

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

Plugin-Manifest

Jedes native Plugin muss eine openclaw.plugin.json im Paketstammverzeichnis bereitstellen. OpenClaw verwendet sie, um die Konfiguration zu validieren, ohne Plugin-Code auszuführen.

{  "id": "my-plugin",  "name": "Mein Plugin",  "description": "Fügt OpenClaw Funktionen von Mein Plugin hinzu",  "configSchema": {    "type": "object",    "additionalProperties": false,    "properties": {      "webhookSecret": {        "type": "string",        "description": "Geheimnis zur Webhook-Verifizierung"      }    }  }}

Fügen Sie für Kanal-Plugins channels hinzu (Provider-Plugins fügen providers hinzu):

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

Auch Plugins ohne Konfiguration müssen ein Schema bereitstellen. 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-Veröffentlichungsbefehle. Verwenden Sie für Plugin-Pakete den paketspezifischen Befehl:

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

Einrichtungseinstiegspunkt

setup-entry.ts ist eine schlanke Alternative zu index.ts, die OpenClaw lädt, wenn nur Einrichtungsoberflä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 Einrichtungsabläufe geladen wird.

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

Schmale Importe für Einrichtungshilfen

Bevorzugen Sie für häufig ausgeführte, ausschließlich der Einrichtung dienende Pfade die schmalen Schnittstellen für Einrichtungshilfen gegenüber dem umfassenderen plugin-sdk/setup-Dachmodul, wenn Sie nur einen Teil der Einrichtungsoberfläche benötigen:

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

Verwenden Sie createSetupTranslator(...) für feste Texte des Einrichtungsassistenten. Dabei wird der erste nicht leere Wert aus OPENCLAW_LOCALE, LC_ALL, LC_MESSAGES und LANG in dieser Reihenfolge verwendet; anschließend wird auf Englisch zurückgegriffen. Setzen Sie OPENCLAW_LOCALE=en, um Englisch ausdrücklich zu erzwingen. Bewahren Sie Plugin-spezifische Einrichtungstexte im Plugin-eigenen Code auf und verwenden Sie gemeinsame Katalogschlüssel nur für allgemeine Einrichtungsbeschriftungen, Statustexte und offizielle Einrichtungstexte gebündelter Plugins.

Die Adapter für Einrichtungs-Patches bleiben beim Import für häufig ausgeführte Pfade geeignet. Die Suche nach der Vertragsoberfläche für die gebündelte Heraufstufung eines Einzelkontos erfolgt verzögert, sodass der Import von plugin-sdk/setup-runtime die Erkennung gebündelter Vertragsoberflächen nicht vorzeitig lädt, bevor der Adapter tatsächlich verwendet wird.

Kanaleigene Eingabefelder für die Einrichtung

ChannelSetupInput ist ein generischer Umschlag, den Einrichtungsaufrufer und Kanal- Plugins gemeinsam verwenden. Seine dauerhaft typisierten Felder sind name, token, tokenFile, useEnv, allowFrom und defaultTo. Zusätzliche Plugin-eigene Schlüssel können weiterhin im Laufzeiteingabeobjekt vorhanden sein, der gemeinsame Typ deklariert jedoch keine Indexsignatur. Jedes Plugin muss seine eigenen Einrichtungsfelder deklarieren und eingrenzen oder sie an der Adaptergrenze mit einem Plugin-eigenen Schema validieren:

 type AcmeSetupInput = ChannelSetupInput & {  workspaceId?: string;  webhookUrl?: string;}; export const acmeSetupAdapter: ChannelSetupAdapter = {  applyAccountConfig: ({ cfg, input }) => {    const setupInput = input as AcmeSetupInput;    return {      ...cfg,      channels: {        ...cfg.channels,        acme: {          token: setupInput.token,          workspaceId: setupInput.workspaceId,          webhookUrl: setupInput.webhookUrl,        },      },    };  },};

Kanalspezifische Felder, die zuvor direkt auf ChannelSetupInput deklariert wurden, bleiben vorübergehend typisiert, um die Kompatibilität mit externem Quellcode zu gewährleisten. Sie sind veraltet. Bei einer Registry-Überprüfung am 2026-07-22 von 426 veröffentlichten, außerhalb des Repositorys verwalteten Kanal-Plugins wurden 21 Felder ohne Leser entfernt und 22 mit bekannten Lesern beibehalten. Jedes beibehaltene Feld wird gelöscht, sobald kein veröffentlichtes Plugin es mehr liest; eine Versionsgrenze ist nicht erforderlich. Neue und gebündelte Plugins dürfen sich nicht auf diese Ebene verlassen; deklarieren Sie die Felder, deren Eigentümer sie sind, lokal.

Kanaleigene Überführung eines Einzelkontos

Wenn ein Kanal von einer Einzelkonto-Konfiguration auf oberster Ebene auf channels.<id>.accounts.* umgestellt wird, verschiebt das standardmäßige gemeinsame Verhalten die überführten kontobezogenen Werte nach accounts.default.

Jedes Kanal-Plugin kann diese Überführung über seinen Setup-Adapter erweitern oder einschränken:

• 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 Kanalstamm
• resolveSingleAccountPromotionTarget(...): legt fest, welches bestehende Konto die überführten Werte erhält

Das Vorhandensein von singleAccountKeysToMove kennzeichnet den Überführungsvertrag als vollständig. Deklarieren Sie das Feld auch dann, wenn es sich um ein leeres Array handelt, um die Überführung veralteter Schlüssel zu deaktivieren. Adapter, die das Feld auslassen, behalten für bereits veröffentlichte Plugins eine lesergestützte Überführungsebene aus der Zeit vor der Deklaration bei. Bei der Registry-Überprüfung am 2026-07-22 wurden 23 Schlüssel ohne veröffentlichte Abhängige entfernt und sechs gängige Schlüssel sowie der ausschließlich für das Setup verwendete Schlüssel rooms beibehalten. Jeder beibehaltene Schlüssel wird gelöscht, sobald seine veröffentlichten Leser zu Deklarationen migriert wurden; eine Versionsgrenze ist nicht erforderlich.

Deklarieren Sie openclaw.setupFeatures.configPromotion: true im Paketmanifest des Plugins, wenn Doctor diese Deklarationen aus dem schlanken gebündelten Setup-Artefakt laden muss. Die ausschließlich für das Setup vorgesehene Plugin-Oberfläche und das vollständige Kanal-Plugin müssen dieselben Deklarationen bereitstellen.

Wenn Sie moveSingleAccountChannelSectionToDefaultAccount(...) mit einem bereits aufgelösten Plugin aufrufen, übergeben Sie dessen Setup-Adapter als setupSurface. Vom Aufrufer bereitgestellte Setup-Oberflächen haben Vorrang vor geladenen und gebündelten Suchmechanismen, wodurch bereichsgebundene oder ausschließlich für das Setup vorgesehene Plugins unabhängig von der globalen Registrierung bleiben.

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

Erstellen von Schemas für Kanalkonfigurationen

Verwenden Sie buildChannelConfigSchema, um ein Zod-Schema in den von Plugin-eigenen Konfigurationsartefakten verwendeten ChannelConfigSchema-Wrapper 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 erstellen, verwenden Sie den direkten Helfer, damit OpenClaw die Konvertierung von Zod in JSON-Schema 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 das Plugin-Manifest der Vertrag für den Kaltpfad: Spiegeln Sie das generierte JSON-Schema in openclaw.plugin.json#channelConfigs, damit Konfigurationsschema-, Setup- und UI-Oberflächen channels.<id> untersuchen 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),        };      },    },  ],};

ChannelSetupWizard unterstützt außerdem textInputs, dmPolicy, allowFrom, groupAccess, prepare, finalize und mehr. Ein vollständiges gebündeltes Beispiel finden Sie unter 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

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

Gebündelte Paketmetadaten werden explizit angegeben und beim Start des Gateway nicht aus dem erstellten JavaScript abgeleitet. Laufzeitabhängigkeiten gehören in das Plugin-Paket, dessen Eigentümer sie sind; der Start einer paketierten OpenClaw-Installation repariert oder spiegelt niemals Plugin-Abhängigkeiten.

Verwandte Themen

• Plugins erstellen — schrittweise Einführung
• Plugin-Manifest — vollständige Referenz zum Manifestschema
• SDK-Einstiegspunkte — definePluginEntry und defineChannelPluginEntry