Créer des plugins de canal

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

Fonctionnement des plugins de canal

• Configuration - résolution du compte et assistant de configuration
• Sécurité - politique de DM et listes d’autorisation
• Appairage - flux d’approbation par DM
• Grammaire de session - façon dont les identifiants de conversation propres au fournisseur correspondent aux discussions de base, aux identifiants de fil et aux solutions de repli parentes
• Sortant - envoi de texte, de médias et de sondages à la plateforme
• Fils de discussion - façon dont les réponses sont organisées en fils
• Saisie Heartbeat - signaux facultatifs de saisie/occupation pour les cibles de livraison Heartbeat

​

Approbations et capacités de canal

• Le noyau prend en charge /approve dans la même conversation, les payloads partagés des boutons d’approbation et la livraison de secours 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 informations de livraison/native/render/auth d’approbation sur approvalCapability.
• plugin.auth sert uniquement à la connexion/déconnexion ; le noyau ne lit plus les hooks d’authentification d’approbation depuis cet objet.
• approvalCapability.authorizeActorAction et approvalCapability.getActionAvailabilityState sont le seam canonique d’authentification d’approbation.
• Utilisez approvalCapability.getActionAvailabilityState pour la disponibilité de l’authentification d’approbation dans la même conversation.
• 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 d’approbation dans la même conversation. Le noyau 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 secours du client natif. createApproverRestrictedNativeApprovalCapability(...) renseigne cela pour le cas courant.
• Utilisez outbound.shouldSuppressLocalPayloadPrompt ou outbound.beforeDeliverPayload pour les comportements de cycle de vie des payloads spécifiques au canal, par exemple masquer les invites locales d’approbation en double ou envoyer des indicateurs de saisie avant la livraison.
• Utilisez approvalCapability.delivery uniquement pour le routage des approbations natives ou la suppression du secours.
• Utilisez approvalCapability.nativeRuntime pour les informations d’approbation native détenues par le canal. Gardez-le paresseux sur les points d’entrée de canal chauds avec createLazyChannelApprovalNativeRuntimeAdapter(...), qui peut importer votre module d’exécution à la demande tout en laissant le noyau assembler le cycle de vie d’approbation.
• 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 réglages de configuration exacts nécessaires pour activer les approbations d’exécution natives. Le hook reçoit { channel, channelLabel, accountId } ; les canaux à comptes nommés doivent rendre des chemins limités au compte, tels que channels.<channel>.accounts.<id>.execApprovals.*, plutôt que des valeurs par défaut de premier niveau.
• Si un canal peut inférer des identités de DM stables de type propriétaire à partir de la configuration existante, utilisez createResolvedApproverActionAuthAdapter depuis openclaw/plugin-sdk/approval-runtime pour restreindre /approve dans la même conversation sans ajouter de logique noyau spécifique aux approbations.
• Si un canal a besoin de livrer des approbations natives, gardez le code du canal centré sur la normalisation de la cible et les informations de transport/présentation. Utilisez createChannelExecApprovalProfile, createChannelNativeOriginTargetResolver, createChannelApproverDmTargetResolver et createApproverRestrictedNativeApprovalCapability depuis openclaw/plugin-sdk/approval-runtime. Placez les informations spécifiques au canal derrière approvalCapability.nativeRuntime, idéalement via createChannelApprovalNativeRuntimeAdapter(...) ou createLazyChannelApprovalNativeRuntimeAdapter(...), afin que le noyau puisse assembler le gestionnaire et prendre en charge le filtrage des requêtes, le routage, la déduplication, l’expiration, l’abonnement Gateway et les avis de routage ailleurs. nativeRuntime est divisé en quelques seams plus petits :
• createChannelNativeOriginTargetResolver utilise par défaut le comparateur de routes de canal partagé pour les cibles { to, accountId, threadId }. Passez targetsMatch uniquement lorsqu’un canal a des règles d’équivalence propres au fournisseur, comme la correspondance de préfixe d’horodatage Slack.
• Passez normalizeTargetForMatch à createChannelNativeOriginTargetResolver lorsque le canal doit canoniser les identifiants fournisseur avant l’exécution du comparateur de routes par défaut ou d’un callback targetsMatch personnalisé, tout en préservant la cible d’origine pour la livraison. Utilisez normalizeTarget uniquement lorsque la cible de livraison résolue elle-même doit être canonisée.
• availability - indique si le compte est configuré et si une requête doit être traitée
• presentation - mappe le modèle de vue d’approbation partagé vers des payloads natifs en attente/résolus/expirés ou vers des actions finales
• transport - prépare les cibles et envoie/met à jour/supprime les messages d’approbation natifs
• interactions - hooks facultatifs de liaison/déliaison/effacement d’action pour les boutons ou réactions natifs
• observe - hooks facultatifs de diagnostic de livraison
• Si le canal a besoin d’objets détenus par l’exécution, comme un client, un jeton, une application Bolt ou un récepteur webhook, enregistrez-les via openclaw/plugin-sdk/channel-runtime-context. Le registre générique de contexte d’exécution permet au noyau d’amorcer des gestionnaires pilotés par les capacités depuis l’état de démarrage du canal sans ajouter de colle d’encapsulation spécifique aux approbations.
• Utilisez les éléments de plus bas niveau createChannelApprovalHandler ou createChannelNativeApprovalRuntime uniquement lorsque le seam piloté par les capacités n’est pas encore assez expressif.
• Les canaux d’approbation native doivent router à la fois accountId et approvalKind via ces helpers. accountId garde la politique d’approbation multi-compte limitée au bon compte bot, et approvalKind garde le comportement des approbations exec et Plugin disponible pour le canal sans branches codées en dur dans le noyau.
• Le noyau prend désormais aussi en charge les avis de reroutage d’approbation. Les plugins de canal ne doivent pas envoyer leurs propres messages de suivi « l’approbation a été envoyée en DM / dans un autre canal » depuis createChannelNativeApprovalRuntime ; exposez plutôt un routage précis origine + DM d’approbateur via les helpers de capacité d’approbation partagés et laissez le noyau agréger les livraisons réelles avant de publier un éventuel avis dans la conversation initiatrice.
• Préservez de bout en bout le type d’identifiant d’approbation livré. Les clients natifs ne doivent pas deviner ni réécrire le routage d’approbation exec contre Plugin à partir d’un état local au canal.
• Différents types d’approbation peuvent intentionnellement exposer différentes surfaces natives. Exemples groupés actuels :
  • Slack garde le routage d’approbation native disponible pour les identifiants exec et Plugin.
  • Matrix garde le même routage natif DM/canal et la même UX de réaction pour les approbations exec et Plugin, tout en permettant que l’authentification diffère selon le type d’approbation.
