Kanaalplugins bouwen

Deze gids laat zien hoe je een kanaal-Plugin bouwt die OpenClaw verbindt met een berichtenplatform. Aan het einde heb je een werkend kanaal met DM-beveiliging, koppeling, antwoordthreading en uitgaande berichten.

Hoe kanaal-Plugins werken

Kanaal-Plugins hebben geen eigen tools voor verzenden/bewerken/reageren nodig. OpenClaw houdt één gedeelde message-tool in core. Je Plugin is eigenaar van:

• Configuratie - accountresolutie en installatiewizard
• Beveiliging - DM-beleid en toelatingslijsten
• Koppeling - DM-goedkeuringsflow
• Sessiesyntaxis - hoe provider-specifieke gespreks-id's worden gekoppeld aan basischats, thread-id's en bovenliggende fallbacks
• Uitgaand - tekst, media en polls naar het platform verzenden
• Threading - hoe antwoorden worden gethread
• Heartbeat-typen - optionele typ-/bezig-signalen voor Heartbeat-bezorgdoelen

Core is eigenaar van de gedeelde message-tool, promptbedrading, de buitenste sessiesleutelvorm, generieke :thread:-boekhouding en dispatch.

Nieuwe kanaal-Plugins moeten ook een message-adapter beschikbaar maken met defineChannelMessageAdapter uit openclaw/plugin-sdk/channel-message. De adapter verklaart welke duurzame final-send-capabilities het native transport daadwerkelijk ondersteunt en laat tekst-/mediaverzendingen wijzen naar dezelfde transportfuncties als de legacy outbound-adapter. Declareer een capability alleen wanneer een contracttest het native neveneffect en het geretourneerde ontvangstbewijs bewijst. Zie voor het volledige API-contract, voorbeelden, capability-matrix, ontvangstbewijsregels, live preview-finalisatie, receive-ack-beleid, tests en migratietabel Channel message API. Als de bestaande outbound-adapter al de juiste verzendmethoden en capability-metadata heeft, gebruik dan createChannelMessageAdapterFromOutbound(...) om de message-adapter af te leiden in plaats van handmatig nog een bridge te schrijven. Adapterverzendingen moeten MessageReceipt-waarden retourneren. Wanneer compatibiliteitscode nog legacy-id's nodig heeft, leid die dan af met listMessageReceiptPlatformIds(...) of resolveMessageReceiptPrimaryId(...) in plaats van parallelle messageIds-velden in nieuwe lifecycle-code bij te houden. Kanalen die previews ondersteunen, moeten ook message.live.capabilities declareren met de exacte live-lifecycle waarvan zij eigenaar zijn, zoals draftPreview, previewFinalization, progressUpdates, nativeStreaming of quietFinalization. Kanalen die een conceptpreview op dezelfde plek finaliseren, moeten ook message.live.finalizer.capabilities declareren, zoals finalEdit, normalFallback, discardPending, previewReceipt en retainOnAmbiguousFailure, en de runtimelogica routeren via defineFinalizableLivePreviewAdapter(...) plus deliverWithFinalizableLivePreviewAdapter(...). Houd die capabilities ondersteund door verifyChannelMessageLiveCapabilityAdapterProofs(...)- en verifyChannelMessageLiveFinalizerProofs(...)-tests, zodat native preview-, voortgangs-, bewerkings-, fallback-/retentie-, opschonings- en ontvangstbewijsgedrag niet stil kan afwijken. Inkomende receivers die platformbevestigingen uitstellen, moeten message.receive.defaultAckPolicy en supportedAckPolicies declareren in plaats van ack-timing te verbergen in monitor-lokale state. Dek elk gedeclareerd beleid af met verifyChannelMessageReceiveAckPolicyAdapterProofs(...).

Legacy helpers voor antwoorden/turns, zoals createChannelTurnReplyPipeline, dispatchInboundReplyWithBase en recordInboundSessionAndDispatchReply, blijven beschikbaar voor compatibiliteitsdispatchers. Gebruik die namen niet voor nieuwe kanaalcode; nieuwe Plugins moeten beginnen met de message-adapter, ontvangstbewijzen en receive/send-lifecyclehelpers op openclaw/plugin-sdk/channel-message.

