Plugin-Einrichtung und Konfiguration

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

# 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 schlanke Paketmetadaten für die Kanalermittlung 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: den Kanal in konfigurierten/statusartigen Listenoberflächen aufnehmen
• setup: den Kanal in interaktive Setup-/Konfigurationsauswahlen aufnehmen
• docs: den Kanal 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

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, auch für bereits konfigurierte Kanäle. Der vollständige Eintrag wird geladen, nachdem der Gateway mit dem Lauschen begonnen hat.

Wenn Ihr Setup-/vollständiger Eintrag 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 ein openclaw.plugin.json im Paketstamm ausliefern. OpenClaw verwendet es, 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 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 Schemareferenz.

# ClawHub-Veröffentlichung

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

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

# Setup-Einstieg

Die Datei 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 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 anstelle von defineSetupPluginEntry(...) verwenden. Dieser gebündelte Contract unterstützt außerdem einen optionalen runtime-Export, damit die Laufzeitverdrahtung zur Setup-Zeit schlank und explizit bleiben kann.

# Enge Setup-Helferimporte

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

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

Die Setup-Patch-Adapter bleiben beim Import für heiße Pfade sicher. Ihre gebündelte Contract-Oberflächen-Suche für die Promotion einzelner Konten ist lazy, sodass der Import von plugin-sdk/setup-runtime die Ermittlung der gebündelten Contract-Oberfläche nicht vorab lädt, bevor der Adapter tatsächlich verwendet wird.

# Kanalverwaltete Promotion einzelner Konten

Wenn ein Kanal von einer Top-Level-Konfiguration für ein einzelnes Konto auf channels.<id>.accounts.* aktualisiert wird, verschiebt das standardmäßige gemeinsame Verhalten promotete kontobezogene Werte nach accounts.default.

Gebündelte Kanäle können diese Promotion über ihre Setup-Contract-Oberfläche eingrenzen oder überschreiben:

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

# Konfigurationsschema

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.

Für kanalspezifische Konfiguration verwenden Sie stattdessen den Abschnitt für 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 Contract 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-Contract 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

Channel-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 und 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

In-Repo-Plugins: Legen Sie sie unter dem gebündelten Plugin-Workspace-Baum ab; sie werden beim Build automatisch erkannt.

Benutzer können installieren:

openclaw plugins install <package-name>

Gebündelte Paketmetadaten sind explizit und werden nicht beim Gateway-Start aus gebautem JavaScript abgeleitet. Runtime-Abhängigkeiten gehören in das Plugin-Paket, dem sie gehören; der Start des 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