跳转至

通道入站 API

频道接收路径遵循单一流程:

platform event -> inbound facts/context -> agent reply -> message delivery

使用 openclaw/plugin-sdk/channel-inbound 进行入站事件规范化、格式化、根(roots)与编排。使用 openclaw/plugin-sdk/channel-outbound 实现原生发送、回执、持久化投递和实时预览行为。

核心辅助函数

import {
  buildChannelInboundEventContext,
  runChannelInboundEvent,
  dispatchChannelInboundReply,
} from "openclaw/plugin-sdk/channel-inbound";
  • buildChannelInboundEventContext(...):将规范化后的频道事实投影到提示词/会话上下文中。通过 channelContext 传递频道所属的发送者/聊天元数据,插件钩子会将其视为 ctx.channelContext。从该子路径扩展 PluginHookChannelSenderContext 或 PluginHookChannelChatContext,以添加频道专属字段。这个公开的独立构建器不具备权威性,不能生成参与者凭证。捆绑的生产接收路径使用宿主注入的已注册 runtime.channel.inbound.buildContext,并将精确的 频道入口 解析器结果作为 channelIngress 传递。在最终路由选择之后,使用 contextBinding 解析该结果。核心仅在相同的活动插件记录、生命周期纪元、智能体、会话、消息、事件和准入范围仍然匹配时接受一次;接收路径不得从上下文字段重建参与者来源信息。只有经过命名且来源可证明为不支持的路径才传递 channelIngress: "unsupported"。
  • runChannelInboundEvent(...):对单个入站平台事件执行摄取(ingest)、分类、预检、解析、记录、分发和最终化。
  • dispatchChannelInboundReply(...):使用投递适配器记录并分发一条已组装好的入站回复。

对于回复,频道插件会解码平台引用并水合(hydrate)可访问的父消息。即使无法获取父消息,也要将引用作为 reply.replyToId 传入,并将可用的文本和发送者事实作为 supplemental.quote 传入。核心会根据配置的上下文可见性策略,为模型渲染回复关系。被引用的机器人文本是当前消息的上下文;它不会独立地准入一条机器人撰写的轮次。默认保留自己撰写的引用文本。默认跳过自己撰写的引用媒体;调用方在解析补充媒体时可以显式设置 suppressSelfQuoteBody: true 或 suppressSelfQuoteMedia: false。

原生命令适配器必须在准备已配置绑定之前授权发送者。来自 openclaw/plugin-sdk/command-auth-native 的 resolveCommandAuthorization(...) 返回一个可选的 assertOwnerCurrent 回调,其中包含宿主已认可的所有者检查。它不能授予所有权;当没有绑定任何所有者检查时,该回调不存在。在等待的准备操作之前捕获授权结果,将其回调与当前频道和命令策略检查组合,并将生成的回调作为 assertActive 传给 ensureConfiguredBindingRouteReady。ACP 准备会在后续后端效果之前检查它,包括排队控件、句柄重开和会话替换。已接受的控制和关闭结果在撤销后仍会结算;撤销会阻止下一个效果。这个可选回调保留那些不携带频道请求权限的现有调用方。

对于有意的跳过场景,logInboundDrop({ log, channel, reason, target?, onceKey?, hint? }) 会通过所提供的记录器格式化一条诊断信息。对于受提及门控的群组,请使用默认级别的记录器和可操作的 hint。将 onceKey 设置为账户/会话范围,例如 JSON.stringify([accountId, conversationId]),以抑制该频道和原因的重复记录。进程本地缓存最多保留 512 个最近使用的键;被淘汰的键可能再次记录。省略 onceKey 则进行逐消息记录。默认级别的诊断信息中不要包含消息正文和发送者详情。

对于群组设置提示,请使用来自 openclaw/plugin-sdk/channel-policy 的 resolveChannelGroupsConfigPath({ cfg, channel, accountId, groups })。直接传递频道所有者选择的确切群组映射,不要克隆它:使用 resolveChannelGroups(cfg, channel, accountId) 进行共享群组策略解析,或对具有自身继承规则的插件使用解析后的账户映射。这样可以识别出已编写的根映射或账户映射,而不会替换继承的通配符或按群组策略。

