会话工具

OpenClaw 为代理提供跨会话工作、检查状态以及编排子代理的工具。

sessions_list、sessions_history、sessions_search、session_status、 sessions_send、sessions 和 sessions_spawn 接受可选的 user（请求者的已验证 requester_profile.id）。 当多人引导了该回合时，它是必需的。指定人员的权限决定会话访问和子执行；未知或已撤销的 参与者将被拒绝。单人回合可以省略它。 没有回合参与者的计划任务和 SDK/插件运行保留其现有会话访问规则。

可用工具¶

这些工具仍受当前工具配置和允许/拒绝策略约束。tools.profile: "coding" 包含完整的会话编排工具集。tools.profile: "messaging" 包含会话自助服务、发现、召回、跨会话消息、外部对话工具以及完整的生成生命周期（sessions_spawn、sessions_yield 和 subagents）。仅用于 UI 的任务建议工具 suggest_task 和 dismiss_task 仍属于 coding 配置工具。

组、提供商、沙箱和每个代理的策略仍可在配置阶段之后移除这些工具。请使用受影响会话中的 /tools 检查有效工具列表。

会话访问拒绝由执行边界使用的同一类型化可见性决策渲染。当为已准入的运行启用执行审计收集时，私有排队事实保留已评估的策略输入和一个安装本地不透明目标引用，而不是原始目标会话密钥。公开检查将该通用事实渲染为未验证的 decision.record；它不声称可信原因或目标显示。成功的会话操作不会仅因为其机制成功而被标记为 enforced。

对于同一已准入的运行，创建、分叉、发送、修补、重置、归档、恢复和删除结果可以排队仅用于归因的通用事实。私有事实区分已提交或已计划的工作与类型化生命周期冲突以及明确的无操作；其公开显示仍保持通用且未验证。直接 Gateway 共享操作位于此运行审计边界之外。

列出和读取会话¶

sessions_list 是元数据清单，而不是记录搜索。行包括会话密钥和 ID、代理、类型、通道、标题/标签、侧边栏组、当前所有者和原始创建者、存储的项目/工作区关联、可见的父/子链接、归档/固定状态、状态版本、模型/Token 计数以及运行状态。未知关联保持缺失；存储的 worktree 关联不能证明其 checkout 仍然存在。

在分页前，请组合使用过滤器以缩小清单范围：

• relationship：相对于经过身份验证的请求用户，取值为 owned、created 或 involving。所有权表示当前责任；创建表示原始来源；参与表示当前所有权或保留的 Prompt 参与。这不是代理的所有者，也不会从会话标签推断身份。如果没有可信的请求用户身份，工具将拒绝此过滤器；请改用显式的 ownerId 或 creatorId。
• ownerId 和 creatorId：精确的规范参与者 ID。关系过滤器缩小可见范围；它们从不授予访问权限。
• projectId 和 workspaceDir：精确的已持久化项目和工作目录关联。列出操作不会检查文件系统或运行 Git。
• group 和 pinned：精确的侧边栏组和固定状态。空组选择未分组会话。
• activeOnly：Gateway 支持清单上的当前直接排队/运行工作；在没有实时 Gateway 投影的嵌入式模式下不可用。activeMinutes 表示最近性，而不是存活状态。excludeSubagents 会省略子代理运行和未分组的生成会话。分配到自定义组的可见生成对话在正常可见性和归档过滤器下仍然符合条件。
• kinds、label、agentId 和 search：现有的分类、精确标签/代理以及元数据文本过滤器。类型包括 main、group、cron、hook、node 和 other。
• archived：false 或省略选择未归档会话；true 选择已归档会话；"all" 同时包含两者。

limit 默认为 100。早期版本接受的更大正数请求仍然有效，但每个响应最多应用 200 行，并在 limitApplied 中报告该上限。count 是返回行数，而不是清单总数。当 hasMore 为 true 时，请使用相同的过滤器将 nextOffset 作为 offset 传递。空页面仍可能有续传。每次调用限制为五个内部页面和一个 64 KiB 序列化结果；truncationReason 标识 scan-limit 或 byte-limit 部分结果。字节限制的续传从第一个被省略的行恢复。

