Plugin-installatie en -configuratie

Referentie voor Plugin-packaging (package.json-metadata), manifests (openclaw.plugin.json), setup-ingangen en configuratieschema's.

Pakketmetadata

Je package.json heeft een openclaw-veld nodig dat het pluginsysteem vertelt wat je Plugin biedt:

{  "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-velden

openclaw.channel

openclaw.channel is lichtgewicht pakketmetadata voor kanaaldetectie en setupweergaven voordat de runtime wordt geladen.

Voorbeeld:

{  "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 ondersteunt:

• configured: neem het kanaal op in geconfigureerde lijsten en statusachtige weergaven
• setup: neem het kanaal op in interactieve setup-/configuratiekeuzelijsten
• docs: markeer het kanaal als publiek zichtbaar in documentatie- en navigatieweergaven

openclaw.install

openclaw.install is pakketmetadata, geen manifestmetadata.

{  "openclaw": {    "install": {      "npmSpec": "@wecom/wecom-openclaw-plugin@1.2.3",      "expectedIntegrity": "sha512-REPLACE_WITH_NPM_DIST_INTEGRITY",      "defaultChoice": "npm"    }  }}

Uitgesteld volledig laden

Kanaalplugins kunnen uitgesteld laden inschakelen met:

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

Wanneer dit is ingeschakeld, laadt OpenClaw tijdens de opstartfase vóór het luisteren alleen setupEntry, zelfs voor reeds geconfigureerde kanalen. De volledige ingang wordt geladen nadat de Gateway begint te luisteren.

Als je setup-/volledige ingang Gateway-RPC-methoden registreert, plaats deze dan onder een Plugin-specifiek voorvoegsel. Gereserveerde beheerdersnaamruimten van de kern (config.*, exec.approvals.*, wizard.*, update.*) blijven eigendom van de kern en worden altijd genormaliseerd naar operator.admin.

Pluginmanifest

Elke native Plugin moet een openclaw.plugin.json in de hoofdmap van het pakket bevatten. OpenClaw gebruikt dit om de configuratie te valideren zonder Plugincode uit te voeren.

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

Voeg voor kanaal-Plugins channels toe (en voor provider-Plugins providers):

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

Zelfs Plugins zonder configuratie moeten een schema bevatten. Een leeg schema is geldig:

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

Zie Pluginmanifest voor de volledige schemareferentie.

Publiceren op ClawHub

Skills en Pluginpakketten gebruiken afzonderlijke ClawHub-publicatieopdrachten. Gebruik voor Pluginpakketten de pakketspecifieke opdracht:

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

Setup-ingangspunt

setup-entry.ts is een lichtgewicht alternatief voor index.ts dat OpenClaw laadt wanneer alleen setup-oppervlakken nodig zijn (onboarding, configuratieherstel, inspectie van uitgeschakelde kanalen):

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

Hierdoor wordt tijdens setupstromen geen zware runtimecode geladen (cryptografische bibliotheken, CLI-registraties, achtergrondservices).

Gebundelde workspace-kanalen die setup-veilige exports in nevenmodules bewaren, kunnen defineBundledChannelSetupEntry(...) uit openclaw/plugin-sdk/channel-entry-contract gebruiken in plaats van defineSetupPluginEntry(...). Dat gebundelde contract ondersteunt ook een optionele runtime-export, zodat runtimebedrading tijdens de setup lichtgewicht en expliciet kan blijven.

Gerichte imports van setuphelpers

Geef voor intensief gebruikte paden die alleen voor setup dienen de voorkeur aan de gerichte setuphelperkoppelingen boven de bredere overkoepelende plugin-sdk/setup-koppeling wanneer je slechts een deel van het setup-oppervlak nodig hebt:

Gebruik de bredere plugin-sdk/setup-koppeling wanneer je de volledige gedeelde set setupgereedschappen wilt, inclusief helpers voor configuratiepatches zoals moveSingleAccountChannelSectionToDefaultAccount(...).

Gebruik createSetupTranslator(...) voor vaste tekst in de setupwizard. Deze volgt de landinstelling van de CLI-wizard (OPENCLAW_LOCALE, daarna de systeemvariabelen voor de landinstelling) en valt terug op Engels. Bewaar Pluginspecifieke setuptekst in code die eigendom is van de Plugin en gebruik gedeelde catalogussleutels alleen voor algemene setuplabels, statustekst en setuptekst van officiële gebundelde Plugins.

De adapters voor setup-patches blijven bij import veilig voor intensief gebruikte paden. Het opzoeken van het gebundelde contractoppervlak voor promotie van één account gebeurt lui, zodat het importeren van plugin-sdk/setup-runtime de detectie van gebundelde contractoppervlakken niet voortijdig laadt voordat de adapter daadwerkelijk wordt gebruikt.

Kanaalgestuurde promotie van één account

Wanneer een kanaal wordt bijgewerkt van een configuratie met één account op het hoogste niveau naar channels.<id>.accounts.*, verplaatst het standaard gedeelde gedrag gepromoveerde accountgebonden waarden naar accounts.default.

Gebundelde kanalen kunnen die promotie beperken of overschrijven via hun setupcontractoppervlak:

• singleAccountKeysToMove: aanvullende sleutels op het hoogste niveau die naar het gepromoveerde account moeten worden verplaatst
• namedAccountPromotionKeys: wanneer benoemde accounts al bestaan, worden alleen deze sleutels naar het gepromoveerde account verplaatst; gedeelde beleids- en afleveringssleutels blijven in de kanaalhoofdstructuur
• resolveSingleAccountPromotionTarget(...): kies welk bestaand account de gepromoveerde waarden ontvangt

Configuratieschema

De Pluginconfiguratie wordt gevalideerd aan de hand van het JSON Schema in je manifest. Gebruikers configureren Plugins via:

{  plugins: {    entries: {      "my-plugin": {        config: {          webhookSecret: "abc123",        },      },    },  },}

Je Plugin ontvangt deze configuratie tijdens de registratie als api.pluginConfig.

Gebruik voor kanaalspecifieke configuratie in plaats daarvan de sectie voor kanaalconfiguratie:

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

Kanaalconfiguratieschema's bouwen

Gebruik buildChannelConfigSchema om een Zod-schema om te zetten in de ChannelConfigSchema-wrapper die wordt gebruikt door configuratieartefacten die eigendom zijn van Plugins:

  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);

Als je het contract al opstelt als JSON Schema of TypeBox, gebruik dan de directe helper zodat OpenClaw de conversie van Zod naar JSON Schema op metadatapaden kan overslaan:

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

Voor Plugins van derden blijft het contract voor zelden gebruikte paden het Pluginmanifest: neem het gegenereerde JSON Schema over in openclaw.plugin.json#channelConfigs, zodat configuratieschema-, setup- en UI-oppervlakken channels.<id> kunnen inspecteren zonder runtimecode te laden.

Setupwizards

Kanaal-Plugins kunnen interactieve setupwizards aanbieden voor openclaw onboard. De wizard is een ChannelSetupWizard-object op de 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 ondersteunt ook textInputs, dmPolicy, allowFrom, groupAccess, prepare, finalize en meer. Zie src/setup-core.ts van de Discord-Plugin voor een volledig gebundeld voorbeeld.

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 }

Publiceren en installeren

Externe plugins: publiceer naar ClawHub en installeer vervolgens:

openclaw plugins install @myorg/openclaw-my-plugin

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

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

Plugins in de repository: plaats deze onder de werkruimteboom voor gebundelde plugins; ze worden tijdens het bouwen automatisch gedetecteerd.

Metadata van gebundelde pakketten is expliciet en wordt bij het starten van de Gateway niet afgeleid uit gebouwde JavaScript. Runtimeafhankelijkheden horen thuis in het pluginpakket dat ze beheert; het starten van een verpakte OpenClaw-installatie repareert of spiegelt nooit plugin-afhankelijkheden.

Gerelateerd

• Plugins bouwen — stapsgewijze introductiegids
• Pluginmanifest — volledige referentie voor het manifestschema
• SDK-ingangspunten — definePluginEntry en defineChannelPluginEntry