• createApproverRestrictedNativeApprovalAdapter existe toujours comme wrapper de compatibilité, mais le nouveau code doit préférer le constructeur 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 pour l’exécution : adaptateurs de patch de configuration sûrs à l’import (createPatchedAccountSetupAdapter, createEnvPatchedAccountSetupAdapter, createSetupInputPresenceValidator), sortie de note de recherche, promptResolvedAllowFrom, splitSetupEntries et les constructeurs de proxy de configuration délégués
• openclaw/plugin-sdk/setup-runtime inclut le seam d’adaptateur sensible à l’environnement pour createEnvPatchedAccountSetupAdapter
• openclaw/plugin-sdk/channel-setup couvre les constructeurs de configuration d’installation facultative ainsi que quelques primitives sûres pour la configuration : createOptionalChannelSetupSurface, createOptionalChannelSetupAdapter,

• utilisez le seam plus large openclaw/plugin-sdk/setup uniquement lorsque vous avez aussi besoin des helpers partagés de configuration/config plus lourds, 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-compte et le secours vers le compte par défaut
• openclaw/plugin-sdk/inbound-envelope et openclaw/plugin-sdk/inbound-reply-dispatch pour la route/enveloppe entrante et le câblage d’enregistrement puis distribution
• openclaw/plugin-sdk/messaging-targets pour l’analyse et 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 et la planification des payloads
• buildThreadAwareOutboundSessionRoute(...) depuis openclaw/plugin-sdk/channel-core lorsqu’une route sortante doit préserver un replyToId/threadId explicite ou récupérer la session :thread: courante après que la clé de session de base corresponde encore. Les plugins fournisseur peuvent remplacer la précédence, le comportement de suffixe et la normalisation de l’identifiant de fil lorsque leur plateforme a des sémantiques natives de livraison dans les fils.
• openclaw/plugin-sdk/thread-bindings-runtime pour le cycle de vie des liaisons de fil et l’enregistrement des adaptateurs
• openclaw/plugin-sdk/agent-media-payload uniquement lorsqu’une disposition héritée de 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 commande stable en secours

