Plugin-Einrichtung und -Konfiguration

Referenz für die 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 Channel",      "blurb": "Kurze Beschreibung des Channels."    }  }}

{  "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 Channel-Erkennung und Einrichtungsoberflächen vor dem Laden der Laufzeit.

Channel-eigene Einrichtungsfelder

Channel-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 Channel-spezifische 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 Channels erkennen, 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 negierter Formen, 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 Channel",      "selectionLabel": "Mein Channel (selbst gehostet)",      "detailLabel": "Mein Channel-Bot",      "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 Channel in konfigurierten/statusähnlichen Listenoberflächen anzeigen
• setup: den Channel in interaktiven Einrichtungs-/Konfigurationsauswahlen anzeigen
• docs: den Channel 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 aktivieren mit:

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

Wenn dies aktiviert ist, lädt OpenClaw während der Startphase vor dem Lauschen nur setupEntry, selbst 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 administrative Kern-Namensräume (config.*, exec.approvals.*, wizard.*, update.*) bleiben im Besitz des Kerns und werden immer zu operator.admin normalisiert.

Plugin-Manifest

Jedes native Plugin muss eine openclaw.plugin.json im Paketstamm bereitstellen. OpenClaw verwendet diese, 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 bei Kanal-Plugins channels hinzu (und bei Provider-Plugins providers):

{  "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, während Einrichtungsabläufen umfangreichen Laufzeitcode zu laden (Kryptografiebibliotheken, CLI-Registrierungen, Hintergrunddienste).

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, damit die Laufzeitverdrahtung während der Einrichtung schlank und explizit bleiben kann.

Schmale Importe von Einrichtungshilfen

Bevorzugen Sie für häufig ausgeführte, reine Einrichtungspfade die schmalen Schnittstellen der Einrichtungshilfen gegenüber dem breiteren plugin-sdk/setup-Dach, wenn Sie nur einen Teil der Einrichtungsoberfläche benötigen:

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

Verwenden Sie createSetupTranslator(...) für feste Texte des Einrichtungsassistenten. Es verwendet den ersten nicht leeren Wert aus OPENCLAW_LOCALE, LC_ALL, LC_MESSAGES und LANG in dieser Reihenfolge und greift anschließend auf Englisch zurück. Legen Sie OPENCLAW_LOCALE=en für eine explizite englische Überschreibung fest. Bewahren Sie Plugin-spezifische Einrichtungstexte im Plugin-eigenen Code auf und verwenden Sie gemeinsame Katalogschlüssel nur für allgemeine Einrichtungsbeschriftungen, Statustexte und Einrichtungstexte offizieller gebündelter Plugins.

Die Adapter für Einrichtungs-Patches bleiben beim Import für häufig ausgeführte Pfade sicher. Ihre Suche nach der gebündelten Vertragsoberfläche zur Hochstufung eines einzelnen Kontos erfolgt verzögert, sodass der Import von plugin-sdk/setup-runtime die Ermittlung der gebündelten Vertragsoberfläche nicht vorzeitig lädt, bevor der Adapter tatsächlich verwendet wird.

Kanaleigene Eingabefelder für die Einrichtung

ChannelSetupInput ist eine generische Hülle, die von Einrichtungsaufrufern und Kanal- Plugins gemeinsam verwendet wird. Ihre 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 mit einem Plugin-eigenen Schema an der Adaptergrenze 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 in ChannelSetupInput deklariert wurden, bleiben vorübergehend für die Kompatibilität mit externem Quellcode typisiert. Sie sind veraltet. Bei einer Registry-Prüfung am 2026-07-22 wurden von 426 veröffentlichten, außerhalb des Repositorys verwalteten Channel-Plugins 21 Felder ohne lesende Zugriffe entfernt und 22 mit bekannten lesenden Zugriffen beibehalten. Jedes beibehaltene Feld wird gelöscht, sobald kein veröffentlichtes Plugin mehr darauf lesend zugreift; 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.

Channel-eigene Hochstufung eines Einzelkontos

Wenn ein Channel von einer Top-Level-Konfiguration für ein Einzelkonto auf channels.<id>.accounts.* umgestellt wird, verschiebt das standardmäßige gemeinsame Verhalten hochgestufte kontobezogene Werte nach accounts.default.

Jedes Channel-Plugin kann diese Hochstufung über seinen Setup-Adapter erweitern oder einschränken:

• singleAccountKeysToMove: zusätzliche Top-Level-Schlüssel, die in das hochgestufte Konto verschoben werden sollen
• namedAccountPromotionKeys: wenn bereits benannte Konten vorhanden sind, werden nur diese Schlüssel in das hochgestufte Konto verschoben; gemeinsame Richtlinien-/Zustellungsschlüssel verbleiben im Channel-Stamm
• resolveSingleAccountPromotionTarget(...): legt fest, welches bestehende Konto die hochgestuften Werte erhält

Das Vorhandensein von singleAccountKeysToMove kennzeichnet den Hochstufungsvertrag als vollständig. Deklarieren Sie das Feld auch dann, wenn es ein leeres Array ist, um die Hochstufung veralteter Schlüssel zu deaktivieren. Adapter, die das Feld auslassen, behalten für bereits veröffentlichte Plugins eine durch lesende Zugriffe belegte Hochstufungsebene aus der Zeit vor der Deklaration bei. Bei der Registry-Prüfung am 2026-07-22 wurden 23 Schlüssel ohne veröffentlichte abhängige Plugins entfernt und sechs allgemeine 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 lesenden Zugriffe auf Deklarationen migriert wurden; eine Versionsgrenze ist nicht erforderlich.

Deklarieren Sie openclaw.setupFeatures.configPromotion: true im Paketmanifest des Plugins, wenn Doctor diese Deklarationen aus dem leichtgewichtigen gebündelten Setup-Artefakt laden muss. Die ausschließlich für das Setup vorgesehene Plugin-Oberfläche und das vollständige Channel-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 Channel-Konfiguration:

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

Channel-Konfigurationsschemas 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 erstellen, verwenden Sie den direkten Helper, damit OpenClaw die Konvertierung von Zod zu 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 selten ausgeführten Pfad: Spiegeln Sie das generierte JSON-Schema nach openclaw.plugin.json#channelConfigs, damit Konfigurationsschema-, Setup- und UI-Oberflächen channels.<id> untersuchen können, ohne Laufzeitcode zu laden.

Setup-Assistenten

Channel-Plugins können interaktive Setup-Assistenten für openclaw onboard bereitstellen. Der Assistent ist ein ChannelSetupWizard-Objekt auf ChannelPlugin:

 const setupWizard: ChannelSetupWizard = {  channel: "my-channel",  status: {    configuredLabel: "Verbunden",    unconfiguredLabel: "Nicht konfiguriert",    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: "MY_CHANNEL_BOT_TOKEN aus der Umgebung verwenden?",      keepPrompt: "Aktuelles Token beibehalten?",      inputPrompt: "Geben Sie Ihr Bot-Token ein:",      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. 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: "Mein Channel",  npmSpec: "@myorg/openclaw-my-channel",  docsPath: "/channels/my-channel",});// Gibt { setupAdapter, setupWizard } zurück

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 gebündelten Plugins ab; sie werden während des Builds automatisch erkannt.

Die Metadaten gebündelter Pakete sind explizit und werden beim Start des Gateways nicht aus dem erstellten JavaScript abgeleitet. Laufzeitabhängigkeiten gehören in das Plugin-Paket, das ihr Eigentümer ist; der Start des paketierten OpenClaw repariert oder spiegelt Plugin-Abhängigkeiten niemals.

Verwandte Themen

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