Configuration et paramétrage du Plugin

Référence pour l’empaquetage des plugins (métadonnées de package.json), les manifestes (openclaw.plugin.json), les points d’entrée de configuration et les schémas de configuration.

Métadonnées du paquet

Votre fichier package.json doit comporter un champ openclaw qui indique au système de plugins ce que fournit votre plugin :

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

Champs openclaw

openclaw.channel

openclaw.channel fournit des métadonnées de paquet légères pour la découverte des canaux et les interfaces de configuration avant le chargement de l’environnement d’exécution.

Exemple :

{  "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 prend en charge :

• configured : inclut le canal dans les interfaces de liste des canaux configurés et d’état
• setup : inclut le canal dans les sélecteurs interactifs de configuration
• docs : indique que le canal est public dans les interfaces de documentation et de navigation

openclaw.install

openclaw.install constitue une métadonnée du paquet, et non du manifeste.

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

Chargement complet différé

Les plugins de canal peuvent activer le chargement différé avec :

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

Lorsque cette option est activée, OpenClaw charge uniquement setupEntry pendant la phase de démarrage précédant la mise en écoute, même pour les canaux déjà configurés. Le point d’entrée complet est chargé une fois que le Gateway commence à écouter.

Si vos points d’entrée de configuration ou complet enregistrent des méthodes RPC du Gateway, utilisez un préfixe propre au plugin. Les espaces de noms d’administration réservés au cœur (config.*, exec.approvals.*, wizard.*, update.*) restent la propriété du cœur et sont toujours normalisés en operator.admin.

Manifeste du plugin

Chaque Plugin natif doit inclure un fichier openclaw.plugin.json à la racine du paquet. OpenClaw l’utilise pour valider la configuration sans exécuter le code du Plugin.

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

Pour les Plugins de canal, ajoutez channels (et, pour les Plugins de fournisseur, ajoutez providers) :

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

Même les Plugins sans configuration doivent inclure un schéma. Un schéma vide est valide :

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

Consultez Manifeste de Plugin pour obtenir la référence complète du schéma.

Publication sur ClawHub

Les Skills et les paquets de Plugins utilisent des commandes de publication ClawHub distinctes. Pour les paquets de Plugins, utilisez la commande propre aux paquets :

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

Point d’entrée de configuration

setup-entry.ts est une alternative légère à index.ts qu’OpenClaw charge lorsqu’il n’a besoin que des surfaces de configuration (intégration initiale, réparation de la configuration, inspection des canaux désactivés) :

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

Cela évite de charger du code d’exécution lourd (bibliothèques cryptographiques, enregistrements CLI, services en arrière-plan) pendant les flux de configuration.

Les canaux intégrés à l’espace de travail qui conservent des exports sûrs pour la configuration dans des modules annexes peuvent utiliser defineBundledChannelSetupEntry(...) depuis openclaw/plugin-sdk/channel-entry-contract au lieu de defineSetupPluginEntry(...). Ce contrat intégré prend également en charge un export facultatif runtime, afin que le câblage de l’environnement d’exécution pendant la configuration reste léger et explicite.

Imports ciblés des assistants de configuration

Pour les chemins critiques réservés à la configuration, préférez les interfaces ciblées d’assistance à la configuration à l’interface globale plugin-sdk/setup lorsque vous n’avez besoin que d’une partie de la surface de configuration :

Utilisez l’interface plus générale plugin-sdk/setup lorsque vous souhaitez disposer de la boîte à outils partagée complète pour la configuration, y compris des assistants de modification de configuration tels que moveSingleAccountChannelSectionToDefaultAccount(...).

Utilisez createSetupTranslator(...) pour les textes fixes de l’assistant de configuration. Il suit les paramètres régionaux de l’assistant CLI (OPENCLAW_LOCALE, puis les variables de paramètres régionaux du système) et utilise l’anglais comme solution de repli. Conservez le texte de configuration propre au Plugin dans le code appartenant à celui-ci et utilisez les clés du catalogue partagé uniquement pour les libellés de configuration communs, les textes d’état et les textes de configuration des Plugins officiels intégrés.

Les adaptateurs de modification de configuration restent sûrs à importer dans les chemins critiques. Leur recherche de la surface contractuelle de promotion d’un compte unique intégré est différée ; ainsi, l’importation de plugin-sdk/setup-runtime ne charge pas immédiatement la découverte des surfaces contractuelles intégrées avant l’utilisation effective de l’adaptateur.

Promotion d’un compte unique détenue par le canal

Lorsqu’un canal passe d’une configuration de compte unique au niveau supérieur à channels.<id>.accounts.*, le comportement partagé par défaut déplace les valeurs promues propres au compte vers accounts.default.

Les canaux intégrés peuvent restreindre ou remplacer cette promotion au moyen de leur surface contractuelle de configuration :

• singleAccountKeysToMove : clés supplémentaires de niveau supérieur à déplacer dans le compte promu
• namedAccountPromotionKeys : lorsque des comptes nommés existent déjà, seules ces clés sont déplacées dans le compte promu ; les clés partagées de stratégie et de distribution restent à la racine du canal
• resolveSingleAccountPromotionTarget(...) : choisit le compte existant qui reçoit les valeurs promues

Schéma de configuration

La configuration du Plugin est validée par rapport au schéma JSON de votre manifeste. Les utilisateurs configurent les Plugins comme suit :

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

Votre Plugin reçoit cette configuration dans api.pluginConfig lors de l’enregistrement.

Pour une configuration propre à un canal, utilisez plutôt la section de configuration du canal :

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

Création de schémas de configuration de canal

Utilisez buildChannelConfigSchema pour convertir un schéma Zod dans l’enveloppe ChannelConfigSchema utilisée par les artefacts de configuration appartenant au Plugin :

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

Si vous définissez déjà le contrat sous forme de schéma JSON ou avec TypeBox, utilisez l’assistant direct afin qu’OpenClaw puisse éviter la conversion de Zod en schéma JSON dans les chemins de métadonnées :

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

Pour les Plugins tiers, le contrat du chemin à froid reste le manifeste du Plugin : reproduisez le schéma JSON généré dans openclaw.plugin.json#channelConfigs afin que le schéma de configuration, la configuration et les surfaces d’interface utilisateur puissent inspecter channels.<id> sans charger le code d’exécution.

Assistants de configuration

Les Plugins de canal peuvent fournir des assistants de configuration interactifs pour openclaw onboard. L’assistant est un objet ChannelSetupWizard dans le 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 prend également en charge textInputs, dmPolicy, allowFrom, groupAccess, prepare, finalize, entre autres. Consultez le fichier src/setup-core.ts du Plugin Discord pour obtenir un exemple intégré complet.

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 }

Publication et installation

Plugins externes : publiez-les sur ClawHub, puis installez-les :

openclaw plugins install @myorg/openclaw-my-plugin

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

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

Plugins du dépôt : placez-les dans l’arborescence de l’espace de travail des Plugins intégrés ; ils sont automatiquement détectés pendant la compilation.

Les métadonnées des paquets intégrés sont explicites et ne sont pas déduites du JavaScript compilé au démarrage du Gateway. Les dépendances d’exécution doivent se trouver dans le paquet du Plugin qui les possède ; le démarrage d’une version empaquetée d’OpenClaw ne répare ni ne réplique jamais les dépendances des Plugins.

Pages connexes

• Créer des Plugins — guide de démarrage pas à pas
• Manifeste de Plugin — référence complète du schéma du manifeste
• Points d’entrée du SDK — definePluginEntry et defineChannelPluginEntry