Installation et configuration du Plugin

Référence pour le packaging des plugins (métadonnées package.json), les manifestes (openclaw.plugin.json), les entrées de configuration et les schémas de configuration.

# Métadonnées du package

Votre package.json a besoin d’un champ openclaw qui indique au système de plugins ce que votre plugin fournit :

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

# Champs openclaw

# openclaw.channel

openclaw.channel est une métadonnée de package légère pour la découverte des canaux et les surfaces 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 : inclure le canal dans les surfaces de liste configurées/de type état
• setup : inclure le canal dans les sélecteurs interactifs de configuration
• docs : marquer le canal comme public dans les surfaces de documentation/navigation

# openclaw.install

openclaw.install est une métadonnée de package, pas une métadonnée de manifeste.

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

# Chargement complet différé

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

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

Lorsque cette option est activée, OpenClaw ne charge que setupEntry pendant la phase de démarrage précédant l’écoute, même pour les canaux déjà configurés. L’entrée complète se charge après que le Gateway commence à écouter.

Si votre entrée de configuration/complète enregistre des méthodes RPC du Gateway, gardez-les sur un préfixe propre au plugin. Les espaces de noms d’administration principaux réservés (config.*, exec.approvals.*, wizard.*, update.*) restent détenus par le cœur et se résolvent toujours en operator.admin.

# Manifeste de Plugin

Chaque plugin natif doit fournir un openclaw.plugin.json à la racine du package. 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 kind et channels :

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

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

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

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

# Publication sur ClawHub

Pour les packages de plugins, utilisez la commande ClawHub propre au package :

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

# Entrée de configuration

Le fichier setup-entry.ts est une alternative légère à index.ts qu’OpenClaw charge lorsqu’il n’a besoin que des surfaces de configuration (onboarding, réparation de 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 de chiffrement, enregistrements CLI, services en arrière-plan) pendant les flux de configuration.

Les canaux d’espace de travail intégrés 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 aussi en charge un export runtime facultatif afin que le câblage d’exécution au moment de la configuration reste léger et explicite.

# Imports étroits d’assistants de configuration

Pour les chemins chauds réservés à la configuration, privilégiez les coutures étroites d’assistants de configuration plutôt que le parapluie plus large plugin-sdk/setup lorsque vous n’avez besoin que d’une partie de la surface de configuration :

Utilisez la couture plus large plugin-sdk/setup lorsque vous voulez la boîte à outils partagée complète de configuration, y compris les assistants de correctifs de configuration comme moveSingleAccountChannelSectionToDefaultAccount(...).

Les adaptateurs de correctifs de configuration restent sûrs à l’import pour les chemins chauds. Leur recherche de surface de contrat intégrée pour la promotion de compte unique est paresseuse, donc importer plugin-sdk/setup-runtime ne charge pas immédiatement la découverte de surface de contrat intégrée avant que l’adaptateur soit réellement utilisé.

# Promotion de compte unique détenue par le canal

Lorsqu’un canal migre d’une configuration de premier niveau à compte unique vers channels.<id>.accounts.*, le comportement partagé par défaut consiste à déplacer les valeurs promues ayant une portée de compte dans accounts.default.

Les canaux intégrés peuvent restreindre ou remplacer cette promotion via leur surface de contrat de configuration :

• singleAccountKeysToMove : clés de premier niveau supplémentaires qui doivent être déplacées 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/livraison restent à la racine du canal
• resolveSingleAccountPromotionTarget(...) : choisir quel compte existant reçoit les valeurs promues

# Schéma de configuration

La configuration du Plugin est validée par rapport au JSON Schema dans votre manifeste. Les utilisateurs configurent les plugins via :

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

Votre Plugin reçoit cette configuration sous la forme api.pluginConfig pendant 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"],
    },
  },
}

# Construire des schémas de configuration de canal

Utilisez buildChannelConfigSchema pour convertir un schéma Zod en enveloppe ChannelConfigSchema utilisée par les artefacts de configuration détenus par le 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 rédigez déjà le contrat en JSON Schema ou TypeBox, utilisez l’assistant direct afin qu’OpenClaw puisse éviter la conversion Zod vers JSON Schema sur 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 de chemin froid reste le manifeste du Plugin : reflétez le JSON Schema généré dans openclaw.plugin.json#channelConfigs afin que le schéma de configuration, la configuration et les surfaces UI puissent inspecter channels.<id> sans charger de 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 sur 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),
        };
      },
    },
  ],
};

Le type ChannelSetupWizard prend en charge credentials, textInputs, dmPolicy, allowFrom, groupAccess, prepare, finalize, et plus encore. Consultez les packages de plugins intégrés (par exemple le Plugin Discord src/channel.setup.ts) pour des exemples complets.

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 sur ClawHub, puis installez :

openclaw plugins install @myorg/openclaw-my-plugin

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

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

Plugins dans le dépôt : placez-les sous l’arborescence de l’espace de travail des plugins groupés ; ils sont automatiquement découverts pendant la compilation.

Les utilisateurs peuvent installer :

openclaw plugins install <package-name>

Les métadonnées des packages groupés sont explicites, elles ne sont pas déduites du JavaScript compilé au démarrage du gateway. Les dépendances d’exécution appartiennent au package de plugin qui les possède ; le démarrage d’OpenClaw packagé ne répare ni ne réplique jamais les dépendances des plugins.

# Associés

• Créer des plugins — guide de démarrage étape par étape
• Manifeste de plugin — référence complète du schéma de manifeste
• Points d’entrée du SDK — definePluginEntry et defineChannelPluginEntry