​

Créer des plugins de canal

​

Fonctionnement des plugins de canal

• Config — résolution des comptes et assistant de configuration
• Security — politique DM et listes d’autorisation
• Pairing — flux d’approbation des DM
• Session grammar — manière dont les ids de conversation propres au fournisseur se mappent aux chats de base, aux ids de thread, et aux fallbacks parents
• Outbound — envoi de texte, médias, et sondages vers la plateforme
• Threading — manière dont les réponses sont threadées

​

Approbations et capacités des canaux

• Le core possède /approve dans le même chat, les payloads partagés des boutons d’approbation, et la livraison de fallback générique.
• Préférez un seul objet approvalCapability sur le plugin de canal lorsque le canal a besoin d’un comportement spécifique aux approbations.
• ChannelPlugin.approvals est supprimé. Placez les faits d’approbation de livraison/natifs/rendu/authentification sur approvalCapability.
• plugin.auth sert uniquement à login/logout ; le core ne lit plus les hooks d’authentification d’approbation depuis cet objet.
• approvalCapability.authorizeActorAction et approvalCapability.getActionAvailabilityState sont la couture canonique pour l’authentification des approbations.
• Utilisez approvalCapability.getActionAvailabilityState pour la disponibilité de l’authentification des approbations dans le même chat.
• Si votre canal expose des approbations d’exécution natives, utilisez approvalCapability.getExecInitiatingSurfaceState pour l’état de la surface initiatrice/du client natif lorsqu’il diffère de l’authentification des approbations dans le même chat. Le core utilise ce hook spécifique à l’exécution pour distinguer enabled de disabled, décider si le canal initiateur prend en charge les approbations d’exécution natives, et inclure le canal dans les indications de fallback du client natif. createApproverRestrictedNativeApprovalCapability(...) remplit ce point pour le cas courant.
• Utilisez outbound.shouldSuppressLocalPayloadPrompt ou outbound.beforeDeliverPayload pour le comportement du cycle de vie des payloads spécifique au canal, par exemple masquer les prompts d’approbation locale en double ou envoyer des indicateurs de frappe avant la livraison.
• Utilisez approvalCapability.delivery uniquement pour le routage d’approbation natif ou la suppression de fallback.
• Utilisez approvalCapability.nativeRuntime pour les faits d’approbation native appartenant au canal. Gardez-le lazy sur les points d’entrée chauds du canal avec createLazyChannelApprovalNativeRuntimeAdapter(...), qui peut importer votre module runtime à la demande tout en laissant le core assembler le cycle de vie des approbations.
• Utilisez approvalCapability.render uniquement lorsqu’un canal a réellement besoin de payloads d’approbation personnalisés au lieu du moteur de rendu partagé.
• Utilisez approvalCapability.describeExecApprovalSetup lorsque le canal veut que la réponse du chemin désactivé explique les paramètres de configuration exacts nécessaires pour activer les approbations d’exécution natives. Le hook reçoit { channel, channelLabel, accountId } ; les canaux à compte nommé doivent afficher des chemins à portée de compte tels que channels.<channel>.accounts.<id>.execApprovals.* au lieu de valeurs par défaut de niveau supérieur.
• Si un canal peut déduire des identités DM stables de type propriétaire à partir de la configuration existante, utilisez createResolvedApproverActionAuthAdapter depuis openclaw/plugin-sdk/approval-runtime pour restreindre /approve dans le même chat sans ajouter de logique core spécifique aux approbations.
• Si un canal a besoin d’une livraison d’approbation native, gardez le code du canal centré sur la normalisation de la cible ainsi que sur les faits de transport/présentation. Utilisez createChannelExecApprovalProfile, createChannelNativeOriginTargetResolver, createChannelApproverDmTargetResolver, et createApproverRestrictedNativeApprovalCapability depuis openclaw/plugin-sdk/approval-runtime. Placez les faits spécifiques au canal derrière approvalCapability.nativeRuntime, idéalement via createChannelApprovalNativeRuntimeAdapter(...) ou createLazyChannelApprovalNativeRuntimeAdapter(...), afin que le core puisse assembler le gestionnaire et posséder le filtrage des requêtes, le routage, la déduplication, l’expiration, l’abonnement gateway, et les avis « routed elsewhere ». nativeRuntime est divisé en quelques coutures plus petites :
• availability — si le compte est configuré et si une requête doit être traitée
• presentation — mapper le modèle de vue d’approbation partagé en payloads natifs en attente/résolus/expirés ou en actions finales
• transport — préparer les cibles plus envoyer/mettre à jour/supprimer les messages d’approbation natifs
• interactions — hooks optionnels de bind/unbind/clear-action pour les boutons ou réactions natifs
• observe — hooks optionnels de diagnostic de livraison
• Si le canal a besoin d’objets possédés par le runtime comme un client, un jeton, une app Bolt, ou un récepteur webhook, enregistrez-les via openclaw/plugin-sdk/channel-runtime-context. Le registre générique de contexte runtime permet au core de bootstrapper des gestionnaires pilotés par capacité à partir de l’état de démarrage du canal sans ajouter de glue wrapper spécifique aux approbations.
• Recourez à createChannelApprovalHandler ou createChannelNativeApprovalRuntime de niveau inférieur uniquement lorsque la couture pilotée par capacité n’est pas encore assez expressive.
• Les canaux d’approbation native doivent router à la fois accountId et approvalKind via ces helpers. accountId conserve la portée de la politique d’approbation multi-comptes sur le bon compte bot, et approvalKind conserve le comportement d’approbation d’exécution vs plugin disponible pour le canal sans branches codées en dur dans le core.
• Le core possède désormais aussi les avis de reroutage d’approbation. Les plugins de canal ne doivent pas envoyer leurs propres messages de suivi « approval went to DMs / another channel » depuis createChannelNativeApprovalRuntime ; exposez plutôt un routage précis de l’origine + DM de l’approbateur via les helpers partagés de capacité d’approbation et laissez le core agréger les livraisons réelles avant de publier tout avis dans le chat initiateur.
• Préservez le type d’id d’approbation livré de bout en bout. Les clients natifs ne doivent pas deviner ni réécrire le routage d’approbation d’exécution vs plugin à partir d’un état local au canal.
• Différents types d’approbation peuvent intentionnellement exposer différentes surfaces natives. Exemples intégrés actuels :
  • Slack conserve le routage d’approbation natif disponible pour les ids d’exécution et de plugin.
  • Matrix conserve le même routage DM/canal natif et la même UX par réaction pour les approbations d’exécution et de plugin, tout en permettant à l’authentification de différer selon le type d’approbation.
