Plugininstallatie en -configuratie

Naslaginformatie voor Plugin-verpakking (package.json-metadata), manifesten (openclaw.plugin.json), setup-items 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": "Mijn kanaal",      "blurb": "Korte beschrijving van het kanaal."    }  }}

{  "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 goedkope pakketmetadata voor kanaaldetectie en setup-oppervlakken voordat de runtime wordt geladen.

Setupvelden in beheer van het kanaal

Kanaalplugins moeten setupvelden eenmaal definiëren in runtimecode met defineChannelSetupContract(...) en de bijbehorende serialiseerbare projectie publiceren onder openclaw.channel.setup.fields. De runtimedefinitie leidt het invoertype af dat lokaal is voor de Plugin, parseert zowel begeleide als niet-interactieve waarden en houdt kanaalspecifieke sleutels buiten kerntypen. Met pakketmetadata kunnen openclaw channels add <channel-id> --help en openclaw channels add --channel <channel-id> --help alleen de opties van het geselecteerde kanaal vinden zonder de Plugin te laden.

 export const setupContract = defineChannelSetupContract({  fields: {    endpoint: {      kind: "string",      cli: { flags: "--endpoint <url>", description: "Service-eindpunt" },    },    transport: {      kind: "choice",      choices: ["native", "container"],      cli: { flags: "--transport <kind>", description: "Transportbeheerder" },    },  },  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": "Service-eindpunt" }          },          {            "key": "transport",            "kind": "choice",            "choices": ["native", "container"],            "cli": { "flags": "--transport <kind>", "description": "Transportbeheerder" }          }        ]      }    }  }}

Ondersteunde veldtypen zijn string, boolean, integer, string-list en choice. Gebruik sensitive: true voor aanmeldgegevens. Elke veldsleutel moet gelijk zijn aan de camelCase-attribuutnaam van de lange CLI-vlag, inclusief een eventuele ontkennende vorm, zoals apiToken voor --api-token. Booleaanse velden kunnen cli.negatedFlags toevoegen wanneer zowel positieve als --no-*-vormen nodig zijn. channel, account en de accountweergave name blijven de gedeelde besturingsenvelop.

De uitgebrachte setup/ChannelSetupInput-adapter blijft beschikbaar voor bestaande externe plugins. Nieuwe plugins moeten setupContract beschikbaar stellen; OpenClaw geeft hier altijd de voorkeur aan wanneer beide aanwezig zijn.

Voorbeeld:

{  "openclaw": {    "channel": {      "id": "my-channel",      "label": "Mijn kanaal",      "selectionLabel": "Mijn kanaal (zelf gehost)",      "detailLabel": "Mijn kanaalbot",      "docsPath": "/channels/my-channel",      "docsLabel": "my-channel",      "blurb": "Zelfgehoste chatintegratie op basis van Webhooks.",      "order": 80,      "aliases": ["mc"],      "preferOver": ["my-channel-legacy"],      "selectionDocsPrefix": "Handleiding:",      "selectionExtras": ["Markdown"],      "markdownCapable": true,      "exposure": {        "configured": true,        "setup": true,        "docs": true      },      "quickstartAllowFrom": true    }  }}

exposure ondersteunt:

• configured: neem het kanaal op in geconfigureerde/statusachtige lijstweergaven
• setup: neem het kanaal op in interactieve setup-/configuratiekeuzelijsten
• docs: markeer het kanaal als openbaar zichtbaar in documentatie-/navigatieoppervlakken

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 kiezen voor uitgesteld laden 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 is begonnen met luisteren.

Als jouw configuratie-/volledige ingang Gateway-RPC-methoden registreert, plaats deze dan onder een pluginspecifiek voorvoegsel. Gereserveerde kernbeheerdersnaamruimten (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 pakketroot bevatten. OpenClaw gebruikt dit om de configuratie te valideren zonder plugincode uit te voeren.

{  "id": "my-plugin",  "name": "Mijn plugin",  "description": "Voegt mogelijkheden van Mijn plugin toe aan OpenClaw",  "configSchema": {    "type": "object",    "additionalProperties": false,    "properties": {      "webhookSecret": {        "type": "string",        "description": "Geheim voor Webhook-verificatie"      }    }  }}

Voeg voor kanaalplugins channels toe (en voor providerplugins 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

Configuratie-ingang

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

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

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

Gebundelde werkruimtekanelen die configuratieveilige 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 configuratie lichtgewicht en expliciet kan blijven.

Gerichte imports van configuratiehulpfuncties

Geef voor veelgebruikte paden die uitsluitend voor configuratie dienen de voorkeur aan de gerichte naden voor configuratiehulpfuncties boven de bredere plugin-sdk/setup-paraplu wanneer je slechts een deel van het configuratieoppervlak nodig hebt:

Gebruik de bredere plugin-sdk/setup-naad wanneer je de volledige gedeelde configuratiegereedschapskist wilt, inclusief hulpfuncties voor configuratiepatches zoals moveSingleAccountChannelSectionToDefaultAccount(...).

Gebruik createSetupTranslator(...) voor vaste tekst van de configuratiewizard. Deze gebruikt de eerste niet-lege waarde uit OPENCLAW_LOCALE, LC_ALL, LC_MESSAGES en LANG, in die volgorde, en valt vervolgens terug op Engels. Stel OPENCLAW_LOCALE=en in voor een expliciete Engelse overschrijving. Bewaar pluginspecifieke configuratietekst in code die eigendom is van de plugin en gebruik gedeelde catalogussleutels alleen voor algemene configuratielabels, statustekst en officiële configuratietekst voor gebundelde plugins.

De adapters voor configuratiepatches blijven bij import veilig voor veelgebruikte paden. Hun opzoekactie voor het contractoppervlak voor gebundelde promotie naar één account is lui, zodat het importeren van plugin-sdk/setup-runtime de detectie van gebundelde contractoppervlakken niet voortijdig laadt voordat de adapter daadwerkelijk wordt gebruikt.

Invoervelden voor configuratie die eigendom zijn van het kanaal

ChannelSetupInput is een generieke envelop die wordt gedeeld door configuratieaanroepers en kanaalplugins. De permanent getypeerde velden zijn name, token, tokenFile, useEnv, allowFrom en defaultTo. Aanvullende sleutels die eigendom zijn van de plugin kunnen nog steeds aanwezig zijn in het runtime-invoerobject, maar het gedeelde type declareert geen indexsignatuur. Elke plugin moet zijn eigen configuratievelden declareren en verfijnen of ze met een schema van de plugin valideren bij de adaptergrens:

 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,        },      },    };  },};

