Building channel plugins

This guide walks through building a channel plugin that connects OpenClaw to a messaging platform. By the end you will have a working channel with DM security, pairing, reply threading, and outbound messaging.

How channel plugins work

Channel plugins do not need their own send/edit/react tools. OpenClaw keeps one shared

• 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

Core owns the shared message tool, prompt wiring, the outer session-key shape, generic

If your channel supports typing indicators outside inbound replies, expose

If your channel adds message-tool params that carry media sources, expose those param names through

If your platform stores extra scope inside conversation ids, keep that parsing in the plugin with

Use

Bundled plugins that need the same parsing before the channel registry boots can also expose a top-level

Approvals and channel capabilities

Most channel plugins do not need approval-specific code.

• Core owns same-chat
  text

  Copy

  /approve
  , shared approval button payloads, and generic fallback delivery.
• Prefer one
  text

  Copy

  approvalCapability
  object on the channel plugin when the channel needs approval-specific behavior.
• text

  Copy

  ChannelPlugin.approvals
  is removed. Put approval delivery/native/render/auth facts on
  text

  Copy

  approvalCapability
  .
• text

  Copy

  plugin.auth
  is login/logout only; core no longer reads approval auth hooks from that object.
• text

  Copy

  approvalCapability.authorizeActorAction
  and
  text

  Copy

  approvalCapability.getActionAvailabilityState
  are the canonical approval-auth seam.
• Use
  text

  Copy

  approvalCapability.getActionAvailabilityState
  for same-chat approval auth availability.
• If your channel exposes native exec approvals, use
  text

  Copy

  approvalCapability.getExecInitiatingSurfaceState
  for the initiating-surface/native-client state when it differs from same-chat approval auth. Core uses that exec-specific hook to distinguish
  text

  Copy

  enabled
  vs
  text

  Copy

  disabled
  , decide whether the initiating channel supports native exec approvals, and include the channel in native-client fallback guidance.
  text

  Copy

  createApproverRestrictedNativeApprovalCapability(...)
  fills this in for the common case.
• Use
  text

  Copy

  outbound.shouldSuppressLocalPayloadPrompt
  or
  text

  Copy

  outbound.beforeDeliverPayload
  for channel-specific payload lifecycle behavior such as hiding duplicate local approval prompts or sending typing indicators before delivery.
• Use
  text

  Copy

  approvalCapability.delivery
  only for native approval routing or fallback suppression.
• Use
  text

  Copy

  approvalCapability.nativeRuntime
  for channel-owned native approval facts. Keep it lazy on hot channel entrypoints with
  text

  Copy

  createLazyChannelApprovalNativeRuntimeAdapter(...)
  , which can import your runtime module on demand while still letting core assemble the approval lifecycle.
• Use
  text

  Copy

  approvalCapability.render
  only when a channel truly needs custom approval payloads instead of the shared renderer.
• Use
  text

  Copy

  approvalCapability.describeExecApprovalSetup
  when the channel wants the disabled-path reply to explain the exact config knobs needed to enable native exec approvals. The hook receives
  text

  Copy

  { channel, channelLabel, accountId }
  ; named-account channels should render account-scoped paths such as
  text

  Copy

  channels.<channel>.accounts.<id>.execApprovals.*
  instead of top-level defaults.
• If a channel can infer stable owner-like DM identities from existing config, use
  text

  Copy

  createResolvedApproverActionAuthAdapter
  from
  text

  Copy

  openclaw/plugin-sdk/approval-runtime
  to restrict same-chat
  text

  Copy

  /approve
  without adding approval-specific core logic.
• If a channel needs native approval delivery, keep channel code focused on target normalization plus transport/presentation facts. Use
  text

  Copy

  createChannelExecApprovalProfile
  ,
  text

  Copy

  createChannelNativeOriginTargetResolver
  ,
  text

  Copy

  createChannelApproverDmTargetResolver
  , and
  text

  Copy

  createApproverRestrictedNativeApprovalCapability
  from
  text

  Copy

  openclaw/plugin-sdk/approval-runtime
  . Put the channel-specific facts behind
  text

  Copy

  approvalCapability.nativeRuntime
  , ideally via
  text

  Copy

  createChannelApprovalNativeRuntimeAdapter(...)
  or
  text

  Copy

  createLazyChannelApprovalNativeRuntimeAdapter(...)
  , so core can assemble the handler and own request filtering, routing, dedupe, expiry, gateway subscription, and routed-elsewhere notices.
  text

  Copy

  nativeRuntime
  is split into a few smaller seams:
• text

  Copy

  createChannelNativeOriginTargetResolver
  uses the shared channel-route matcher by default for
  text

  Copy

  { to, accountId, threadId }
  targets. Pass
  text

  Copy

  targetsMatch
  only when a channel has provider-specific equivalence rules, such as Slack timestamp prefix matching.
• Pass
  text

  Copy

  normalizeTargetForMatch
  to
  text

  Copy

  createChannelNativeOriginTargetResolver
  when the channel needs to canonicalize provider ids before the default route matcher or a custom
  text

  Copy

  targetsMatch
  callback runs, while preserving the original target for delivery. Use
  text

  Copy

  normalizeTarget
  only when the resolved delivery target itself should be canonicalized.
• text

  Copy

  availability
  — whether the account is configured and whether a request should be handled
• text

  Copy

  presentation
  — map the shared approval view model into pending/resolved/expired native payloads or final actions
• text

  Copy

  transport
  — prepare targets plus send/update/delete native approval messages
• text

  Copy

  interactions
  — optional bind/unbind/clear-action hooks for native buttons or reactions
• text

  Copy

  observe
  — optional delivery diagnostics hooks
• If the channel needs runtime-owned objects such as a client, token, Bolt app, or webhook receiver, register them through
  text

  Copy

  openclaw/plugin-sdk/channel-runtime-context
  . The generic runtime-context registry lets core bootstrap capability-driven handlers from channel startup state without adding approval-specific wrapper glue.
• Reach for the lower-level
  text

  Copy

  createChannelApprovalHandler
  or
  text

  Copy

  createChannelNativeApprovalRuntime
  only when the capability-driven seam is not expressive enough yet.
• Native approval channels must route both
  text

  Copy

  accountId
  and
  text

  Copy

  approvalKind
  through those helpers.
  text

  Copy

  accountId
  keeps multi-account approval policy scoped to the right bot account, and
  text

  Copy

  approvalKind
  keeps exec vs plugin approval behavior available to the channel without hardcoded branches in core.
• Core now owns approval reroute notices too. Channel plugins should not send their own "approval went to DMs / another channel" follow-up messages from
  text

  Copy

  createChannelNativeApprovalRuntime
  ; instead, expose accurate origin + approver-DM routing through the shared approval capability helpers and let core aggregate actual deliveries before posting any notice back to the initiating chat.
• Preserve the delivered approval id kind end-to-end. Native clients should not guess or rewrite exec vs plugin approval routing from channel-local state.
• Different approval kinds can intentionally expose different native surfaces. Current bundled examples:
  • Slack keeps native approval routing available for both exec and plugin ids.
  • Matrix keeps the same native DM/channel routing and reaction UX for exec and plugin approvals, while still letting auth differ by approval kind.
• text

  Copy

  createApproverRestrictedNativeApprovalAdapter
  still exists as a compatibility wrapper, but new code should prefer the capability builder and expose
  text

  Copy

  approvalCapability
  on the plugin.

For hot channel entrypoints, prefer the narrower runtime subpaths when you only need one part of that family:

• text

  Copy

  openclaw/plugin-sdk/approval-auth-runtime
• text

  Copy

  openclaw/plugin-sdk/approval-client-runtime
• text

  Copy

  openclaw/plugin-sdk/approval-delivery-runtime
• text

  Copy

  openclaw/plugin-sdk/approval-gateway-runtime
• text

  Copy

  openclaw/plugin-sdk/approval-handler-adapter-runtime
• text

  Copy

  openclaw/plugin-sdk/approval-handler-runtime
• text

  Copy

  openclaw/plugin-sdk/approval-native-runtime
• text

  Copy

  openclaw/plugin-sdk/approval-reply-runtime
• text

  Copy

  openclaw/plugin-sdk/channel-runtime-context

Likewise, prefer

For setup specifically:

• text

  Copy

  openclaw/plugin-sdk/setup-runtime
  covers the runtime-safe setup helpers: import-safe setup patch adapters (
  text

  Copy

  createPatchedAccountSetupAdapter
  ,
  text

  Copy

  createEnvPatchedAccountSetupAdapter
  ,
  text

  Copy

  createSetupInputPresenceValidator
  ), lookup-note output,
  text

  Copy

  promptResolvedAllowFrom
  ,
  text

  Copy

  splitSetupEntries
  , and the delegated setup-proxy builders
• text

  Copy

  openclaw/plugin-sdk/setup-adapter-runtime
  is the narrow env-aware adapter seam for
  text

  Copy

  createEnvPatchedAccountSetupAdapter
• text

  Copy

  openclaw/plugin-sdk/channel-setup
  covers the optional-install setup builders plus a few setup-safe primitives:
  text

  Copy

  createOptionalChannelSetupSurface
  ,
  text

  Copy

  createOptionalChannelSetupAdapter
  ,

If your channel supports env-driven setup or auth and generic startup/config flows should know those env names before runtime loads, declare them in the plugin manifest with

If your channel can appear in

Keep the main channel entry import path narrow too. Discovery can evaluate the entry and the channel plugin module to register capabilities without activating the channel. Files such as

• use the broader
  text

  Copy

  openclaw/plugin-sdk/setup
  seam only when you also need the heavier shared setup/config helpers such as
  text

  Copy

  moveSingleAccountChannelSectionToDefaultAccount(...)

If your channel only wants to advertise "install this plugin first" in setup surfaces, prefer

For other hot channel paths, prefer the narrow helpers over broader legacy surfaces:

• text

  Copy

  openclaw/plugin-sdk/account-core
  ,
  text

  Copy

  openclaw/plugin-sdk/account-id
  ,
  text

  Copy

  openclaw/plugin-sdk/account-resolution
  , and
  text

  Copy

  openclaw/plugin-sdk/account-helpers
  for multi-account config and default-account fallback
• text

  Copy

  openclaw/plugin-sdk/inbound-envelope
  and
  text

  Copy

  openclaw/plugin-sdk/inbound-reply-dispatch
  for inbound route/envelope and record-and-dispatch wiring
• text

  Copy

  openclaw/plugin-sdk/messaging-targets
  for target parsing/matching
• text

  Copy

  openclaw/plugin-sdk/outbound-media
  and
  text

  Copy

  openclaw/plugin-sdk/outbound-runtime
  for media loading plus outbound identity/send delegates and payload planning
• text

  Copy

  buildThreadAwareOutboundSessionRoute(...)
  from
  text

  Copy

  openclaw/plugin-sdk/channel-core
  when an outbound route should preserve an explicit
  text

  Copy

  replyToId
  /
  text

  Copy

  threadId
  or recover the current
  text

  Copy

  :thread:
  session after the base session key still matches. Provider plugins can override precedence, suffix behavior, and thread id normalization when their platform has native thread delivery semantics.
• text

  Copy

  openclaw/plugin-sdk/thread-bindings-runtime
  for thread-binding lifecycle and adapter registration
• text

  Copy

  openclaw/plugin-sdk/agent-media-payload
  only when a legacy agent/media payload field layout is still required
• text

  Copy

  openclaw/plugin-sdk/telegram-command-config
  for Telegram custom-command normalization, duplicate/conflict validation, and a fallback-stable command config contract

Auth-only channels can usually stop at the default path: core handles approvals and the plugin just exposes outbound/auth capabilities. Native approval channels such as Matrix, Slack, Telegram, and custom chat transports should use the shared native helpers instead of rolling their own approval lifecycle.

Inbound mention policy

Keep inbound mention handling split in two layers:

• plugin-owned evidence gathering
• shared policy evaluation

Use

Good fit for plugin-local logic:

• reply-to-bot detection
• quoted-bot detection
• thread-participation checks
• service/system-message exclusions
• platform-native caches needed to prove bot participation

Good fit for the shared helper:

• text

  Copy

  requireMention
• explicit mention result
• implicit mention allowlist
• command bypass
• final skip decision

Preferred flow:

1. Compute local mention facts.
2. Pass those facts into
   text

   Copy

   resolveInboundMentionDecision({ facts, policy })
   .
3. Use
   text

   Copy

   decision.effectiveWasMentioned
   ,
   text

   Copy

   decision.shouldBypassMention
   , and
   text

   Copy

   decision.shouldSkip
   in your inbound gate.

typescript
Copy
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;

• text

  Copy

  buildMentionRegexes
• text

  Copy

  matchesMentionPatterns
• text

  Copy

  matchesMentionWithExplicit
• text

  Copy

  implicitMentionKindWhen
• text

  Copy

  resolveInboundMentionDecision

If you only need

The older

Walkthrough

text
Copy
<CodeGroup>
  ```json package.json theme={"theme":{"light":"min-light","dark":"min-dark"}}
  {
    "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."
      }
    }
  }
  ```

  ```json openclaw.plugin.json theme={"theme":{"light":"min-light","dark":"min-dark"}}
  {
    "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
          }
        }
      }
    }
  }
  ```
</CodeGroup>

`configSchema` validates `plugins.entries.acme-chat.config`. Use it for
plugin-owned settings that are not the channel account config. `channelConfigs`
validates `channels.acme-chat` and is the cold-path source used by config
schema, setup, and UI surfaces before the plugin runtime loads.

text
Copy
Create `src/channel.ts`:

```typescript src/channel.ts theme={"theme":{"light":"min-light","dark":"min-dark"}}
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);
      },
    },
  },
});
```

For channels that accept both canonical top-level DM keys and legacy nested keys, use the helpers from `plugin-sdk/channel-config-helpers`: `resolveChannelDmAccess`, `resolveChannelDmPolicy`, `resolveChannelDmAllowFrom`, and `normalizeChannelDmPolicy` keep account-local values ahead of inherited root values. Pair the same resolver with doctor repair through `normalizeLegacyDmAliases` so runtime and migration read the same contract.

<Accordion title="What createChatChannelPlugin does for you">
  Instead of implementing low-level adapter interfaces manually, you pass
  declarative options and the builder composes them:

  | Option                     | What it wires                                             |
  | -------------------------- | --------------------------------------------------------- |
  | `security.dm`              | Scoped DM security resolver from config fields            |
  | `pairing.text`             | Text-based DM pairing flow with code exchange             |
  | `threading`                | Reply-to-mode resolver (fixed, account-scoped, or custom) |
  | `outbound.attachedResults` | Send functions that return result metadata (message IDs)  |

  You can also pass raw adapter objects instead of the declarative options
  if you need full control.

  Raw outbound adapters may define a `chunker(text, limit, ctx)` function.
  The optional `ctx.formatting` carries delivery-time formatting decisions
  such as `maxLinesPerMessage`; apply it before sending so reply threading
  and chunk boundaries are resolved once by shared outbound delivery.
  Send contexts also include `replyToIdSource` (`implicit` or `explicit`)
  when a native reply target was resolved, so payload helpers can preserve
  explicit reply tags without consuming an implicit single-use reply slot.
</Accordion>

text
Copy
```typescript index.ts theme={"theme":{"light":"min-light","dark":"min-dark"}}
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(/* ... */);
  },
});
```

Put channel-owned CLI descriptors in `registerCliMetadata(...)` so OpenClaw
can show them in root help without activating the full channel runtime,
while normal full loads still pick up the same descriptors for real command
registration. Keep `registerFull(...)` for runtime-only work.
If `registerFull(...)` registers gateway RPC methods, use a
plugin-specific prefix. Core admin namespaces (`config.*`,
`exec.approvals.*`, `wizard.*`, `update.*`) stay reserved and always
resolve to `operator.admin`.
`defineChannelPluginEntry` handles the registration-mode split automatically. See
[Entry Points](/plugins/sdk-entrypoints#definechannelpluginentry) for all
options.

text
Copy
```typescript setup-entry.ts theme={"theme":{"light":"min-light","dark":"min-dark"}}
import { defineSetupPluginEntry } from "openclaw/plugin-sdk/channel-core";
import { acmeChatPlugin } from "./src/channel.js";

export default defineSetupPluginEntry(acmeChatPlugin);
```

OpenClaw loads this instead of the full entry when the channel is disabled
or unconfigured. It avoids pulling in heavy runtime code during setup flows.
See [Setup and Config](/plugins/sdk-setup#setup-entry) for details.

Bundled workspace channels that split setup-safe exports into sidecar
modules can use `defineBundledChannelSetupEntry(...)` from
`openclaw/plugin-sdk/channel-entry-contract` when they also need an
explicit setup-time runtime setter.

text
Copy
```typescript}
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;
    },
  });
}
```

<Note>
  Inbound message handling is channel-specific. Each channel plugin owns
  its own inbound pipeline. Look at bundled channel plugins
  (for example the Microsoft Teams or Google Chat plugin package) for real patterns.
</Note>

text
Copy
```typescript src/channel.test.ts theme={"theme":{"light":"min-light","dark":"min-dark"}}
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);
  });
});
```

```bash}
pnpm test -- <bundled-plugin-root>/acme-chat/
```

For shared test helpers, see [Testing](/plugins/sdk-testing).

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

• 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

Related

• Plugin SDK setup
• Building plugins
• Agent harness plugins