Plugin instellen en configureren

Referentie voor Plugin-verpakking (package.json-metadata), manifests (openclaw.plugin.json), setupvermeldingen en configuratieschema's.

# Pakketmetadata

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

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

# openclaw.channel

openclaw.channel is goedkope pakketmetadata voor kanaalontdekking en setupoppervlakken voordat de runtime laadt.

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/statusachtige lijstoppervlakken
• setup: neem het kanaal op in interactieve setup-/configuratiekiezers
• docs: markeer het kanaal als publiek zichtbaar in documentatie-/navigatieoppervlakken

# openclaw.install

openclaw.install is pakketmetadata, geen manifestmetadata.

{
  "openclaw": {
    "install": {
      "npmSpec": "@wecom/[email protected]",
      "expectedIntegrity": "sha512-REPLACE_WITH_NPM_DIST_INTEGRITY",
      "defaultChoice": "npm"
    }
  }
}

# Uitgestelde volledige laadactie

Kanaal-Plugins 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 al geconfigureerde kanalen. De volledige entry laadt nadat de Gateway begint te luisteren.

Als je setup-/volledige entry Gateway-RPC-methoden registreert, houd ze dan op een Plugin-specifieke prefix. Gereserveerde core-adminnamespaces (config.*, exec.approvals.*, wizard.*, update.*) blijven eigendom van core en worden altijd opgelost naar operator.admin.

# Pluginmanifest

Elke native Plugin moet een openclaw.plugin.json in de pakketroot meeleveren. OpenClaw gebruikt dit om configuratie te valideren zonder Plugin-code 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 kind en channels toe:

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

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

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

Zie Pluginmanifest voor de volledige schemareferentie.

# Publiceren op ClawHub

Gebruik voor Plugin-pakketten de pakketspecifieke ClawHub-opdracht:

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

# Setup-entry

Het bestand setup-entry.ts is een lichtgewicht alternatief voor index.ts dat OpenClaw laadt wanneer het alleen setup-oppervlakken nodig heeft (onboarding, config-reparatie, inspectie van uitgeschakelde kanalen).

// setup-entry.ts


export default defineSetupPluginEntry(myChannelPlugin);

Dit voorkomt dat zware runtimecode (cryptobibliotheken, CLI-registraties, achtergrondservices) tijdens setup-flows wordt geladen.

Gebundelde workspace-kanalen die setup-veilige exports in sidecar-modules 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 runtime-bedrading tijdens setup lichtgewicht en expliciet kan blijven.

# Smalle setup-helperimports

Gebruik voor hete paden die alleen setup nodig hebben liever de smalle setup-helperseams dan de bredere plugin-sdk/setup-paraplu wanneer je slechts een deel van het setup-oppervlak nodig hebt:

Gebruik de bredere plugin-sdk/setup-seam wanneer je de volledige gedeelde setup-toolbox wilt, inclusief config-patchhelpers zoals moveSingleAccountChannelSectionToDefaultAccount(...).

De setup-patchadapters blijven veilig voor het hete pad bij import. Hun gebundelde contract-oppervlaklookup voor promotie van één account is lazy, dus het importeren van plugin-sdk/setup-runtime laadt de gebundelde contract-oppervlakontdekking niet gretig voordat de adapter daadwerkelijk wordt gebruikt.

# Kanaal-eigen promotie van één account

Wanneer een kanaal wordt geüpgraded van een top-level config voor één account naar channels.<id>.accounts.*, is het standaard gedeelde gedrag dat gepromoveerde account-scoped waarden naar accounts.default worden verplaatst.

Gebundelde kanalen kunnen die promotie beperken of overschrijven via hun setup-contractoppervlak:

• singleAccountKeysToMove: extra top-level keys die naar het gepromoveerde account moeten worden verplaatst
• namedAccountPromotionKeys: wanneer benoemde accounts al bestaan, worden alleen deze keys naar het gepromoveerde account verplaatst; gedeelde policy-/delivery-keys blijven op de kanaalroot
• resolveSingleAccountPromotionTarget(...): kies welk bestaand account gepromoveerde waarden ontvangt

# Config-schema

Pluginconfiguratie wordt gevalideerd tegen het JSON Schema in je manifest. Gebruikers configureren plugins via:

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

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

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 naar de ChannelConfigSchema-wrapper die wordt gebruikt door Plugin-eigen configuratieartefacten:

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 schrijft, 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 cold-pathcontract het Plugin-manifest: spiegel het gegenereerde JSON Schema naar openclaw.plugin.json#channelConfigs, zodat configuratieschema-, setup- en UI-oppervlakken channels.<id> kunnen inspecteren zonder runtimecode te laden.

# Setupwizards

Kanaalplugins kunnen interactieve setupwizards bieden 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),
        };
      },
    },
  ],
};

Het type ChannelSetupWizard ondersteunt credentials, textInputs, dmPolicy, allowFrom, groupAccess, prepare, finalize en meer. Zie gebundelde Pluginpakketten (bijvoorbeeld de Discord-Plugin src/channel.setup.ts) voor volledige voorbeelden.

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

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 repo: plaats ze onder de meegeleverde Plugin-workspaceboom en ze worden automatisch ontdekt tijdens de build.

Gebruikers kunnen installeren:

openclaw plugins install <package-name>

Metadata van gebundelde pakketten is expliciet en wordt niet afgeleid uit gebouwde JavaScript bij het opstarten van de Gateway. Runtime-afhankelijkheden horen thuis in het Plugin-pakket dat ze bezit; het opstarten van verpakte OpenClaw repareert of spiegelt Plugin-afhankelijkheden nooit.

# Gerelateerd

• Plugins bouwen — stapsgewijze gids om aan de slag te gaan
• Plugin-manifest — volledige referentie voor het manifestschema
• SDK-entrypoints — definePluginEntry en defineChannelPluginEntry