Kanaalplugins bouwen

​

Hoe kanaalplugins werken

• Configuratie - accountresolutie en installatiewizard
• Beveiliging - DM-beleid en allowlists
• Koppeling - DM-goedkeuringsflow
• Sessiesyntaxis - hoe providerspecifieke gespreks-id’s worden gekoppeld aan basischats, thread-id’s en ouder-fallbacks
• Uitgaand - tekst, media en polls naar het platform verzenden
• Threading - hoe antwoorden worden gethread
• Heartbeat-typen - optionele typ-/bezig-signalen voor Heartbeat-afleverdoelen

​

Goedkeuringen en kanaalmogelijkheden

• Core is eigenaar van /approve in dezelfde chat, gedeelde payloads voor goedkeuringsknoppen en generieke fallbacklevering.
• Geef de voorkeur aan één approvalCapability-object op de kanaalplugin wanneer het kanaal goedkeuringsspecifiek gedrag nodig heeft.
• ChannelPlugin.approvals is verwijderd. Zet feiten over goedkeuringslevering/native/render/auth op approvalCapability.
• plugin.auth is alleen voor inloggen/uitloggen; core leest geen goedkeurings-auth-hooks meer uit dat object.
• approvalCapability.authorizeActorAction en approvalCapability.getActionAvailabilityState zijn de canonieke approval-auth-seam.
• Gebruik approvalCapability.getActionAvailabilityState voor beschikbaarheid van goedkeuringsauth in dezelfde chat. Houd geconfigureerde goedkeurders beschikbaar voor /approve, zelfs wanneer native levering is uitgeschakeld; gebruik in plaats daarvan de native initiërende-surface-status voor leverings-/setupbegeleiding.
• Als je kanaal native exec-goedkeuringen aanbiedt, gebruik dan approvalCapability.getExecInitiatingSurfaceState voor de initiërende-surface/native-client-status wanneer die verschilt van goedkeuringsauth in dezelfde chat. Core gebruikt die exec-specifieke hook om enabled van disabled te onderscheiden, te bepalen of het initiërende kanaal native exec-goedkeuringen ondersteunt en het kanaal op te nemen in fallbackbegeleiding voor native clients. createApproverRestrictedNativeApprovalCapability(...) vult dit in voor het gangbare geval.
• Gebruik outbound.shouldSuppressLocalPayloadPrompt of outbound.beforeDeliverPayload voor kanaalspecifiek payload-lifecycle-gedrag, zoals het verbergen van dubbele lokale goedkeuringsprompts of het verzenden van typindicatoren vóór levering.
• Gebruik approvalCapability.delivery alleen voor native goedkeuringsrouting of fallbackonderdrukking.
• Gebruik approvalCapability.nativeRuntime voor native goedkeuringsfeiten die eigendom zijn van het kanaal. Houd dit lazy op hot kanaal-entrypoints met createLazyChannelApprovalNativeRuntimeAdapter(...), dat je runtime-module op aanvraag kan importeren terwijl core nog steeds de goedkeuringslifecycle kan samenstellen.
• Gebruik approvalCapability.render alleen wanneer een kanaal echt aangepaste goedkeuringspayloads nodig heeft in plaats van de gedeelde renderer.
• Gebruik approvalCapability.describeExecApprovalSetup wanneer het kanaal wil dat het antwoord op het uitgeschakelde pad uitlegt welke exacte config-knoppen nodig zijn om native exec-goedkeuringen in te schakelen. De hook ontvangt { channel, channelLabel, accountId }; kanalen met benoemde accounts moeten account-scoped paden renderen, zoals channels.<channel>.accounts.<id>.execApprovals.*, in plaats van top-level defaults.
• Gebruik approvalCapability.describePluginApprovalSetup wanneer begeleiding bij falende Plugin-goedkeuring veilig kan worden getoond voor no-route- en timeoutfouten bij Plugin-goedkeuring. createApproverRestrictedNativeApprovalCapability(...) leidt dit niet af uit describeExecApprovalSetup; geef dezelfde helper alleen expliciet door wanneer Plugin- en exec-goedkeuringen echt dezelfde native setup gebruiken.
• Als een kanaal stabiele, eigenaarachtige DM-identiteiten kan afleiden uit bestaande config, gebruik dan createResolvedApproverActionAuthAdapter uit openclaw/plugin-sdk/approval-runtime om /approve in dezelfde chat te beperken zonder goedkeuringsspecifieke core-logica toe te voegen.
• Als aangepaste goedkeuringsauth bewust alleen fallback in dezelfde chat toestaat, retourneer dan markImplicitSameChatApprovalAuthorization({ authorized: true }) uit openclaw/plugin-sdk/approval-auth-runtime; anders behandelt core het resultaat als expliciete goedkeurderautorisatie.
• Als een kanaaleigen native callback goedkeuringen direct oplost, gebruik dan isImplicitSameChatApprovalAuthorization(...) vóór het oplossen, zodat impliciete fallback nog steeds via de normale actorautorisatie van het kanaal loopt.
• Als een kanaal native goedkeuringslevering nodig heeft, houd kanaalcode dan gericht op targetnormalisatie plus transport-/presentatiefeiten. Gebruik createChannelExecApprovalProfile, createChannelNativeOriginTargetResolver, createChannelApproverDmTargetResolver en createApproverRestrictedNativeApprovalCapability uit openclaw/plugin-sdk/approval-runtime. Zet de kanaalspecifieke feiten achter approvalCapability.nativeRuntime, idealiter via createChannelApprovalNativeRuntimeAdapter(...) of createLazyChannelApprovalNativeRuntimeAdapter(...), zodat core de handler kan samenstellen en requestfiltering, routing, dedupe, verval, Gateway-abonnement en routed-elsewhere-meldingen kan beheren. nativeRuntime is opgesplitst in een paar kleinere seams:
• Gebruik createNativeApprovalChannelRouteGates uit openclaw/plugin-sdk/approval-native-runtime wanneer een kanaal zowel native levering vanaf de sessie-oorsprong als expliciete forwardingtargets voor goedkeuringen ondersteunt. De helper centraliseert selectie van goedkeuringsconfig, mode-afhandeling, agent-/sessiefilters, accountbinding, sessietargetmatching en targetlistmatching, terwijl callers nog steeds eigenaar zijn van het kanaal-id, de standaard forwardingmodus, accountlookup, transport-enabled-check, targetnormalisatie en resolutie van turn-source-targets. Gebruik dit niet om core-owned kanaalbeleidsdefaults te maken; geef de gedocumenteerde standaardmodus van het kanaal expliciet door.
• createChannelNativeOriginTargetResolver gebruikt standaard de gedeelde channel-route-matcher voor { to, accountId, threadId }-targets. Geef targetsMatch alleen door wanneer een kanaal provider-specifieke equivalentieregels heeft, zoals Slack-timestamp-prefixmatching.
• Geef normalizeTargetForMatch door aan createChannelNativeOriginTargetResolver wanneer het kanaal provider-id’s moet canoniseren voordat de standaard route-matcher of een aangepaste targetsMatch-callback draait, terwijl het oorspronkelijke target voor levering behouden blijft. Gebruik normalizeTarget alleen wanneer het opgeloste leveringstarget zelf gecanoniseerd moet worden.
• availability - of het account is geconfigureerd en of een request moet worden afgehandeld
• presentation - map het gedeelde approval-viewmodel naar pending/resolved/expired native payloads of definitieve acties
• transport - bereid targets voor en verzend/update/verwijder native goedkeuringsberichten
• interactions - optionele bind-/unbind-/clear-action-hooks voor native knoppen of reacties, plus een optionele cancelDelivered-hook. Implementeer cancelDelivered wanneer deliverPending in-process of persistente state registreert (zoals een reaction-target-store), zodat die state kan worden vrijgegeven als een handlerstop de levering annuleert voordat bindPending draait of wanneer bindPending geen handle retourneert
• observe - optionele hooks voor leveringsdiagnostiek
• Als het kanaal runtime-owned objecten nodig heeft, zoals een client, token, Bolt-app of webhook-ontvanger, registreer die dan via openclaw/plugin-sdk/channel-runtime-context. Het generieke runtime-contextregister laat core capability-driven handlers bootstrappen vanuit kanaal-startup-state zonder goedkeuringsspecifieke wrapper-glue toe te voegen.
• Grijp alleen naar de lower-level createChannelApprovalHandler of createChannelNativeApprovalRuntime wanneer de capability-driven seam nog niet expressief genoeg is.
• Native goedkeuringskanalen moeten zowel accountId als approvalKind via die helpers routeren. accountId houdt multi-account-goedkeuringsbeleid scoped naar het juiste botaccount, en approvalKind houdt exec- versus Plugin-goedkeuringsgedrag beschikbaar voor het kanaal zonder hardcoded branches in core.
• Core is nu ook eigenaar van goedkeurings-reroute-meldingen. Kanaalplugins moeten geen eigen follow-upberichten “goedkeuring ging naar DM’s / een ander kanaal” verzenden vanuit createChannelNativeApprovalRuntime; expose in plaats daarvan accurate origin- en approver-DM-routing via de gedeelde approval-capability-helpers en laat core daadwerkelijke leveringen aggregeren voordat er een melding terug naar de initiërende chat wordt geplaatst.
• Behoud de geleverde goedkeurings-id-soort end-to-end. Native clients mogen exec- versus Plugin-goedkeuringsrouting niet raden of herschrijven vanuit kanaallokale state.
• Verschillende goedkeuringssoorten kunnen bewust verschillende native surfaces aanbieden. Huidige gebundelde voorbeelden:
  • Slack houdt native goedkeuringsrouting beschikbaar voor zowel exec- als Plugin-id’s.
  • Matrix behoudt dezelfde native DM-/kanaalrouting en reaction-UX voor exec- en Plugin-goedkeuringen, terwijl auth nog steeds per goedkeuringssoort kan verschillen.