Kanaalspecifieke velden die eerder rechtstreeks op ChannelSetupInput waren gedeclareerd, blijven tijdelijk getypeerd voor compatibiliteit met externe broncode. Ze zijn verouderd. Bij een registercontrole op 2026-07-22 van 426 gepubliceerde kanaalplugins van buiten de bronstructuur werden 21 velden zonder lezers verwijderd en 22 velden met bekende lezers behouden. Elk behouden veld wordt verwijderd zodra geen enkele gepubliceerde plugin het nog leest; er is geen versiegrens vereist. Nieuwe en gebundelde plugins mogen niet op deze laag vertrouwen; declareer de velden waarvan ze eigenaar zijn lokaal.

Kanaalgestuurde promotie van één account

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

Elke kanaalplugin kan die promotie uitbreiden of beperken via zijn setupadapter:

• singleAccountKeysToMove: extra 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-/afleveringssleutels blijven op het hoofdniveau van het kanaal
• resolveSingleAccountPromotionTarget(...): kies welk bestaand account gepromoveerde waarden ontvangt

De aanwezigheid van singleAccountKeysToMove geeft aan dat het promotiecontract volledig is. Declareer het veld ook wanneer het een lege array is om promotie van verouderde sleutels uit te schakelen. Adapters die het veld weglaten, behouden een door lezers ondersteunde promotielaag van vóór de declaratie voor reeds gepubliceerde plugins. Bij de registercontrole op 2026-07-22 werden 23 sleutels zonder gepubliceerde afhankelijken verwijderd en zes algemene sleutels plus de uitsluitend voor setup bestemde sleutel rooms behouden. Elke behouden sleutel wordt verwijderd zodra de gepubliceerde lezers ervan naar declaraties zijn gemigreerd; er is geen versiegrens vereist.

Declareer openclaw.setupFeatures.configPromotion: true in het pakketmanifest van de plugin wanneer doctor deze declaraties uit het lichtgewicht gebundelde setup-artefact moet laden. Het uitsluitend voor setup bestemde pluginoppervlak en de volledige kanaalplugin moeten dezelfde declaraties beschikbaar stellen.

Wanneer je moveSingleAccountChannelSectionToDefaultAccount(...) aanroept met een reeds opgeloste plugin, geef je de setupadapter ervan door als setupSurface. Door de aanroeper aangeleverde setupoppervlakken hebben voorrang op geladen en gebundelde opzoekmechanismen, waardoor plugins met een beperkt bereik of uitsluitend voor setup onafhankelijk blijven van globale registratie.

Configuratieschema

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 kanaalconfiguratiesectie:

{  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 waarvan de plugin eigenaar is:

  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 als JSON Schema of TypeBox opstelt, gebruik je 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 pluginmanifest het contract voor het koude pad: 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

Kanaalplugins kunnen interactieve setupwizards voor openclaw onboard aanbieden. 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 ze onder de gebundelde pluginwerkruimtestructuur; ze worden tijdens het bouwen automatisch ontdekt.

Gebundelde pakketmetadata is expliciet en wordt bij het starten van Gateway niet afgeleid van gebouwde JavaScript. Runtime-afhankelijkheden horen thuis in het pluginpakket dat er eigenaar van is; bij het starten herstelt of spiegelt de verpakte OpenClaw nooit plugin-afhankelijkheden.

Gerelateerd

• Plugins bouwen — stapsgewijze handleiding om aan de slag te gaan
• Pluginmanifest — volledige schemareferentie voor het manifest
• SDK-ingangspunten — definePluginEntry en defineChannelPluginEntry