• createApproverRestrictedNativeApprovalAdapter existe toujours comme wrapper de compatibilité, mais le nouveau code doit préférer le builder de capacité et exposer approvalCapability sur le plugin.

• openclaw/plugin-sdk/approval-auth-runtime
• openclaw/plugin-sdk/approval-client-runtime
• openclaw/plugin-sdk/approval-delivery-runtime
• openclaw/plugin-sdk/approval-gateway-runtime
• openclaw/plugin-sdk/approval-handler-adapter-runtime
• openclaw/plugin-sdk/approval-handler-runtime
• openclaw/plugin-sdk/approval-native-runtime
• openclaw/plugin-sdk/approval-reply-runtime
• openclaw/plugin-sdk/channel-runtime-context

• openclaw/plugin-sdk/setup-runtime couvre les helpers de configuration sûrs au runtime : adaptateurs de patch de configuration import-safe (createPatchedAccountSetupAdapter, createEnvPatchedAccountSetupAdapter, createSetupInputPresenceValidator), sortie de note de lookup, promptResolvedAllowFrom, splitSetupEntries, et les builders délégués de setup-proxy
• openclaw/plugin-sdk/setup-adapter-runtime est la couture étroite d’adaptateur sensible à l’environnement pour createEnvPatchedAccountSetupAdapter
• openclaw/plugin-sdk/channel-setup couvre les builders de configuration à installation optionnelle ainsi que quelques primitives sûres pour la configuration : createOptionalChannelSetupSurface, createOptionalChannelSetupAdapter,

• utilisez la couture plus large openclaw/plugin-sdk/setup uniquement lorsque vous avez aussi besoin des helpers partagés plus lourds de configuration/setup tels que moveSingleAccountChannelSectionToDefaultAccount(...)

