构建通道插件

Documentation Index

Fetch the complete documentation index at: https://openclaw.zhcndoc.com/llms.txt

Use this file to discover all available pages before exploring further.

​

通道插件如何工作

• 配置 — 账号解析和设置向导
• 安全性 — DM 策略和允许列表
• 配对 — DM 审批流程
• 会话语法 — 提供商特定的会话 id 如何映射到基础聊天、线程 id 和父级回退
• 外发 — 向平台发送文本、媒体和投票
• 线程化 — 回复如何被归入线程
• 心跳输入提示 — 为心跳交付目标提供可选的输入中/忙碌信号

​

审批与通道能力

• 核心负责同聊天 /approve、共享审批按钮负载，以及通用的回退交付。
• 当通道需要审批特定行为时，优先在通道插件上使用一个 approvalCapability 对象。
• ChannelPlugin.approvals 已移除。请把审批交付/原生/渲染/认证事实放到 approvalCapability 上。
• plugin.auth 仅用于登录/登出；核心不再从该对象读取审批认证钩子。
• approvalCapability.authorizeActorAction 和 approvalCapability.getActionAvailabilityState 是规范的审批认证接入点。
• 对于同聊天审批认证可用性，请使用 approvalCapability.getActionAvailabilityState。
• 如果你的通道暴露原生执行审批，请在它与同聊天审批认证不同的时候，使用 approvalCapability.getExecInitiatingSurfaceState 获取发起表面/原生客户端状态。核心会使用这个 exec 专用钩子区分 enabled 与 disabled，判断发起通道是否支持原生 exec 审批，并把该通道包含在原生客户端回退指引中。createApproverRestrictedNativeApprovalCapability(...) 为常见情况填充了这一点。
• 对于诸如隐藏重复的本地审批提示或在交付前发送输入提示指示之类的通道特定负载生命周期行为，请使用 outbound.shouldSuppressLocalPayloadPrompt 或 outbound.beforeDeliverPayload。
• 仅在原生审批路由或回退抑制时使用 approvalCapability.delivery。
• 对于通道拥有的原生审批事实，请使用 approvalCapability.nativeRuntime。在高频通道入口处用 createLazyChannelApprovalNativeRuntimeAdapter(...) 保持其惰性加载，它可以按需导入你的运行时模块，同时仍然让核心组装审批生命周期。
• 只有当通道真正需要自定义审批负载，而不是共享渲染器时，才使用 approvalCapability.render。
• 当通道希望禁用路径的回复解释启用原生 exec 审批所需的确切配置开关时，请使用 approvalCapability.describeExecApprovalSetup。该钩子接收 { channel, channelLabel, accountId }；具名账号通道应当渲染账号作用域路径，例如 channels.<channel>.accounts.<id>.execApprovals.*，而不是顶层默认值。
• 如果通道可以从现有配置中推断出稳定的类所有者 DM 身份，请使用 openclaw/plugin-sdk/approval-runtime 中的 createResolvedApproverActionAuthAdapter，在不增加审批特定核心逻辑的情况下限制同聊天 /approve。
• 如果通道需要原生审批交付，请让通道代码专注于目标规范化和传输/展示事实。请使用 openclaw/plugin-sdk/approval-runtime 中的 createChannelExecApprovalProfile、createChannelNativeOriginTargetResolver、createChannelApproverDmTargetResolver 和 createApproverRestrictedNativeApprovalCapability。将通道特定事实放在 approvalCapability.nativeRuntime 后面，最好通过 createChannelApprovalNativeRuntimeAdapter(...) 或 createLazyChannelApprovalNativeRuntimeAdapter(...)，这样核心就可以组装处理器并负责请求过滤、路由、去重、过期、网关订阅以及路由到其他位置的通知。nativeRuntime 被拆分为几个更小的接入面：
• createChannelNativeOriginTargetResolver 默认使用共享的 channel-route 匹配器来处理 { to, accountId, threadId } 目标。只有当通道存在提供商特定等价规则时才传入 targetsMatch，例如 Slack 时间戳前缀匹配。
• 当通道需要在默认路由匹配器或自定义 targetsMatch 回调运行之前，将提供商 id 规范化，同时保留原始目标用于交付时，请向 createChannelNativeOriginTargetResolver 传入 normalizeTargetForMatch。只有当解析后的交付目标本身也应被规范化时，才使用 normalizeTarget。
• availability — 账号是否已配置，以及请求是否应被处理
• presentation — 将共享审批视图模型映射为待处理/已解决/已过期的原生负载或最终动作
• transport — 准备目标并发送/更新/删除原生审批消息
• interactions — 原生按钮或表情反应的可选绑定/解绑/清理动作钩子
• observe — 可选的交付诊断钩子
• 如果通道需要运行时拥有的对象，例如客户端、令牌、Bolt 应用或 webhook 接收器，请通过 openclaw/plugin-sdk/channel-runtime-context 注册它们。通用的 runtime-context 注册表允许核心在不增加审批专用包装胶水的情况下，从通道启动状态引导基于能力的处理器。
• 只有在能力驱动的接入面还不够表达时，才使用更底层的 createChannelApprovalHandler 或 createChannelNativeApprovalRuntime。
• 原生审批通道必须通过这些帮助器同时路由 accountId 和 approvalKind。accountId 将多账号审批策略限定在正确的机器人账号范围内，而 approvalKind 则让 exec 与 plugin 的审批行为无需在核心中硬编码分支即可供通道使用。
• 核心现在也负责审批重路由通知。通道插件不应再从 createChannelNativeApprovalRuntime 发送自己的“审批已转到 DM / 另一个通道”的后续消息；相反，应通过共享审批能力帮助器暴露准确的来源 + 审批者 DM 路由，并让核心在向发起聊天发布任何通知前聚合实际交付结果。
• 端到端保留交付的审批 id 类型。原生客户端不应根据通道本地状态去猜测或重写 exec 与 plugin 审批路由。
• 不同的审批类型可以有意暴露不同的原生界面。当前打包示例：
  • Slack 为 exec 和 plugin id 都保持原生审批路由可用。
  • Matrix 为 exec 和 plugin 审批保持相同的原生 DM/通道路由和表情反应 UX，同时仍允许认证因审批类型而异。
• 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-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 覆盖运行时安全的设置帮助器： 导入安全的设置补丁适配器（createPatchedAccountSetupAdapter、 createEnvPatchedAccountSetupAdapter、 createSetupInputPresenceValidator）、查找说明输出、 promptResolvedAllowFrom、splitSetupEntries，以及委托式 setup-proxy 构建器
• openclaw/plugin-sdk/setup-adapter-runtime 是用于 createEnvPatchedAccountSetupAdapter 的更窄的、感知环境的适配器接入面
• openclaw/plugin-sdk/channel-setup 覆盖可选安装的设置 构建器以及一些设置安全的原语： createOptionalChannelSetupSurface、createOptionalChannelSetupAdapter、

• 只有在你还需要更重的共享设置/配置帮助器，例如 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/inbound-reply-dispatch，用于入站路由/信封以及记录并分发接线
• openclaw/plugin-sdk/messaging-targets，用于目标解析/匹配
• openclaw/plugin-sdk/outbound-media 和 openclaw/plugin-sdk/outbound-runtime，用于媒体加载以及外发身份/发送委托和负载规划
• 来自 openclaw/plugin-sdk/channel-core 的 buildThreadAwareOutboundSessionRoute(...)，当外发路由应保留显式的 replyToId/threadId，或者在基础会话键仍然匹配后恢复当前 :thread: 会话时使用。若平台具有原生线程交付语义，提供商插件可以覆盖优先级、后缀行为和线程 id 规范化。
• openclaw/plugin-sdk/thread-bindings-runtime，用于线程绑定生命周期和适配器注册
• openclaw/plugin-sdk/agent-media-payload，仅当仍然需要遗留的 agent/media 负载字段布局时使用
• openclaw/plugin-sdk/telegram-command-config，用于 Telegram 自定义命令规范化、重复/冲突校验以及稳定回退的命令配置契约

​

传入提及策略

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

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

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

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

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;

• buildMentionRegexes
• matchesMentionPatterns
• matchesMentionWithExplicit
• implicitMentionKindWhen
• resolveInboundMentionDecision

​

操作指南

{
  "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。"
    }
  }
}

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",
    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: {
    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: {
      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.setup!.resolveAccount(cfg, undefined);
    expect(account.token).toBe("test-token");
  });

  it("检查账户时不具现化密钥", () => {
    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("报告缺失配置", () => {
    const cfg = { channels: {} } as any;
    const result = acmeChatPlugin.setup!.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      # 带有配置 schema 的清单
├── 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            # 运行时存储（如需要）

​

高级主题

​

下一步

• 提供者插件 — 如果你的插件也提供模型
• SDK 概览 — 完整的子路径导入参考
• SDK 测试 — 测试工具和契约测试
• 插件清单 — 完整清单 schema

​

相关内容

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