• createApproverRestrictedNativeApprovalAdapter bestaat nog steeds als compatibiliteitswrapper, maar nieuwe code moet de capability-builder verkiezen en approvalCapability op de plugin exposen.

• 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 dekt de runtime-safe setuphelpers: createSetupTranslator, import-safe setup-patchadapters (createPatchedAccountSetupAdapter, createEnvPatchedAccountSetupAdapter, createSetupInputPresenceValidator), lookup-note-output, promptResolvedAllowFrom, splitSetupEntries en de gedelegeerde setup-proxy-builders
• openclaw/plugin-sdk/setup-runtime bevat de env-aware adapter-seam voor createEnvPatchedAccountSetupAdapter
• openclaw/plugin-sdk/channel-setup dekt de optional-install setup- builders plus een paar setup-safe primitives: createOptionalChannelSetupSurface, createOptionalChannelSetupAdapter,

• gebruik de bredere openclaw/plugin-sdk/setup-seam alleen wanneer je ook de zwaardere gedeelde setup-/confighelpers nodig hebt, zoals moveSingleAccountChannelSectionToDefaultAccount(...)

• openclaw/plugin-sdk/account-core, openclaw/plugin-sdk/account-id, openclaw/plugin-sdk/account-resolution en openclaw/plugin-sdk/account-helpers voor configuratie met meerdere accounts en fallback voor standaardaccounts
• openclaw/plugin-sdk/inbound-envelope en openclaw/plugin-sdk/channel-inbound voor inkomende route/envelope en record-and-dispatch-bedrading
• openclaw/plugin-sdk/channel-targets voor helpers voor doelparsing
• openclaw/plugin-sdk/outbound-media voor het laden van media en openclaw/plugin-sdk/channel-outbound voor uitgaande identiteit/send-delegates en payloadplanning
• buildThreadAwareOutboundSessionRoute(...) uit openclaw/plugin-sdk/channel-core wanneer een uitgaande route een expliciete replyToId/threadId moet behouden of de huidige :thread:-sessie moet herstellen nadat de basissessiesleutel nog steeds overeenkomt. Provider-Plugins kunnen prioriteit, suffixgedrag en normalisatie van thread-id’s overschrijven wanneer hun platform native semantiek voor threadaflevering heeft.
• openclaw/plugin-sdk/thread-bindings-runtime voor de levenscyclus van threadbindings en adapterregistratie
• openclaw/plugin-sdk/agent-media-payload alleen wanneer een legacy agent/media payload-veldindeling nog steeds vereist is
• openclaw/plugin-sdk/telegram-command-config voor Telegram-normalisatie van aangepaste opdrachten, validatie van duplicaten/conflicten en een fallback-stabiel contract voor opdrachtconfiguratie

​

Beleid voor inkomende vermeldingen

• door de Plugin beheerde bewijsverzameling
• gedeelde beleidsevaluatie

• detectie van antwoord-aan-bot
• detectie van geciteerde bot
• controles op threaddeelname
• uitsluitingen voor service-/systeemberichten
• platform-native caches die nodig zijn om botdeelname te bewijzen

• requireMention
• expliciet vermeldingsresultaat
• allowlist voor impliciete vermeldingen
• opdrachtbypass
• definitieve overslabeslissing

1. Bereken lokale vermeldingsfeiten.
2. Geef die feiten door aan resolveInboundMentionDecision({ facts, policy }).
3. Gebruik decision.effectiveWasMentioned, decision.shouldBypassMention en decision.shouldSkip in je inkomende gate.

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

​

Doorloop

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

{
  "id": "acme-chat",
  "kind": "channel",
  "channels": ["acme-chat"],
  "name": "Acme Chat",
  "description": "Acme Chat channel plugin",
  "configSchema": {
    "type": "object",
    "additionalProperties": false,
    "properties": {}
  },
  "channelConfigs": {
    "acme-chat": {
      "schema": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "token": { "type": "string" },
          "allowFrom": {
            "type": "array",
            "items": { "type": "string" }
          }
        }
      },
      "uiHints": {
        "token": {
          "label": "Bot token",
          "sensitive": true
        }
      }
    }
  }
}

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/

​

Bestandsstructuur

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

​

Geavanceerde onderwerpen

​

Volgende stappen

• Provider-Plugins - als je Plugin ook modellen levert
• SDK-overzicht - volledige importreferentie voor subpaden
• SDK-testen - testhulpprogramma’s en contracttests
• Plugin-manifest - volledig manifestschema

​

Gerelateerd

• Plugin SDK-setup
• Plugins bouwen
• Agent-harness-Plugins