对于仅包含媒体的入站事件,保持消息正文和命令文本为空,并为每个原生附件传入一个 ChannelInboundMediaInput 事实。当环境历史行或其他纯文本载体必须描述这些事实时,请使用 formatMediaPlaceholderText(media)。它会根据 kind、MIME 类型,然后是路径或 URL 扩展名对每个事实进行分类;未下载的原生附件仍应各自贡献一个仅含类型的事实。不要使用该格式化器来合成主要的入站正文。

使用 toInboundMediaFacts(...) 规范化插件拥有的附件记录,然后将生成的有序数组通过上下文的 media 字段传递:

// saved, nativeUrl, messageId, and caption are plugin-supplied values from the
// platform event you just normalized.
const media = toInboundMediaFacts([
  { path: saved.path, url: nativeUrl, contentType: saved.contentType, messageId },
]);

const ctx = runtime.channel.reply.finalizeInboundContext({ Body: caption, media });

toInboundMediaFacts 从该子路径导出。finalizeInboundContext 则不是:它需要通过注入的插件运行时以 runtime.channel.reply.finalizeInboundContext 方式访问。

数组位置即附件标识。每个事实的 transcribed、messageId 和 workspaceDir 取代了旧的并行索引/工作区字段。MediaPath、MediaPaths、MediaUrl、MediaUrls、MediaType、MediaTypes、MediaTranscribedIndexes、MediaWorkspaceDir 和 MediaStaged 上下文字段,以及 buildChannelInboundMediaPayload(...),现在仅作为已弃用的兼容性保留。兼容性注册表于 2026-07-24 弃用它们,removeAfter 日期为 2026-10-01;请参阅移除时间线。新插件不应构造或读取它们。

内置/原生通道在已经接收注入的插件运行时对象后,可以调用 runtime.channel.inbound.* 下的同一组辅助函数,而无需直接导入此子路径:

await runtime.channel.inbound.run({
  channel: "demo",
  accountId,
  raw: platformEvent,
  adapter: {
    ingest: normalizePlatformEvent,
    resolveTurn: resolveInboundReply,
  },
});

为将平台投递保留在投递适配器中的兼容性分发器组装 dispatchChannelInboundReply(...) 的输入。新的发送路径应改用 channel-outbound 中的消息适配器和持久化消息辅助函数。

平台选择的历史窗口

当平台拥有近期历史时,将所选条目作为 message.inboundHistory 传入,并设置 sessionTranscript: { historyLimit, historyKind: "recent" }。宿主渲染该配置的窗口,而不会将规范会话记录行合并回去。未设置 "recent" 时,现有的会话记录增强和传统的防御性 20 条提示上限保持不变。

通道负责有界获取、当前账户/对话权限、重置边界以及当前消息排除。历史获取失败时不得静默恢复过期的缓存内容。保持所选快照在格式化上下文与结构化历史之间一致。

对于纯文本上下文,来自 openclaw/plugin-sdk/reply-history 的 buildHistoryContext(...) 和 buildHistoryContextFromEntries(...) 也接受 historyKind: "recent"。它们默认的 "pending" 框定方式保持不变;应使用这些辅助函数,而不是自行发明对命令敏感的标记。

代理组分发

共享的入站分发器在普通单代理调用之前协调符合条件的 broadcast 条目。通过入站上下文传递真实的通道、账户、对话、线程和根消息身份。核心负责参与者选择、代理/会话重新绑定、有界的同级最终摘要、延续身份以及同步的 maxTurns 预留。通道插件负责准入事实和平台编码;不要在插件中实现另一套参与者循环。

MsgContext.GroupThread 以纯数据契约的形式携带准备好的参与者提及事实。共享上下文类型不依赖提及匹配或通道注册表;准入解析器在分发前负责提及匹配。

一个轮次是由协调器启动的一次参与者运行。它的预览、分块和消息工具发送可能产生多条物理消息。不要通过缓冲或计数投递来强制 maxTurns。组预算为进程本地且不可恢复。已配置的 ACP 绑定保留对其路由的独占所有权。

参见 广播组 了解操作者配置,并参见 入站提及策略 了解面向参与者的准入。

内部轮次来源

MsgContext.InternalTurnSource 标识内部唤醒:"heartbeat"、"cron" 或 "exec"。对于普通通道消息,保持其未设置。它可以防止内部轮次重置会话或替换对话绑定;它不授予执行权限,也不替代 InputProvenance。

保留 Provider 和 Surface 用于传输身份,并保留 OriginatingChannel 和 OriginatingTo 中的回复路由。内部唤醒可能没有传输或显式回复目标。不要将唤醒标签放入这些通道字段中。

对于现有 SDK 调用者,入站最终化和会话记录入口会将旧版 Provider 值 "heartbeat"、"cron-event" 和 "exec-event" 转换为 InternalTurnSource。它们会从通道字段中移除这些标签,同时保留真实的回复路由。新调用者应直接设置类型化的来源。

接收确认策略

createMessageReceiveContext(...) 从 openclaw/plugin-sdk/channel-outbound 导出,用于跟踪单个入站事件的确认状态。其 ackPolicy 选择由 shouldAckAfter(...) 接受的阶段:

策略 确认边界
after_receive_record 在持久化入站元数据为去重和路由而记录之后。
after_agent_dispatch 在代理运行被分发之后。
after_durable_send 在持久化出站投递提交之后。
manual 没有任何阶段自动符合条件;由调用者决定何时确认。

该辅助函数默认为 after_receive_record,而非 manual。调用者仍需执行实际工作并调用 ack() 或 nack(error);选择策略本身不会持久化、分发或发送消息。

投递结算契约

ChannelInboundTurnPlan.delivery 负责每个逻辑回复载荷的原生发送。在路由 API 上,核心运行 reply_payload_sending,调用 preparePayload,然后分配恰好一个 message_sending 所有者:

  • 已声明的 durable 分支在共享持久化投递中运行该钩子;
  • 直接的 deliver 分支在核心中、原生适配器之前运行该钩子;
  • 例外提供者漏斗可以在必须在该漏斗内选择持久化投递或原生最终化时使用 deliverWithProviderMessageSending。

不要在普通的 deliver 回调内再次应用 message_sending。仅当分支无法在进入提供者漏斗前声明时,才使用提供者拥有的回调;它与 deliver 和 durable 互斥。现有的直接和持久化计划继续使用 ChannelInboundTurnPlan;将例外漏斗显式类型化为 ChannelInboundTurnPlan<"provider_message_sending">。由调用者组装的 dispatchChannelInboundReply(...) 仍然是兼容性边界,并保留由调用者提供的分发器所有权。

当一次发送可能已完成但其结果未确认时,来自 openclaw/plugin-sdk/reply-runtime 的底层 createReplyDispatcher(...) 回调可能返回 ambiguous: true。核心会记录现有的 unknown 保管状态和 failedAfterSend 回执计数,在不证明已观察到投递的情况下抑制重复回退。带有原因 channel_transform 的已结算 suppression 会记录 suppressed 保管状态。回执的 anyVisibleDelivered 保持保守:它包含不确定的发送。已被证明未发生的发送仍可属于持久化恢复队列。核心保留该重试所有者并记录 failedBeforeSend,不发出说明文字或最终回退;它不会将失败尝试计为已观察到的投递。

preparePayload 可能在通道策略有意抑制逻辑载荷时返回 null。Core 会记录一个带类型的不可见结果,并跳过持久化选择、message_sending 和原生投递,因此后续的修改钩子无法恢复通道已拒绝的内容。

Core 还负责在适配器选择加入时管理终态 message_sent 观察。保持这些职责分离,以便一个载荷不会生成重复的修改器或终态事件。

投递结果字段具有以下含义:

字段 契约
content 逻辑载荷在原生格式化或最终化之后,提供方接受的可见文本。省略它可让终态观察使用已准备好的载荷文本。仅媒体发送可以省略它。
messageIds / receipt 可见发送的实际提供方标识。优先使用 MessageReceipt;core 会使用其主要提供方标识用于 message_sent。
visibleReplySent 仅当提供方未产生任何可见预览或最终消息时,将其设置为 false。Core 不会为该结果发出成功的 message_sent。
suppression 在修改钩子或载荷策略确定之后,带类型的有意不发送原因。钩子取消也可以包含 cancelReason 和元数据。对于由 core 拥有的抑制,Core 永远不会调用直接原生适配器。
finalization 用于同一逻辑载荷延迟原生结算的 Promise,例如关闭或编辑就地流式卡片。其解析后的字段会在终态观察和 onDelivered 之前覆盖立即结果。

当 core 应为该适配器的非持久化发送发出规范的插件和内部 message_sent 事件时,将投递适配器的 observeMessageSent 选项设置为 true。不要从 deliver 返回此选项,也不要同时在插件中发出这些事件。持久化发送已经通过共享出站所有者发出,且不会重复。