• openclaw/plugin-sdk/account-core, openclaw/plugin-sdk/account-id, openclaw/plugin-sdk/account-resolution, et openclaw/plugin-sdk/account-helpers pour la configuration multi-comptes et le fallback de compte par défaut
• openclaw/plugin-sdk/inbound-envelope et openclaw/plugin-sdk/inbound-reply-dispatch pour le câblage de route/enveloppe entrante et d’enregistrement-et-répartition
• openclaw/plugin-sdk/messaging-targets pour l’analyse/la correspondance des cibles
• openclaw/plugin-sdk/outbound-media et openclaw/plugin-sdk/outbound-runtime pour le chargement des médias ainsi que les délégués d’identité/envoi sortants
• openclaw/plugin-sdk/thread-bindings-runtime pour le cycle de vie des liaisons de thread et l’enregistrement des adaptateurs
• openclaw/plugin-sdk/agent-media-payload uniquement lorsqu’une disposition héritée des champs de payload agent/média est encore requise
• openclaw/plugin-sdk/telegram-command-config pour la normalisation des commandes personnalisées Telegram, la validation des doublons/conflits, et un contrat de configuration de commandes stable en fallback

​

Politique de mention entrante

• collecte des preuves appartenant au plugin
• évaluation partagée de la politique

• détection des réponses au bot
• détection des citations du bot
• vérifications de participation au thread
• exclusions des messages de service/système
• caches natifs à la plateforme nécessaires pour prouver la participation du bot

• requireMention
• résultat de mention explicite
• liste d’autorisation de mention implicite
• contournement de commande
• décision finale d’ignorer

1. Calculez les faits de mention locaux.
2. Transmettez ces faits à resolveInboundMentionDecision({ facts, policy }).
3. Utilisez decision.effectiveWasMentioned, decision.shouldBypassMention, et decision.shouldSkip dans votre garde d’entrée.

import {
  implicitMentionKindWhen,
  matchesMentionWithExplicit,
  resolveInboundMentionDecision,
} from "openclaw/plugin-sdk/channel-inbound";

const mentionMatch = matchesMentionWithExplicit(text, {
  mentionRegexes,
  mentionPatterns,
});

const facts = {
  canDetectMention: true,
  wasMentioned: mentionMatch.matched,
  hasAnyMention: mentionMatch.hasExplicitMention,
  implicitMentionKinds: [
    ...implicitMentionKindWhen("reply_to_bot", isReplyToBot),
    ...implicitMentionKindWhen("quoted_bot", isQuoteOfBot),
  ],
};

const decision = resolveInboundMentionDecision({
  facts,
  policy: {
    isGroup,
    requireMention,
    allowedImplicitMentionKinds: requireExplicitMention ? [] : ["reply_to_bot", "quoted_bot"],
    allowTextCommands,
    hasControlCommand,
    commandAuthorized,
  },
});

if (decision.shouldSkip) return;

• buildMentionRegexes
• matchesMentionPatterns
• matchesMentionWithExplicit
• implicitMentionKindWhen
• resolveInboundMentionDecision

​

Procédure pas à pas

{
  "name": "@myorg/openclaw-acme-chat",
  "version": "1.0.0",
  "type": "module",
  "openclaw": {
    "extensions": ["./index.ts"],
    "setupEntry": "./setup-entry.ts",
    "channel": {
      "id": "acme-chat",
      "label": "Acme Chat",
      "blurb": "Connect OpenClaw to Acme Chat."
    }
  }
}

import {
  createChatChannelPlugin,
  createChannelPluginBase,
} from "openclaw/plugin-sdk/channel-core";
import type { OpenClawConfig } from "openclaw/plugin-sdk/channel-core";
import { acmeChatApi } from "./client.js"; // votre client API de plateforme

type ResolvedAccount = {
  accountId: string | null;
  token: string;
  allowFrom: string[];
  dmPolicy: string | undefined;
};

function resolveAccount(
  cfg: OpenClawConfig,
  accountId?: string | null,
): ResolvedAccount {
  const section = (cfg.channels as Record<string, any>)?.["acme-chat"];
  const token = section?.token;
  if (!token) throw new Error("acme-chat: token is required");
  return {
    accountId: accountId ?? null,
    token,
    allowFrom: section?.allowFrom ?? [],
    dmPolicy: section?.dmSecurity,
  };
}