Kanalen die inkomende autorisatie migreren, kunnen het experimentele openclaw/plugin-sdk/channel-ingress-runtime-subpad gebruiken vanuit runtime-receivepaden. Het subpad houdt platformlookup en neveneffecten in de Plugin, terwijl allowlist-state-resolutie, route-/sender-/command-/event-/activation- beslissingen, geredigeerde diagnostiek en turn-admission-mapping worden gedeeld. Houd Plugin-identiteitsnormalisatie in de descriptor die je aan de resolver doorgeeft; serialiseer geen ruwe matchwaarden uit de opgeloste state of beslissing. Zie Channel ingress API voor het API-ontwerp, de eigendomsgrens en testverwachtingen.

Als je kanaal typindicatoren buiten inkomende antwoorden ondersteunt, stel dan heartbeat.sendTyping(...) beschikbaar op de kanaal-Plugin. Core roept dit aan met het opgeloste Heartbeat-bezorgdoel voordat de Heartbeat-modelrun start en gebruikt de gedeelde typing-keepalive-/cleanup-lifecycle. Voeg heartbeat.clearTyping(...) toe wanneer het platform een expliciet stopsignaal nodig heeft.

Als je kanaal message-tool-parameters toevoegt die mediabronnen dragen, stel die parameternamen dan beschikbaar via describeMessageTool(...).mediaSourceParams. Core gebruikt die expliciete lijst voor sandboxpadnormalisatie en outbound media-access- beleid, zodat Plugins geen gedeelde-core special cases nodig hebben voor provider-specifieke avatar-, attachment- of cover-image-parameters. Geef bij voorkeur een action-keyed map terug zoals { "set-profile": ["avatarUrl", "avatarPath"] }, zodat niet-gerelateerde acties niet de media-argumenten van een andere actie erven. Een platte array werkt nog steeds voor parameters die bewust worden gedeeld door elke beschikbare actie.

Als je kanaal provider-specifieke vormgeving nodig heeft voor message(action="send"), gebruik dan bij voorkeur actions.prepareSendPayload(...). Zet native kaarten, blocks, embeds of andere duurzame data onder payload.channelData.<channel> en laat core de daadwerkelijke verzending uitvoeren via de outbound/message-adapter. Gebruik actions.handleAction(...) voor verzending alleen als compatibiliteitsfallback voor payloads die niet kunnen worden geserialiseerd en opnieuw geprobeerd.

Als je platform extra scope opslaat in gespreks-id's, houd die parsing dan in de Plugin met messaging.resolveSessionConversation(...). Dat is de canonieke hook voor het mappen van rawId naar het basisgespreks-id, optioneel thread- id, expliciete baseConversationId en eventuele parentConversationCandidates. Wanneer je parentConversationCandidates retourneert, houd ze dan geordend van de smalste parent naar het breedste/basisgesprek.

Gebruik openclaw/plugin-sdk/channel-route wanneer Plugin-code route-achtige velden moet normaliseren, een child-thread moet vergelijken met de parent-route, of een stabiele dedupe-sleutel moet bouwen uit { channel, to, accountId, threadId }. De helper normaliseert numerieke thread-id's op dezelfde manier als core, dus Plugins moeten dit verkiezen boven ad-hoc String(threadId)-vergelijkingen. Plugins met provider-specifieke doelsyntaxis kunnen hun parser injecteren in resolveChannelRouteTargetWithParser(...) en toch dezelfde route target- vorm en thread-fallbacksemantiek krijgen die core gebruikt.

Gebundelde Plugins die dezelfde parsing nodig hebben voordat de kanaalregistry opstart, kunnen ook een top-level session-key-api.ts-bestand beschikbaar maken met een overeenkomende resolveSessionConversation(...)-export. Core gebruikt dat bootstrap-veilige oppervlak alleen wanneer de runtime-Pluginregistry nog niet beschikbaar is.

messaging.resolveParentConversationCandidates(...) blijft beschikbaar als een legacy compatibiliteitsfallback wanneer een Plugin alleen parent-fallbacks nodig heeft bovenop het generieke/ruwe id. Als beide hooks bestaan, gebruikt core eerst resolveSessionConversation(...).parentConversationCandidates en valt alleen terug op resolveParentConversationCandidates(...) wanneer de canonieke hook ze weglaat.

Goedkeuringen en kanaal-capabilities

De meeste kanaal-Plugins hebben geen goedkeuringsspecifieke code nodig.

• Core is eigenaar van same-chat /approve, gedeelde approval-knoppayloads en generieke fallback-bezorging.
• Geef de voorkeur aan één approvalCapability-object op de channel-plugin wanneer het kanaal approval-specifiek gedrag nodig heeft.
• ChannelPlugin.approvals is verwijderd. Zet approval-bezorging/native/render/auth-feiten op approvalCapability.
• plugin.auth is alleen login/logout; core leest niet langer approval-auth-hooks uit dat object.
• approvalCapability.authorizeActorAction en approvalCapability.getActionAvailabilityState zijn de canonieke approval-auth-naad.
• Gebruik approvalCapability.getActionAvailabilityState voor beschikbaarheid van same-chat approval-auth.
• Als je kanaal native exec-approvals blootstelt, gebruik dan approvalCapability.getExecInitiatingSurfaceState voor de initiating-surface/native-client-status wanneer die verschilt van same-chat approval-auth. Core gebruikt die exec-specifieke hook om enabled van disabled te onderscheiden, te bepalen of het initiërende kanaal native exec-approvals ondersteunt, en het kanaal op te nemen in fallback-instructies 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 approval-prompts of het verzenden van typindicatoren vóór bezorging.
• Gebruik approvalCapability.delivery alleen voor native approval-routing of fallback-onderdrukking.
• Gebruik approvalCapability.nativeRuntime voor native approval-feiten die eigendom zijn van het kanaal. Houd dit lazy op hete kanaal-entrypoints met createLazyChannelApprovalNativeRuntimeAdapter(...), dat je runtime-module op aanvraag kan importeren terwijl core nog steeds de approval-lifecycle kan samenstellen.
• Gebruik approvalCapability.render alleen wanneer een kanaal echt aangepaste approval-payloads nodig heeft in plaats van de gedeelde renderer.
• Gebruik approvalCapability.describeExecApprovalSetup wanneer het kanaal wil dat het disabled-path-antwoord uitlegt welke exacte configuratieknoppen nodig zijn om native exec-approvals in te schakelen. De hook ontvangt { channel, channelLabel, accountId }; named-account-kanalen moeten account-gescopete paden renderen, zoals channels.<channel>.accounts.<id>.execApprovals.*, in plaats van defaults op topniveau.
• Als een kanaal stabiele owner-achtige DM-identiteiten uit bestaande config kan afleiden, gebruik dan createResolvedApproverActionAuthAdapter uit openclaw/plugin-sdk/approval-runtime om same-chat /approve te beperken zonder approval-specifieke core-logica toe te voegen.
• Als een kanaal native approval-bezorging nodig heeft, houd de kanaalcode dan gericht op target-normalisatie 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 request-filtering, routing, dedupe, expiry, Gateway-subscription en routed-elsewhere-meldingen kan beheren. nativeRuntime is opgesplitst in een paar kleinere naden:
• createChannelNativeOriginTargetResolver gebruikt standaard de gedeelde channel-route-matcher voor { to, accountId, threadId }-targets. Geef targetsMatch alleen mee wanneer een kanaal providerspecifieke equivalentieregels heeft, zoals Slack-timestamp-prefixmatching.
• Geef normalizeTargetForMatch door aan createChannelNativeOriginTargetResolver wanneer het kanaal provider-id's moet canonicaliseren voordat de standaard route-matcher of een aangepaste targetsMatch-callback draait, terwijl het originele target voor bezorging behouden blijft. Gebruik normalizeTarget alleen wanneer het opgeloste bezorgtarget zelf moet worden gecanonicaliseerd.
• 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 finale acties
• transport - bereid targets voor en verzend/update/verwijder native approval-berichten
• interactions - optionele bind/unbind/clear-action-hooks voor native knoppen of reacties
• observe - optionele hooks voor bezorgdiagnostiek
• Als het kanaal runtime-owned objecten nodig heeft, zoals een client, token, Bolt-app of webhook receiver, registreer ze dan via openclaw/plugin-sdk/channel-runtime-context. De generieke runtime-context-registry laat core capability-gedreven handlers bootstrappen vanuit de kanaal-startupstatus zonder approval-specifieke wrapperlijm toe te voegen.
• Grijp alleen naar de lagere-level createChannelApprovalHandler of createChannelNativeApprovalRuntime wanneer de capability-gedreven naad nog niet expressief genoeg is.
• Native approval-kanalen moeten zowel accountId als approvalKind via die helpers routeren. accountId houdt multi-account-approvalbeleid gescopet op het juiste botaccount, en approvalKind houdt exec- versus plugin-approvalgedrag beschikbaar voor het kanaal zonder hardcoded branches in core.
• Core is nu ook eigenaar van approval-reroute-meldingen. Channel-plugins moeten niet hun eigen vervolgberichten "approval went to DMs / another channel" verzenden vanuit createChannelNativeApprovalRuntime; stel in plaats daarvan accurate origin- en approver-DM-routing beschikbaar via de gedeelde approval-capability-helpers en laat core daadwerkelijke bezorgingen aggregeren voordat er een melding terug naar de initiërende chat wordt geplaatst.
• Behoud het soort van de bezorgde approval-id end-to-end. Native clients mogen exec- versus plugin-approval-routing niet raden of herschrijven vanuit kanaallokale status.
• Verschillende approval-soorten kunnen bewust verschillende native surfaces blootstellen. Huidige gebundelde voorbeelden:
  • Slack houdt native approval-routing beschikbaar voor zowel exec- als plugin-id's.
  • Matrix houdt dezelfde native DM-/kanaalrouting en reactie-UX voor exec- en plugin-approvals, terwijl auth nog steeds per approval-soort kan verschillen.
• createApproverRestrictedNativeApprovalAdapter bestaat nog steeds als compatibiliteitswrapper, maar nieuwe code moet de voorkeur geven aan de capability-builder en approvalCapability op de plugin blootstellen.

Voor hete kanaal-entrypoints geef je de voorkeur aan de smallere runtime-subpaden wanneer je slechts één deel van die familie nodig hebt:

• 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

Geef op dezelfde manier de voorkeur aan openclaw/plugin-sdk/setup-runtime, openclaw/plugin-sdk/setup-runtime, openclaw/plugin-sdk/reply-runtime, openclaw/plugin-sdk/reply-dispatch-runtime, openclaw/plugin-sdk/reply-reference en openclaw/plugin-sdk/reply-chunking wanneer je de bredere overkoepelende surface niet nodig hebt.

Specifiek voor setup:

• openclaw/plugin-sdk/setup-runtime dekt de runtime-veilige setup-helpers: import-veilige setup-patchadapters (createPatchedAccountSetupAdapter, createEnvPatchedAccountSetupAdapter, createSetupInputPresenceValidator), lookup-note-output, promptResolvedAllowFrom, splitSetupEntries en de gedelegeerde setup-proxy-builders
• openclaw/plugin-sdk/setup-runtime bevat de env-bewuste adapter-naad voor createEnvPatchedAccountSetupAdapter
• openclaw/plugin-sdk/channel-setup dekt de optional-install setup- builders plus een paar setup-veilige primitives: createOptionalChannelSetupSurface, createOptionalChannelSetupAdapter,

Als je kanaal env-gedreven setup of auth ondersteunt en generieke startup-/config- flows die env-namen moeten kennen voordat runtime laadt, declareer ze dan in het pluginmanifest met channelEnvVars. Houd runtime-envVars van het kanaal of lokale constanten alleen voor operatorgerichte tekst.

Als je kanaal in status, channels list, channels status of SecretRef-scans kan verschijnen voordat de pluginruntime start, voeg dan openclaw.setupEntry toe in package.json. Dat entrypoint moet veilig te importeren zijn in read-only command paths en moet de kanaalmetadata, setup-veilige config-adapter, status- adapter en kanaal-secret-target-metadata teruggeven die nodig zijn voor die samenvattingen. Start geen clients, listeners of transportruntimes vanuit de setup-entry.

Houd ook het importpad van de hoofd-channel-entry smal. Discovery kan de entry en de channel-plugin-module evalueren om capabilities te registreren zonder het kanaal te activeren. Bestanden zoals channel-plugin-api.ts moeten het channel- pluginobject exporteren zonder setup-wizards, transportclients, socket- listeners, subprocess launchers of service-startupmodules te importeren. Zet die runtime- onderdelen in modules die worden geladen vanuit registerFull(...), runtime-setters of lazy capability-adapters.

createOptionalChannelSetupWizard, DEFAULT_ACCOUNT_ID, createTopLevelChannelDmPolicy, setSetupChannelEnabled en splitSetupEntries

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

Als je kanaal alleen "installeer deze plugin eerst" wil tonen in setup- surfaces, geef dan de voorkeur aan createOptionalChannelSetupSurface(...). De gegenereerde adapter/wizard falen gesloten bij config-writes en finalization, en ze hergebruiken hetzelfde install-required-bericht in validatie, finalize en docs-link- tekst.

Voor andere hete kanaalpaden geef je de voorkeur aan de smalle helpers boven bredere legacy- surfaces:

• openclaw/plugin-sdk/account-core, openclaw/plugin-sdk/account-id, openclaw/plugin-sdk/account-resolution en openclaw/plugin-sdk/account-helpers voor multi-account-config en default-account-fallback
• openclaw/plugin-sdk/inbound-envelope en openclaw/plugin-sdk/inbound-reply-dispatch voor inbound route/envelope en record-and-dispatch-bedrading
• openclaw/plugin-sdk/messaging-targets voor target parsing/matching
• openclaw/plugin-sdk/outbound-media en openclaw/plugin-sdk/outbound-runtime voor medialading plus outbound identity/send-delegates en payloadplanning
• buildThreadAwareOutboundSessionRoute(...) uit openclaw/plugin-sdk/channel-core wanneer een outbound route een expliciete replyToId/threadId moet behouden of de huidige :thread:-sessie moet herstellen nadat de basissessiesleutel nog steeds matcht. Provider-plugins kunnen precedence, suffixgedrag en thread-id-normalisatie overschrijven wanneer hun platform native thread-bezorgsemantiek heeft.
• openclaw/plugin-sdk/thread-bindings-runtime voor thread-binding-lifecycle en adapterregistratie
• openclaw/plugin-sdk/agent-media-payload alleen wanneer een legacy agent/media- payloadveldindeling nog vereist is
• openclaw/plugin-sdk/telegram-command-config voor Telegram custom-command- normalisatie, validatie van duplicaten/conflicten en een fallback-stabiel command- configcontract

Auth-only-kanalen kunnen meestal stoppen bij het standaardpad: core handelt approvals af en de plugin stelt alleen outbound/auth-capabilities bloot. Native approval-kanalen zoals Matrix, Slack, Telegram en aangepaste chattransports moeten de gedeelde native helpers gebruiken in plaats van hun eigen approval-lifecycle te bouwen.

Inbound mention-beleid

Houd inbound mention-afhandeling opgesplitst in twee lagen:

• plugin-owned evidence gathering
• gedeelde beleidsevaluatie

Gebruik openclaw/plugin-sdk/channel-mention-gating voor mention-policy-beslissingen. Gebruik openclaw/plugin-sdk/channel-inbound alleen wanneer je de bredere inbound helper-barrel nodig hebt.

Goede plek voor plugin-lokale logica:

• reply-to-bot-detectie
• quoted-bot-detectie
• controles op thread-deelname
• uitsluitingen voor service-/systeemberichten
• platform-native caches die nodig zijn om botdeelname te bewijzen

Goede plek voor de gedeelde helper:

• requireMention
• expliciet vermeldingsresultaat
• impliciete vermeldings-allowlist
• commando-omzeiling
• uiteindelijke oversla-beslissing

Aanbevolen flow:

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.

   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;

api.runtime.channel.mentions stelt dezelfde gedeelde vermeldingshelpers beschikbaar voor gebundelde kanaalplugins die al afhankelijk zijn van runtime-injectie:

• buildMentionRegexes
• matchesMentionPatterns
• matchesMentionWithExplicit
• implicitMentionKindWhen
• resolveInboundMentionDecision

Als je alleen implicitMentionKindWhen en resolveInboundMentionDecision nodig hebt, importeer dan vanuit openclaw/plugin-sdk/channel-mention-gating om te voorkomen dat niet-gerelateerde inkomende runtimehelpers worden geladen.

De oudere resolveMentionGating*-helpers blijven alleen als compatibiliteitsexports beschikbaar op openclaw/plugin-sdk/channel-inbound. Nieuwe code moet resolveInboundMentionDecision({ facts, policy }) gebruiken.

Stapsgewijze uitleg

{"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&lt;ResolvedAccount&gt;({  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 met configuratieschema├── index.ts                  # defineChannelPluginEntry├── setup-entry.ts            # defineSetupPluginEntry├── api.ts                    # Publieke exports (optioneel)├── runtime-api.ts            # Interne runtime-exports (optioneel)└── src/    ├── channel.ts            # ChannelPlugin via createChatChannelPlugin    ├── channel.test.ts       # Tests    ├── client.ts             # Platform-API-client    └── runtime.ts            # Runtime-store (indien nodig)

Geavanceerde onderwerpen

Volgende stappen

• Provider-Plugins - als je plugin ook modellen levert
• SDK-overzicht - volledige referentie voor subpath-imports
• SDK-testen - testhulpmiddelen en contracttests
• Plugin-manifest - volledig manifestschema

Gerelateerd

• Plugin SDK-installatie
• Plugins bouwen
• Agent-harnessplugins