跳转至

引导与事件

客户端如何在一次调用中引导会话列表、常见的网关事件族,以及节点辅助函数和 exec 生命周期契约。

会话列表引导

调用 sessions.subscribe 并传入非空的 sessions.list 参数对象,例如 { limit: 60, ownerFirst: true },可在一次请求中完成订阅并加载初始名册。成功的 WebSocket 响应载荷为 { subscribed: true, list },其中 list 是常规的 SessionsListResult。使用 {} 调用时,保持仅确认响应 { subscribed: true },并且不读取快照。列表参数用于选择快照;它们不会过滤该连接的会话事件订阅。

列表视图可传入 rowMode: "compact" 以省略重复的仅详情元数据:contextWindows、contextWindowDefault、thinkingLevels、thinkingOptions、thinkingDefault、toolOverrides、providerReview、nativeRuntimeConsent、contextBudgetStatus、agentRuntime 和 pluginExtensions。每个返回行都带有 rowMode: "compact";这些省略表示未请求详情,并且不得清除先前已接纳的详情字段。请使用 sessions.describe 或完整的 chat.history.sessionInfo 获取详情。省略 rowMode 会保留完整行契约。标题、预览和 Activity 摘要增强仍由其现有 include 标志控制。

控制 UI 列表请求使用紧凑行和有界的诊断 source:sidebar、dashboard、activity、sessions-page、chat-pane、agent-roster、command-palette 或 skill-workshop。该 source 不会更改选择或访问权限。列表行和事件行包含 hasBoard,即已准备好的仪表板成员资格事实,因此仪表板画廊可以应用行更新,而无需再次枚举其页面。在 Sessions 页面上展开紧凑行时,会使用 sessions.describe 读取其完整详情。行还带有 childOwnerSessionKeys,即 Gateway 的 spawnedBy 过滤器当前使用的保留所有者。这些回执包含运行时控制器和导航所有权,并通过同一所有者过期,使子窗口能够应用事件,而无需在浏览器中重新实现保留规则。

Gateway 在投影列表之前注册订阅。客户端必须在发起请求前监听 sessions.changed:在快照构建期间可能会收到事件。需要将这些事件与响应进行协调,并在必要时发出尾随的 sessions.list 刷新,包括当事件仅使缓存列表失效时。重连需要新的订阅和快照。

Gateway 在内存中保留持久会话元数据,并在正常启动完成前完成初始行物化。重连客户端可以在 Gateway 就绪后立即读取初始名册。已提交的所有者变更会增量刷新受影响的行;响应消费当前行事实,不存在陈旧窗口。键控描述、解析和聊天启动会准备其请求的行,而无需等待批量刷新。新接纳或替换的存储只加载一次其元数据,当其存储离开当前拓扑时,行会消失。每个响应都应用当前查看者的可见性和当前活动时间。等效查看者共享不可变的行表示和编码行字节,直到其投影事实发生变化;snapshotAt 保留行的采样时间。运行时权限、权限变更和基于时钟过期的事实在复用前会被检查。具有相同身份、共享策略和查询的 WebSocket 视图也在当前行发布内共享选择和切面。依赖实时运行、时钟窗口、子项保留或搜索的查询会在每次读取时重新选择。每次读取都呈现当前行;未变更的行共享其数组和组装后的 JSON 字节。进程内调用者保留其自己的选择和行包装器,用于授权增强。

常驻行使用已存储的标题和用量。可选的消息预览和终端回退模型元数据通过有界的只读后台转录读取填充;它们可能不存在于早期响应中。前台请求优先。这些读取不会恢复冷归档、解析超大消息、调用模型,或更改已存储元数据或会话活动顺序。缺失的历史标题和旧版 ACP 键只能由 openclaw doctor --fix 修复。缺失的用量在正常用量写入器记录之前保持缺失。

两种方法都接受 activeOnly: true,以在分页之前选择当前正在运行或排队中的会话。活动来自实时运行时所有者,而不是已存储的状态标志。当省略该选项或为 false 时,常规列表行为不变。仅活动的结果包括每个可见的、由 agent 拥有的 global 和 unknown 会话,并带有其原始键和捕获的 agentId;调用方需同时通过 agent、key 和 sessionId 标识行。字面量 agent:<id>:global 和 agent:<id>:unknown 会话仍为不同行。仅活动的原始哨兵行会省略可选的 childSessions 和 hasActiveSubagentRun 字段;请使用 hasActiveRun 表示直接活动。常规权限、归档/包含过滤器和页面限制仍然适用。无会话/内部运行位于会话索引之外。

两种方法都接受 ownerFirst: true,以在常规第一页之前添加最多 60 行匹配的查看者拥有的行(或更小的 limit),并按会话键去重。这仅在 offset 为零或省略时适用;后续页面使用常规分页。拥有的行必须通过共享页面相同的可见性和列表过滤器。Gateway 从已认证连接解析查看者;客户端提供的身份不会选择这些行。如果没有已认证的查看者身份,或 ownerFirst 为 false 或省略,列表使用常规排序。

共享页面仍决定 limitApplied、offset、nextOffset、hasMore 和 totalCount。前置行可能使 sessions.length 和 count 超过共享页面大小。使用 nextOffset 前进,并跨页面按会话键对行去重;不要从显示的行数推导下一个偏移量。

会话消息订阅与旁白

sessions.messages.subscribe 将一个连接订阅到某个会话的实时消息。其 key 和可选 agentId 用于选择会话;这与上文较宽泛的名册订阅相互独立。省略 mode 表示完整的 chat 和 agent 流,包括前台转录以及由其他客户端启动的运行所对应的被动视图。重复请求会替换该观察者的订阅模式。 sessions.messages.unsubscribe 移除由相同可选 subscriptionId 标识的观察者;省略时选择旧版观察者。 订阅确认包含规范化的 key 和解析后的 agentId。 客户端保留解析后的所有者,用于后续的 global 请求;仅凭 key 无法标识某个 agent。SDK 会为每个线路观察者发送一个稳定的不透明 subscriptionId,并在重新订阅和取消订阅请求中包含它。 对于同一连接和会话上的多个 ID,完整流兴趣优先,直到其最后一个所有者释放;只要有任何所有者请求审批,审批就保持启用。省略 ID 会保留旧版单观察者行为。 旧版客户端仍与更新后的 Gateway 兼容;更新后的 SDK 的所有权字段需要更新后的 Gateway。

后台旁白消费者声明 mode: "narration"。Gateway 会用 session.narration 快照替换其 token 级 chat 增量和原始 agent 助手事件。每个快照包含 sessionKey、可选 agentId、runId 和 text:当前可见助手尾部最多 16,384 个字符。在限定尾部长度之前,会移除隐藏推理和内部上下文。空 text 会撤回之前的旁白。消费者可以从该文本派生出一行紧凑内容,而无需重建 token 增量。

首个文本更新可以立即到达。后续快照在每个会话、每个连接上最多每两秒到达一次,使用最新文本,且不会推迟待处理的截止时间。终结 chat 事件会在终结事件之前立即刷新最后一个快照,包括最终文本更正或撤回;此最终刷新不受两秒间隔限制。 更新的工具活动或运行变更会丢弃待处理的旧文本,因此延迟快照不会替换更新的工具行,也不会将侧边栏切换回较早的运行。 生命周期、状态、工具、最终、中止和错误事件保留其现有投递方式。原始思考流以及进行中的前言或答案候选文本会被省略;条目完成和答案选择仍会到达。审批事件仍需要 includeApprovals: true 和正常的审批权限。排队中的旁白会在取消订阅、模式变更、连接退役或运行退役时丢弃,并且投递会重新检查当前访问权限。

Gateway 客户端 SDK 在本地所有者之间共享匹配的会话地址。 Gateway 还会合并独立标识但解析到相同订阅 key 的观察者。如果任何所有者需要完整流,投递保持完整;只有最后一个完整流所有者释放后,才会恢复为旁白。 共享前台订阅的旁白消费者也必须接受完整流事件。Control UI 在获取历史之前会等待前台准入,因此快照会覆盖在启用完整流之前发出的活动。

捆绑的 Control UI 会为侧边栏兴趣声明旁白意图。它与 Gateway 版本锁定,并在升级时重新加载。共享的 Apple 聊天客户端对前台会话使用默认的完整模式;Android 和 TUI 保留其广泛的事件投递。现有 SDK 调用方以及省略 mode 的旧版客户端保留完整流。因此,自定义 UI 根、开发 UI 以及豁免构建准入的跨源 UI 可以保留完整流旁白,直到更新。这是一个增量式 protocol-v4 契约,不涉及能力协商或协议版本变更。

常见事件族

  • chat: UI 聊天更新,例如 chat.inject 和其他仅转录的聊天事件。 state: "delta" 负载在 deltaText 中携带追加内容。 为某个运行投递给接收方的首个文本帧也包含完整的 message 快照,包括该接收方在运行中途接入或重新连接时。 后续追加帧省略 message。提供的快照是权威的,并且已包含 deltaText;不要将增量追加两次。 非前缀替换会设置 replace=true,并将 deltaText 用作整个替换文本,包括用空字符串清除它。 需要新基线的替换以及画布或媒体变更会包含完整快照。 客户端在普通文本追加过程中保留非文本消息块。最终、中止和错误事件保留其现有的完整消息和有意省略消息语义。 待处理追加会按顺序拼接;工具边界和终结边界会在落定之前刷新待处理文本。 失败运行(state: "error")可能包含 errorDetail,与粗粒度 errorKind 和人类可读的 errorMessage 一起提供。 这个封闭对象有七个可选字段:provider、model、failoverReason、 providerRuntimeFailureKind、providerErrorType、httpStatus 和 providerErrorMessagePreview。字符串上限为 300 个字符;httpStatus 是 100 到 599 的整数。详情来自失败尝试的 已净化 provider 观察,而不是重新解析面向用户的消息。 预览会进行凭据脱敏,并且可能短于协议上限。 原始正文、原始预览和诊断哈希绝不会包含在 errorDetail 中。没有 provider 观察的运行省略它;成功和 中止事件不携带它。这是一个增量式 protocol-v4 字段。
  • agent: 助手文本事件使用 data.delta 进行追加。可选 data.text 是该助手条目的权威快照,并且已包含增量。 首个投递的文本事件、替换/条目边界以及媒体 更新会在需要时保留快照。遵循 data.replace(包括空 替换),并将助手条目文本与显示投影的 chat 流保持分离。为一个显示订阅一个文本投影;将两个流都消费到一个累加器中会重复输出。进程内 agent 观察者 保留其累积文本契约。 仅从 chat 渲染助手文本的客户端可以在其连接 caps 中声明 chat-only-assistant-text。然后 Gateway 会从该连接省略 携带文本且 stream: "assistant" 的 agent 事件, 包括前台和后台旁白订阅。其他 agent 流(工具、条目、用量、运行状态、生命周期、计划和审批)、 无文本的助手事件以及 chat 流保持不变。被过滤 的帧不会消耗连接序列号。不具备该能力的 客户端保留两个投影;将当前条目 agent 文本与累积聊天文本分开显示的原生客户端不应声明它。
  • session.message、session.operation、session.tool: 已订阅会话的转录、进行中的会话操作以及事件流更新。
  • session.narration: 具有旁白意图的订阅的有界助手文本快照,其节奏和落定方式如上文所述。
  • session.approval: 为明确选择加入的精确会话订阅者提供已净化的待处理和终结审批事实。子审批使用持久化的祖先受众;事件绝不会修改转录或唤醒 agent。
  • session.observer: 安全的实时会话标题和状态摘要。模型撰写的前言可以立即更新标题;工具模型评估会在可用时稍后替换它。Web、iOS 和 Android 使用相同的运行范围摘要。 工具模型回复可能将 JSON 摘要包裹在一个普通或 json Markdown 围栏中;周围散文和无效摘要字段会被拒绝。如果重复 的无效回复导致该运行禁用观察者,警告会包含最后一次被拒绝回复的脱敏、 空白折叠前缀,上限为 160 个字符。 可选 sessionId 和不透明 lifecycleRevision 标识会话 生命周期;lifecycleRevision 在首次重置之前可能缺失。修订 号在该生命周期内的多次运行中递增,但在重置后可能重新开始。 /clear 保留 sessionId 并更改 lifecycleRevision。 客户端仅在摘要的确切 runId 存在于 activeRunIds 中时显示其标题或检查器链接。
  • sessions.changed: 会话索引或元数据已变更。带 key 的变更会在 session 中携带受影响行,并针对该连接呈现。sessions.changed 和 session.message 中的嵌套行使用与 sessions.list 相同的完整预置元数据、查看者权限和时钟,并启用标题、最后消息和活动摘要增强。这会在事件行中添加目录支持的字段(例如思考选项),并用规范模型 ID 替换旧版模型别名。Control UI 会在本地将这些行应用到现有名册成员,因此其值与列表匹配。显式的模型、账户或运行时选择也可以将事件标记为 catalogChanged: true。 完整行可以包含 sessionModelRevision,它会随已保存的模型、账户、运行时和生命周期输入而变化,独立于标题和活动。 可见的 Control UI 窗格保留匹配的模型目录,并立即刷新已变更的选择。缺失的修订和显式 catalogChanged 提示仍会使目录失效。会话事件保留 agent 的命令列表;chat.metadata.changed 会使命令失效,除非 commandsChanged: false。 仅用量和仅模型发布会保留命令可用,无需另一个元数据 RPC。 顶层生命周期和容量字段仍为事件回执,包括显式清除值。当嵌套行省略某个可选字段时,遵循其顶层清除墓碑;存在嵌套值时,嵌套值优先。当查询的成员资格和分页窗口仍然有效时,在本地合并现有名册成员的快照。Control UI 会复用生命周期以及普通 patch、participants、placement、send、steer、agent.run.started、agent.input.settled、run-capacity 和 chat.title 快照,用于身份、归档、置顶、所有者和父级事实未变且新近度非递减的持有行。带 key 的 sessions.changed 和 session.message 发布还会携带 ancestorSessions,即受影响导航、控制、请求者和 swarm 祖先的完整行数组,并可能携带 ancestorSessionRefs,用于已在该连接上投递且未变更的祖先呈现。引用绝不会出现在 ancestorSessions 内部。 投影会沿现有父引用向上遍历到根,对物理行身份去重,并停止循环。每个祖先都会经过与 sessions.list 相同的按查看者可见性过滤和呈现;不可见的中间项不会阻止投递它们上方的可见祖先。 这两个数组合计最多包含 64 个祖先。如果某个祖先无法解析或遍历超过该上限,则省略这两个字段,以便客户端保留权威刷新行为。ancestorSessions 的存在证明两个数组共同覆盖完整的可见祖先;空数组仅在 ancestorSessionRefs 也缺失或为空时,才证明没有可见祖先。这些是增量式 protocol-v4 字段;它们不改变订阅范围或列表成员资格,也不需要能力协商。 完整祖先行携带不透明的 ancestorRevision;每个引用包含 key、revision 和 snapshotAt,如果完整行中存在 sessionId 和 agentId,则也包含它们。在添加修订标签之前,Gateway 会比较确切的连接特定呈现行,仅排除 snapshotAt。一个引用

证明由 revision 标识的展示保持不变。客户端仅在仍持有该精确的已接纳展示且标识匹配时,才保留被引用的行,然后推进其时钟而不改变其其他事实。Control UI 仅在确认其事实与完整展示行匹配后,才将该修订绑定到不可变的已接纳行。列表替换或本地行变更会失去该证明,即使其采样时钟恰好匹配。缺失的行、代际或修订不匹配,以及不确定的展示所有权,都需要现有的权威刷新路径。Gateway 会约束此每连接记录,并在首次投递、成功的列表读取、重连、重新订阅、重置/删除、展示或可见性变更、逐出或投递不确定之后发送完整行。取消订阅和断开连接会清除该记录;会话删除会使记住的祖先失效。仅回顾(reason: "activity-summary")事件会保留其祖先负载,但这些事件中的完整行会使相应引用记录作废:共享名册可跳过回顾接纳。下一个普通事件会再次提供完整行;客户端已持有的未变更引用仍可复用。旧版 Web 客户端会忽略新增的引用字段。由于 ancestorSessions 仅包含完整行,它们不能将引用作为部分行应用并擦除已持有字段。缺失的祖先快照会触发其现有的权威 sessions.list 刷新。捆绑的同源 Control UI 构建接纳可防止版本偏差;自定义根、开发 UI 和跨源客户端可以使用这条正确但较慢的路径。原生 Apple 和 Android 客户端、TUI 以及 SDK 不会协调祖先行,并保留其现有行为。客户端会一起应用子行和已持有的完整祖先行,并遵循每行的标识和时钟。在完整快照中,省略的可选行事实会清除先前持有的值,包括子链接、swarm 摘要和后代运行标志。非空的传统顶层行字段不会填充完整、按查看者过滤的行中的省略项。显式 null 清除回执和独立的生命周期回执仍然有效。现有的可选标题/预览增强和 thinking 元数据保留规则仍然适用。Control UI 会为缺失的行或快照、广泛/无键变更、catalogChanged、无法从行事实确定成员资格的过滤器、不完整的祖先快照以及不确定边界(包括被提升到共享页面的 owner-first 行)合并一次权威刷新。与名册读取重叠的事件会保留一个尾部刷新,以确保其响应不会丢失更新。带有读取错误的保留列表也会在下一个相关事件时刷新。个人资料标识、runner 可用性以及已加载的 cron 绑定可能产生广泛失效。仅活动摘要的发布会更新已选择加入的 Activity 消费者;共享会话和 agent 名册不会为这些仅回顾变更重新获取。已持有行的更新会在不重新获取的情况下保留未过滤和仪表板过滤的窗口;标题和预览增强标志不会改变成员资格。健康的行流量会在至少 60 秒后保留一次回退读取。仪表板分页属于共享名册窗口,该窗口会在行更新之间保留已加载页面,并合并同一查询的并发读取。子窗口使用 Gateway 的所有权回执和完整的父级子列表。已认证的排除祖先行可以跳过;引用需要来自该连接共享来源所有者的已接纳当前行。侧边栏所有者计数 facet 也会在已接纳的旧行和新行事实证明贡献未变更时保留其聚合值。运行状态、所有权、共享、归档或不确定的过滤器变更仍需要权威计数读取。在突发期间,已准备的行发布会在有限切片之间让出。同一会话代际的待处理活动摘要更新共享最新快照;生命周期、容量、转录、删除和清除回执仍然相互独立。发布会在每次让出后重新检查行就绪状态。已接纳的回顾通知会存活于触发它们的压缩或调度器工作之后。关闭会停止新通知,并在关闭客户端和释放其投影之前等待已接纳的发布。已授权的隐身描述和事件使用来自临时进程本地状态的相同行展示。隐身行仍被排除在会话名册之外,且排队事件不能跨越重置或数据库替换。工具/进度事件在行刷新期间继续投递;其可选行元数据在就绪前可能缺失。在带键的 sessions.changed 和 session.message 快照上,完整名册行仍得到保证。活动运行字段使用与 sessions.list 相同的聚合和完整精确语义;activeRunIds: null 会将缓存的精确标识清除为不可用,省略会使缓存保持不变,而数组会替换它。来自 sessions.delete 和隐身重置的删除通知携带被移除代际的 sessionId,而不携带当前行快照。客户端不得删除具有不同 ID 的替换项。仅键删除事件或无行全局通知会使规范会话列表失效;它不会将当前代际标识为已删除。 - presence:系统在线状态快照更新。 - tick:周期性保活/存活事件。 - health:Gateway 健康快照更新。 - heartbeat:心跳事件流更新。 - cron:cron 运行/作业变更事件。 - shutdown:Gateway 关闭通知。 - node.pair.requested / node.pair.resolved:节点配对生命周期。 - node.invoke.request:节点调用请求广播。 - device.pair.requested / device.pair.resolved:已配对设备审批生命周期。 - device.pair.setup.completed:精确设置代码交接完成,作用域为 operator.pairing。 - device.pair.setup.deliveryUncertain:可重放安全的设置代码退役,其凭据响应投递无法确认,作用域为 operator.pairing。 - voicewake.changed:唤醒词触发配置已变更。 - plugins.changed:插件运行时发布完成。负载为 { generation };刷新 plugins.list 以协调已安装状态和运行时状态。 - config.changed:配置写入已持久化(负载携带配置路径、新的快照哈希和时间戳——绝不携带配置内容)。作用域为操作员读取;客户端通过 config.get 刷新。 - skills.changed:在网关使其技能快照失效后,连接性、技能目录、配置或资格发生变更。负载的 reason 为 watch、watch-targets、manual、remote-node、config-change 或 workshop。作用域为操作员读取;客户端通过 skills.status 刷新。 - exec.approval.requested / exec.approval.resolved:exec 审批生命周期。 - plugin.approval.requested / plugin.approval.resolved:插件审批生命周期。

