Building channel plugins

This guide builds a channel plugin that connects OpenClaw to a messaging platform: DM security, pairing, reply threading, and outbound messaging.

What your plugin owns

Channel plugins do not implement send/edit/react tools; core provides one shared message tool. Your plugin owns:

• Config - account resolution and setup wizard
• Security - DM policy and allowlists
• Pairing - DM approval flow
• Session grammar - how provider-specific conversation ids map to base chats, thread ids, and parent fallbacks
• Outbound - sending text, media, and polls to the platform
• Threading - how replies are threaded
• Heartbeat typing - optional typing/busy signals for heartbeat delivery targets
• Formatting contract - optional agentPrompt.inboundFormattingHints, resolved per delivering account. Despite its name, core gives it to every OpenClaw agent turn whose visible text reaches the channel: replies, heartbeats, cron announces, subagent announces, and cron runs without a reply route that can send with the message tool (for example delivery.mode: "none"). Such a run uses the message tool's default channel: its current channel, or the only configured channel. A message tool send to another channel does not get that channel's rules, and external ACP agents do not receive it. Keep all formatting rules in this one hook.
• Message guidance - agentPrompt.messageToolHints supplies account-scoped instructions. Set agentPrompt.customInlineButtonHint: true when the channel owns inline-button guidance; core then omits its generic callback example and capability-configuration hint. Return no button instructions when the account has buttons disabled. The flag defaults to false.
• Question input - declare agentPrompt.questionInputMode: "buttons" only when your channel supports native ask_user controls. Core resolves this from the inbound channel when preparing the conversation's tool capabilities; omission keeps ask_user out of the tool catalog so the agent asks in plain text.

Core owns the shared message tool, prompt wiring, the outer session-key shape, generic :thread: bookkeeping, and dispatch. For configured agent group threads, core also owns participant selection, follow-up rounds, and turn budgets. Keep those policies out of channel adapters.

Core also owns model-picker product actions. A channel that renders a ModelPickerAction declares its ModelPickerCapabilityProfile, then encodes the typed action in a transport-private authenticated callback envelope. Keep approval, command, URL, web-app, question, callback, and model-picker actions distinguishable until that encoding boundary; never infer picker intent from a raw callback string. Actor and source-message checks remain channel-owned.

Opted-in public child sessions

The ingress resolver accepts an optional host-invocation intent, childSessionPublication: { audience: "public", assertCurrent }. Supply it only after explicit operator opt-in and provider-native proof that the entire supplied context is public. Unknown audience metadata must deny publication. assertCurrent synchronously rechecks account policy and the live ingress owner; never derive this field from message text, stored permalinks, or model arguments. The ordinary decision-only resolver does not grant authority.

For mutable source policy, the intent may also supply prepare: async () => assertCurrent. The host invokes it once at run admission and retains the returned synchronous guard for child publication. The channel must reacquire current authorization and routing with bounded retries and return null if the prepared prompt's route, access tier, or public-context proof is no longer valid. This drops the turn without trying another model or publishing a generic model-failure reply. Throw operational failures instead; these stop model fallback but produce a retryable access-verification error. Preparation cannot renew an already admitted run; use-time checks and revocation remain mandatory.

An exact host resolver-to-context handoff binds the intent to one admitted run. Only its fresh immediate isolated visible children can receive public grants, in their creation commits before launch. Private/draft, incognito, existing, forked, retargeted, and descendant sessions do not qualify. The intent cannot be serialized for future turns or transport fallback. This does not grant creator/admin authority or change Team collaboration permissions. Consumers of onVisibleWorkSessions may use publicRead: true as the creation receipt; a normalized URL alone is not proof of anonymous access.

The host awaits onVisibleWorkSessions(sessions, creation) for fresh visible children before their first turn starts, so a channel can persist session-scoped origin context before prompt assembly. The optional second argument supplies creation.createdSessionKey even when there is no public Gateway origin or the Control UI is disabled; in that case sessions is empty. Existing one-argument consumers still receive only usable URL descriptors. The callback may receive the same child again when the parent turn settles; make writes idempotent by child session key. Only immediate children of that turn are reported. Return a Promise when initialization must finish before the child runs.

Walkthrough

{  "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",  "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",    // Account resolution/inspection belongs on `config`, not `setup`.    // `setup` covers onboarding writes (applyAccountConfig, validateInput).    config: {      listAccountIds: () => ["default"],      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",        };      },    },    setup: {      applyAccountConfig: ({ cfg, input }) => ({        ...cfg,        channels: {          ...cfg.channels,          "acme-chat": { ...(cfg.channels as any)?.["acme-chat"], ...input },        },      }),    },  }),   // 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: {      channel: "acme-chat",      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 { createSimpleChannelSecretContract } from "openclaw/plugin-sdk/channel-secret-basic-runtime"; const channelSecrets = createSimpleChannelSecretContract({  channelKey: "acme-chat",  label: "Acme Chat",  accountFields: ["token"],  channelFields: ["token"],  mode: "account-inheritance",}); export const { secretTargetRegistryEntries, collectRuntimeConfigAssignments } = channelSecrets;

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.config.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.config.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.config.inspectAccount!(cfg, undefined);    expect(result.configured).toBe(false);  });});

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

File structure

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

Delegated context reads

Bundled actions can prove equivalence between provider-native delivery aliases and the current conversation with actions.messageActionTargetAliases[action].matchesCurrentConversationAsync. The callback receives { args, accountId, toolContext } and returns Promise<boolean>. The host awaits it only after checking the current provider, account, and any additional requested targets. External registrations cannot use this callback to bypass exact-current matching. A successful async match does not replace live caller or registration authority; the host rechecks those before dispatch.

Async alias proof requires the selected bundled registration to be loaded. Liveness checks use its captured owner authority and the loaded registry; they never discover or load a bundled fallback after the registration is retired. Normal bundled runtime registration satisfies this requirement. The retained synchronous path keeps its existing compatibility behavior.

The async callback takes precedence over matchesCurrentConversation when both are present. A false result or rejected promise never falls back to the legacy callback. The synchronous callback is deprecated for storage-backed matching but remains supported for older plugins and hosts, with no removal version scheduled. Keep its return type strictly boolean: older hosts treat a returned promise as truthy rather than awaiting it. Hosts predating the async companion ignore the new field and use only the synchronous callback. An async-only alias therefore cannot prove equivalence on those hosts; exact normalized target matching still works.

Verified official installed plugins can delegate supported conversation, metadata, and attachment reads to provider-owned access checks. Channel-origin requests need server-owned current provider, account, and conversation context. An authenticated dashboard user turn can also use those provider-owned checks without native channel context, including Incognito sessions and fresh messages after reconnect. Ordinary transport loss does not cancel an already admitted turn. This permission belongs only to that turn; background work and scheduled jobs keep their separate authorization. Normal chat, session participation, and tool permissions, along with provider account, destination, action, and requester policies, remain in force.

Account-created scheduled reads use the live job's recorded creator account and origin. An external creator origin restricts reads to that provider; a missing or unknown origin cannot authorize a read. Omitting accountId selects the recorded creator account, including after the provider's default account changes. Provider destination and action policies remain in force. See Scheduled tool policy for reauthorization and execution rules.

An adapter lists actions that support the lifetime fence in actions.readAuthorityActions. Its actions.providerOwnedReadGates declaration separately identifies the actions whose admission the provider owns. The host also classifies the action as eligible; a later host addition does not opt existing adapters into it. Only host-verified official registrations qualify. Discord supports read, search, reactions, list-pins, thread-list, channel-info, permissions, member-info, role-info, emoji-list, channel-list, voice-status, and event-list. Feishu supports read, reactions, list-pins, member-info, channel-info, channel-list, and configured sticker-search. Matrix supports read, reactions, list-pins, emoji-list, member-info, and channel-info. Mattermost supports read. Slack supports read, reactions, list-pins, member-info, emoji-list, and download-file. Older external adapters and unverified plugins retain the exact-current-conversation restriction. These declarations apply only to the listed read actions.

Delegated Slack member info is limited to the current requester on the same account, and emoji discovery uses the trusted workspace. Neither metadata action requires a channel target.

Microsoft Teams supports read, search, reactions, list-pins, member-info, channel-info, and channel-list under the Teams access rules.

Discord's permissions action inspects the bot's permissions for an allowed channel. Guild-wide metadata reads require the requested guild to be allowed by the selected account's current configuration, with unrestricted or wildcard channel access. The narrow exception is an active thread-list naming a parent channelId: the parent must be allowed and its metadata must confirm the requested guild before the guild-wide fetch. The result includes only allowed threads under that parent and member records for those returned threads. An active list without a parent still requires guild-wide channel access; archived lists keep their channel-scoped path. Only direct operators receive the filtered-results relaxation for channel-list; delegated channel-list callers still require guild-wide channel access.

The transport contract is mandatory for opt-in adapters:

• Capture captureChannelReadAuthority() from openclaw/plugin-sdk/fetch-runtime when submitting each request, before handing it to a shared queue.
• Retain that exact callback through waits and retries; invoke it immediately before every provider request, including target lookup requests, after any asynchronous DNS or dispatcher preparation.
• An absent callback means this invocation has no additional read-authority fence. A thrown error stops the request; do not retry with a new callback.

Bundled transports also capture captureEffectAuthority() from openclaw/plugin-sdk/fetch-runtime before handing requests to shared queues. Use its run method to restore that captured scope in a queued continuation. After asynchronous preparation, call effect.initiate(() => provider.send(...)) and run the existing synchronous assertion inside that callback. The owner releases the interval when the provider call is issued, before its response. Every retry or separately submitted chunk calls initiate again to prepare a fresh use. A fully prepared synchronous batch, such as Twitch's SDK calls or IRC's raw lines, acquires one use before its first handoff and submits all parts inside that callback. Never acquire multiple held uses upfront: the owner's FIFO waits for the preceding use to release. Library work after the SDK handoff belongs to the already initiated operation. Preserve preparation refusals unchanged when nothing was sent. Once a part is accepted, later refusals, transport failures, and delivery-observer failures must preserve all accepted receipts in a partial-delivery error, including when the caller omits its progress callback. Wait for an initiated batch to settle before reporting its outcome. Apply provider-specific failure normalization only after entering the SDK or transport call.

The initiation boundary is the call into the provider SDK, CLI runner, or native transport. OpenClaw finishes its asynchronous preparation before that call and does not hold the interval while awaiting a provider response. Provider libraries can still queue, authenticate, encrypt, connect, or retry internally after the handoff; those windows are part of the initiated operation. Application retries and separately submitted chunks each acquire a new use.

Matrix's client-owned crypto maintenance uses its client lifecycle rather than retaining a completed message invocation. Its message fetches still acquire their own current use. Independent owners can restore an explicitly captured scope with withEffectAuthority; an absent scope does not provide message authority.

The host binds the callback to the selected registration and its active lifecycle. Local message tools and Gateway agent requests retain the originating run and turn authority. Opted-in bundled reads use the same lifetime fence while keeping their existing provider-owned admission rules. A bundled artifact or an omitted scoped registration cannot supply that authority; delegated execution requires the active registered instance. The host rejects stale action results and errors after either caller or plugin authority is revoked. A completed action also closes its captured callbacks. The fence prevents subsequent requests; it cannot undo a request already sent to the provider. No configuration switch or plugin-supplied trust field can mint this authority.

Slack attachment downloads retain the originating read authority through URL refresh, binary transfer, media-store publication, image processing, and final host completion. The existing media artifact is kept only when the read succeeds. If completion is rejected, cleanup removes only files created by that operation; preexisting files, replacements, and shared files are preserved. The source abort signal also reaches the binary transfer where the caller supplies one.

Scheduled channel administration

ChannelMessageActionAdapter exposes the optional writeAuthorityActions?: readonly ChannelMessageActionName[] declaration through openclaw/plugin-sdk/channel-contract. It identifies write actions whose transport preserves the host's live request authority. Advertising an action through describeMessageTool or declaring read support does not establish that contract.

The host separately selects eligible actions and requires an active bundled or loader-verified official registration. A bundled artifact fallback or a plugin's own trust claim cannot supply registration authority. Discord declares writeAuthorityActions: ["channel-edit", "delete", "edit", "pin", "unpin"]. Other action names do not gain scheduled access from this declaration.

Scheduled channel-edit, including its existing channel and thread edit variants, accepts trusted operator job authority or the account job's authenticated native requester. The declaration cannot promote an account-mode job to operator authority or replace authenticated requester identity and current sender permission checks.

For native account edits, the host supplies its validated requesterAccountId and requesterSenderId with senderIsOwner: false. There is no current inbound conversation to put in toolContext. The adapter uses these host-provided facts for its normal current requester-permission checks; model arguments and the presence of a handoff callback cannot supply a requester identity. The host keeps the saved native requester separate from an earlier complete-tool-surface read origin. Discovery can use both facts to present configured actions, but the native requester does not establish read access. Jobs without usable native facts receive reauthorization guidance before the provider is called.

Scheduled edit, delete, pin, and unpin support both trusted operator jobs and account jobs. An account job must use its recorded creator account and a known creator origin; external origins also bind it to the recorded provider. Its delivery destination does not supply authority. These actions also require the adapter's existing providerOwnedReadGates declaration and retain its target checks. Account jobs use delegated target policy; trusted jobs use operator target policy. The job's current execution policy and toolsAllow, account restrictions, enabled actions, and provider permissions still apply.

The host evaluates current tool policy when each new scheduled message invocation is admitted, including global, agent, profile, and selected model-provider policy. Configuration changes govern the next invocation; they do not retroactively change the configuration of an admitted operation. Revoking or narrowing the job itself, canceling its run, or ending caller or plugin authority still blocks later provider requests and retries within that operation.

The host admits channel-name resolution before directory requests and retains the selected registration through the write. Its preparation read scope closes before the write starts, so a read completion check cannot discard an accepted mutation result.

An opted-in adapter must honor the existing ChannelMessageActionContext.assertDirectAdapterHandoff callback:

• Retain the exact host-provided callback through asynchronous preparation, permission and target lookups, rate-limit queues, and retries.
• Invoke it synchronously after awaited preparation and immediately before every actual provider request, including lookup requests and each retry attempt.
• If it throws, stop that request. Do not suppress the rejection, replace the callback, or put the rejected operation into replayable recovery.
• Let a submitted request settle and preserve its outcome, including a confirmed mutation when authority expires while awaiting the response. Expired authority blocks later requests; it must not cause an accepted mutation to be replayed.

This optional field keeps older adapters source-compatible. An omitted or empty declaration leaves newly enabled scheduled actions denied. Existing bundled provider-owned interactive paths keep their admission rules. To support the new installed-plugin path, upgrade OpenClaw and the plugin, implement the request and retry checks above, declare only the covered actions, and load the updated registration. Existing direct-operator and interactive actions retain their admission rules. Upgrading the plugin does not grant additional authority to an existing job.

Advanced topics

Next steps

• Provider Plugins - if your plugin also provides models
• SDK Overview - full subpath import reference
• SDK Testing - test utilities and contract tests
• Plugin Manifest - full manifest schema

Where each section moved

Every section of the single-page version now lives on this page or on one of the seven child pages below. The anchors from the single-page version still resolve here.

Channel message adapter

Channel message adapter — The message adapter surface: live and finalizer capabilities, progress visibility, commentary delivery, and native TTS voice delivery.

• Message adapter
• Progress visibility acceptance
• Quiet progress presentation
• Quiet acknowledgement and coalesced progress
• Commentary delivery ownership
• TTS voice delivery

Durable channel ingress

Durable channel ingress — The ingress resolver, durable queue and replay dedupe, transport retention classes, at-least-once side effects, and the reload and restart contract.

• Inbound ingress (experimental)
• Durable ingress and replay dedupe
• Transport classes and retention
• At-least-once side effects
• Dynamic policy publication
• Account-scoped restart contract

Channel status and media

Channel status and media — Channel runtime status signals plus media limits, hosted media stores, inbound media facts, and native payload shaping.

• Runtime lifecycle status
• Typing indicators
• Media source params
• Native payload shaping

Channel sessions and bindings

Channel sessions and bindings — Session conversation grammar, conversation route ownership, and account-scoped conversation binding support.

• Session conversation grammar
• Conversation route ownership
• Account-scoped conversation binding support

Channel approvals

Channel approvals — Approval capabilities, approval auth, payload lifecycle and setup guidance, native approval delivery, and the narrower approval runtime subpaths.

• Approvals and channel capabilities
• Approval auth
• Payload lifecycle and setup guidance
• Native approval delivery
• Narrower approval runtime subpaths

Channel setup and config

Channel setup and config — Setup subpaths, account schemas and inheritance, and the other narrow channel subpaths for config, inbound, targets, and threading.

• Setup subpaths
• Account schemas and inheritance
• Other narrow channel subpaths

Channel mention policy

Channel mention policy — Plugin-owned mention evidence gathering plus the shared inbound mention policy evaluation.

• Inbound mention policy

Related

• Plugin SDK setup
• Building plugins
• Agent harness plugins