页面是实时视图，而不是冻结快照。并发更新、固定、重新分配或归档可能使行在页面之间移动。按 agent/key/session ID 去重；当需要全新的完整清单时，从 offset 零重新开始。每次调用都会重新应用访问检查。续传不是访问授权，并且工具不公开隐藏会话的全局计数。

转录派生字段是可选的：includeDerivedTitles、includeLastMessage 或 messageLimit（每个选定行最多 20 条消息）。仅元数据调用不会读取转录或启动会话。预览仅在会话可见性过滤后填充。如果某行在富集过程中变得不可访问或其会话被替换，则它会被从完成的清单中省略。如果第一个富集行无法放入结果预算，调用将返回不含内联消息或转录派生预览的元数据，并设置 enrichmentOmitted: true；使用 sessions_history 获取完整对话。仍然超过 64 KiB 的元数据行会显式失败，而不是静默丢失身份或关联。

当 sessions 工具归档、恢复或删除会话时，将返回的 sessionId 用作 expectedSessionId，以便过期的 key 无法指向替换会话。投递路由、详细运行时设置、成本估算和转录路径仍被省略。受限清单包含 visibility 元数据，用于说明有效的会话工具范围。

sessions_history 获取特定会话的对话转录。默认情况下，工具结果被排除；传递 includeTools: true 可查看它们。使用 limit 获取最新的有界尾部。当需要分页元数据时，传递 offset: 0，然后传递返回的 nextOffset 值，以向后翻页浏览较早的 OpenClaw 转录窗口，而无需读取原始转录文件。当符合条件的绑定外部 CLI 转录提供消息时，history 返回合并快照，而不是数字偏移分页——即使显式指定 offset。Gateway 将这些视为终结快照（hasMore: false）；超大快照仍受字节边界限制，因此终结并不意味着完整。当没有外部导入保留时，应用本地偏移分页。无锚点读取保持当前重置相对视图。如果显式 messageId 仍位于该当前视图中（包括重置后保留的重置前行），则保持当前视图行为。对于当前视图之外保留的活跃路径行，显式 messageId 会打开其原始闭区间，并且不会混入重置后的后续轮次；缺失或偏离路径的 messageId 会返回空历史，而不是最新消息。

来自 sessions_send 或 Gateway agent 方法的持久已准入输入会单独出现在 pendingInputs 中，而不是转录 messages 中。每行记录 queued、cancelled 或 interrupted。已取消和已中断的输入会被保留以供检查，并且永远不会自动运行。使用 pendingBefore 和页面的 nextBefore 读取较早的输入；limit 限制两个页面。待处理预览在总体 80 KB 响应预算内共享 4 KB 预算，因此使用更小的 limit 可获得更丰富的预览。

pendingInputs.total 统计当前物理会话中保留且未消费的输入，位于显示过滤和分页之前。它不是可见消息或可运行作业计数。items.length 是本页的可见计数。空的 items 数组仍可能有 nextBefore；跟随它可检查较早条目。缺少 nextBefore 表示所检查的原始窗口已耗尽，而不是所有保留输入都可执行。待处理元数据既不授权重放，也不阻止无关工作。执行仍需要当前准入和精确输入保管。

返回的视图被有意限制并脱敏：

• 即使通用日志脱敏已禁用，凭据/令牌样式的文本也会被脱敏
• 思考签名、推理重放负载和内联图像数据会被省略
• 长文本块会被截断为 4000 个字符，并附加截断标记
• 返回的消息上限为 80 KB；较旧的行可能被丢弃，或超大行被替换为 [sessions_history omitted: message too large]
• 工具会报告诸如 truncated、droppedMessages、contentTruncated、contentRedacted、bytes 以及分页元数据等摘要标志

这是结构化历史，而不是 /subagents log 使用的纯文本渲染。sessions_history 不会应用该命令的助手文本净化器：推理标签、<relevant-memories> / <relevant_memories> 脚手架、纯文本工具调用 XML（包括格式错误的 MiniMax XML）、降级工具标记和模型控制令牌可能保留在返回的消息文本中。includeTools 控制工具结果消息，而不是这些嵌入式文本形式。

将返回的 会话 key（如 "main"）与 sessions_history、sessions_send 和 session_status 一起使用。要重新打开搜索命中项，还需将其 messageId 和 sessionId 传递给 sessions_history；参见 Session search。在锚定召回之外，使用持久的 sessionId 作为上述生命周期身份。

如果你需要确切的原始转录，请检查作用域内的 SQLite 转录行，而不是将 sessions_history 视为未过滤的转储。

使用 sessions_search 对可见的用户和助手转录文本进行精确全文召回。其结果包含一个 sessionKey，用于后续 sessions_history 调用；可见性过滤、片段脱敏和输出边界与历史边界一致。

管理会话设置和分组¶

sessions 工具公开有界的自助服务界面。Gateway 所有者保留完整工具。拥有 operator.write 的已准入非管理员操作员仅能对其创建的会话或被指定为人类所有者的会话使用归档、恢复和停止控制，并受现有会话访问检查约束。仅更窄的 operator.sessions.write 范围不会公开这些 agent 控制。其他设置、所有权、删除和全局分组操作通过该受限工具仍不可用。工具发现永远不会授予对另一个会话的访问权限；Gateway 会在操作边界重新检查请求者和目标。已撤销的权限和被替换的会话代际无法重用。

• action: "patch" 默认更改当前会话，或更改由 sessionKey 选定的另一个可见会话。它可以设置标签、持久侧边栏 icon、自定义侧边栏 group、置顶/归档状态、模型和思考级别。根会话和普通 Home 关联的仪表盘会话可以置顶；派生、子代理和嵌套子会话会拒绝置顶请求。子代理运行会出现在会话记录中，不在侧边栏导航里。传入 null 或空字符串以清除 group；分配新名称会在首次使用时创建该分组。图标接受一个表情符号字素、命名图标 braces、book、monitor、bot、kanban 和 coins 之一，或自定义 SVG 标记/SVG 数据 URL；传入空字符串以清除它。SVG 必须自包含，解码后最大 16 KiB，且不得包含脚本、嵌入文档或外部引用。包含 xmlns="http://www.w3.org/2000/svg" 和一个 viewBox；SVG 数据 URL 可以使用百分号编码或 base64。Gateway 存储规范 SVG 数据 URL，Control UI 将其渲染为图像。Control UI 自定义图标选择器接受相同输入，并显示 macOS（Control-Command-Space）或 Windows（Windows 键加句点）系统表情选择器快捷键。归档或恢复其他会话时，需要将其 sessions_list 中的 sessionId 作为 expectedSessionId。
• action: "reset" 重置由 sessionKey 选定的另一个可见会话。
• action: "stop" 停止另一个已授权会话，而不归档或删除它。包含来自会话发现的 expectedSessionId 以拒绝替换，并可选包含 runId 以仅停止该确切运行。会话级停止默认会清除排队中的后续操作；传入 clearQueued: false 以保留它们。精确运行停止无法清除无关的排队后续操作。若要停止调用方会话，请改为完成其当前回复。非交互式 Swarm 收集器不会收到 Stop；它们现有的归档和其他会话操作保持不变。
• action: "delete" 首先归档，然后删除由 sessionKey 选定的另一个可见会话的完全相同代际。默认情况下，其记录会作为已删除归档保留；传入 deleteTranscript: false 以不改动记录状态。重置或删除当前正在运行该工具的会话会被拒绝。
• action: "assign_owner" 将会话责任移交给人员或代理。传入 ownerType（"human" 或 "agent"）和 ownerId；目标默认为当前会话，或通过 sessionKey 指定另一个可见会话。代理所有者 ID 必须指定一个已配置的代理。该分配会记录谁在何时重新分配了它，Control UI 会立即反映新所有者。所有权是显示和责任，而非访问控制；参见 多用户模式。
• group_list、group_set、group_rename 和 group_delete 管理全局有序会话分组目录。group_set（names）以声明方式替换目录：数组顺序成为侧边栏顺序，新名称会被创建，而列表中未包含的现有空分组会被删除——要重新排序，请传入按新顺序排列的完整当前列表；删除单个分组时优先使用 group_delete。group_set 从不移动会话；要设置选定成员关系，请使用带 group 的 action: "patch"。group_rename 会更新所有成员类别，group_delete 会清除它们。group_set 会拒绝删除仍包含成员会话的分组；请先使用 group_delete。

中断的分组重命名/删除操作会保留剩余成员所需的分组。重命名可能使源分组和目标分组都保持可见；重试该操作以完成剩余成员的移动。

要将同一补丁应用到多个会话，请传入包含 1–100 个 { sessionKey, expectedSessionId? } 对象的 targets，而不是顶层 sessionKey 和 expectedSessionId。例如：

{
  "action": "patch",
  "targets": [
    { "sessionKey": "agent:main:dashboard:review-api" },
    { "sessionKey": "agent:main:dashboard:review-ui" }
  ],
  "group": "Reviews"
}

每个目标使用与单个补丁相同的可见性规则。提供其 sessions_list 中的 sessionId 作为 expectedSessionId，以拒绝过期选择；归档和恢复要求每个目标都提供此身份。当另一个目标失败时，有效目标仍可能成功。结果的 succeeded 和 failed 数组包含指向 targets 的从零开始索引；有界的 errors 会解释失败原因。明确的警告会标识被省略的错误详情。需要更多详情时，请单独重试这些失败目标。通过这些检查的重复目标会在变更之前拒绝整个批次。要归档符合条件的当前会话，请使用单个补丁；其归档会延迟到运行结束时执行，而批次会将该当前会话目标报告为失败，并继续处理其他目标。

使用带 visible: true 的 sessions_spawn 创建持久仪表盘会话。传入 group 以原子地将其放入侧边栏分组；省略 group 或传入空字符串以使其不分组。这将使会话创建保持在受控的派生路径上，该路径会强制父级的工具策略、沙箱、并发限制和运行超时。

如果启动或注册失败，清理只会删除由该派生创建的子会话。在此期间被重置或替换的会话会被保留。当无法确认清理时，错误会包含子会话键，以便在重试前检查。

代理选择的模型补丁在所选模型完成一次成功运行之前保持可逆。如果所选模型因身份验证、计费或模型未找到失败而确定不可用，OpenClaw 会恢复之前的模型并写入可见的系统备注。瞬时的速率限制、过载、超时、网络和服务端失败不会撤销该选择。

会话与对话¶

会话是本地模型上下文。对话是精确的外部地址，例如某个对等方、频道或线程。两者相关联，但不可互换：直接消息可以共享一个 main 会话，同时保留不同的对话地址。

conversations_list 为当前活动智能体返回不透明的 conversationRef 值。在显式指定 channel 时，Gateway 还会从该通道的本地目录刷新地址，例如已获批准的 Reef 对等节点；使用 query 可在当前结果页之外查找特定对等节点。发现过程会登记地址，但不会创建模型上下文会话；底层会话仅当投递或入站上下文需要时才会创建。会话发现和投递仅限所有者使用，因为它们使用 Gateway 的通道凭据。如需即发即忘（fire-and-forget）投递，请使用 conversations_send。当远程回复属于当前模型回合时，请使用 conversations_turn：Gateway 会保留一个传输消息 ID，在传输 I/O 之前持久化投递操作和排队意图，然后从该工具返回关联回复，而不是启动第二个本地智能体回合。投递操作位于模型转录之外；捕获的回复仅作为附带产物保留，而工具结果拥有模型上下文。如果 Gateway 在排队后重启，投递可以恢复，但之后的回复会遵循普通入站分发，因为进程本地的等待者已消失。未请求的入站消息始终继续通过正常的通道分发路径。

当你已经拥有明确的原始通道目标，或需要执行通道特定操作时，请使用共享的 message 工具。会话引用的作用域限定为当前智能体，应通过 conversations_list 获取，而不应从会话键构造。

在 Code Mode 中，会话工具会复用它们与 Gateway 完全一致的输出契约。单个 exec 单元可以列出地址、选择返回的 conversationRef，然后调用 conversations_send 或 conversations_turn；常规工具策略和审批仍然适用于这些嵌套调用。

发送跨会话消息¶

sessions_send 在同一 Gateway 上运行另一个会话，并可选择等待响应。其 sessionKey、label 或 agentId 选择的是本地模型上下文，而非外部目标。生成的回复仍可通过已建立的请求方或目标投递上下文进行通告；该既有行为不变。如需精确的外部投递，请使用会话工具或带显式通道和目标的 message。

当执行在 Gateway、配对设备和云 worker 之间移动时，会话会保留其地址。OpenClaw worker 可以使用其精确的会话键向已获授权的父级、子级或同级发送消息，包括运行在 Gateway 上的目标。Gateway 在允许目标回合之前，会验证当前会话身份和常规可见性策略；目标部署位置本身并不授予消息访问权限。已配置可见性范围之外的目标、已归档目标和已被替换的目标仍会被拒绝。

在 worker 正常预配或工作区准备期间，已接受的输入会保持排队，直到目标 worker 就绪。OpenClaw 重新检查会话和部署位置后，它只会启动一次。取消、设置失败或目标被替换时，不会在本地或其他 worker 上静默运行该输入。在再次提交消息前，请检查保留的输入和设置错误。

• 即发即忘： 设置 timeoutSeconds: 0 以入队并立即返回。
• 等待回复： 设置超时并内联获取响应。
• 引导正在运行的子级： 在不指定 mode 且将 timeoutSeconds 设为 0 的情况下，向你自己生成的子级发送消息会引导其进入当前运行，并确认队列准入，类似于 mode: "steer"，而不是持久化或模型消费。这种准入不具备跨重启持久性。使用 mode: "followup" 可启动一个拥有自身完成机制的独立子回合。空闲的子级，或其运行拒绝该引导的子级，会启动新回合。显式模式保持其既有行为。
• 继续已暂停的子任务： 不指定 mode 发送续接内容。当调用方控制着一个由 sessions_yield 暂停、且完成机制归任务所有的原生子级时，运行时会自动恢复该任务，并保留其身份和原始完成接收者。使用 mode: "resume" 可显式要求此行为。显式 mode: "followup" 会启动独立回合，并保持暂停任务不变。

对原生子级的独立 follow-up 仅在 Gateway 准入和输入准备完成后才会启动。如果准入拒绝该回合，发送会返回错误，且该回合不会启动。请求的状态监视只会在成功准入后安装。

对于采用进程内单向结果投递的原生子级 follow-up，向已接受的子级让渡会保持相同的逻辑结果义务。其确切准入的续接只会返回一个最终结果；空的已让渡前驱并不等于已完成的 no_reply。正数超时等待可以转移到异步投递，而无需第二个消费者。这种托管是进程本地的：Gateway 重启后它不会恢复调用方权限，并且当该权限或任一对话发生变化时，它会关闭。由所有者启动的 follow-up 还会在同一请求方会话中，为其单向结果回合保留原始通道所有者身份。因此，成功结果和子级失败可以继续使用仅限所有者的插件工具，执行已获授权的工作。这不会使子级成为所有者，也不会将其文本视为用户指令。新的用户回合、所有权被撤销、对话变更或 Gateway 重启都会使保留的权限失效。原始暂停的子任务与显式 follow-up 保持独立。

使用相同输入 ID 重试时，会在准入另一次执行之前，先对保留的 Gateway 准入和回复回执进行对账。

任务恢复会返回 status: "accepted"、mode: "resume"、后继 runId、原始 taskRunId 和 completion: "task"。现有任务所有者只会投递最终结果一次；该工具不会等待答案，也不会启动单独的回复回环。自动恢复接受常规 watch 和 timeoutSeconds 参数，但会将所有结果投递保留给现有任务，而不是增加内联等待或第二个 watcher。显式 mode: "resume" 会拒绝 watch: true 和正数超时等待。恢复要求可信的进程内 Gateway 准入。无关调用方、已完成任务和已变更的子会话会被拒绝，而不是回退到普通消息传递。Controller 所有权仍然绑定于最初记录的会话存储。未记录存储来源的保留任务会沿用普通默认消息传递，以及其现有的显式恢复和取消控制。新注册的任务会记录其存储，并可使用自动续接。

timeoutSeconds 限制的是发送工具的等待时间，而非接收方的执行预算。对于非阻塞协调，使用 sessions_send 并设置 timeoutSeconds: 0。当该等待到期时，待处理的公告会继续观察已接受的运行直到其结束；等待间隔不会丢弃迟到的回复。嵌套的代理间回复使用相同的完成观察机制。

底层 Gateway sessions.send RPC 的契约不同：其 JSON timeoutMs 限制的是接收方执行，就像 chat.send 一样。省略该字段以保留接收方配置的预算；使用 gateway call --timeout 单独限制 CLI 的等待时间。

已接受的结果将目标准入与公告投递分开。targetDisposition 对于新回合为 queued，对于活动回合为 steered，包括对自己正在运行的子代理进行默认发送且不等待回复的情况；delivery.status 仅将后续公告描述为 pending 或 skipped。这两个字段都不是目标完成回执。

对你自己正在运行的子代理进行默认零等待发送仅确认队列准入，类似于 mode: "steer"；它们不确认转录持久化或模型消费，也不具备重启持久性。它们不产生单独的完成回合。当你需要那个单独的子回合和完成时，使用 mode: "followup"。

如果幂等重试发现原始准入仍处于待处理状态，工具会返回一个错误，包含 sentBeforeError: true 和现有的运行 ID，且不安装观察。在重试前检查该运行。

回复来自已完成运行的终端结果。当同一会话的目标已经通过 message 将其最终回复投递到源会话时，OpenClaw 会跳过重复的频道公告。仅存储在内部 UI 中的进度消息和回复不计为外部投递。当同一会话的后续消息仍有公告目标时，其回复在可用时保留请求回合的频道、账户、收件人和线程。后续消息可以更新会话存储的路由，而不会重定向已接受的回复，包括当身份链接从会话密钥中隐藏地址时。

每个已完成的同一会话回复都会针对其原始会话的世代单独排队。后续普通回合和其他已完成的回复不会取消它。重置、删除或替换原始会话会停止尚未开始发送的回复；已经交给频道的发送会保持其正常结果。队列可以在重启后恢复已完成的回复。这并不会使未完成的模型运行或其内存中的回复观察者可重启。

无法识别这些队列条目的旧版本会将其及其附件保留为待处理状态，同时继续普通工作。返回到支持版本以恢复投递。完整状态备份包括排队的附件；仅数据库备份不包括。备份恢复有意省略待处理的投递记录，并且不会恢复这些回复。

等待的发送在没有可见助手文本的情况下完成时，返回 status: "no_reply"；不会有公告保持待处理状态。如果目标直接投递了其最终回复，结果显示如此并告知调用者不要重新发送。否则，继续不等待，或者如果需要响应则发送新消息。

线程范围的聊天会话，例如以 :thread:<id> 结尾的密钥，不是有效的 sessions_send 目标。使用父频道会话密钥进行代理间协调，以便工具路由的消息不会出现在活动的面向用户的对话线程中。

消息和 A2A 后续回复在接收提示中标记为会话间数据（[Inter-session message ... isUser=false]）并在转录出处中标记。接收代理应将其视为工具路由的数据，而不是直接由最终用户编写的指令。

代理 shell 命令不得用操作员 CLI 消息 RPC 替代此路径。在继承的 OPENCLAW_SHELL=exec 标记下，CLI 拒绝包含初始消息、任务或附件的 sessions.send、sessions.steer、chat.send、agent 和 sessions.create 请求。在可用时使用会话工具；没有它的子代理应通过正常完成返回其结果。投递失败不授权切换到操作员 CLI。此检查防止意外丢失归属；环境标记不是认证，也不是与同一操作系统用户运行的其他进程的隔离。

在独立对等会话响应后，OpenClaw 可以运行回复回环，代理在其中交替发送消息直到内置限制。目标代理可以回复 REPLY_SKIP 以提前停止。控制界面请求者反而只接收一次目标结果；他们面向用户的响应不会回馈到目标会话中。

子代理协调不使用此回环。子代理报告仅发送给其收件人一次，在子代理中不会自动生成确认回合。显式等待的调用者仍然可以内联接收收件人的回复。对于子代理的新回合，子代理的回复内联返回或在等待到期后投递一次；接收者的响应不会发送回子代理。

隔离的计划作业不会收到自动回复回合，包括失败通知。它们的对等目标公告保持不变。如果此类计划作业的等待在原生子代理回复之前结束，该回复会遵循目标现有的公告路径，而不会进行相互回复交换。

这些回复投递适用于新回合或后续回合。对你自己正在运行的子代理进行默认发送且不等待回复时，会跳过单独的回复投递，并将完成留给活动运行的拥有者。mode: "steer" 仅返回对添加到活动运行的指导的准入，并将完成留给该运行现有的拥有者。它使用现有的 sessions_send 访问检查。对于内置运行时，繁忙的工具或模型响应可能会将转录持久化延迟到下一个转向边界；发送的回复等待截止日期不会撤回已准入的指导。接受不是转录持久化或模型消费的证明，也不会使内存中的转向队列具备重启持久性。接收运行保留源权限，直到输入稳定或该确切运行结束或中止；缺失的后端结算回调不能使其保留超过该运行。现有的显式取消、运行生命周期和授权规则仍然适用。mode: "notify" 将上下文排队而不启动回合。已注册任务的完成和暂停任务的恢复保留其现有的完成拥有者，并且不会添加第二个回复投递。

Child coordination stays in agent context and raw transcripts. The receiving chat hides child reports and automatic coordination replies, while normal task-completion summaries and direct human answers remain visible. Historical messages without source provenance cannot be classified as child traffic.

传入 watch: true 还可将发送方注册为目标的状态变更监视器：当其他参与者稍后向目标发送直接人类消息或更改其目标时，发送方会收到一条指向 session_status changesSince 的系统通知。注册发生在成功分发之后，针对实际接收消息的会话，并从其当前状态版本开始，因此只有后续变更才会产生通知。注册成功时，结果会报告 watched: true。参见 会话状态感知。

状态与编排辅助工具¶

session_status 是轻量级 /status 等效工具，用于当前或另一个可见会话。它报告用量、时间、模型/运行时状态，以及存在时关联的后台任务上下文。与 /status 类似，它可以从最新转录用量条目回填稀疏的 token/缓存计数器，并且 model=default 会清除按会话的覆盖。使用 sessionKey="current" 表示调用者的当前会话；诸如 openclaw-tui 等可见客户端标签不是会话密钥。

模型更改的范围仅限于所选会话，不会更新代理或全局默认值。网关管理的会话应用与其他会话模型选择相同的模型、运行时和执行环境检查。重复未更改的选择不会更新会话活动或发出模型变更通知。

当路由元数据可用时，session_status 还包括一个可见的 Route context JSON 块和匹配的 details 结构化字段。这些字段用于区分会话密钥与当前处理实时运行的路由：

• origin 是会话创建的位置，或者当旧状态缺少存储的源元数据时，从可交付会话密钥前缀推断出的提供商。
• active 是当前实时运行路由。它仅针对当前正在处理的实时或当前会话报告。
• deliveryContext 是存储在会话上的持久投递路由，即使活动界面不同，OpenClaw 也可以将其用于后续投递。

会话状态变更¶

OpenClaw 维护一个持久信号日志，记录重要的会话状态变更（发往被监视会话的直接人类消息、子运行结果、目标变更、压缩）。sessions_list 行和 session_status 暴露会话的 stateVersion，并且 session_status 接受 changesSince: <version> 以返回该版本之后的类型化事件，并通过精确的 historyGap 信号指示请求版本早于保留历史。监视器——生成父级自动成为监视器，sessions_send watch: true 显式成为监视器——当其他参与者更改被监视会话时，会收到一条合并的过期状态通知。

状态变更事件省略重复的会话/代理 ID，仅暴露对模型有用的负载字段（outcome、channel 或 turns）。事件摘要和参与者/运行标识符仍可用于对账。

参见 会话状态感知 了解完整模型：事件类型、监视器注册、防垃圾通知协议、对账流程以及当前限制。

sessions_yield 有意结束当前回合，以便下一条消息可以是已宣布的子级完成事件。用它来宣布子代理，而不是 Swarm 收集器：收集器需要通过 agents_wait 或在 OpenClaw Code Mode 中等待 agents.run() 来显式收集结果，并且不发送完成通知。

subagents 列出受控会话树内的原生子代理运行。将返回的 runId 与 action: "wait" 或 action: "cancel" 一起使用；取消不会授予对无关会话的访问权限。ACP、媒体、shell 进程和 cron 保留其自身的状态和取消所有者。

生成子代理¶

