将提供方会话 ID 映射到 OpenClaw 会话,并负责其路由与绑定规则。本文属于构建渠道插件指南的一部分。¶
会话会话语法¶
如果你的平台在会话 ID 中存储了额外的范围信息,请将该解析逻辑保留在插件内,使用 messaging.resolveSessionConversation(...)。这是将 rawId 映射到基础会话 ID、可选线程 ID、显式 baseConversationId 以及任意 parentConversationCandidates 的标准钩子。当返回 parentConversationCandidates 时,请按从最具体的父级到最宽泛/基础会话的顺序排列。
messaging.resolveParentConversationCandidates(...) 是一个已弃用的兼容性回退,供那些只需要在通用/原始 ID 之上提供父级回退的插件使用。如果两个钩子都存在,核心会优先使用 resolveSessionConversation(...).parentConversationCandidates,仅当标准钩子省略了候选时,才会回退到 resolveParentConversationCandidates(...)。
那些需要在渠道注册表启动前进行相同解析的内置插件,可以暴露一个顶层 session-key-api.ts 文件,并提供相应的 resolveSessionConversation(...) 导出(参见 Feishu 和 Telegram 插件)。核心仅在运行时插件注册表尚不可用时使用这一对启动过程安全的接口。
当插件代码需要规范化类似路由的字段、将子线程与其父路由进行比较,或从 { channel, to, accountId, threadId } 构建稳定的去重键时,请使用 openclaw/plugin-sdk/channel-route。该辅助函数与核心使用相同的方式规范化数字线程 ID,因此应优先使用它,而不是临时进行 String(threadId) 比较。具有提供方专属目标语法的插件应暴露 messaging.resolveOutboundSessionRoute(...),以便核心无需解析器适配层即可获得提供方原生的会话和线程标识。
从属主派生的心跳路由会向该解析器传递 deliveryPurpose: "heartbeat-owner"。插件可以利用它来解析缺失的操作者投递上下文,而无需为其他出站调用方放宽目标要求。
会话路由归属¶
当通用路由匹配无法复现渠道已配置及运行时的绑定规则时,请实现 messaging.resolveConversationRouteOwner(...)。该解析器会接收当前配置、账户以及已记录的会话标识,并在此标识与路由对端不同时接收投递 target。它必须复用与入站路由相同的优先级和提供方标识语法。
归属检查是同步且只读的。不要刷新绑定活跃状态、执行网络请求或推断缺失的提供方事实。返回:
{ kind: "agent", agentId }:代理(agent)拥有的路由。{ kind: "plugin", pluginId, fallbackAgentId }:插件拥有的运行时绑定。fallbackAgentId是在该插件没有活动入站认领处理器时使用的路由。{ kind: "unavailable" }:权威属主状态暂时不可用,调用方应重试。null:提供的标识无效或无法获得授权,包括已被移除或禁用的账户。保留的该账户会话历史不得导致活动账户列表失败。undefined:委托给核心的通用属主解析。
请将临时的不可用状态与 null 区分开:适配器重启并不能证明之前绑定的会话已无属主。
请使用 openclaw/plugin-sdk/conversation-binding-inspection-runtime 中的 inspectConversationBinding(...) 及其 ConversationBindingInspection 结果来区分“可用/不可用”。这个公开的检查辅助函数是同步、只读的,并且不会刷新绑定活跃状态。
账户级会话绑定支持¶
当渠道支持通用的当前会话绑定时,设置 conversationBindings.supportsCurrentConversationBinding。createChatChannelPlugin(...) 默认将此静态能力设置为 true。如果渠道的 monitor(监控器)拥有自定义绑定适配器,则还必须设置 bindingStore: "adapter";这样在该适配器不可用时,核心会失败关闭(fail closed),而不是读取或写入通用绑定行。较旧的、仅使用 createManager 的插件保留相同的适配器持有行为。
如果支持情况因所配置的账户而异,还应实现 conversationBindings.isCurrentConversationBindingSupported({ accountId })。核心仅在静态能力启用后才评估这个同步钩子。返回 false 会使该账户的通用当前会话能力(capability)、bind、lookup、list、touch 和 unbind 操作均不可用。省略该钩子会将静态能力应用于每个账户。
应基于已加载的账户配置或运行时状态来解析该答案。此钩子仅控制通用当前会话绑定;它不会替代已配置的绑定规则或插件拥有的会话路由。契约测试应通过 openclaw/plugin-sdk/channel-core 导出的 ChannelPlugin["conversationBindings"] 契约,至少覆盖一个受支持的账户和一个不受支持的账户。
绑定 ID 在一个渠道和一个账户范围内是局部的。SessionBindingService.touchAsync(bindingId, at?, scope?) 和 unbind({ bindingId, reason, scope }) 接受可选的 { channel, accountId } scope 来选择该属主。对于单个变更,将现有绑定的 conversation 作为 scope 传入。例如,要解除一个已解析的绑定:
await getSessionBindingService().unbind({
bindingId: binding.bindingId,
scope: binding.conversation,
reason: "manual",
});
从 openclaw/plugin-sdk/session-binding-runtime 导入 getSessionBindingService。对于活跃度更新,请使用 await service.touchAsync(binding.bindingId, at, binding.conversation)。仅在有意进行全局清理或执行现有的旧版跨渠道操作时省略 scope。Scope 不会更改绑定 ID,也无需新的适配器方法。
刷新相同的目标会话和目标类型会保留省略的运行时元数据。替换其中任何一个都会使目标元数据重新开始,因此新会话无法继承之前的插件属主、代理或标签。请将会话传输细节和显式的生命周期设置与目标元数据分开保存。
使用来自
openclaw/plugin-sdk/thread-bindings-session-runtime 的
resolveThreadBindingLifecycle(...) 处理标准空闲和最大存活时间过期。具有不同旧版时间戳约定的插件可以在同一子路径上,将准备好的 inactivityExpiresAt 和 maxAgeExpiresAt 值传递给 resolveThreadBindingExpiry(...)。它会选择较早的截止时间及其原因,在截止时间相同时优先选择空闲过期;省略的截止时间视为禁用。插件仍负责时间戳验证和时长默认值。
在同一子路径上,projectThreadBindingRecord(...) 会投影准备好的会话身份和过期信息,并带有显式的元数据合并回调。
createAccountScopedBindingAdapter(...) 为带账户前缀的绑定 ID 共享 list、resolve、touch 和 unbind 分发。插件的管理器仍负责存储、变更准入和结算、子项创建以及关闭。具有不同身份语法的平台(例如 Matrix 父房间键)可以在不使用带账户前缀适配器的情况下使用投影。
在投影绑定记录时,保留不透明的插件所有权元数据。
插件拥有的目标不需要 OpenClaw agent id;在解析 agent 之前,请使用来自
openclaw/plugin-sdk/conversation-binding-runtime 的
isPluginOwnedSessionBindingRecord(...) 将它们与 agent 拥有的目标区分开。
对于具有无作用域会话键(例如 global)的 agent 拥有的目标,请保留
metadata.agentId,以便路由保持绑定的所有者。agent 作用域的目标键相对于冲突的元数据仍具有权威性。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw