Creazione di Plugin di canale

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.

​

Come funzionano i Plugin di canale

• Configurazione - risoluzione dell’account e procedura guidata di configurazione
• Sicurezza - criteri per i DM e allowlist
• Abbinamento - flusso di approvazione tramite DM
• Grammatica della sessione - come gli id conversazione specifici del provider vengono mappati su chat base, id thread e fallback padre
• In uscita - invio di testo, media e sondaggi alla piattaforma
• Threading - come vengono organizzate le risposte in thread
• Digitazione Heartbeat - segnali facoltativi di digitazione/occupato per le destinazioni di consegna Heartbeat

​

Approvazioni e capacità del canale

• Il core gestisce /approve nella stessa chat, i payload condivisi dei pulsanti di approvazione e la consegna di fallback generica.
• Preferisci un singolo oggetto approvalCapability sul Plugin del canale quando il canale richiede un comportamento specifico per le approvazioni.
• ChannelPlugin.approvals è stato rimosso. Metti i dati di consegna/native/render/auth dell’approvazione su approvalCapability.
• plugin.auth è solo login/logout; il core non legge più gli hook di autenticazione delle approvazioni da quell’oggetto.
• approvalCapability.authorizeActorAction e approvalCapability.getActionAvailabilityState sono il seam canonico per l’autenticazione delle approvazioni.
• Usa approvalCapability.getActionAvailabilityState per la disponibilità dell’autenticazione delle approvazioni nella stessa chat.
• Se il tuo canale espone approvazioni exec native, usa approvalCapability.getExecInitiatingSurfaceState per lo stato della superficie di avvio/client nativo quando differisce dall’autenticazione delle approvazioni nella stessa chat. Il core usa quell’hook specifico per exec per distinguere enabled da disabled, decidere se il canale di avvio supporta le approvazioni exec native e includere il canale nelle indicazioni di fallback del client nativo. createApproverRestrictedNativeApprovalCapability(...) lo compila per il caso comune.
• Usa outbound.shouldSuppressLocalPayloadPrompt o outbound.beforeDeliverPayload per comportamenti del ciclo di vita dei payload specifici del canale, come nascondere prompt locali duplicati di approvazione o inviare indicatori di digitazione prima della consegna.
• Usa approvalCapability.delivery solo per il routing delle approvazioni native o la soppressione del fallback.
• Usa approvalCapability.nativeRuntime per i dati di approvazione nativa gestiti dal canale. Mantienilo lazy sugli entrypoint caldi del canale con createLazyChannelApprovalNativeRuntimeAdapter(...), che può importare il tuo modulo runtime on demand pur consentendo al core di assemblare il ciclo di vita dell’approvazione.
• Usa approvalCapability.render solo quando un canale ha davvero bisogno di payload di approvazione personalizzati invece del renderer condiviso.
• Usa approvalCapability.describeExecApprovalSetup quando il canale vuole che la risposta del percorso disabilitato spieghi le esatte manopole di configurazione necessarie per abilitare le approvazioni exec native. L’hook riceve { channel, channelLabel, accountId }; i canali con account nominati dovrebbero renderizzare percorsi con ambito account come channels.<channel>.accounts.<id>.execApprovals.* invece dei default di livello superiore.
• Se un canale può inferire identità DM stabili assimilabili al proprietario dalla configurazione esistente, usa createResolvedApproverActionAuthAdapter da openclaw/plugin-sdk/approval-runtime per limitare /approve nella stessa chat senza aggiungere logica core specifica per le approvazioni.
• Se un canale necessita della consegna di approvazioni native, mantieni il codice del canale focalizzato sulla normalizzazione del target e sui dati di trasporto/presentazione. Usa createChannelExecApprovalProfile, createChannelNativeOriginTargetResolver, createChannelApproverDmTargetResolver e createApproverRestrictedNativeApprovalCapability da openclaw/plugin-sdk/approval-runtime. Metti i dati specifici del canale dietro approvalCapability.nativeRuntime, idealmente tramite createChannelApprovalNativeRuntimeAdapter(...) o createLazyChannelApprovalNativeRuntimeAdapter(...), così il core può assemblare l’handler e gestire filtro delle richieste, routing, deduplicazione, scadenza, sottoscrizione Gateway e notifiche di instradamento altrove. nativeRuntime è suddiviso in alcuni seam più piccoli:
• createChannelNativeOriginTargetResolver usa per default il matcher condiviso delle route di canale per i target { to, accountId, threadId }. Passa targetsMatch solo quando un canale ha regole di equivalenza specifiche del provider, come il matching del prefisso timestamp di Slack.
• Passa normalizeTargetForMatch a createChannelNativeOriginTargetResolver quando il canale deve canonicalizzare gli id del provider prima che venga eseguito il matcher di route predefinito o una callback targetsMatch personalizzata, preservando al tempo stesso il target originale per la consegna. Usa normalizeTarget solo quando il target di consegna risolto stesso deve essere canonicalizzato.
• availability - se l’account è configurato e se una richiesta deve essere gestita
• presentation - mappa il modello di vista condiviso dell’approvazione in payload nativi pending/resolved/expired o azioni finali
• transport - prepara i target e invia/aggiorna/elimina i messaggi di approvazione nativi
• interactions - hook opzionali bind/unbind/clear-action per pulsanti o reazioni native
• observe - hook opzionali di diagnostica della consegna
• Se il canale necessita di oggetti gestiti dal runtime come un client, token, app Bolt o ricevitore Webhook, registrali tramite openclaw/plugin-sdk/channel-runtime-context. Il registro generico del contesto runtime consente al core di avviare handler guidati dalle capability dallo stato di startup del canale senza aggiungere colla wrapper specifica per le approvazioni.
• Ricorri ai livelli inferiori createChannelApprovalHandler o createChannelNativeApprovalRuntime solo quando il seam guidato dalle capability non è ancora abbastanza espressivo.
• I canali di approvazione nativa devono instradare sia accountId sia approvalKind tramite questi helper. accountId mantiene la policy di approvazione multi-account nell’ambito del giusto account bot, e approvalKind mantiene disponibile al canale il comportamento di approvazione exec vs Plugin senza branch hardcoded nel core.
• Ora il core gestisce anche le notifiche di reinstradamento delle approvazioni. I Plugin di canale non dovrebbero inviare propri messaggi di follow-up “approvazione inviata ai DM / a un altro canale” da createChannelNativeApprovalRuntime; invece, esponi routing accurato di origine + DM dell’approvatore tramite gli helper condivisi della capability di approvazione e lascia che il core aggreghi le consegne effettive prima di pubblicare qualsiasi notifica nella chat di avvio.
• Preserva end-to-end il tipo di id dell’approvazione consegnata. I client nativi non dovrebbero indovinare o riscrivere il routing delle approvazioni exec vs Plugin dallo stato locale del canale.
• Tipi di approvazione diversi possono intenzionalmente esporre superfici native diverse. Esempi bundled attuali:
  • Slack mantiene disponibile il routing delle approvazioni native sia per gli id exec sia per quelli Plugin.
  • Matrix mantiene lo stesso routing nativo DM/canale e la stessa UX a reazioni per le approvazioni exec e Plugin, pur consentendo ancora all’autenticazione di differire per tipo di approvazione.