节点辅助方法

节点可以调用 skills.bins 获取当前技能可执行文件列表,用于自动允许检查。

节点 exec 生命周期事件

节点通过节点角色的 node.event RPC 报告 system.run 生命周期,事件为 event: "exec.started"、"exec.finished" 或 "exec.denied"。这些不是操作员的 exec.approval.* 广播,也不使用已弃用的 TCP 桥接。

该 RPC 接受 payloadJSON 中的 JSON 字符串或 payload 中的对象。当两者同时提供时,字符串形式的 payloadJSON 优先。示例:

{
  "event": "exec.finished",
  "payload": {
    "sessionKey": "agent:main:main",
    "runId": "<exec-run-id>",
    "host": "node",
    "exitCode": 0,
    "timedOut": false,
    "success": true,
    "output": "done"
  }
}

当前无头节点包含 sessionKey、runId 和 host: "node"。其他字段如下:

字段 含义
command 原始或格式化后的命令文本。
exitCode、timedOut 进程完成代码和超时标志。
success 生产者结果标志,不是通知门控谓词。
output 有界的合并 stdout、stderr 和错误文本。
reason exec.denied 的拒绝原因。
suppressNotifyOnExit 抑制本次调用的系统通知。

回显随 system.run 转发的关联字段;ID 或 payload 的 host 字段均不授予权限。Gateway 会匹配已认证的节点和连接、运行 ID,以及当调用绑定了会话键时的会话键。未匹配的事件返回 handled: false,并带有 reason: "unmatched_exec_event",且不会产生系统通知。一个有限的旧版 macOS 客户端路径可能仅将缺失或不匹配的运行 ID 匹配到该连接/会话上的一个无歧义调用;新客户端必须发送已签发的运行 ID。

exec.started 保留授权记录;exec.finished 和 exec.denied 在通知过滤之前消费它。tools.exec.notifyOnExit: false 或 suppressNotifyOnExit: true 会抑制通知。被拒绝的事件永远不会入队系统事件或唤醒 agent 工作。完成事件仅在超时、非零或未知退出代码、或非空压缩输出时通知;成功退出 0 且无输出时保持静默。带有运行 ID 的完成通知会按规范会话和运行 ID 去重。只有在系统事件入队后,才会请求心跳唤醒。

节点事件投递是尽力而为的,不是持久完成台账。

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