构建通道插件

​

你的插件负责什么

• 配置 - 账号解析和设置向导
• 安全 - DM 策略和允许名单
• 配对 - DM 批准流程
• 会话语法 - 提供方特定的会话 id 如何映射到基础 聊天、线程 id 和父级回退
• 出站 - 向平台发送文本、媒体和投票
• 线程化 - 回复如何进行线程化
• 心跳输入中 - 可选的输入中/忙碌信号，用于心跳投递 目标

​

消息适配器

​

进度可见性验收

​

TTS 语音投递

​

入站入口（实验性）

​

持久化入口与重放去重

​

传输类别与保留

• 确认门控的 webhook 或事件投递： 仅在持久化追加之后确认或返回成功。 追加失败必须使该投递仍具备重试资格，或使接收边界失败。此类别包括 Slack、SMS、Zalo、 Microsoft Teams、Google Chat、LINE 和 Synology Chat。
• 等待式轮询或流式投递： 仅在追加之后推进远程游标或发送传输确认。当不存在显式游标时， 保持接收回调串行并等待完成，以确保追加失败不会让接收循环超前运行。Telegram 轮询、Signal 和 Tlon 使用此类别；Telegram webhook 投递遵循上述确认门控规则。
• 不可重放的套接字： IRC、Mattermost、Twitch 和 Zalo Personal 无法请求平台重新投递 已接受的事件。它们的持久化队列用于保护进程崩溃窗口，并支持本地重启恢复；完成墓碑对于防止平台重放几乎不起作用。

​

至少一次副作用

​

账户范围的重启契约

​

运行时生命周期状态

​

正在输入指示器

​

媒体来源参数

​

原生负载整形

​

会话对话语法

​

按账号作用域的会话绑定支持

​

审批和通道能力

​

审批认证

• approvalCapability.authorizeActorAction 和 approvalCapability.getActionAvailabilityState 是规范的 审批认证接口。
• 使用 getActionAvailabilityState 来获取同聊天室审批认证可用性。 即使原生投递被禁用，也要让已配置的审批人在 /approve 中保持可用； 交由原生启动面状态用于投递／设置指引。
• 如果你的通道暴露原生 exec 审批，在原生客户端状态与同聊天室 审批认证不同时，使用 approvalCapability.getExecInitiatingSurfaceState 作为启动面／原生客户端状态。Core 会使用这个 exec 专用钩子来区分 enabled 与 disabled，判断启动通道是否支持原生 exec 审批，并将该通道 纳入原生客户端回退指引中。 createApproverRestrictedNativeApprovalCapability(...) 已为常见情况补足此项。
• 如果某个通道能够从现有配置中推断出稳定的、类似 owner 的 DM 身份， 使用 openclaw/plugin-sdk/approval-runtime 中的 createResolvedApproverActionAuthAdapter 来限制同聊天室 /approve， 而无需增加审批专用的 core 逻辑。
• 如果自定义审批认证有意只允许同聊天室回退，从 openclaw/plugin-sdk/approval-auth-runtime 返回 markImplicitSameChatApprovalAuthorization({ authorized: true })； 否则 core 会将结果视为显式的审批人授权。
• 如果由通道拥有的原生回调直接解析审批，在解析前使用 isImplicitSameChatApprovalAuthorization(...)，这样隐式回退仍会经过通道的 常规 actor 认证。

​

载荷生命周期与设置指引

• 当需要通道特定的载荷生命周期行为时，例如隐藏重复的本地审批提示， 或在投递前发送 typing 指示器，使用 outbound.shouldSuppressLocalPayloadPrompt 或 outbound.beforeDeliverPayload。
• 当通道希望 disabled 路径的回复能够解释启用原生 exec 审批所需的具体配置项时， 使用 approvalCapability.describeExecApprovalSetup。该钩子接收 { channel, channelLabel, accountId }；带命名账户的通道应渲染账户范围路径， 例如 channels.<channel>.accounts.<id>.execApprovals.*，而不是顶层默认项。
• 当插件审批失败指引在插件审批的 no-route 和超时失败场景中可以安全展示时， 使用 approvalCapability.describePluginApprovalSetup。 createApproverRestrictedNativeApprovalCapability(...) 不会从 describeExecApprovalSetup 推断这一点；只有当插件审批和 exec 审批确实使用相同的原生设置时， 才显式传入相同的 helper。

​

原生审批投递

• availability - 账户是否已配置，以及请求是否应被处理
• presentation - 将共享审批视图模型映射为 pending／resolved／expired 原生载荷或最终动作
• transport - 准备目标并发送／更新／删除原生审批消息
• interactions - 可选的原生按钮或 reaction 的 bind/unbind/clear-action 钩子，以及可选的 cancelDelivered 钩子。若 deliverPending 会注册进程内或持久化状态（例如 reaction 目标存储），请实现 cancelDelivered，以便在处理器停止且在 bindPending 执行前取消投递时，或者当 bindPending 返回空句柄时能够释放这些状态
• observe - 可选的投递诊断钩子

• 当一个通道同时支持会话来源的原生投递和显式审批转发目标时，请使用 openclaw/plugin-sdk/approval-native-runtime 中的 createNativeApprovalChannelRouteGates。该帮助器集中处理审批配置选择、mode 处理、代理／会话过滤、账户绑定、会话目标匹配和目标列表匹配，同时调用方仍负责通道 ID、默认转发模式、账户查找、传输启用检查、目标规范化和轮次来源目标解析。不要使用它来创建由 core 所有的通道策略默认值；请显式传入通道文档规定的默认模式。
• createNativeApprovalMessagingTargetResolvers 集中处理消息传输中的通道匹配以及 { to, accountId, threadId } 规范化，这些传输的原生审批目标是通道自有的规范化目的地。 请将群组授权、审批人映射和其他传输策略保留在通道插件中。
• createChannelNativeOriginTargetResolver 默认使用共享的通道路由匹配器来处理 { to, accountId, threadId } 目标。只有当通道具有提供商特定的等价规则（例如 Slack 时间戳前缀匹配）时，才传入 targetsMatch。当通道需要在默认路由匹配器或自定义 targetsMatch 回调运行之前规范化提供商 ID 时，请传入 normalizeTargetForMatch，同时保留原始目标用于投递。只有当解析出的投递目标本身应被规范化时，才使用 normalizeTarget。
• 如果通道需要客户端、令牌、Bolt 应用或 webhook 接收器等由运行时拥有的对象，请通过 openclaw/plugin-sdk/channel-runtime-context 注册它们。通用的运行时上下文注册表可以让 core 从通道启动状态引导基于能力的处理器，而无需添加审批专用的包装代码。
• 只有当基于能力的衔接点暂时无法满足需求时，才使用较低层级的 createChannelApprovalHandler 或 createChannelNativeApprovalRuntime。
• 原生审批通道必须通过这些帮助器传递 accountId 和 approvalKind。accountId 确保多账户审批策略限定在正确的机器人账户范围内，而 approvalKind 则使通道能够处理 exec 与插件审批行为，无需在 core 中使用硬编码分支。
• Core 也负责审批重新路由通知。通道插件不应从 createChannelNativeApprovalRuntime 发送自己的“审批已转到私信／另一个通道”后续消息；相反，应通过共享审批能力帮助器准确暴露来源 + 审批人私信路由，并让 core 在向发起审批的聊天发布任何通知之前，汇总实际投递结果。
• 端到端保留已投递审批 ID 的类型。原生客户端不应根据通道本地状态猜测或重写 exec 与插件审批的路由。
• 将显式的 approvalKind 传递给 resolveApprovalOverGateway。这会使用规范的 approval.resolve 服务，并在另一个界面先作出响应时返回已记录的获胜者。较旧的显式 resolveMethod 输入仍用于基于命令的控制；新的原生操作不得使用它，也不得从 ID 推断类型。
• 不同的审批类型可以有意暴露不同的原生界面。目前打包的示例包括：Matrix 对 exec 和插件审批保持相同的原生私信／频道路由和 reaction 用户体验，同时仍允许按审批类型区分授权；Slack 则同时为 exec ID 和插件 ID 提供原生审批路由。
• createApproverRestrictedNativeApprovalAdapter 仍作为兼容性包装器存在，但新代码应优先使用能力构建器，并在插件上暴露 approvalCapability。

​

更窄的审批运行时子路径

• 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-reference-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 覆盖运行时安全的设置 helper： createSetupTranslator、可安全导入的 setup patch 适配器 (createPatchedAccountSetupAdapter、createEnvPatchedAccountSetupAdapter、 createSetupInputPresenceValidator)、lookup-note 输出、 promptResolvedAllowFrom、splitSetupEntries，以及委托式 setup-proxy builders。
• openclaw/plugin-sdk/channel-setup 覆盖可选安装的设置 builders，以及少量设置安全原语： createOptionalChannelSetupSurface、createOptionalChannelSetupAdapter、 createOptionalChannelSetupWizard、DEFAULT_ACCOUNT_ID、 createTopLevelChannelDmPolicy、setSetupChannelEnabled 和 splitSetupEntries。
• 仅当你还需要更重的共享 setup/config helper，例如 moveSingleAccountChannelSectionToDefaultAccount(...) 时，才使用更宽泛的 openclaw/plugin-sdk/setup 接口。

​

其他更窄的通道子路径

• openclaw/plugin-sdk/account-core、openclaw/plugin-sdk/account-id、 openclaw/plugin-sdk/account-resolution 和 openclaw/plugin-sdk/account-helpers，用于多账户配置和 默认账户回退
• openclaw/plugin-sdk/inbound-envelope 和 openclaw/plugin-sdk/channel-inbound，用于入站路由／信封以及 记录并分发的衔接
• 当终端 reaction 或状态 UI 必须区分已完成的 core agent 运行和恢复后的失败运行时，使用 openclaw/plugin-sdk/channel-inbound 中的 readAgentRunTerminalOutcome(dispatchResult)。它仅在 core 运行确实启动时返回 "completed" 或 "failed"，对于命令、去重、繁忙、运行前中止和自定义分发结果则返回 undefined。投递计数和可见性仍属于传输事实，包括错误载荷的成功投递；进程本地载体不会序列化为 JSON。
• 当成功的出站发送必须停用活动的入站事件标记时，使用 openclaw/plugin-sdk/inbound-event-delivery 中的 createInboundEventDeliveryCorrelation(...)；每个通道创建一个跟踪器，并将目标匹配保留在通道插件中
• openclaw/plugin-sdk/channel-targets，用于目标解析帮助器
• openclaw/plugin-sdk/channel-outbound，用于出站身份／发送委托和类型化载荷规划
• 当出站路由应保留显式的 replyToId／threadId，或在基础会话键仍匹配后恢复当前的 :thread: 会话时，使用 openclaw/plugin-sdk/channel-core 中的 buildThreadAwareOutboundSessionRoute(...)。当提供商平台具有原生线程投递语义时，提供商插件可以覆盖优先级、后缀行为和线程 ID 规范化。
• openclaw/plugin-sdk/thread-bindings-runtime，用于线程绑定生命周期和适配器注册

​

传入提及策略

• 插件拥有的证据收集
• 共享策略评估

• 回复到机器人检测
• 引用机器人检测
• 线程参与检查
• 服务/系统消息排除
• 用于证明机器人参与所需的平台原生缓存

• requireMention
• 显式提及结果
• 隐式提及允许列表
• 命令旁路
• 最终跳过决策

1. 计算本地提及事实。
2. 将这些事实传入 resolveInboundMentionDecision({ facts, policy })。
3. 在你的传入门控中使用 decision.effectiveWasMentioned、decision.shouldBypassMention 和 decision.shouldSkip。

import {
  implicitMentionKindWhen,
  matchesMentionWithExplicit,
  resolveInboundMentionDecision,
} from "openclaw/plugin-sdk/channel-inbound";
import { resolveChannelImplicitMentions } from "openclaw/plugin-sdk/channel-ingress-runtime";

const wasMentioned = matchesMentionWithExplicit({
  text,
  mentionRegexes,
  explicit: {
    hasAnyMention,
    isExplicitlyMentioned,
    canResolveExplicit,
  },
});

const facts = {
  canDetectMention: true,
  wasMentioned,
  hasAnyMention,
  implicitMentionKinds: [
    ...implicitMentionKindWhen("reply_to_bot", isReplyToBot),
    ...implicitMentionKindWhen("quoted_bot", isQuoteOfBot),
  ],
};

const implicitMentions = resolveChannelImplicitMentions({
  cfg,
  channel: channelId,
  accountId,
});

const decision = resolveInboundMentionDecision({
  facts,
  policy: {
    isGroup,
    requireMention,
    implicitMentions,
    allowTextCommands,
    hasControlCommand,
    commandAuthorized,
  },
});

if (decision.shouldSkip) return;

​

操作指南

{
  "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": "将 OpenClaw 连接到 Acme Chat。"
    }
  }
}

{
  "id": "acme-chat",
  "channels": ["acme-chat"],
  "name": "Acme Chat",
  "description": "Acme Chat 频道插件",
  "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": "机器人令牌",
          "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"; // 你的平台 API 客户端

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");
  return {
    accountId: accountId ?? null,
    token,
    allowFrom: section?.allowFrom ?? [],
    dmPolicy: section?.dmSecurity,
  };
}

export const acmeChatPlugin = createChatChannelPlugin<ResolvedAccount>({
  base: createChannelPluginBase({
    id: "acme-chat",
    // 账户解析/检查属于 `config`，而不是 `setup`。
    // `setup` 负责引导写入（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: {
    dm: {
      channelKey: "acme-chat",
      resolvePolicy: (account) => account.dmPolicy,
      resolveAllowFrom: (account) => account.allowFrom,
      defaultPolicy: "allowlist",
    },
  },

  // 配对：新 DM 联系人的审批流程
  pairing: {
    text: {
      idLabel: "Acme Chat 用户名",
      message: "发送此代码以验证你的身份：",
      notify: async ({ target, code }) => {
        await acmeChatApi.sendDm(target, `Pairing code: ${code}`);
      },
    },
  },

  // 线程：回复如何被投递
  threading: { topLevelReplyToMode: "reply" },

  // 发出：向平台发送消息
  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 { 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 频道插件",
  plugin: acmeChatPlugin,
  registerCliMetadata(api) {
    api.registerCli(
      ({ program }) => {
        program
          .command("acme-chat")
          .description("Acme Chat 管理");
      },
      {
        descriptors: [
          {
            name: "acme-chat",
            description: "Acme Chat 管理",
            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", // 由插件管理的认证（自行验证签名）
    handler: async (req, res) => {
      const event = parseWebhookPayload(req);

      // 你的传入处理器将消息分发给 OpenClaw。
      // 具体接线取决于你的平台 SDK -
      // 请参见打包的 Microsoft Teams 或 Google Chat 插件包中的真实示例。
      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("从配置中解析账户", () => {
    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("检查账户时不具现化密钥", () => {
    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("报告缺失配置", () => {
    const cfg = { channels: {} } as any;
    const result = acmeChatPlugin.config.inspectAccount!(cfg, undefined);
    expect(result.configured).toBe(false);
  });
});

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

​

文件结构

<bundled-plugin-root>/acme-chat/
├── package.json              # openclaw.channel 元数据
├── openclaw.plugin.json      # 带有配置模式的清单
├── index.ts                  # defineChannelPluginEntry
├── setup-entry.ts            # defineSetupPluginEntry
├── api.ts                    # 公共导出（可选）
├── runtime-api.ts            # 内部运行时导出（可选）
└── src/
    ├── channel.ts            # 通过 createChatChannelPlugin 实现的 ChannelPlugin
    ├── channel.test.ts       # 测试
    ├── client.ts             # 平台 API 客户端
    └── runtime.ts            # 运行时存储（如需要）

​

高级主题

​

下一步

• Provider 插件 - 如果你的插件还提供模型
• SDK 概览 - 完整的子路径导入参考
• SDK 测试 - 测试工具和契约测试
• 插件清单 - 完整的清单架构.schemas。

​

相关内容

• 插件 SDK 设置
• 构建插件
• Agent harness 插件