export const acmeChatPlugin = createChatChannelPlugin<ResolvedAccount>({
  base: createChannelPluginBase({
    id: "acme-chat",
    setup: {
      resolveAccount,
      inspectAccount(cfg, accountId) {
        const section =
          (cfg.channels as Record<string, any>)?.["acme-chat"];
        return {
          enabled: Boolean(section?.token),
          configured: Boolean(section?.token),
          tokenStatus: section?.token ? "available" : "missing",
        };
      },
    },
  }),

  // Sécurité DM : qui peut envoyer un message au bot
  security: {
    dm: {
      channelKey: "acme-chat",
      resolvePolicy: (account) => account.dmPolicy,
      resolveAllowFrom: (account) => account.allowFrom,
      defaultPolicy: "allowlist",
    },
  },

  // Appairage : flux d’approbation pour les nouveaux contacts DM
  pairing: {
    text: {
      idLabel: "Nom d’utilisateur Acme Chat",
      message: "Envoyez ce code pour vérifier votre identité :",
      notify: async ({ target, code }) => {
        await acmeChatApi.sendDm(target, `Pairing code: ${code}`);
      },
    },
  },

  // Threading : comment les réponses sont livrées
  threading: { topLevelReplyToMode: "reply" },

  // Outbound : envoyer des messages vers la plateforme
  outbound: {
    attachedResults: {
      sendText: async (params) => {
        const result = await acmeChatApi.sendMessage(
          params.to,
          params.text,
        );
        return { messageId: result.id };
      },
    },
    base: {
      sendMedia: async (params) => {
        await acmeChatApi.sendFile(params.to, params.filePath);
      },
    },
  },
});

import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core";
import { acmeChatPlugin } from "./src/channel.js";

export default defineChannelPluginEntry({
  id: "acme-chat",
  name: "Acme Chat",
  description: "Plugin de canal Acme Chat",
  plugin: acmeChatPlugin,
  registerCliMetadata(api) {
    api.registerCli(
      ({ program }) => {
        program
          .command("acme-chat")
          .description("Gestion Acme Chat");
      },
      {
        descriptors: [
          {
            name: "acme-chat",
            description: "Gestion Acme Chat",
            hasSubcommands: false,
          },
        ],
      },
    );
  },
  registerFull(api) {
    api.registerGatewayMethod(/* ... */);
  },
});

import { defineSetupPluginEntry } from "openclaw/plugin-sdk/channel-core";
import { acmeChatPlugin } from "./src/channel.js";

export default defineSetupPluginEntry(acmeChatPlugin);

registerFull(api) {
  api.registerHttpRoute({
    path: "/acme-chat/webhook",
    auth: "plugin", // authentification gérée par le plugin (vérifiez vous-même les signatures)
    handler: async (req, res) => {
      const event = parseWebhookPayload(req);

      // Votre gestionnaire entrant répartit le message vers OpenClaw.
      // Le câblage exact dépend de votre SDK de plateforme —
      // voir un exemple réel dans le package de plugin Microsoft Teams ou Google Chat intégré.
      await handleAcmeChatInbound(api, event);

      res.statusCode = 200;
      res.end("ok");
      return true;
    },
  });
}

import { describe, it, expect } from "vitest";
import { acmeChatPlugin } from "./channel.js";

describe("plugin acme-chat", () => {
  it("résout le compte à partir de la configuration", () => {
    const cfg = {
      channels: {
        "acme-chat": { token: "test-token", allowFrom: ["user1"] },
      },
    } as any;
    const account = acmeChatPlugin.setup!.resolveAccount(cfg, undefined);
    expect(account.token).toBe("test-token");
  });

  it("inspecte le compte sans matérialiser les secrets", () => {
    const cfg = {
      channels: { "acme-chat": { token: "test-token" } },
    } as any;
    const result = acmeChatPlugin.setup!.inspectAccount!(cfg, undefined);
    expect(result.configured).toBe(true);
    expect(result.tokenStatus).toBe("available");
  });

  it("signale une configuration manquante", () => {
    const cfg = { channels: {} } as any;
    const result = acmeChatPlugin.setup!.inspectAccount!(cfg, undefined);
    expect(result.configured).toBe(false);
  });
});

pnpm test -- <bundled-plugin-root>/acme-chat/

​

Structure des fichiers

<bundled-plugin-root>/acme-chat/
├── package.json              # métadonnées openclaw.channel
├── openclaw.plugin.json      # manifeste avec schéma de configuration
├── index.ts                  # defineChannelPluginEntry
├── setup-entry.ts            # defineSetupPluginEntry
├── api.ts                    # exports publics (optionnel)
├── runtime-api.ts            # exports runtime internes (optionnel)
└── src/
    ├── channel.ts            # ChannelPlugin via createChatChannelPlugin
    ├── channel.test.ts       # tests
    ├── client.ts             # client API de la plateforme
    └── runtime.ts            # store runtime (si nécessaire)

​

Sujets avancés

​

Étapes suivantes

• Provider Plugins — si votre plugin fournit aussi des modèles
• SDK Overview — référence complète des imports de sous-chemins
• SDK Testing — utilitaires de test et tests de contrat
• Plugin Manifest — schéma complet du manifeste