Plugin SDK Channel 插件构建

概述

Channel 插件将 OpenClaw 连接到消息平台。插件拥有：配置、安全（DM 策略和 allowlist）、配对（DM 审批流程）、会话语法、出站消息、线程和心跳打字指示器。核心拥有共享 message 工具、提示词接线、外层 session-key 形状和通用 :thread: 记账。

核心 API

构建 Channel 插件对象

import { createChatChannelPlugin, createChannelPluginBase } from "openclaw/plugin-sdk/channel-core";
 
export const myPlugin = createChatChannelPlugin<ResolvedAccount>({
  base: createChannelPluginBase({
    id: "my-channel",
    setup: { resolveAccount, inspectAccount },
  }),
  security: {
    dm: {
      channelKey: "my-channel",
      resolvePolicy: (account) => account.dmPolicy,
      resolveAllowFrom: (account) => account.allowFrom,
      defaultPolicy: "allowlist",
    },
  },
  pairing: {
    text: {
      idLabel: "Username",
      message: "Send this code to verify:",
      notify: async ({ target, code }) => { /* ... */ },
    },
  },
  threading: { topLevelReplyToMode: "reply" },
  outbound: {
    attachedResults: {
      sendText: async (params) => {
        const result = await api.sendMessage(params.to, params.text);
        return { messageId: result.id };
      },
    },
  },
});

关键适配器接口

适配器	用途
security.dm	DM 安全解析器
pairing.text	文本 DM 配对流程
threading	回复模式解析器
outbound.attachedResults	返回结果元数据的发送函数
message	新消息生命周期适配器（defineChannelMessageAdapter）
approvalCapability	审批能力（替代旧 approvals 字段）
heartbeat.sendTyping(...)	心跳打字指示器

入站提及策略

import { resolveInboundMentionDecision } from "openclaw/plugin-sdk/channel-mention-gating";
 
const decision = resolveInboundMentionDecision({
  facts: { canDetectMention: true, wasMentioned, implicitMentionKinds },
  policy: { isGroup, requireMention, allowTextCommands, hasControlCommand, commandAuthorized },
});
if (decision.shouldSkip) return;

入站授权（实验性）

import { resolveChannelMessageIngress } from "openclaw/plugin-sdk/channel-ingress-runtime";
 
const result = await resolveChannelMessageIngress({
  channelId: "my-channel",
  accountId,
  identity,
  subject: { stableId: platformUserId },
  conversation: { kind: isGroup ? "group" : "direct", id: conversationId },
  event: { kind: "message", authMode: "inbound", mayPair: !isGroup },
  policy: { dmPolicy, groupPolicy },
  allowFrom: config.allowFrom,
  route,
});

使用示例

// index.ts
import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core";
 
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: "...", hasSubcommands: false }] });
  },
  registerFull(api) {
    api.registerHttpRoute({
      path: "/acme-chat/webhook",
      auth: "plugin",
      handler: async (req, res) => {
        await handleInbound(api, parseWebhookPayload(req));
        res.statusCode = 200; res.end("ok"); return true;
      },
    });
  },
});

相关页面

• concepts/plugin-sdk-channel-turn — 共享入站轮次内核
• concepts/plugin-sdk-channel-message — 消息生命周期 API
• concepts/plugin-sdk-channel-ingress — 入站授权 API
• concepts/plugin-sdk-entrypoints — 入口点定义
• concepts/plugin-sdk-runtime — 运行时辅助工具