• createApproverRestrictedNativeApprovalAdapter esiste ancora come wrapper di compatibilità, ma il nuovo codice dovrebbe preferire il builder di capability ed esporre approvalCapability sul 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 copre gli helper di setup sicuri per il runtime: adattatori di patch del setup sicuri da importare (createPatchedAccountSetupAdapter, createEnvPatchedAccountSetupAdapter, createSetupInputPresenceValidator), output di note di lookup, promptResolvedAllowFrom, splitSetupEntries e i builder delegati setup-proxy
• openclaw/plugin-sdk/setup-runtime include il seam dell’adattatore consapevole dell’env per createEnvPatchedAccountSetupAdapter
• openclaw/plugin-sdk/channel-setup copre i builder di setup con installazione opzionale più alcune primitive sicure per il setup: createOptionalChannelSetupSurface, createOptionalChannelSetupAdapter,

• usa il seam più ampio openclaw/plugin-sdk/setup solo quando ti servono anche gli helper condivisi più pesanti di setup/config, come moveSingleAccountChannelSectionToDefaultAccount(...)

• openclaw/plugin-sdk/account-core, openclaw/plugin-sdk/account-id, openclaw/plugin-sdk/account-resolution e openclaw/plugin-sdk/account-helpers per la configurazione multi-account e il fallback dell’account predefinito
• openclaw/plugin-sdk/inbound-envelope e openclaw/plugin-sdk/inbound-reply-dispatch per route/envelope inbound e cablaggio record-and-dispatch
• openclaw/plugin-sdk/messaging-targets per parsing/matching dei target
• openclaw/plugin-sdk/outbound-media e openclaw/plugin-sdk/outbound-runtime per caricamento media più delegati identità/send outbound e pianificazione dei payload
• buildThreadAwareOutboundSessionRoute(...) da openclaw/plugin-sdk/channel-core quando una route outbound dovrebbe preservare un replyToId/threadId esplicito o recuperare la sessione corrente :thread: dopo che la chiave di sessione di base corrisponde ancora. I Plugin provider possono sovrascrivere precedenza, comportamento del suffisso e normalizzazione dell’id del thread quando la loro piattaforma ha semantiche native di consegna nei thread.
• openclaw/plugin-sdk/thread-bindings-runtime per il ciclo di vita dei binding di thread e la registrazione degli adattatori
• openclaw/plugin-sdk/agent-media-payload solo quando è ancora richiesto un layout legacy dei campi del payload agente/media
• openclaw/plugin-sdk/telegram-command-config per la normalizzazione dei comandi personalizzati Telegram, la validazione di duplicati/conflitti e un contratto di configurazione dei comandi stabile in fallback

​

Policy delle menzioni inbound

• raccolta delle evidenze gestita dal Plugin
• valutazione della policy condivisa

• rilevamento di risposta al bot
• rilevamento di bot citato
• controlli di partecipazione al thread
• esclusioni di messaggi di servizio/sistema
• cache native della piattaforma necessarie per provare la partecipazione del bot

• requireMention
• risultato di menzione esplicita
• allowlist delle menzioni implicite
• bypass dei comandi
• decisione finale di salto

1. Calcola i fatti locali sulla menzione.
2. Passa quei fatti a resolveInboundMentionDecision({ facts, policy }).
3. Usa decision.effectiveWasMentioned, decision.shouldBypassMention e decision.shouldSkip nel tuo gate in ingresso.

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

​

Procedura guidata

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

​

Struttura dei file

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

​

Argomenti avanzati

​

Passaggi successivi

• Plugin provider - se il tuo plugin fornisce anche modelli
• Panoramica dell’SDK - riferimento completo agli import dei subpath
• Test dell’SDK - utilità di test e test di contratto
• Manifest del Plugin - schema completo del manifest

​

Correlati

• Configurazione del Plugin SDK
• Creazione di plugin
• Plugin harness agente