每个逻辑载荷返回一个结果。finalization 不是第二次发送,且不得重新运行 reply_payload_sending 或 message_sending。一旦 deliver 返回,core 就会观察 finalization Promise 的拒绝,使其不会成为未处理错误;core 仍会在回复分发确定后等待原始 Promise。随后,它最多为每个载荷发出一个终态观察,并附带最终化后的内容和提供方 id。如果存在 onDelivered,它会在该观察之后接收已确定的结果。

onDelivered 还会接收已确定的被抑制结果。被抑制结果具有 visibleReplySent: false,不会发出 message_sent,也不计为可见的排队回复。这让插件能够区分钩子取消和提供方失败,而无需虚构一个原生消息标识。

默认情况下,路由轮次会将入站元数据记录到 ctxPayload.SessionKey ?? route.sessionKey。仅当原生命令有意在一个命令会话中执行,同时更新另一个提供方路由的目标会话时,才设置 record.sessionKey。该覆盖会影响入站元数据、转录上下文合并和记录阶段诊断;它不会改变分发路由或钩子关联。显式覆盖必须非空,且不能包含周围空白。

共享的 recordInboundSession 记录器在返回前会等待其元数据写入器,因此分发不会与会话存储的创建发生竞态。如果代理数据库仍在等待启动检查,则记录会在分发前拒绝,以便通道传输可以重试入站消息。其他元数据写入失败仍会到达 onRecordError,而不会使轮次失败。传递给 trackSessionMetaTask 的 Promise 包含异步错误报告;报告和自动会话维护仍位于前台完成之外。

当原生投递失败时,拒绝 deliver 或 finalization。如果未尝试任何提供方发送,请从 openclaw/plugin-sdk/error-runtime 抛出 PlatformMessageNotDispatchedError;core 会抑制虚假的 message_sent 事件。如果原生发送在后续操作失败之前已变为可见,请在错误上保留可见子集:

import { createChannelPartialDeliveryError } from "openclaw/plugin-sdk/channel-inbound";

throw createChannelPartialDeliveryError(cause, {
  visibleReplySent: true,
  content: finalizedVisibleText,
  receipt,
});

由此辅助函数创建的错误会在 cause 中保留原始失败。在 isChannelPartialDeliveryError(error) 之后,error.cause 为 unknown;结构化信封可以省略它。

Core 会发出一个失败的终态观察,并附带该提供方可见的内容和标识,然后保持投递失败,以便调用方不会将部分成功误认为一次干净的发送。在任何预览、草稿、附件或最终消息变为可见之后,不要报告 visibleReplySent: false。

当注册了 reply_payload_sending 或 message_sending 时,这些钩子必须在任何提供方可见内容创建之前确定,因为任一钩子都可能重写或取消逻辑载荷。急切的原生预览会泄露重写前的内容,或留下一个已取消的草稿。请缓冲预览内容,直到已接受的载荷到达 deliver;较早开始预览的兼容性分发器必须在任一钩子注册期间抑制该急切预览。对于新的预览路径,请使用来自 Channel outbound API 的可最终化实时预览辅助函数。

迁移

runtime.channel.turn 是已弃用的兼容性别名,用于在 inbound 重命名之前编译的已发布插件。它与 runtime.channel.inbound 是同一个对象,包括其运行时绑定的 dispatch 辅助函数。 新插件和已迁移的插件应使用:

  • runtime.channel.inbound.run(...) 用于原始入站事件。
  • runtime.channel.inbound.dispatchReply(...) 用于已组装的回复上下文。
  • runtime.channel.inbound.buildContext(...) 用于入站上下文负载。
  • runtime.channel.inbound.runPreparedReply(...),已弃用,仅用于通道自有的已准备分发路径,这些路径已经组装了自己的分发闭包。

turn 和 runPreparedReply 由 plugin-runtime-api-compat-aliases 兼容性记录承载,其最早移除审查日期为 2026-10-01。该日期是审查日期,而非计划移除日期:该别名会保留,直到所有已枚举的接口都被证明没有捆绑或已发布的读取方。

新插件代码不应引入以 turn 命名的通道 API。将模型或 agent 的 turn 词汇保留在 agent/provider 代码中;通道插件使用 inbound、message、delivery 和 reply 术语。

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw