跳转至

会话控制

会话控制 RPC 系列:会话列表与过滤、消息发送与流式传输、运行生命周期和会话维护。

会话行包含 snapshotAt,即 Gateway 的采样时间,以 Unix 纪元以来的毫秒数表示。缓存行保留其原始采样时间。客户端使用它来排列读取快照的顺序,包括那些不推进持久化 updatedAt 的仅运行时变更;请求顺序可打破同时刻的平局。不带采样元数据的读取观察仍按请求顺序进行协调。此读取时间戳不会取代事件排序或会话身份检查。

一旦会话存储被准入,针对直接会话目标的授权将仅准备所请求的行。脏目标必须在授权前通过规范验证;不相关的行继续在后台验证。准备完成后,会再次检查方法作用域、配置文件绑定和启动可用性。sessions.list 首先对调用者的作用域进行授权,并将行有效性和可见性过滤交给会话读取器处理。

sessions.describe 和 sessions.get 是连接绑定的观察操作。在途准备结束后,断开连接会取消后续的行准备重试,包括授权期间正在进行的准备。重新连接并发出新的读取请求以获取当前结果。已接受的会话变更保留其既有的完成生命周期。

更改会话的模型或原生运行时许可可能需要等待运行时准备。在等待期间,其他会话仍可被创建或更新。对同一会话的更改保持有序;如果某个准备好的更改在提交前其捕获的会话状态已发生变化,该更改将被拒绝。

sessions.create、sessions.patch、sessions.patchMany 中的模型目录读取,以及通过 sessions.catalog.continue 进行的 Gateway 复制,每个请求共享 20 秒的预算。目录停滞或调用者取消时,会在受影响的会话变更提交前返回可重试的 UNAVAILABLE。sessions.patchMany 保留有序的逐目标结果;独立的成功目标保持已提交状态。

会话列表顺序会随着已提交的会话元数据变更而增量更新。每个请求在分页前仍会应用当前的可见性、活动和时间过滤器。当显示行从内存中释放时,已归档会话会保留其列表位置。

会话控制

  • sessions.catalog.list 列出外部会话目录。当客户端需要目录 ID、标签、能力和共享路由元数据而无需枚举主机或会话时,请传入 metadataOnly: true。此模式返回带有 hosts: [] 的正常目录对象;它保留代理和目录选择,跳过行过滤/分页,并且不发出主机进度事件。省略该标志可进行完整列出,包括终端选择所需的主机可用性。Control UI 使用仅元数据发现来支持新会话选择器和设置中的隐藏来源标签。
  • sessions.catalog.import(operator.write)在普通 Gateway 会话中保留一份可读的目录记录。传入 { catalogId, hostId, threadId, agentId?, sourceHomeId?, displayName? };调用者可见性和提供方解析与目录读取一致。可选的 displayName(1–500 个字符)仅设置新建导入记录的展示标题;已有导入记录保留其标题。Control UI 和 CLI --all 在可用时提供目录行名称;没有标题的导入记录使用 Imported <catalog label> session。最终结果是 { sessionKey, importedItems, totalItems, complete, created },项目计数为非负整数。importedItems 统计新追加的源项目数量,totalItems 统计已读取的源项目数量,created 报告目标会话是否已创建。对同一代理重新导入相同的定位符会复用其会话,并且仅追加未见过的项目。导入保留最近最多 50,000 个项目或 64 MiB 的历史记录,并沿用现有的逐项目文本限制;complete: false 表示较旧的历史记录因边界限制而被省略。它记录来源出处,并将内容标记为不受信任的参考材料,不包含原生延续、模型锁或节点运行绑定。参见 导入记录。
  • sessions.list 返回当前会话索引;当配置了代理运行时后端时,还包括逐行的 agentRuntime 元数据。hasActiveRun 是权威的聚合直接会话活动事实。当投影该字段时,activeRunIds 是完整的精确活动集合;空数组证明会话处于空闲状态。如果聚合活动为真但该字段被省略,则表示另一个运行时所有者处于活动状态,但其精确身份不可用。快照中省略该字段意味着身份不可用。在增量事件中,省略意味着没有变化;null 是仅出现在事件中的墓碑标记,用于将缓存的精确 ID 清除为不可用;数组则替换缓存。客户端只关联其在本地拥有或从请求、历史记录或事件中收到的精确 ID,绝不会选择列表中的第一个条目作为所有者。当启用云工作器部署或存在持久恢复状态时,会话行还包含一个封闭的 placement 状态(local、requested、provisioning、syncing、starting、active、draining、reconciling、reclaimed 或 failed),以及特定于状态的环境、所有者纪元、工作区、捆绑包、ACK 游标或恢复字段。工作器和终端部署可能包含 providerId、profileId 和一个可选的封闭 machine 对象:class(1–128 个字符)、os 和 osLabel(各 1–64 个字符),以及整数 cpu 和 memoryGb(各 1–65,536)。每个机器字段都是可选的;未知字段和空的机器摘要会被省略。Class 和 OS 使用所选覆盖值或提供方目录默认值,标签和容量来自该目录。在目录可用之前,只会出现已知的 class 和 OS 覆盖值。本地和已请求的部署永远不会携带机器身份。活动部署可能包含一个提示性的 diskSpace 样本,带有 status(ok、warning 或 critical)、availableBytes、totalBytes 和 observedAtMs。当 Gateway 正在传输或节点正在安装新运行时,provisioning 和活动部署可能包含 workerRuntimeInstall:phase(transferring 或 installing)、transferredBytes、totalBytes、startedAtMs 和 updatedAtMs。安装落定后,此进程本地进度会清除;进度变化会发出 sessions.changed。活动的配对设备部署还包含 runner: { kind: "device", status: "available" | "offline", deviceId? };deviceId 指定承载该部署的配对设备(即 autoDevice 调度所选的主机),非设备部署则省略该字段。此可用性是进程当前的,来源于精确的活动环境绑定和重连作用域的节点运行器证明,并且在 Gateway 重启后以离线状态开始,直到该运行器重新连接。运行器可用性变化仅为受影响的活动设备部署发出带键的 sessions.changed 快照,因此客户端无需重新加载会话列表即可更新所持有的行。仅容量的库存变更不会使会话行失效。行携带所有权投影——写一次的 createdActor、可变的 owner(参与者加 assignedBy/assignedAt)、有界的 participants 列表(排除所有者,最多 4 个参与者)以及完整的 participantCount;参与者显示标签和头像在读取时从当前配置文件和代理身份解析。传入 creatorId 按不可变的 createdActor.id 过滤;传入 ownerId 按当前可分配的所有者过滤,未分配所有者时回退到 createdActor。完整的 owners 分面独立于分页,并且不受任一查询过滤,因此客户端可以渲染完整的所有者选择器。经过身份验证的调用者可以传入 involvingMe: true,仅保留调用者拥有或向其发送过提示的会话,并依据完整的参与者历史记录(仅限有配置文件支持的人类参与者)进行评估。
  • sessions.list 接受 excludeDock: true,在所有者/人员分面、计数和分页之前省略使用 surface: "plugin-dock" 创建的对话。行在暴露 createdSurface: "plugin-dock" 的同时也暴露 isDock。常规的 Control UI 发现流程和 Workboard 名册使用此过滤器;精确会话读取和深链接保留其正常的访问检查。sessions.search.scope 接受相同的过滤器。
  • sessions.list 接受 includeOwnerSessionCounts: true,为有效的人类配置文件所有者返回包含 { profileId, open, running } 的完整 ownerSessionCounts 数组。计数在分页之前使用调用者可见的匹配会话,并将合并的配置文件解析为其规范身份。open 统计未归档的会话;running 在会话具有直接执行的代理轮次工作或活跃的委派子代理后代时,使用与会话行相同的后代活动投影对每个对话计数一次。它包含仅后代的工作以及保留子会话中的后续轮次,但排除排队中的仅直接工作和过时的已存储运行状态。所有列表过滤器仍然适用。对于侧边栏范围的摘要,省略 agentId 和时间/搜索/所有者过滤器,排除全局/未知哨兵,并使用 excludeSubagents、excludeCron、excludeSystem 和 excludeDock;较小的 limit 不会截断计数。与有界的基于关联的 people 分面不同,此数组不受人员选择器上限的约束。仅当响应包含 ownerSessionCounts 时,配置文件缺失才意味着零;省略的字段并不建立计数。客户端在 sessions.changed 时刷新此摘要(包括无键的可见性/配置文件失效),而不是从分页的会话行或人类在场状态中重建它。
  • sessions.list 接受 sortBy: "activity" 以按最新活动优先排序,不涉及置顶优先级。其时间戳取最后一次完成的运行(lastActivityAt)和最后一次用户/频道输入(lastInteractionAt)中较晚者。没有任一有效活动时间戳的会话回退到 updatedAt,再回退到 createdAt;缺失时间戳的会话排在最后。在此模式下,activeMinutes 使用相同的时间戳。过滤和排序在分页之前进行,会话键用于打破时间戳平局。默认的 updatedAt 顺序将置顶会话置于最前,并按元数据更新时长过滤;lastInteractionAt 保留其仅输入的排序。
  • 使用 activeMinutes 时,当可见候选存在年龄边界时,sessions.list 返回 activityExpiresAt。此纪元毫秒截止时间也包括所选人员和返回页面之外的候选,因此派生视图也可以让其人员分面过期。边界是包含式的:在 Date.now() > activityExpiresAt 之后重新读取。如果没有年龄过滤器,或者没有候选会超出年龄上限,则该字段不存在;它不会取代会话变更失效机制。
  • sessions.list 接受 activityPulseBoundaries,即 2–64 个在调用者本地时区中计算的严格递增的纪元毫秒边界。返回的 activityPulse.buckets 统计每个半开区间内的活动;会话、运行以及可选的不同人员计数覆盖分页前的完整过滤结果。started 统计在 activeMinutes 范围内创建的会话,当该时间过滤器不存在时省略此字段。
  • sessions.subscribe 为当前 WebSocket 客户端启用会话变更事件,并接受与 sessions.list 相同的参数,以在同一响应中返回初始列表。空的 {} 参数仅返回订阅确认。当该客户端断开连接时,订阅结束。参见 会话列表引导。
  • sessions.messages.subscribe 和 sessions.messages.unsubscribe 切换单个会话的转录/消息事件订阅。传入 includeApprovals: true 还会接收脱敏后的 session.approval 生命周期事件,这些审批的持久化受众包含该确切会话,且其审核者绑定授权了订阅客户端。订阅响应随后包含一个有界的待处理 approvalReplay;当 truncated 为 false 时,它是权威的。针对同一会话和审核者的并发请求会共享重放准备。该会话和审核者之外的审批活动不会使重放失效。如果在准备期间可见的审批状态发生变化,Gateway 会重试一次;若再次变化,则返回 UNAVAILABLE 并回滚暂定订阅,以便客户端重试。此选择加入是按订阅调用进行的,不具有粘性:在未传入 includeApprovals: true 的情况下重新订阅同一会话,会移除现有的审批订阅。除正常的会话读取权限外,此选择加入还需要 operator.admin,或配对设备上的 operator.approvals。

  • sessions.preview 为特定会话键返回有界(bounded)的转录预览。冷转录返回 status: "cold" 和空的 items 数组。批量预览请求会将已归档的有效负载保留在冷存储中;打开聊天或请求历史记录时会将其恢复。客户端应针对此状态显示“已归档历史”占位符。

  • sessions.storage.status 返回每个代理的转录计数、数据库和归档大小,以及后台维护状态(operator.admin)。
  • sessions.storage.run 使用已应用策略启动或加入一个后台归档批次,并迅速返回(operator.admin)。当 maintenance.running 为 true 时,请持续查询 sessions.storage.status。即使请求客户端断开连接,批次仍会继续。参见 冷转录存储。
  • sessions.describe 针对精确的会话键返回一条 Gateway 会话记录,包括当前调用者的 sharingRole(与会话列表和聊天历史所报告的一致)。
  • sessions.branches.list 独立于检出可用性列出已持久化的转录分支。并发的标签和活动更新不会使列表失效;但会话标识或读取权限的变更仍会拒绝读取。
  • sessions.github.options、sessions.github.publish、sessions.github.status 和 sessions.github.confirm 在 sessionKey 之外接受可选的 agentId。在全部四个调用中携带所选会话的代理,尤其是对于不标识其所有者的共享键 global。必须配置一个显式代理,且该代理必须与任何代理限定的会话键匹配;格式错误、未知或冲突的所有者会在发布前返回 INVALID_REQUEST。由工具发起的发布仍然绑定到工具调用者的会话和代理。发布和确认通过 error.details.leaseAcquisition 报告租约获取情况:held 返回 FORBIDDEN,并附有记录的持有者和租约纪元;store-unavailable 返回可重试的 UNAVAILABLE,并带有封闭的 reason 代码(sqlite-busy、lifecycle-busy 或 storage-error);调用者取消则返回不可重试的 UNAVAILABLE,带有 aborted、调用者信号原因和已用时间。SQLite 拥有有界的写入准入。在报告的后端失败清除后,使用相同的发布幂等键或确认请求重试;获取失败不会启动发布效果。已被某个 turn 或协调过程占用的工作区仍返回可重试的 UNAVAILABLE。sessions.github.options 有五秒的处理程序截止时间,超时返回可重试的 UNAVAILABLE。重试选项发现;过期会阻止延迟交付和后续读取步骤,但不会取消已由生命周期服务拥有的 OAuth token 轮换。
  • sessions.resolve 通过键、原始会话 ID、标签、Control UI 短 ID 或 reference: { key, slug? } 解析或规范化会话目标。引用会在可见的活动和已归档会话中搜索:其精确规范键优先,然后可选的显示名称 slug 会与 UUID 支持的会话匹配。引用发现保留会话列表可见性规则;单独的 key 选择器保留精确键读取语义。模糊的引用和短 ID 最多返回十个候选,作为成功的 RPC 结果。设置 allowMissing: true 可在没有会话匹配时收到 { ok: false }。
  • sessions.create 创建新的会话条目。在采用 agents.ownership: "explicit" 的集群中,如果请求带有代理限定的 parentSessionKey 且没有 key 或 agentId,则会在父级代理下创建子会话。显式的子级键或 agentId 优先,旧版集群保持其现有默认放置位置。当沙箱包含规则适用时,本地 cwd 和项目路径会对照所选代理的规范工作区进行检查:其内部的别名被接受,解析到外部的符号链接被拒绝。可选的 model、contextWindow 和 thinkingLevel 值会原子化地持久化初始模型、公布的上下文窗口选择和推理覆盖;可选的 category 将会话分配到自定义组,并在首次使用时注册该组。worktree: true 会预配一个受管理工作树;可选的 worktreeBaseRef/worktreeName 选择基础引用和分支名称,execNode(operator.admin)将会话执行绑定到节点主机。若无 worktreeName,OpenClaw 会从会话标签或生成的首条消息标题派生一个可读名称,然后退回到甲壳类主题名称;已被其他所有者、本地分支或非受管路径占用的名称会获得数字后缀。创建的工作树会在结果中回显,并持久化在会话行上(worktree: { id, branch, repoRoot })。当条目已创建但其嵌套的初始 chat.send 被拒绝时,成功结果包含 runStarted: false 和 runError;客户端可以保留提示词并根据返回的会话键重试。传入 parentSessionKey 且带有 emitCommandHooks: true 的调用者还应声明一个独立子会话的生命周期处置:succeedsParent: true 以 session_end 结束父会话,false 则保持父会话活动并仅发出子会话的 session_start。省略 succeedsParent 会为现有客户端保留旧版父级滚动行为。该处置要求同时具备父级关联和命令钩子;fork 不能接替其父级。主会话原地重置行为不变,因为不会创建独立子会话。新行会从受信任的创建接缝处盖上一次性创建来源戳(createdVia、createdActor、createdAt);采用现有键绝不会重新盖章。对于人类资料参与者,createdActor.label 在行投影时从当前用户资料解析,且永远不会存储在会话条目上,因此资料重命名不会造成漂移。会话行还携带 parentSessionKey(导航父级,持久化)、controlOwnerSessionKey(活动时的运行时控制器)、forkSource(fork 的精确来源键 + 转录代数)和 previousSessionId(同一键下的先前转录代数)。
  • sessions.dispatch 将经过授权的本地 OpenClaw 或 Codex 会话(带有活动且由注册表拥有的会话管理工作树)移动到配对设备或已配置的云资料。传入 { key, deviceId, agentId? } 以指定显式设备,{ key, autoDevice: true, agentId? } 用于自动配对设备选择,{ key, profileId, machineClass?, agentId? } 用于显式资料,或 { key, agentId? } 以在 cloudWorkers.projectProfiles 中查找受管理工作树的规范化来源。这些目标模式互斥,显式目标优先于项目资料查找。自动选择首先按已获准入的工作相对于 worker 容量对 worker 槽运行时排序,然后按计入挂起分派后的空闲槽排序,最后按设备 ID 排序;没有 worker 槽的运行时按设备 ID 顺序排序。只有在工作区准备开始之前检测到的主机资格失败会在清理任何失败分配后重试,总共最多三个排名候选。其他错误立即返回;工作区准备和已开始的工作绝不重放。显式和自动设备分派需要 operator.write;显式资料和项目资料分派需要 operator.admin。缺少来源、映射不匹配或映射到未配置的资料会返回类型化的 INVALID_REQUEST,不会预配或回退到其他目标。格式错误的参数在模式验证前使用写入作用域。缺少云资料只会隐藏云目标;符合条件的配对设备分派仍然可用。分派会在排空活动工作之前关闭本地 turn 准入,仅在放置达到 active 后返回;worker-turn 具有 worker 子进程所有权,remote-exec 由 Gateway 拥有的 harness 执行。任意普通目录不可分派;准入后,如果受管理工作树的 Git 元数据随后不可用,工作区传输可能使用清单镜像。SSH 回退候选仅用于幂等检查、内容寻址传输、收据/锁保护的工件安装、收敛式受管理工作树镜像和隧道重连时轮换。不明确的、无保护的有状态命令会安全失败(fail closed),且不会被重放。分派是单向的;worker 到本地的拉回不属于此 RPC。
  • sessions.reclaim(operator.write)按键安全地停止会话放置。它等待正在进行的分派、排空已准入的工作、协调活动工作区变更,并通过放置所有者重试挂起的失败环境拆除。调用者永远不需要原始的环境销毁权限。
  • sessions.move 将经过授权的活动会话移动到 Gateway、配对设备或已配置的资料。Gateway 和设备目标需要 operator.write;资料目标需要 operator.admin;格式错误的目标在模式验证前使用写入作用域。调用者会提供精确观察到的代数、环境和所有者纪元;会话授权和这些来源事实会在移动提交前重新验证。普通移动始终协调来源。只有 Gateway 目标可以添加 abandonSource: true,且仅当确切来源是当前离线的配对设备放置时。该持久决策会强制隔离并销毁远程所有者,跳过远程工作区协调,并从最后的 Gateway 同步状态继续而不重放;未同步的文件和进行中的工作可能丢失。可用、未知、资料和其他 worker 来源会拒绝显式放弃。
  • sessions.groups.list、sessions.groups.put、sessions.groups.rename 和 sessions.groups.delete 管理 Gateway 拥有的自定义会话组目录(名称 + 显示顺序)。只读范围的列表结果有意不包含路径。sessions.groups.defaults 和 sessions.groups.update 需要 operator.write,用于读取或替换一个自定义组的可选工作目录和工作树默认值。非管理员调用者只能保存已配置代理工作区内的目录;其他绝对 Gateway 路径需要 operator.admin。成员资格保留在每个会话的 category 字段上;重命名和删除会在服务端更新成员会话。sessions.groups.put 只替换名称列表和顺序,并拒绝移除仍包含成员会话的组——请先显式删除该组。移除组参与与删除相同的成员会话授权。
  • sessions.send 向现有会话发送一条消息。
  • sessions.files.list 和 sessions.files.get 列出并预览对某个可见会话可见的文件。根目录内的文件需要会话读取访问。根目录外的读取需要该会话的 Gateway 主机文件工具访问权限,以及当前在该处启动 turn 的权限;成功的根目录外预览会省略 hash 并保持只读。sessions.files.set 保留工作区包含规则,并对现有文件采用基于哈希的比较并交换(compare-and-swap)。
  • sessions.files.assets 接受 { sessionKey, agentId?, path, refs },其中 path 是 HTML 文件返回的 workspacePath 或 path,refs 包含从其文件夹解析出的相对资源 URL。它使用与 sessions.files.get 相同的当前会话读取边界。每次调用最多接受 64 个引用,每个引用最多 4,096 个字符,在 base64 编码前每个资源 1 MiB、总计 4 MiB 的字节上限。云仓库检查保留其更严格的每文件预览 256 KiB 上限和已停止仓库的工件可用性。它返回 { assets },每个条目要么是包含 base64 字节的 { ref, mimeType, content },要么是 { ref, error },其中 error 为 not_found、too_large、outside_session_boundary 或 unsupported。带 scheme 的、协议相对的和仅片段(fragment-only)的引用不受支持。canvas.document.preview 对调用者提供的 HTML 和隔离沙箱元数据接受会话读取访问;它不读取会话数据。

  • sessions.steer 是带有 queueMode: "interrupt" 的 chat.send 的已弃用别名;其移除遵循协议弃用策略。

  • sessions.abort 中止某个会话的活动工作,包括在没有 Gateway 聊天控制器的情况下启动的活动运行(例如 OpenAI 兼容的 HTTP 请求或频道回复)。会话范围的 chat.abort { sessionKey } 也覆盖这些运行,且不会级联到子会话。当该运行具有已知的运行 ID 时,chat.abort 会在 runIds 中返回它,sessions.abort 会将其作为 abortedRunId 返回。传入 key 以及可选的 runId,或者仅传入 runId 以处理 Gateway 可解析到会话的活动运行。提供 runId 会将取消操作限定在该运行范围内。在仅包含 key 的非全局请求上设置 clearQueued: true,以同时丢弃由该会话拥有的 followup 和 lane 队列。省略 clearQueued 的现有调用方会保留这些队列。字面量 global key 保留现有的 agent 限定的 chat.abort 所有权规则,并且不执行非全局 followup 或 lane 清理。
  • sessions.patch 更新会话元数据/覆盖项,并报告解析后的规范模型以及生效的 agentRuntime。contextWindow 仅接受所选模型 contextWindows 数组中通告的 id;null 恢复 contextWindowDefault。会话组织字段以及每个会话的 model、thinkingLevel 和 fastMode 覆盖项需要 operator.write,包括使用 null 清除覆盖项。相同字段策略适用于 sessions.patchMany。上下文窗口、verbose、trace、推理可见性、工具以及其他特权覆盖项仍需要 operator.admin;将它们与 write 范围字段组合不会降低该要求。只有管理员模型选择才能持久化为已配置的 agent 默认值。在多用户 Gateway 上,归档和恢复还要求会话创建者或 operator.admin;成员身份和已分配所有权不授予归档访问权限。归档、恢复、休眠和唤醒补丁要求将调用方从 sessions.list 或 sessions.describe 观察到的 sessionId 作为 expectedSessionId;缺失或已变更的目标会失败,而不会实例化或修改替代项。当 archived: true 时,Gateway 会保护 agent 主会话(包括配置了全局范围时的 global)以及 unknown 哨兵;对于其他每个真实会话,它首先对新准入加围栏,取消精确会话的活动、待处理、排队、回复、嵌入和 worker 工作,并在提交 archivedAt 前等待准入和运行时终结持久化排空。取消、排空或持久化失败会返回可重试的 UNAVAILABLE,并使会话保持未归档状态。sessions.patchMany 为每个目标携带 expectedSessionId,在同一个批处理生命周期围栏内按输入顺序准备归档目标,并返回按目标排序的结果。生成谱系(spawnedBy、spawnedWorkspaceDir、spawnedCwd、spawnDepth、subagentRole、subagentControlScope)不再公开可修补;这些事实由受信任的创建路径一次性写入,仍然发送它们的请求会被拒绝。
  • sessions.patch 回执包含会话元数据以及解析后的模型/运行时事实。其 entry 会省略已保存的 skillsSnapshot 和 systemPromptReport;这两个快照在显示元数据补丁中保持持久化且不变。
  • sessions.patch { snoozedUntil } 设置一个未来的正整数唤醒时间,单位为 epoch 毫秒;null 清除休眠。当唤醒时间变化时,Gateway 会标记 snoozedAt,对于相同值则保留它。休眠接受有资格固定的活动会话,并拒绝与归档相同的受保护目标,外加已归档和子会话。它保持会话活动及其固定状态不变,不执行生命周期排空、自动化禁用、worktree 转换或工作准入变更。固定或归档会清除休眠。真实用户/频道交互以及更新面向用户活动的已完成运行也会清除它;系统事件和保留状态运行不会。会话行公开 snoozedUntil 和 snoozedAt,因此客户端将唤醒时间与自身时钟进行比较。时间到期不会发出事件,并保留过期字段,直到后续写入清除它们;显式休眠和唤醒补丁发布正常的 sessions.changed 事件,原因为 patch。sessions.list 不按休眠过滤。
  • sessions.assignOwner(operator.write)将会话的可变所有者重新分配给人员或已配置 agent({ key, owner: { type, id } })。它要求已识别的调用方(已认证 profile 或受信任 agent 身份),按会话可见性进行授权,并在行的 owner 字段上记录 assignedBy/assignedAt。一次性写入的 createdActor 和以创建者为锚点的共享权限保持不变;参见 多用户模式。
  • sessions.reset、sessions.delete 和 sessions.compact 执行会话维护。无法识别 agent 的显式 agentId 值会在重置清理或修改之前被拒绝;它们永远不会回退到默认 agent。sessions.reset 接受来自 sessions.list 或 sessions.describe 的可选 expectedSessionId。如果重置进入其生命周期围栏时该会话 ID 不再当前有效,Gateway 会在中断工作之前以 INVALID_REQUEST 和 error.details.reason: "session-changed" 拒绝请求;在决定是否重试之前重新读取会话。省略该字段会保留无条件重置行为。该守卫不会拒绝保持相同会话 ID 的变更,包括元数据编辑或另一次就地重置。
  • sessions.get 返回 { messages },其中包含所选会话的 OpenClaw 拥有的存储转录中的最近消息。它不会导入外部 CLI 转录。使用 sessions.describe 获取会话元数据,使用 chat.history 获取显示归一化的对话。
  • 聊天执行仍使用 chat.history、chat.send、chat.abort 和 chat.inject。其 sessionInfo 使用与 sessions.list 相同的聚合 hasActiveRun 和可选完整精确 activeRunIds 语义。chat.history 针对 UI 客户端进行显示归一化:从可见文本中剥离内联指令标签,剥离纯文本工具调用 XML 负载(<tool_call>...</tool_call>、<function_call>...</function_call>、<tool_calls>...</tool_calls>、<function_calls>...</function_calls> 以及截断的工具调用块)以及泄漏的 ASCII/全角模型控制标记,省略纯静默标记助手行(精确 NO_REPLY / no_reply),并且超大行可以被占位符替换。 对于符合条件的 Claude CLI 绑定,chat.history 将外部转录消息与本地消息合并。这些合并快照仍保持字节有界;终结快照不保证完整的对话历史。 尾部响应可以包含不透明 deltaCursor。将其作为 cursor 传回 chat.history 或 chat.startup,而不是 offset 或 messageId。成功追赶返回 { kind: "delta", messages, deltaCursor, sessionInfo };将每个 messages 条目通过同一 reducer 重放,如同实时 session.message 负载。未变更历史返回空 messages 数组,并附带当前会话元数据和请求的输入回执。{ kind: "reset" } 表示游标无效、过期、属于另一个会话、跨越了重置、压缩或分支选择,或落后太多;获取正常尾部页面。追赶从不返回部分页面或续传:超过 200 个原始事件或其字节预算会重置为尾部获取。所有历史页面使用 512 KiB 消息预算;maxBytes 可以降低它。超大源行,包括不可分割的显示组,会变成带有其原始 __openclaw.id 和 truncated: true 的引用。通过 chat.message.get 读取它们;存储的转录字节保持不变。 锚定 messageId 读取可以返回不透明 olderCursor 和 newerCursor 值。将其中任意一个作为 cursor 传回,并附带相同的 sessionKey 和可选 agentId,以沿该方向继续。这些响应使用完整页面形状,而不是 delta 形状。只要方向游标存在,就继续穿过空页面;隐藏行仍会推进游标。游标保留所选物理会话和转录源;windowReset: true 表示该源不再可用,调用方必须重新打开锚点。响应预算不会缩短错误恢复前瞻。锚定读取及其续传需要当前共享访问权限。删除移除逻辑会话条目但保留其转录后,直接历史读取需要 operator.admin。cron.history 单独验证对其记录的自动化运行和转录的访问权限。访问权限在加载历史之前检查,并在发布之前再次检查。
  • chat.message.get 是单个可见转录条目的附加有界完整消息读取器。传入 sessionKey、当会话选择为 agent 范围时的可选 agentId,以及先前通过 chat.history 呈现的转录 messageId;当存储条目仍可用且未超大时,Gateway 返回相同的显示归一化投影,而不带轻量历史截断上限。从保留的物理会话获取引用时,传入历史页面的 sessionId;相同的会话所有权和当前共享检查适用。maxChars 对大型引用输出每个文本字段最多接受 8,000,000 个字符;序列化响应仍必须适合 WebSocket 负载限制。
  • chat.toolTitles 已弃用。它验证现有有界请求形状,并返回 { titles: {}, disabled: true },以便旧客户端停止请求标题。它不进行模型调用,也不访问旧标题缓存。当前 Control UI 客户端会自动显示随工具调用提供的描述。
  • chat.send 接受单轮 fastMode: "auto",以在自动截止前启动的模型调用中使用快速模式,然后启动后续重试、回退、工具结果或续接调用而不使用快速模式。截止默认值为 60 秒(DEFAULT_FAST_MODE_AUTO_ON_SECONDS),并可通过 agents.defaults.models["<provider>/<model>"].params.fastAutoOnSeconds 按模型配置。chat.send 调用方可以传入单轮 fastAutoOnSeconds 以覆盖该请求的截止值。传入 queueMode(steer、followup、collect 或 interrupt)以仅针对此请求覆盖存储的队列模式;显式 Control UI steer 操作使用 queueMode: "steer"。中断模式捕获并中止会话当前已准入的轮次,等待该精确所有者稳定,然后启动新轮次;空闲会话正常启动。steer 发送针对所选会话的当前状态:Gateway 原子地将消息注入该会话的直接活动运行,或在会话空闲时启动新轮次。后代 subagent 会话中的活动永远不会使所选会话在此决策中变为忙碌。expectedLeafEntryId 是非 steer 交互式发送的独立转录分支比较并交换:传入显示的分支叶(或有意 null 表示权威空转录),如果另一个客户端先切换了转录分支,则发送会以 details.reason: "active-leaf-changed" 拒绝;steer 发送忽略它。

  • chat.send、sessions.send 以及初始回合的 sessions.create 确认消息将准入与转录持久化分开报告。可选的 messageSeq 是来自实际已提交用户回合回执的一基位置;当输入仅存在于待处理托管中时,它不存在。仅凭 status: "started" 和 runStarted: true 不能确立转录行。应根据提交身份将临时输入与已接受的托管或规范转录身份进行对账,绝不能使用预测位置或匹配内容。

  • sessions.create.fastMode 接受 true、false 或 "auto",并在初始回合开始前持久化该速度覆盖设置。

  • sessions.create.label 在物理会话存储中声明一个显式标签,包括已归档会话。标签会被修剪且区分大小写。使用不同键的并发创建不能声明同一标签:失败的请求会收到带有 label already in use: <label> 的 INVALID_REQUEST,并且必须选择另一个标签。被拒绝的分支不会保留复制的历史。配置为共享存储的代理共享其标签命名空间;独立存储则不共享。
  • sessions.title.prepare({ agentId, message, model?, catalogId?, incognito? }、operator.write,作为控制平面写入进行速率限制)仅从所选代理的实用模型返回 { title },不会创建或重命名会话;对于隐身、空、斜杠命令或不可用实用模型的输入,它返回 title: null,并且从不回退到主模型。客户端将已就绪的结果作为 sessions.create.displayName 传递:这是一个展示标题,其存储方式与生成的首条消息标题相同,因此不唯一,从不声明 label,并且在采用现有键时被忽略。
  • sessions.activitySummary.ensure({ sessions: [{ key, agentId? }] }、1–20 个条目、operator.write)请求为调用方可能修改的会话生成有界的后台回顾。整个批次在任何生成入队之前都会获得授权。它会立即返回 { sessions: [{ key, agentId, activitySummary }] },其中 activitySummary.state 设置为 current、stale、updating 或 unavailable,并包含可选的缓存 text 和 updatedAt。生成使用拥有代理的实用路由,并在失败时保留上一份回顾。sessions.changed 会在工作完成时使该行失效。sessions.list 仅在 includeActivitySummary: true 时包含这些只读投影,并添加调用方特定的 activitySummary.canEnsure。客户端在请求生成前需要该标志和 operator.write;已接受的 ensure 响应返回 canEnsure: true。此权限标志不会持久化在回顾缓存中。普通列表不会请求模型生成。有关持久化和生命周期语义,参见 活动会话回顾。
  • sessions.create.titleSource 可选地提供所提交主题最多 1,000 个字符,用于第一个回合将单独发送的情况,例如在云分发之后。对于没有初始回合的新交互式会话,它会启动普通的后台标题生成,而不会延迟创建或启动任务。现有名称保持优先;隐身会话以及对现有会话的采用会忽略此输入。完成时会发出原因为 chat.title 的 sessions.changed。

  • sessions.create.surface 可选地接受 "plugin-dock",用于由插件坞拥有的操作员创建的对话。它会持久化不可变的 createdSurface 标记;createdVia、经过身份验证的人类创建者、共享以及沙箱策略保留其普通操作员行为。省略它会保持现有的创建行为。可信生成和其他内部创建契约不能由该选项替代。采用现有会话会保留其原始创建界面和溯源。

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