通道辅助工具
频道专属运行时辅助函数,在加载频道插件时可用。属于 插件运行时辅助函数 参考的一部分;频道插件 是分步指南。
频道命名空间¶
api.runtime.channel
频道专属运行时辅助函数(在加载频道插件时可用)。按关注点分组:
| 分组 | 用途 |
|---|---|
text |
分块(chunkText、chunkMarkdownText、resolveChunkMode)、控制命令检测、Markdown 表格转换。 |
reply |
缓冲块回复分发、信封格式化、有效消息/人工延迟配置解析。 |
routing |
buildAgentSessionKey、resolveAgentRoute。 |
pairing |
buildPairingReply、允许列表读取/移除、配对请求插入或更新,以及由请求派生的审批条目。 |
media |
远程媒体下载/保存(见下文)。 |
activity |
记录/读取最近频道活动。 |
session |
来自入站事件的会话元数据、最后路由更新。 |
mentions |
提及策略辅助函数(见下文)。 |
reactions |
用于处理中指示的确认反应句柄。 |
groups |
群组策略和需要提及解析。 |
debounce |
入站消息防抖。 |
commands |
命令授权和文本命令门控。 |
outbound |
加载频道的出站适配器。 |
inbound |
使用主机绑定的 ingress 辅助函数解析入口,构建入站事件上下文,并运行共享的入站事件/回复内核。 |
threadBindings |
调整绑定会话线程的空闲超时/最大存活时间。 |
runtimeContexts |
注册、读取和监视进程本地的按频道/账户/能力上下文。 |
api.runtime.channel.media 是频道媒体下载和存储的首选接口:
const saved = await api.runtime.channel.media.saveRemoteMedia({
url,
subdir: "inbound",
maxBytes,
filePathHint: fileName,
});
当远程 URL 应成为 OpenClaw 媒体时,使用 saveRemoteMedia(...)。当插件已经获取了带有插件自有认证、重定向或允许列表处理的 Response 时,使用 saveResponseMedia(...)。仅当插件需要原始字节以进行检查、转换、解密或重新上传时,使用 readRemoteMediaBuffer(...)。fetchRemoteMedia(...) 仍然是 readRemoteMediaBuffer(...) 的已弃用兼容别名,在 兼容性注册表 中作为 plugin-runtime-api-compat-aliases 跟踪,removeAfter 日期为 2026-10-01。
对于不成功的 HTTP 响应,媒体错误会报告状态,并在可用时包含有界的响应体摘录。被丢弃的错误响应体不会被报告为空的上游响应。没有响应体的成功响应仍会被拒绝为空媒体。
远程媒体选项和来自 openclaw/plugin-sdk/ssrf-runtime 的 fetchWithSsrFGuard(...) 接受同步的 beforeRequest 回调,用于最终分发授权检查。它在代理、DNS 和分发器准备之后、每个物理请求之前立即运行。重定向会每跳调用一次;媒体重试会为每次尝试和每跳再次调用它。如果它抛出异常,则该请求不会发送,并且相同错误会传播。Promise 或 thenable 结果会在传输分发前被拒绝。
对于 saveRemoteMedia(...),当读取可能在响应体下载期间失去权限时,请传入同步的 assertCurrent 回调。媒体所有者会将其与任何外层读取范围组合,并在请求、流式传输和本地文件发布过程中重新检查它,在失败时清理未接受的文件。同时通过 requestInit.signal 转发取消。省略 assertCurrent 会保留现有行为;beforeRequest 仍然是按请求的钩子,而不是文件发布守卫。
受保护的 fetch 还接受同步的 resolveDispatcherPolicy(url) 覆盖,并为每个重定向重新评估。未定义的结果会使用 dispatcherPolicy,或者在未提供默认策略时使用直接路由。保留操作员配置的代理路由的提供者可以使用来自 openclaw/plugin-sdk/fetch-runtime 的 resolveEnvHttpProxyAgentOptions 和 matchesNoProxy 来选择每一跳。trusted_explicit_proxy 模式允许 HTTP、HTTPS、socks: 和 socks5: 代理 URL,并将目标 DNS 委托给显式信任的代理;代理主机验证和目标主机策略仍然适用。直接跳保持 DNS 固定。严格模式拒绝 SOCKS 代理,并且独立的 trusted-env-proxy 门控仍然仅限 HTTP(S)。
当为流式传输返回受保护的响应时,请使用来自 openclaw/plugin-sdk/fetch-runtime 的 responseWithRelease(response, release) 来保留请求所有权,直到其响应体完成、失败或被取消。显式消费或取消响应体以便及时释放;对废弃包装器的垃圾回收仅提供尽力而为的清理。
api.runtime.channel.mentions 是使用运行时注入的捆绑频道插件共享的入站提及策略接口:
const mentionMatch = api.runtime.channel.mentions.matchesMentionWithExplicit(text, {
mentionRegexes,
mentionPatterns,
});
const decision = api.runtime.channel.mentions.resolveInboundMentionDecision({
facts: {
canDetectMention: true,
wasMentioned: mentionMatch.matched,
implicitMentionKinds: api.runtime.channel.mentions.implicitMentionKindWhen(
"reply_to_bot",
isReplyToBot,
),
},
policy: {
isGroup,
requireMention,
allowTextCommands,
hasControlCommand,
commandAuthorized,
},
});
可用的提及辅助函数:
buildMentionRegexesmatchesMentionPatternsmatchesMentionWithExplicitimplicitMentionKindWhenresolveInboundMentionDecision
对于提及决策,使用归一化的 { facts, policy } 路径。
`reply`、`session` 和 `inbound` 下的若干字段带有逐字段的 `@deprecated` 说明,指向当前的频道轮次内核或频道出站适配器;在基于某个特定 helper 构建新代码之前,请检查其内联 JSDoc。它们共享同一个 `plugin-runtime-api-compat-aliases` 注册表记录,且 `removeAfter` 日期均为 2026-10-01。
回复选项接受 onVisibleWorkSessions(sessions),以便在最终回复投递之前接收已接受的可见工作会话,包括已结算运行失败的情况。每个描述符携带 sessionKey、规范化的 url 以及可选的 label;描述符按会话键以接受顺序去重。
需要等待的会话绑定变更¶
从
openclaw/plugin-sdk/conversation-binding-runtime 导入路由和服务 helper。
在发布绑定
变更之前,等待 service.bind(input) 和 service.unbind(input)。当前会话持久化使用现有的 worker owner,并在
提交前重新检查所选适配器。失败或不确定的写入
不会授权重放。已发布的同步选择器保留其当前
契约;捆绑的会话列表等待内部 owner。
对于同步目录所有权检查,频道可以实现
messaging.prepareConversationRouteOwners(inputs, inspectBindings)。它一次性准备绑定读取,
并为每个输入按相同顺序返回恰好一个同步 resolver。
Core 会立即调用这些 resolver,并保留标量 resolver 的
错误和回退处理。现有插件继续使用 resolveConversationRouteOwner。
准备好的事实不得在等待后存活,也不得用于后续权限检查。
对批次调用所提供的 inspectBindings(refs) 一次。它跨通用绑定和账户拥有的绑定执行一次
当前原生选择,同时保留外部适配器所有权。它仅在同步
准备期间有效,并拒绝后续使用。每次后续检查都会获得一个新的 inspector。
Slack 通过其未更改的 标量 resolver 保留其声明的 OpenClaw 2026.9.8 host 支持。旧版 host 不会调用可选的准备 hook。
在记录
绑定时,等待 getSessionBindingService().touchAsync(bindingId, at, scope)。适配器实现 touchAsync 以返回一个 Promise,该 Promise 会结算
其已接受的变更。异步分发优先使用该方法并传播其
失败;它不会同时调用旧版 touch。在调用
每个所选适配器之前,分发会检查其注册是否仍然当前有效。
它会跳过已退役的注册,而不会采用其替代项。
对于记录活动的路由,使用 resolveRuntimeConversationBindingRouteAsync。
它会等待所选变更,然后在返回其路由之前重新检查当前绑定。使用
await service.inspectByConversationAsync(conversation) 准备所有权事实,然后将这些事实传递给
inspectRuntimeConversationBindingRoute({ route, inspection })。此同步
投影不执行任何存储访问。检查保留缺失绑定与不可用适配器之间的区别,而不会创建缺失的
store 或修剪过期行。
inspectRuntimeConversationBindingRoute 和同步的
resolveRuntimeConversationBindingRoute 也接受延迟的 resolveRoute 回调,
而不是已完成的 route。
必须恰好传递 route 或 resolveRoute 之一;输入类型会拒绝同时提供两者
或两者都不提供。现有调用方可以继续传递已完成的路由。
该回调在 owner 对绑定进行分类之后、普通 agent 选择之前接收 { inspection, bindingOwnerAvailable, bindingRecord, boundAgentId }:
const result = inspectRuntimeConversationBindingRoute({
inspection,
resolveRoute: ({ bindingOwnerAvailable, boundAgentId }) => {
if (!bindingOwnerAvailable) {
throw new Error("Conversation binding owner is unavailable; retry the message.");
}
return resolveAgentRoute({
channel: "acme-chat",
accountId,
peer,
cfg: boundAgentId ? { session: cfg.session } : cfg,
defaultAgentId: boundAgentId,
});
},
});
从 openclaw/plugin-sdk/routing 导入 resolveAgentRoute。因此,即使普通 roster 需要显式
选择,绑定的 agent 也可以提供路由。Agent 作用域的会话键优先于 metadata;无作用域
目标可以使用 metadata.agentId。缺失的、被忽略的 cron-run 以及插件拥有的
绑定不会提供绑定的 agent。没有非空 metadata
agent ID 的无作用域目标也会使 boundAgentId 保持 undefined;它不会虚构一个默认 agent。
插件绑定保留其记录,以便
频道能够区分插件回退与未绑定父级查找。
inspection 保留准备好的会话身份,以便在其选定父级之前组合线程
观察,而无需再次读取绑定 store。
回调负责路由构建;core 仍然投影所选会话
和所有权事实。如果 agent 拥有的绑定选择了不同的 agent,core
会为该 agent 重建 mainSessionKey,同时保留基础路由的主键
名称,然后针对绑定 agent 的主会话推导 lastRoutePolicy。这
也适用于已完成路由输入,并保持普通路由不变,
用于频道特定的过期绑定比较。
在上下文构建过程中保留这些事实,以便回复
准入可以拒绝已撤销、已重新分配或不可用的 owner。当活动
必须保留已捕获的选择时,在投影后等待作用域化的 touchAsync,
并保留该路由用于准入,而不是静默选择替代项。
适配器提供 inspectByConversationAsync 用于只读检查,
以及 resolveByConversationAsync 用于普通查找。host 服务公开这两种
方法。通用绑定和捆绑的账户作用域适配器在
共享状态读取 worker 中运行检查;查找修复和活动写入使用现有的
writer broker。它们的事务谓词、过期规则和账户所有权
保持不变。host 资格在 IPC 之前准备,并在读取之后以及写入准入时重新检查当前适配器
和注册表所有权。
生命周期 setter 具有显式的返回 Promise 的对应方法:
channel.threadBindings.setIdleTimeoutBySessionKeyAsync 和
setMaxAgeBySessionKeyAsync。通道适配器暴露相同带后缀的方法。
调用方在报告受影响的绑定之前,需等待其结果。
现有的同步查找、touch、路由解析器和生命周期 setter 契约 将在下一个 Plugin SDK 主要版本中保持弃用。该解析器的分阶段 迁移已在此处和兼容性注册表中记录;其宽泛 barrel 已弃用,而按函数的 IDE 注释则推迟到 调用方迁移完成。同步入口点仅调用同步实现;它们绝不会启动一个结果会丢失的异步变更。 同时暴露两种变体的适配器会将它们置于同一状态所有者之下。
在分阶段迁移期间,当异步对应方法缺失时,异步分发将回退到适配器现有的 同步方法。这保留了外部插件兼容性;该回退不会使旧版适配器变为非阻塞。 通用和账户范围的绑定/解绑操作以及捆绑会话列表 使用共享状态 worker。它们已发布的同步选择器仍可通过 兼容性边界使用。独立的生命周期 setter 和其他捆绑 存储在各自切换之前保留其现有行为;此 执行变更不会增强其持久性契约。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw