Plugin SDK Channel 消息生命周期

概述

Channel 插件应从 openclaw/plugin-sdk/channel-message 暴露一个 message 适配器，描述平台支持的原生消息生命周期：

receive -> route and record -> agent turn -> durable final send
send -> render batch -> platform I/O -> receipt -> lifecycle side effects
live preview -> final edit or fallback -> receipt

核心拥有：队列、持久性、通用重试策略、钩子、回执和共享 message 工具。插件拥有：原生发送/编辑/删除调用、目标规范化、平台线程、选定引用、通知标志、账号状态和平台特定副作用。

核心 API

定义消息适配器

import { defineChannelMessageAdapter } from "openclaw/plugin-sdk/channel-message";
 
const adapter = defineChannelMessageAdapter({
  id: "demo",
  durableFinal: {
    capabilities: { text: true, replyTo: true, thread: true, messageSendingHooks: true },
  },
  send: {
    text: async ({ cfg, to, text, accountId, replyToId, threadId, signal }) => {
      const sent = await sendDemoMessage({ cfg, to, text, replyToId, threadId, signal });
      return {
        receipt: createMessageReceiptFromOutboundResults({
          results: [{ channel: "demo", messageId: sent.id, conversationId: to }],
          kind: "text",
        }),
      };
    },
  },
});

持久化最终投递能力

能力	声明时机
`text`	适配器可发送文本并返回回执
`media`	媒体发送为每条可见平台消息返回回执
`replyTo`	原生回复目标到达平台
`thread`	原生线程/话题目标到达平台
`silent`	通知抑制到达平台
`messageSendingHooks`	核心 message-sending 钩子可在平台 I/O 前取消或重写内容
`reconcileUnknownSend`	适配器可解析 `unknown_after_send` 恢复

消息回执

type MessageReceipt = {
  primaryPlatformMessageId?: string;
  platformMessageIds: string[];
  parts: MessageReceiptPart[];
  threadId?: string;
  replyToId?: string;
  sentAt: number;
};

实时预览能力

live: {
  capabilities: { draftPreview: true, previewFinalization: true, progressUpdates: true },
  finalizer: {
    capabilities: { finalEdit: true, normalFallback: true, discardPending: true },
  },
}

接收确认策略

策略	使用时机
`after_receive_record`	入站事件解析并记录后确认
`after_agent_dispatch`	等到 Agent 派发被接受后确认
`after_durable_send`	等到最终投递有持久决策后确认
`manual`	插件拥有确认（平台语义不匹配通用阶段）

运行时投递辅助工具

import { sendDurableMessageBatch, deliverInboundReplyWithMessageSendContext } from "openclaw/plugin-sdk/channel-message-runtime";

sendDurableMessageBatch 返回明确的生命周期结果：sent、suppressed、partial_failed、failed。

使用示例

// 从现有 outbound 适配器派生
import { createChannelMessageAdapterFromOutbound } from "openclaw/plugin-sdk/channel-message";
 
const messageAdapter = createChannelMessageAdapterFromOutbound({
  id: "demo",
  outbound: demoOutboundAdapter,
});
 
// 附加到 channel 插件
export const demoPlugin = createChatChannelPlugin({
  base: { id: "demo", message: messageAdapter },
});

Wiki AI

目录