​

Politique de mention entrante

• collecte de preuves détenue par le plugin
• évaluation de politique partagée

• détection de réponse au bot
• détection de bot cité
• vérifications de participation au fil
• exclusions de 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’ignorance

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

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"; // your platform API client

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",
        };
      },
    },
  }),

  // DM security: who can message the bot
  security: {
    dm: {
      channelKey: "acme-chat",
      resolvePolicy: (account) => account.dmPolicy,
      resolveAllowFrom: (account) => account.allowFrom,
      defaultPolicy: "allowlist",
    },
  },

  // Pairing: approval flow for new DM contacts
  pairing: {
    text: {
      idLabel: "Acme Chat username",
      message: "Send this code to verify your identity:",
      notify: async ({ target, code }) => {
        await acmeChatApi.sendDm(target, `Pairing code: ${code}`);
      },
    },
  },

  // Threading: how replies are delivered
  threading: { topLevelReplyToMode: "reply" },

  // Outbound: send messages to the platform
  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: "Acme Chat channel plugin",
  plugin: acmeChatPlugin,
  registerCliMetadata(api) {
    api.registerCli(
      ({ program }) => {
        program
          .command("acme-chat")
          .description("Acme Chat management");
      },
      {
        descriptors: [
          {
            name: "acme-chat",
            description: "Acme Chat management",
            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", // plugin-managed auth (verify signatures yourself)
    handler: async (req, res) => {
      const event = parseWebhookPayload(req);

      // Your inbound handler dispatches the message to OpenClaw.
      // The exact wiring depends on your platform SDK -
      // see a real example in the bundled Microsoft Teams or Google Chat plugin package.
      await handleAcmeChatInbound(api, event);

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

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

describe("acme-chat plugin", () => {
  it("resolves account from config", () => {
    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("inspects account without materializing 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("reports missing config", () => {
    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              # openclaw.channel metadata
├── openclaw.plugin.json      # Manifest with config schema
├── index.ts                  # defineChannelPluginEntry
├── setup-entry.ts            # defineSetupPluginEntry
├── api.ts                    # Public exports (optional)
├── runtime-api.ts            # Internal runtime exports (optional)
└── src/
    ├── channel.ts            # ChannelPlugin via createChatChannelPlugin
    ├── channel.test.ts       # Tests
    ├── client.ts             # Platform API client
    └── runtime.ts            # Runtime store (if needed)

​

Sujets avancés

​

Étapes suivantes

• Plugins de fournisseur - si votre Plugin fournit également des modèles
• Vue d’ensemble du SDK - référence complète des importations de sous-chemins
• Tests du SDK - utilitaires de test et tests de contrat
• Manifeste de Plugin - schéma complet du manifeste

​

Associé

• Configuration du SDK de Plugin
• Création de Plugins
• Plugins de harnais d’agent