sessions_spawn 为后台任务创建一个独立会话。非线程生成默认以隔离上下文开始；线程绑定生成遵循下文所述的已配置上下文策略。当启动被接受时，它返回 runId 和 childSessionKey，而不会等待子任务完成。来自 OpenClaw 云工作器的生成可以先等待子级配置和节点注册。原生子代理运行会在任何分叉历史之后追加的 [Subagent Task] 消息中接收其委派任务；继承的任务信封是上下文，而不是当前子级的分配。系统提示仅携带子代理运行时规则和路由上下文。

关键选项：

• runtime: "subagent"（默认）或 "acp"，用于外部 harness 代理。
• 用于子会话的 model 和 thinking 覆盖。
• runTimeoutSeconds 用于覆盖已配置的子运行超时；0 将其禁用。
• thread: true 将生成绑定到聊天线程（Discord、Slack 等）。
• sandbox: "require" 强制对子级启用沙箱。
• 当子级需要当前请求者的转录时使用 context: "fork"；这要求 runtime: "subagent" 且与请求者使用同一代理，无论子级是隐藏还是可见。显式使用 context: "isolated" 以获得干净的子级。省略意味着非线程生成使用隔离上下文；线程绑定的原生子代理遵循 threadBindings.defaultSpawnContext，其默认值为 fork。
• visible: true 创建一个持久仪表板会话，而不是隐藏的子代理会话。可见生成支持显式侧边栏 group、模型、工作目录、同代理转录分叉，以及可选的 托管工作树；有关确切的兼容性限制，参见 子代理。接受的结果是一个回执：它包括子会话密钥、运行 ID、Control UI sessionUrl（当 Control UI 被禁用时省略），以及一个 owner 记录，其中指明存储的所有者。当活动人类请求者与请求会话的已验证人类所有者匹配时，新的可见子级继承该人作为所有者。否则，所有者回退到请求代理。请求代理通常是不可变的创建者；强制沙箱则作为隔离策略保留父级的创建者溯源。在频道中确认生成时，将会话 URL 放在第一行，Owner: <label> 放在第二行。所有权控制责任和显示，而不是基于创建者的访问；参见 多用户模式。

低于默认深度限制 5 的子代理会获得 sessions_spawn、subagents、sessions_list 和 sessions_history，以便它们管理自己的子会话。设置更低的 maxSpawnDepth 可以让该深度的会话更早成为叶子节点。

普通 announcing 运行会向请求方返回完成事件。其他完成模式遵循已接受的回执：collectors 需要显式收集，直接路由的线程会话会在绑定的线程中回复，quiet 运行不发送完成通知。Announce 投递在可用时会保留绑定的线程/主题路由；如果完成来源仅标识了一个频道，OpenClaw 仍可以复用请求方会话中存储的路由（lastChannel / lastTo）进行直接投递。

有关 ACP 特定行为，请参阅 ACP Agents。

可见性¶

会话工具通过范围限制代理可见的内容：

默认为 all：非沙箱会话（包括保留的 cron 会话）可以在 Gateway 上跨代理列出、读取、搜索、发送消息并检查状态。这可能包括其他用户的转录记录。跨代理访问默认开启，并由 tools.agentToAgent 控制；设置 enabled: false 可阻止普通跨代理访问，或使用 allow 限制允许的代理对；请求方拥有的原生子代理和 ACP 子会话在 tree 或 all 下均可达。设置 agent 表示仅限同代理访问，或设置 tree 表示当前加已派生范围；其规范的主会话例外仍覆盖所有同代理会话。设置 self 表示严格的当前会话访问，包括主会话。

agent 范围不包括由另一个代理拥有的子会话。如果依赖其拥有的原生/ACP 子会话例外，请保留显式 tree；或使用默认 all 并配合适当的 tools.agentToAgent 策略。在默认仅派生会话工具限制下的沙箱调用方仍限于其派生子树。隐身会话对所有跨会话工具保持隐藏。环境群组监视仍会添加活动通知和提示；它们不授予访问权限。

相关¶

• 会话管理：路由、生命周期、维护
• 会话修剪
• 子代理：子会话生命周期与投递
• ACP Agents：外部 harness 派生
• 多代理：多代理架构
• Goal — 持久化的每会话目标，通过专用的 get_goal、create_goal 和 update_goal 工具读取和更新
• Gateway 配置：会话工具配置项