​

Plugins (Extensions)

​

Démarrage rapide (nouveau sur les plugins ?)

1. Voir ce qui est déjà chargé :

openclaw plugins list

2. Installer un plugin officiel (exemple : Voice Call) :

openclaw plugins install @openclaw/voice-call

3. Redémarrez la Gateway (passerelle), puis configurez sous plugins.entries.<id>.config.

​

Plugins disponibles (officiels)

• Microsoft Teams est uniquement disponible via plugin depuis le 15/01/2026 ; installez @openclaw/msteams si vous utilisez Teams.
• Memory (Core) — plugin de recherche de mémoire groupé (activé par défaut via plugins.slots.memory)
• Memory (LanceDB) — plugin de mémoire long terme groupé (rappel/capture automatiques ; définir plugins.slots.memory = "memory-lancedb")
• Voice Call — @openclaw/voice-call
• Zalo Personal — @openclaw/zalouser
• Matrix — @openclaw/matrix
• Nostr — @openclaw/nostr
• Zalo — @openclaw/zalo
• Microsoft Teams — @openclaw/msteams
• Google Antigravity OAuth (authentification fournisseur) — groupé en tant que google-antigravity-auth (désactivé par défaut)
• Gemini CLI OAuth (authentification fournisseur) — groupé en tant que google-gemini-cli-auth (désactivé par défaut)
• Qwen OAuth (authentification fournisseur) — groupé en tant que qwen-portal-auth (désactivé par défaut)
• Copilot Proxy (authentification fournisseur) — pont local VS Code Copilot Proxy ; distinct de la connexion intégrée github-copilot par appareil (groupé, désactivé par défaut)

• Des méthodes RPC de la Gateway (passerelle)
• Des gestionnaires HTTP de la Gateway (passerelle)
• Des outils d’agent
• Des commandes CLI
• Des services en arrière-plan
• Une validation de configuration optionnelle
• Des Skills (en listant des répertoires skills dans le manifeste du plugin)
• Des commandes de réponse automatique (exécutées sans invoquer l’agent IA)

​

Aides à l’exécution

const result = await api.runtime.tts.textToSpeechTelephony({
  text: "Hello from OpenClaw",
  cfg: api.config,
});

• Utilise la configuration centrale messages.tts (OpenAI ou ElevenLabs).
• Retourne un tampon audio PCM + un taux d’échantillonnage. Les plugins doivent rééchantillonner/encoder pour les fournisseurs.
• Edge TTS n’est pas pris en charge pour la téléphonie.

​

Découverte et priorité

1. Chemins de configuration

• plugins.load.paths (fichier ou répertoire)

2. Extensions de l’espace de travail

• <workspace>/.openclaw/extensions/*.ts
• <workspace>/.openclaw/extensions/*/index.ts

3. Extensions globales

• ~/.openclaw/extensions/*.ts
• ~/.openclaw/extensions/*/index.ts

4. Extensions groupées (livrées avec OpenClaw, désactivées par défaut)

• <openclaw>/extensions/*

​

Package packs

{
  "name": "my-pack",
  "openclaw": {
    "extensions": ["./src/safety.ts", "./src/tools.ts"]
  }
}

​

Métadonnées du catalogue de canaux

{
  "name": "@openclaw/nextcloud-talk",
  "openclaw": {
    "extensions": ["./index.ts"],
    "channel": {
      "id": "nextcloud-talk",
      "label": "Nextcloud Talk",
      "selectionLabel": "Nextcloud Talk (self-hosted)",
      "docsPath": "/channels/nextcloud-talk",
      "docsLabel": "nextcloud-talk",
      "blurb": "Self-hosted chat via Nextcloud Talk webhook bots.",
      "order": 65,
      "aliases": ["nc-talk", "nc"]
    },
    "install": {
      "npmSpec": "@openclaw/nextcloud-talk",
      "localPath": "extensions/nextcloud-talk",
      "defaultChoice": "npm"
    }
  }
}

• ~/.openclaw/mpm/plugins.json
• ~/.openclaw/mpm/catalog.json
• ~/.openclaw/plugins/catalog.json

​

IDs de plugin

• Package packs : package.json name
• Fichier autonome : nom de base du fichier (~/.../voice-call.ts → voice-call)

​

Configuration

{
  plugins: {
    enabled: true,
    allow: ["voice-call"],
    deny: ["untrusted-plugin"],
    load: { paths: ["~/Projects/oss/voice-call-extension"] },
    entries: {
      "voice-call": { enabled: true, config: { provider: "twilio" } },
    },
  },
}

• enabled : interrupteur principal (par défaut : true)
• allow : liste d’autorisation (optionnelle)
• deny : liste de refus (optionnelle ; le refus l’emporte)
• load.paths : fichiers/répertoires de plugins supplémentaires
• entries.<id> : interrupteurs par plugin + configuration

• Les ids de plugin inconnus dans entries, allow, deny ou slots sont des erreurs.
• Les clés channels.<id> inconnues sont des erreurs, sauf si un manifeste de plugin déclare l’id de canal.
• La configuration du plugin est validée à l’aide du schéma JSON intégré dans openclaw.plugin.json (configSchema).
• Si un plugin est désactivé, sa configuration est conservée et un avertissement est émis.

​

Emplacements de plugin (catégories exclusives)

{
  plugins: {
    slots: {
      memory: "memory-core", // or "none" to disable memory plugins
    },
  },
}

​

Interface de contrôle (schéma + libellés)

• Ajoute des libellés par plugin pour plugins.entries.<id> / .enabled / .config
• Fusionne des indications de champs de configuration optionnelles fournies par les plugins sous : plugins.entries.<id>.config.<field>

{
  "id": "my-plugin",
  "configSchema": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
      "apiKey": { "type": "string" },
      "region": { "type": "string" }
    }
  },
  "uiHints": {
    "apiKey": { "label": "API Key", "sensitive": true },
    "region": { "label": "Region", "placeholder": "us-east-1" }
  }
}

​

CLI

openclaw plugins list
openclaw plugins info <id>
openclaw plugins install <path>                 # copy a local file/dir into ~/.openclaw/extensions/<id>
openclaw plugins install ./extensions/voice-call # relative path ok
openclaw plugins install ./plugin.tgz           # install from a local tarball
openclaw plugins install ./plugin.zip           # install from a local zip
openclaw plugins install -l ./extensions/voice-call # link (no copy) for dev
openclaw plugins install @openclaw/voice-call # install from npm
openclaw plugins update <id>
openclaw plugins update --all
openclaw plugins enable <id>
openclaw plugins disable <id>
openclaw plugins doctor

​

API de plugin (aperçu)

• Une fonction : (api) => { ... }
• Un objet : { id, name, configSchema, register(api) { ... } }

​

Hooks de plugin

​

Exemple

import { registerPluginHooksFromDir } from "openclaw/plugin-sdk";

export default function register(api) {
  registerPluginHooksFromDir(api, "./hooks");
}

• Les répertoires de hooks suivent la structure normale des hooks (HOOK.md + handler.ts).
• Les règles d’éligibilité des hooks s’appliquent toujours (OS/binaires/variables d’environnement/exigences de configuration).
• Les hooks gérés par des plugins apparaissent dans openclaw hooks list avec plugin:<id>.
• Vous ne pouvez pas activer/désactiver les hooks gérés par des plugins via openclaw hooks ; activez/désactivez le plugin à la place.

​

Plugins de fournisseur (authentification de modèle)

• openclaw models auth login --provider <id> [--method <id>]

api.registerProvider({
  id: "acme",
  label: "AcmeAI",
  auth: [
    {
      id: "oauth",
      label: "OAuth",
      kind: "oauth",
      run: async (ctx) => {
        // Run OAuth flow and return auth profiles.
        return {
          profiles: [
            {
              profileId: "acme:default",
              credential: {
                type: "oauth",
                provider: "acme",
                access: "...",
                refresh: "...",
                expires: Date.now() + 3600 * 1000,
              },
            },
          ],
          defaultModel: "acme/opus-1",
        };
      },
    },
  ],
});

• run reçoit un ProviderAuthContext avec des aides prompter, runtime, openUrl et oauth.createVpsAwareHandlers.
• Retournez configPatch lorsque vous devez ajouter des modèles par défaut ou une configuration de fournisseur.
• Retournez defaultModel afin que --set-default puisse mettre à jour les valeurs par défaut de l’agent.

​

Enregistrer un canal de messagerie

const myChannel = {
  id: "acmechat",
  meta: {
    id: "acmechat",
    label: "AcmeChat",
    selectionLabel: "AcmeChat (API)",
    docsPath: "/channels/acmechat",
    blurb: "demo channel plugin.",
    aliases: ["acme"],
  },
  capabilities: { chatTypes: ["direct"] },
  config: {
    listAccountIds: (cfg) => Object.keys(cfg.channels?.acmechat?.accounts ?? {}),
    resolveAccount: (cfg, accountId) =>
      cfg.channels?.acmechat?.accounts?.[accountId ?? "default"] ?? {
        accountId,
      },
  },
  outbound: {
    deliveryMode: "direct",
    sendText: async () => ({ ok: true }),
  },
};

export default function (api) {
  api.registerChannel({ plugin: myChannel });
}

• Placez la configuration sous channels.<id> (pas plugins.entries).
• meta.label est utilisé pour les libellés dans les listes CLI/UI.
• meta.aliases ajoute des ids alternatifs pour la normalisation et les entrées CLI.
• meta.preferOver liste les ids de canal à ignorer pour l’activation automatique lorsque les deux sont configurés.
• meta.detailLabel et meta.systemImage permettent aux interfaces d’afficher des libellés/icônes de canal plus riches.

​

Écrire un nouveau canal de messagerie (étape par étape)

1. Choisir un id + une forme de configuration

• Toute la configuration du canal se trouve sous channels.<id>.
• Préférez channels.<id>.accounts.<accountId> pour les configurations multi‑comptes.

2. Définir les métadonnées du canal

• meta.label, meta.selectionLabel, meta.docsPath, meta.blurb contrôlent les listes CLI/UI.
• meta.docsPath doit pointer vers une page de documentation comme /channels/<id>.
• meta.preferOver permet à un plugin de remplacer un autre canal (l’activation automatique le privilégie).
• meta.detailLabel et meta.systemImage sont utilisés par les interfaces pour le texte/icônes de détail.

3. Ajouter des adaptateurs optionnels selon les besoins

• config.listAccountIds + config.resolveAccount
• capabilities (types de chat, médias, fils, etc.)
• outbound.deliveryMode + outbound.sendText (pour l’envoi de base)

4. Implémenter les adaptateurs requis

• setup (assistant), security (politique de message privé), status (santé/diagnostics)
• gateway (démarrer/arrêter/connexion), mentions, threading, streaming
• actions (actions sur les messages), commands (comportement des commandes natives)

5. Enregistrer le canal dans votre plugin

• api.registerChannel({ plugin })

{
  channels: {
    acmechat: {
      accounts: {
        default: { token: "ACME_TOKEN", enabled: true },
      },
    },
  },
}

const plugin = {
  id: "acmechat",
  meta: {
    id: "acmechat",
    label: "AcmeChat",
    selectionLabel: "AcmeChat (API)",
    docsPath: "/channels/acmechat",
    blurb: "AcmeChat messaging channel.",
    aliases: ["acme"],
  },
  capabilities: { chatTypes: ["direct"] },
  config: {
    listAccountIds: (cfg) => Object.keys(cfg.channels?.acmechat?.accounts ?? {}),
    resolveAccount: (cfg, accountId) =>
      cfg.channels?.acmechat?.accounts?.[accountId ?? "default"] ?? {
        accountId,
      },
  },
  outbound: {
    deliveryMode: "direct",
    sendText: async ({ text }) => {
      // deliver `text` to your channel here
      return { ok: true };
    },
  },
};

export default function (api) {
  api.registerChannel({ plugin });
}

​

Outils d’agent

​

Enregistrer une méthode RPC de la gateway (passerelle)

export default function (api) {
  api.registerGatewayMethod("myplugin.status", ({ respond }) => {
    respond(true, { ok: true });
  });
}

​

Enregistrer des commandes CLI

export default function (api) {
  api.registerCli(
    ({ program }) => {
      program.command("mycmd").action(() => {
        console.log("Hello");
      });
    },
    { commands: ["mycmd"] },
  );
}

​

Enregistrer des commandes de réponse automatique

export default function (api) {
  api.registerCommand({
    name: "mystatus",
    description: "Show plugin status",
    handler: (ctx) => ({
      text: `Plugin is running! Channel: ${ctx.channel}`,
    }),
  });
}

• senderId : l’id de l’expéditeur (si disponible)
• channel : le canal où la commande a été envoyée
• isAuthorizedSender : si l’expéditeur est un utilisateur autorisé
• args : arguments passés après la commande (si acceptsArgs: true)
• commandBody : le texte complet de la commande
• config : la configuration OpenClaw actuelle

• name : nom de la commande (sans le / initial)
• description : texte d’aide affiché dans les listes de commandes
• acceptsArgs : indique si la commande accepte des arguments (par défaut : false). Si false et que des arguments sont fournis, la commande ne correspondra pas et le message sera transmis aux autres gestionnaires
• requireAuth : indique s’il faut exiger un expéditeur autorisé (par défaut : true)
• handler : fonction qui retourne { text: string } (peut être async)

api.registerCommand({
  name: "setmode",
  description: "Set plugin mode",
  acceptsArgs: true,
  requireAuth: true,
  handler: async (ctx) => {
    const mode = ctx.args?.trim() || "default";
    await saveMode(mode);
    return { text: `Mode set to: ${mode}` };
  },
});

• Les commandes de plugin sont traitées avant les commandes intégrées et l’agent IA
• Les commandes sont enregistrées globalement et fonctionnent sur tous les canaux
• Les noms de commande sont insensibles à la casse (/MyStatus correspond à /mystatus)
• Les noms de commande doivent commencer par une lettre et ne contenir que des lettres, chiffres, tirets et underscores
• Les noms de commande réservés (comme help, status, reset, etc.) ne peuvent pas être redéfinis par des plugins
• L’enregistrement de commandes en double entre plugins échouera avec une erreur de diagnostic

​

Enregistrer des services en arrière-plan

export default function (api) {
  api.registerService({
    id: "my-service",
    start: () => api.logger.info("ready"),
    stop: () => api.logger.info("bye"),
  });
}

​

Conventions de nommage

• Méthodes de la Gateway (passerelle) : pluginId.action (exemple : voicecall.status)
• Outils : snake_case (exemple : voice_call)
• Commandes CLI : kebab ou camel, mais évitez les conflits avec les commandes du cœur

​

Skills

​

Distribution (npm)

• Paquet principal : openclaw (ce dépôt)
• Plugins : paquets npm séparés sous @openclaw/* (exemple : @openclaw/voice-call)

• Le package.json du plugin doit inclure openclaw.extensions avec un ou plusieurs fichiers d’entrée.
• Les fichiers d’entrée peuvent être .js ou .ts (jiti charge TS à l’exécution).
• openclaw plugins install <npm-spec> utilise npm pack, extrait dans ~/.openclaw/extensions/<id>/ et l’active dans la configuration.
• Stabilité des clés de configuration : les paquets scopés sont normalisés vers l’id non scopé pour plugins.entries.*.

​

Exemple de plugin : Voice Call

• Source : extensions/voice-call
• Skill : skills/voice-call
• CLI : openclaw voicecall start|status
• Outil : voice_call
• RPC : voicecall.start, voicecall.status
• Configuration (twilio) : provider: "twilio" + twilio.accountSid/authToken/from (statusCallbackUrl, twimlUrl optionnels)
• Configuration (dev) : provider: "log" (sans réseau)

​

Remarques de sécurité

• N’installez que des plugins de confiance.
• Préférez les listes d’autorisation plugins.allow.
• Redémarrez la Gateway (passerelle) après les modifications.

​

Tester les plugins

• Les plugins dans le dépôt peuvent conserver des tests Vitest sous src/** (exemple : src/plugins/voice-call.plugin.test.ts).
• Les plugins publiés séparément doivent exécuter leur propre CI (lint/build/test) et valider que openclaw.extensions pointe vers le point d’entrée compilé (dist/index.js).