本页内容
本页内容
会话和内存
会话工具
OpenClaw 提供代理工具,用于跨会话工作、检查状态并编排子代理。
sessions_list、sessions_history、sessions_search、session_status、sessions_send、sessions、sessions_create 和 sessions_spawn 接受可选的 user(请求者已验证) requester_profile.id)。当多人转向时需要这样做。指定人员的权限决定会话访问和子进程执行;未知或已撤销的参与者将被拒绝。单人回合可以省略。计划作业和 SDK/plugin 运行时不轮流参与者保留其现有的会话访问规则。
可用工具
| 工具 | 它的作用 |
|---|---|
sessions |
管理可见会话并组织会话组 |
sessions_create |
创建一个独立的会话,可选择开始工作 |
sessions_list |
列出会话,可选筛选条件包括(kind、label、agent、archive、preview) |
sessions_search |
搜索可见会话转录并返回匹配的摘录 |
sessions_history |
读取特定会话的转录内容 |
sessions_send |
在同一个 Gateway 上运行另一个会话,并可选择等待结果 |
conversations_list |
列出稳定的外部会话地址 |
conversations_send |
向一个精确的外部会话发送内容,不会运行本地会话 |
conversations_turn |
向一个精确的外部会话发送内容,并等待其关联回复 |
sessions_spawn |
为后台工作创建一个隔离的子代理会话 |
sessions_yield |
结束当前轮次并等待后续子代理结果 |
subagents |
列出或取消此会话树中的后台工作 |
session_status |
显示 /status-style 卡并可选择设置每个会话模型覆盖 |
这些工具仍受有效工具配置文件和 allow/deny 政策的约束。 tools.profile: "coding" 包括完整的会话编排集。 tools.profile: "messaging" 包括会话自助服务、发现、召回、跨会话消息传递、外部对话工具以及完整的生成生命周期(sessions_spawn、sessions_yield 和 subagents)。 UI-only 任务建议工具 suggest_task 和 dismiss_task 仍然是编码配置文件工具。
组、提供方、沙箱以及每个代理的策略在配置文件阶段之后仍可能移除这些工具。请在受影响的会话中使用 /tools 来检查实际生效的工具列表。
会话访问拒绝是根据执行边界使用的相同类型的可见性决策来呈现的。当为允许的运行启用执行审核收集时,私有排队事实将保留评估的策略输入和安装本地不透明目标引用,而不是原始目标会话密钥。公共检查将该一般事实呈现为未经验证的 decision.record;它不声明可信原因或目标显示。成功的会话操作不会仅仅因为其机制成功而被标记为 enforced。
对于同一承认的运行、创建、分叉、发送、修补、重置、存档、恢复和删除结果可以对仅归因的通用事实进行排队。私有事实将已提交或计划的工作与类型化的生命周期冲突和明确的无操作区分开来;他们的公开展示仍然是通用的且未经证实。直接网关共享操作在此运行审核边界之外。
创建独立会话
当用户明确要求启动或创建会话或任务(包括“启动新任务”)时,请使用 sessions_create。这将创建一个正常的、持久的可见会话,用户可以返回并独立控制该会话。它不是受监督的子级,并且不会向调用者发送完成事件;不要产生期待的结果。
- 提供一个非空
message来开始第一轮,或者忽略它来创建一个空闲会话。 - 可选
label、agentId、cwd、group、model和permissionMode配置新会话。user在需要时选择经过验证的请求者,如上所述。agentId默认为请求代理;省略的设置使用目标默认值。group选择侧边栏类别,而不是执行来源。该工具不接受创建者身份、角色、密钥、父级、分叉、生成或采用字段。 - 结果识别出新的
sessionKey和sessionId。runStarted报告首轮是否开始;runId可用时存在。如果创建成功但启动失败,runError报告失败并且会话仍然可用。在重试创建之前检查该会话。
只有通过现场承认的 operator.sessions.write 权限才能公开创作。现有的sessions管理工具不会创建会话,并且无发送者运行不会获得单独的创建功能。具有会话写入权限的公认非所有者的默认沙箱表面包括创建和重命名。工具策略和执行时权限检查仍然适用。
使用 sessions_spawn 作为实际委托的帮助者。隐藏的孩子是默认的; visible: true 仍然可用于用户需要重新访问或引导的有意监督的子工作。使用 suggest_task 进行主动的、未经请求的后续提案:它会记录一张卡片,并且在被接受之前不会启动任何操作。明确的开始工作请求不是建议请求。
列出和读取会话
sessions_list 是元数据清单,而不是文字记录搜索。行包括会话密钥和 ID、代理、种类、通道、title/label、侧边栏组、当前所有者和原始创建者、存储的 project/workspace 关联、可见的 parent/child 链接、archive/pin 状态、状态版本、model/token 计数和运行状态。未知的关联仍然不存在;存储的工作树关联并不能证明其签出仍然存在。
在分页之前一起使用过滤器来缩小库存范围:
relationship:owned、created或involving,相对于经过身份验证的请求用户。所有权就是当前的责任;创造是原始出处;参与是指当前的所有权或保留的即时参与。这不是代理的所有者,并且不会从会话标签推断身份。如果没有可信的请求用户身份,该工具将拒绝此过滤器;请改用显式的ownerId或creatorId。ownerId和creatorId:精确解析的演员 ID。关系过滤了狭隘的可见性;他们从不授予访问权限。projectId和workspaceDir:精确的持久项目和工作目录关联。列表不会检查文件系统或运行 Git。group和pinned:准确的侧边栏组和引脚状态。空组选择未分组的会话。activeOnly:当前直接 queued/running 在网关支持的库存上工作;如果没有实时网关投影,它在嵌入模式下不可用。activeMinutes是新近度,而不是活跃度。excludeSubagents省略子代理运行和取消分组的生成会话。分配给自定义组的可见生成对话在正常可见性和存档过滤器下仍然符合资格。kinds、label、agentId和search:现有分类、精确 label/agent 和元数据文本过滤器。种类有main、group、cron、hook、node和other。archived: false 或省略选择未存档的会话; true 选择存档会话;"all"包括两者。
limit 默认为 100。早期版本接受的较大肯定请求仍然有效,但每个响应最多应用 limitApplied 中绑定的 200 行和报告。 count 是返回的行数,而不是库存总数。虽然 hasMore 为 true,但使用相同的过滤器将 nextOffset 作为 offset 传递。空白页面仍然可以有延续。每个调用都绑定到五个内部页面和一个 64 KiB 序列化结果; truncationReason 标识 scan-limit 或 byte-limit 部分结果。字节限制的延续从第一个省略的行处恢复。
页面是实时视图,而不是冻结快照。并发更新、固定、重新分配或归档可以在页面之间移动行。通过 agent/key/session ID 进行重复数据删除;当需要新的完整库存时,从偏移量零重新启动。每次调用都会重新应用访问检查。延续不是访问授权,并且该工具不会公开隐藏会话的全局计数。
转录衍生字段是可选的:includeDerivedTitles、includeLastMessage 或 messageLimit(每个选定行最多 20 条消息)。仅元数据调用不会读取文字记录或启动会话。仅在会话可见性过滤后才对预览进行水化。如果在扩充过程中某行变得不可访问或其会话被替换,则该行将从已完成的清单中忽略。如果第一个丰富的行无法满足结果预算,则调用将返回没有内联消息或转录衍生预览的元数据,并设置 enrichmentOmitted: true;使用 sessions_history 进行完整对话。仍然超过 64 KiB 的元数据行会显式失败,而不是默默地丢失标识或关联。
当 sessions 工具存档、恢复或删除会话时,使用返回的 sessionId 作为 expectedSessionId,因此过时的密钥无法定位替换。传递路由、详细的运行时设置、成本估算和转录路径仍然被省略。受限清单包括解释有效会话工具范围的 visibility 元数据。
sessions_history 获取特定会话的对话记录。默认情况下,排除工具结果;通过 includeTools: true 即可看到它们。使用 limit 作为最新的有界尾部。当您需要分页元数据时,传递 offset: 0,然后传递返回的 nextOffset 值,以通过旧的 OpenClaw 转录本窗口向后翻页,而无需读取原始转录本文件。当符合条件的绑定外部 CLI 转录本贡献消息时,历史记录将返回合并的快照而不是数字偏移页 - 即使使用显式 offset 也是如此。网关将这些视为终端快照 (hasMore: false);超大快照仍然受字节限制,因此终端并不意味着完整。当没有外部导入存在时,本地偏移分页适用。未锚定的读取保留当前的重置相对视图。保留在当前视图中的显式 messageId(包括重置后保留的预重置行)保持当前视图行为。当前视图外部保留的活动路径行的显式 messageId 打开原始闭合间隔,并且不会混合稍后的重置后转弯;丢失或偏离路径的 messageId 返回空历史记录而不是最新消息。
在加载消息正文之前,显示历史记录将原始页面限制为 8 MiB。较大的消息会返回错误,而不是耗尽转录工作人员的精力。如果锚定页面超出此限制,请请求较小的 limit。该工具的文本和响应字节上限仍然适用。
来自 sessions_send 或网关 agent 方法的持久承认的输入单独出现在 pendingInputs 中,而不是出现在转录本 messages 中。每行记录 queued、cancelled 或 interrupted。取消的输入永远不会自动运行。中断的输入被保留以供检查;网关可以重新接纳具有持久交付所有权的未使用的普通对等发送,如下所述。其他中断的输入不会自动运行。即使会话历史记录工具不可用,内置代理和 CLI 代理也会接收最近可见中断输入的有限文本预览作为历史上下文。这些预览不会消耗输入、恢复旧权限或在没有当前请求的情况下恢复工作。预览告诉代理仅当用户要求继续它们时才恢复它们,否则回答当前请求。不包括排队、取消、隐藏和上下文排除的输入。使用 pendingBefore 和页面的 nextBefore 来读取较旧的输入; limit 装订两个页面。待定预览在 80 个 KB 响应预算中共享 4 个 KB 预算,因此使用较小的 limit 可以获得更丰富的预览。
pendingInputs.total 在显示过滤和分页之前对当前物理会话中保留的、未使用的输入进行计数。它不是可见消息或可运行作业计数。 items.length 是此页面上的可见计数。空的 items 数组仍然可以有 nextBefore;按照它检查旧条目。缺少 nextBefore 意味着检查的原始窗口已耗尽,而不是所有保留的输入都是可执行的。待处理的元数据既不会授权重播,也不会阻止不相关的工作。执行仍然需要当前的许可和准确的输入保管。
返回的视图是有意限制的:
- 返回文本,包括工具结果和凭证,无需秘密屏蔽
- thinking 签名、推理重放有效负载和内联图像数据被省略
- 长文本块被截断为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 控制工具结果消息,而不是那些嵌入的文本表单。
将返回的 会话密钥(如 "main")与 sessions_history、sessions_send 和 session_status 一起使用。要重新打开搜索命中,请将其 messageId 和 sessionId 传递给 sessions_history;请参阅 会话搜索 。在锚定召回之外,使用持久的 sessionId 作为上述生命周期标识。
如果你需要精确的原始转录,请检查作用域限定的 SQLite 转录行,而不是将 sessions_history 视为未过滤的转储。
使用 sessions_search 跨可见的用户和助理转录文本进行准确的全文回忆。其结果包括后续 sessions_history 调用的 sessionKey;可见性过滤和输出边界与历史边界匹配。
管理会话设置和分组
sessions 工具公开有界自助服务表面。网关所有者保留完整的工具。显式非所有者发送方收到可见会话的 assign_owner。拥有 operator.sessions.write 的认可操作员还可以重命名他们使用仅标签补丁创建的会话。重命名默认为当前会话,并保留其标识、历史记录、工作区、设置和正在运行的工作。重命名另一个已创建的会话需要将其 sessions_list sessionId 更改为 expectedSessionId。拥有 operator.write 的认可非管理员操作员只能存档或恢复他们创建的会话。他们可以停止他们创建的会话或作为人类所有者分配的会话,但须遵守现有会话访问检查。较窄的 operator.sessions.write 范围本身不会公开这些控件。对于具有会话写入权限的非所有者操作员,默认沙箱公开 sessions_create 并通过 sessions 进行仅标签重命名。明确的沙箱允许名单和拒绝仍然适用;明确允许 sessions 保留调用者权限允许的操作。其他设置、删除、云配置文件发现和全局组操作仍然由所有者控制。无发送者系统运行保留其现有的会话管理界面,并遵守工具策略、范围和实时调用者检查。
显式工具否认仍删除该工具。独立的 HTTP/RPC 工具调用和会话绑定的 MCP 附加授权保留其所有者门控,并且不会获得代理身份。没有肯定的所有者权限的分配需要现场承认的代理轮流,并在所有者写入时重新检查。工具发现永远不会授予对另一个会话的访问权限;撤销的权限和替换的会话生成不能重复使用。
action: "patch"默认更改当前会话,或sessionKey选择的另一个可见会话。可以设置标签、持久侧边栏icon、自定义侧边栏group、pin/archive状态、模型、思维层次。可以固定根会话、普通的主页链接仪表板会话以及明确移动到 Control UI 顶层的持久子级;隐藏的子代理运行和仍然嵌套的子会话拒绝 pin 请求。子代理运行显示在侧边栏导航之外的会话记录中。传递null或空字符串来清除group;分配新名称会在首次使用时创建组。该图标接受一个表情符号字素、指定图标braces、book、monitor、bot、kanban和coins之一,或自定义 SVG markup/an SVG 数据 URL;传递一个空字符串来清除它。 SVG 必须是独立的,最多解码 16 个 KiB,没有脚本、嵌入文档或外部引用。包括xmlns="http://www.w3.org/2000/svg"和viewBox; SVG 数据 URL 可以使用百分比编码或 base64。网关存储标准化的 SVG 数据 URL,并且 Control UI 将其呈现为图像。 Control UI 自定义图标选择器接受相同的输入,并显示 macOS (Control-Command-Space) 或 Windows (Windows-period) 系统表情符号选择器快捷方式。归档或恢复另一个会话需要将其sessions_listsessionId更改为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从不移动会话;对于选定的会员资格,请使用action: "patch"和group。group_rename更新所有成员类别,group_delete清除它们。group_set拒绝删除仍有成员会话的组;首先使用group_delete。
中断的组 rename/delete 操作保留剩余成员所需的组。重命名可以使源组和目标组都可见;重试该操作以完成剩余成员的移动。
要将同一补丁应用于多个会话,请传递带有 1–100 个 { sessionKey, expectedSessionId? } 对象的 targets,而不是顶级 sessionKey 和 expectedSessionId。例如:
每个目标都使用与单个补丁相同的可见性规则。将其 sessions_list sessionId 提供为 expectedSessionId 以拒绝过时的选择;归档和恢复需要每个目标的此标识。当另一个目标失败时,有效目标可以成功。结果的 succeeded 和 failed 数组包含 targets 的从零开始的索引;有界 errors 解释失败。显式警告标识遗漏的错误详细信息。当需要更多详细信息时,单独重试那些失败的目标。通过这些检查的重复目标会拒绝突变前的批次。要存档符合条件的当前会话,请使用单个补丁;它的归档被推迟到运行完成,而批处理报告当前会话目标失败并继续处理其他目标。
使用 sessions_create 进行独立会话。对于有意监督的儿童工作,请使用 sessions_spawn 和 visible: true。传递 group 以原子方式将该子项放入侧边栏组中;省略 group 或传递空字符串以使其不分组。生成路径强制执行父级的工具策略、沙箱、并发限制和运行超时。
如果启动或注册失败,清理只会删除该生成创建的子项。同时保留重置或替换的会话。当无法确认清理时,错误会包含子会话密钥,以便在重试之前进行检查。
由代理选择的模型补丁在该选择成功完成一次运行之前都是可回滚的。如果所选模型由于认证、计费或模型不存在而明确不可用,OpenClaw 会恢复到先前的模型并写入一条可见的系统提示。瞬时的速率限制、过载、超时、网络和服务器故障不会撤销该选择。
会话与对话
会话(session)是本地模型上下文。对话(conversation)是一个精确的外部地址,例如某个对等方、频道或线程。这两者是关联的,但不能互换:直接消息可以共享一个 main 会话,同时保留各自独立的对话地址。
conversations_list 会为活动代理返回不透明的 conversationRef 值。对于显式的 channel,Gateway 还会从该频道的本地目录刷新地址,例如已批准的 Reef 对等方;可使用 query 在当前结果页之外查找特定对等方。发现过程会对地址进行编目,但不会创建模型上下文会话;只有在需要投递或接收入站上下文时,才会创建底层会话。对话发现和投递仅限所有者使用,因为它们使用的是 Gateway 的频道凭据。使用 conversations_send 进行一次性投递。使用 conversations_turn 当远端回复属于当前模型轮次时:Gateway 会预留一个传输消息 ID,在传输 I/O 之前持久化投递操作和队列意图,并将关联的回复从工具中返回,而不是启动第二个本地代理轮次。投递操作存在于模型转录之外;捕获到的回复仅作为侧边工件保留,而工具结果才拥有模型上下文。如果 Gateway 在排队后重启,投递可以恢复,但后续回复将遵循普通的入站分发,因为进程本地的等待器已经消失。未请求的入站消息始终会继续通过正常的频道分发路径处理。
当你已经拥有显式的原始频道目标,或需要执行特定于频道的操作时,请使用共享的 message 工具。对话引用的作用域限定于活动代理,应通过 conversations_list 获取,而不要从会话键构造。
在 Code Mode 中,对话工具会复用其完全一致的 Gateway 输出契约。单个 exec 单元可以列出地址、选择返回的 conversationRef,并调用 conversations_send 或 conversations_turn;正常的工具策略和审批仍然适用于这些嵌套调用。
跨会话消息发送
通讯偏好
在会话菜单中打开 Advanced,选择 Always、Ask 或 Never 发送消息和接收消息。在接受新的对等输入之前,Ask 会向 Control UI 中的授权人员提出待决问题。拒绝或过期的请求不会开始工作。请求的答复和授权的委派任务指导和结果保留其现有的权威。
会话创建者或网关管理员可以更改这些首选项。代理无法通过会话工具更改它们。 Reset 清除覆盖并遵循 session.communication。更改默认值会影响继承会话,而不是显式覆盖。
两个方向都默认为“始终”以保留现有行为。这些首选项绝不会授予超出工具策略、共享、沙箱或代理间限制的访问权限。它们不会隐藏聊天历史记录、控制外部渠道传递或阻止人工输入。批准后和发送输入之前再次检查权限。改变这些偏好会阻碍新的录取;已接受的消息和工作保留其交付和完成义务。使用停止来取消正在运行的工作。
在所需的 message 参数中提供消息正文。不接受 SendMessage、content 和 text 等隐藏别名。
sessions_send 在同一网关上运行另一个会话,并可选择等待响应。其 sessionKey、label 或 agentId 选择本地模型上下文,而不是外部目标。对等方的回复会一次性到达请求者,无论是内联还是作为稍后的会话间输入。继续与另一个 sessions_send 对话。要发布到频道,请使用带有显式频道和目标的 message。
当执行在网关、配对设备和云工作人员之间移动时,会话会保留其地址。 OpenClaw 工作线程可以使用其确切的会话密钥发送给授权的父级、子级或兄弟级,包括在网关上运行的目标。网关在允许目标轮流之前验证当前会话身份、可见性和任何每个代理只发送策略;目标放置不授予消息访问权限。在配置的可见性范围和授权的仅发送规则之外的目标、已存档的目标和替换的目标仍会被拒绝。
显式 agents.entries.<agentId>.tools.agentToAgent.send 列表可以将 sessions_send 授权给选定的代理,而无需将其会话暴露给列表、历史记录、搜索、状态或会话控制工具。遗漏保持正常的全球政策和可见性检查; [] 拒绝普通跨代理发送。全局代理对代理限制、隐身拒绝和沙箱生成会话限制仍然适用。同一代理可见性和请求者拥有的 native/ACP 子访问权限保持不变。请参阅 仅发送配置。
在接受目标输入之前,将再次检查当前的发送策略,包括在会话解析或调度准备期间配置更改时。撤回访问权限并不取消目标已接受的输入或消除其提供相应结果的义务。
仅发送呼叫者可以内联或通过正常延迟传递接收授权发送轮次的回复。这是运行拥有的结果,而不是检索任意目标历史记录的权限。目标仍然可以披露数据或根据请求采取行动;仅发送访问并不能隔离特权目标的行为。
在健康的工作人员配置或工作区准备期间,接受的输入将保持排队状态,直到目标工作人员准备就绪。它在 OpenClaw 重新检查会话和放置后启动一次。取消、安装失败或替换的目标不会在本地或其他工作人员上静默运行该输入。在提交另一条消息之前检查保留的输入和设置错误。
网关接受的普通对等发送保留传递所有权以及保存的输入。意外关闭或更新重新启动后,启动仅重新接纳未使用的输入,这些输入的确切源会话和目标会话仍然存在,并且其当前通信策略和可见性允许传递。它重用原始输入身份,保留每个目标的顺序和消耗重复数据删除;它不会重新运行发送者的任务。取消、重置、存档、撤销访问权限或需要重新批准的策略会阻止自动恢复。没有交付所有权的旧版本保存的输入仍然可供检查,而不是自动重试。在历史上,queued 表示输入具有当前托管权,而不是模型正在执行它;保留 interrupted 的输入已保存,但不会重试。仅显示的通知可以区分更改的会话、拒绝的通信和不可用的准入,而不会将这些诊断反馈给模型。任务延续和引导保留其单独的生命周期所有者。
- 即发即弃: 将
timeoutSeconds: 0以入队并立即返回。 - 等待回复: 设置超时时间并内联获取响应。
- 引导正在运行的子进程:,没有
mode和timeoutSeconds: 0,向您自己生成的子进程的发送将引导到其活动运行并确认队列准入,如mode: "steer",而不是持久性或模型消耗。该承认不是重启持久的。使用mode: "followup"进行单独的子回合并自行完成。闲置的孩子或奔跑拒绝引导的孩子开始新一轮。显式模式保留其现有行为。 - 继续暂停的子任务: 发送没有
mode的继续。当调用者通过任务拥有的完成来控制由sessions_yield暂停的本机子级时,运行时会自动恢复该任务,并保留其身份和原始完成接收者。使用mode: "resume"明确要求此行为。显式mode: "followup"启动单独的回合并保持暂停的任务不变。
仅在网关入学和输入准备后,才会开始对您的本地孩子进行单独的跟进。如果接纳拒绝轮次,发送将返回错误并且轮次不会开始。仅在成功准入后才会安装请求的状态监视。
对于具有进程内单向结果传递的本地子级后续,屈服于接受的子级保持相同的逻辑结果义务。其精确承认的延续返回一个最终结果;空的生成的前身不是完整的 no_reply。积极等待可以转换为异步交付,而无需第二个消费者。这种保管是进程本地的:网关重新启动后它不会恢复调用者权限,并且当该权限或任一对话发生更改时它会关闭。所有者启动的后续行动还保留原始通道所有者身份,以用于同一请求者对话中的单向结果轮转。因此,成功的结果和子失败可以使用所有者专用的插件工具继续已经授权的工作。这不会使子项成为所有者或将其文本视为用户指令。新用户轮换、撤销所有权、更改会话或网关重新启动都会使保留的权限失效。原始暂停的子任务与显式后续任务保持分离。
在允许另一次执行之前,使用相同的输入 ID 重试可协调保留的网关准入和回复收据。
任务恢复返回 status: "accepted"、mode: "resume"、后继 runId、原始 taskRunId 和 completion: "task"。现有任务所有者一次性交付最终结果;该工具不会等待答案或开始单独的回复传递。自动恢复接受普通的 watch 和 timeoutSeconds 参数,但将所有结果传递保留在现有任务中,而不是添加内联等待或第二个观察程序。显式 mode: "resume" 拒绝 watch: true 并积极等待。恢复需要受信任的进程内网关准入。不相关的呼叫者、已完成的任务和更改的子会话都会被拒绝,而不是退回到普通消息传递。控制器所有权仍然绑定到最初记录的会话存储。在没有存储来源的情况下创建的保留任务保留普通的默认消息传递及其现有的显式恢复和取消控制。新注册的任务会记录其存储并可以使用自动延续。
timeoutSeconds 限制发送工具的等待,而不是接收器的执行预算。对于非阻塞协调,请使用 sessions_send 和 timeoutSeconds: 0。当等待到期时,符合条件的待处理答复交付将继续观察已接受的运行,直到完成;等待间隔不会丢弃迟到的回复。嵌套会话间回复使用相同的完成观察。低级网关sessions.send RPC有一个不同的合约:它的JSON timeoutMs限制接收器执行,就像chat.send一样。省略该字段以保留接收者的配置预算;将 CLI 等待与 gateway call --timeout 分开绑定。
接受的结果将目标接纳与回复传递分开。 targetDisposition 是 queued(表示新回合)或 steered(表示活动回合),包括默认发送但不等待您自己的正在运行的孩子; delivery.status 仅将稍后的回复传递描述为 pending 或 skipped。内联回复具有 delivery.status: "skipped" 并且不会启动额外的请求者回合。这两个字段都不是目标完成收据。发送到繁忙聊天会话的新轮次等待其主动回复和传送完成。他们的命令落后于其他特工命令;取消或接收者的执行截止日期可以在运行之前撤回等待轮次。默认零等待发送到您自己正在运行的子进程确认队列准入,例如 mode: "steer";它们不确认转录本持久性或模型消耗,并且不具有重新启动持久性。它们不产生单独的完成转弯。当您需要单独的子回合和完成时,请使用 mode: "followup"。
如果使用相同请求 ID 重试发现原始准入仍处于待处理状态,则该工具将返回错误 sentBeforeError: true 和现有运行 ID,而不安装监视。在重试之前检查该运行。
委派轮流写入目标会话的记录,包括来自设备托管工作人员的回复和工作区冲突报告。请求会话保留自己的记录。
回复来自已完成运行的最终结果。当同一会话目标已通过 message 向源会话发送最终回复时,OpenClaw 会跳过重复的源通道回复。仅存储在内部 UI 中的进度消息和回复不算作外部传送。当同一会话后续仍需要源通道传递时,其回复会保留请求轮次的通道、帐户、收件人和线程(如果可用)。稍后的消息可以更新会话的存储路由,而无需重定向已接受的回复,包括当身份链接隐藏会话密钥中的地址时。
每个完成的同一会话回复都会单独排队以生成原始会话。后来的普通回合和其他已完成的回复不会取消它。重置、删除或替换原始会话会停止尚未开始发送的回复;已经交给通道的发送将保持其正常结果。队列可以在重新启动后恢复已完成的回复。这不会使未完成的模型运行或其内存中回复观察器可重新启动。
无法识别这些队列条目的旧版本会使它们及其附件挂起,同时继续正常工作。返回支持版本以恢复交付。全状态备份包括排队附件;仅数据库备份则不然。备份恢复有意忽略待处理的传送记录并且不恢复这些回复。
在没有可见辅助文本的情况下完成的等待发送将返回 status: "no_reply";没有回复交付仍然待处理。如果目标直接发送了最终回复,结果会如此说明并告诉调用者不要重新发送。否则,无需等待即可继续,或者在需要响应时发送新消息。
线程范围的聊天会话(例如以 :thread:<id> 结尾的密钥)不是有效的 sessions_send 目标。使用父通道会话密钥进行代理间协调,以便工具路由的消息不会出现在活动的面向人的线程内。设置 tools.sessions.allowThreadTargets: true 以选择加入线程和主题目标;目标在该会话中运行,并且使用 message 工具发送的任何内容都会落在线程中。
消息和延迟回复在接收提示 ([Inter-session message ... isUser=false]) 和转录来源中标记为会话间数据。接收代理应将它们视为工具路由数据,而不是直接由最终用户编写的指令。
代理 shell 命令不得替换此路径的操作员 CLI 消息 RPC。通过继承的 OPENCLAW_SHELL=exec 标记,CLI 会拒绝包含初始消息、任务或附件的 sessions.send、sessions.steer、chat.send、agent 和 sessions.create 请求。可用时使用会话工具;没有它的子代理应该通过正常完成返回其结果。交付失败并不授权切换至运营商 CLI。此检查可防止归因意外丢失;环境标记不是与以同一 OS 用户运行的其他进程进行身份验证或隔离。
节点和 Control UI 请求者收到一次已解决的回复。请求者响应不会反馈到目标中,并且不会生成目标通告轮次。传送到目标自己的通道不会抑制特定请求者的回复。
非阻塞发送在返回之前保留请求者的回复权限。完成请求者回合并不会取消已接受的回复;访问撤销或网关更换仍然会阻止它。
子报告也会发送给其收件人一次,而不会自动确认子报告。明确等待的呼叫者仍然可以在线接收接收者的回复。对于新的子轮流,子代理的回复会内联返回或在等待到期后传递一次,并保留子代理完成来源和监护权。
隔离的计划作业可以等待内联回复,但不会收到分离的回复轮次或失败通知。来自此类作业的发送也不会生成目标公告;单独注册的任务完成保留其自己的交付所有者。
这些回复交付适用于新的或后续的回合。默认发送不回复等待您自己的正在运行的子进程,跳过单独的回复传递并将完成留给活动运行的所有者。 mode: "steer" 仅返回添加到活动运行的指导的入场许可,并将完成留给该运行的现有所有者。它使用现有的 sessions_send 访问检查。对于内置运行时,繁忙的工具或模型响应可以延迟转录持久性,直到下一个转向边界;发送者的回复等待期限不会撤回已接受的指导。接受并不是转录持久性或模型消耗的证明,也不会使内存中的转向队列重新启动持久。接收运行保留源权限,直到输入稳定或确切的运行结束或中止;缺少后端结算回调无法将其保留到运行之后。现有的显式取消、运行生命周期和授权规则仍然适用。 mode: "notify" 将上下文排队而不开始轮次。注册任务完成和暂停任务恢复保留其现有的完成所有者,并且不添加第二个回复传递。
具有 operator.sessions.write 的操作员可以将 mode: "notify" 用于他们拥有的授权会话,包括拥有的子级。通知在排队之前保留请求者的当前权限和目标会话检查。它们保留在内存中并且不会开始运行。
儿童协调保留在代理上下文和原始记录中。接收聊天隐藏了子报告和自动协调回复,而正常的任务完成摘要和直接的人工答案仍然可见。没有来源的历史消息不能归类为子流量。
传递 watch: true 也可以将发送者注册为目标的状态更改观察者。观看还需要正常状态可见性;仅发送规则不会授权订阅其他隐藏的会话状态。注册后,当另一个参与者稍后向目标发送直接人类消息或更改其目标时,发送者会收到指向 session_status changesSince 的系统通知。注册在成功分派后发生,以实际接收消息的会话为目标,并从其当前状态版本开始,因此只有稍后的更改才会产生通知。注册成功,结果报告watched: true。请参见 会话状态感知。
对现有本机子项的每个非阻塞后续操作都会在工具返回之前向当前请求者发出完成声明; watch 不是必需的。接受后调用 sessions_yield 等待完成,包括当后续任务在子进程的活动运行之后排队时。正常的子解决路径只传递一次结果。没有请求者轮流的发送保持普通的回复传递行为。被监视的引导者可以声明现有子级的当前回合的待宣布完成,而无需创建另一个完成或更改子级的任务身份。如果转向已被承认但无法再声明其已完成,则该工具会返回错误 sentBeforeError: true。重试前检查目标;该指导已被接受。
状态与编排助手
session_status 是用于当前或另一个可见会话的轻量级 /status- 等效工具。它报告使用情况、时间、model/runtime 状态以及链接的后台任务上下文(如果存在)。与 /status 一样,它可以从最新的记录使用条目回填稀疏的 token/cache 计数器,并且 model=default 清除每个会话覆盖。使用 sessionKey="current" 表示呼叫者的当前会话;可见的客户端标签(例如 openclaw-tui)不是会话密钥。
模型更改的范围仅限于所选会话,并且不会更新代理或全局默认值。网关管理的会话应用与其他会话模型选择相同的模型、运行时和执行环境检查。重复未更改的选择不会更新会话活动或发出模型更改通知。
当路由元数据可用时,session_status 还会包含一个可见的 Route context JSON 块以及匹配的结构化 details 字段。这些字段用于区分会话 key 与当前正在处理实时运行的路由:
origin是会话创建的位置,或者在旧状态缺少已存储的 origin 元数据时,由可交付会话 key 前缀推断出的提供方。active是当前实时运行的路由。它只会针对当前正在处理的实时或当前会话报告。deliveryContext是存储在会话上的持久化交付路由,OpenClaw 即使在活动界面不同的情况下,也可以在后续交付中复用它。
会话状态变更
OpenClaw 会保留一份持久的信号日志,记录重要的会话状态变更(发给受监视会话的直接人工消息、子运行结果、目标变更、压缩)。sessions_list 行和 session_status 会公开该会话的 stateVersion,并且 session_status 接受 changesSince: <version>,以返回该版本之后的类型化事件;当请求的版本早于保留历史时,会精确通过 historyGap 发出信号。监视者——由父级自动生成,或通过 sessions_send watch: true 显式设置——在其他参与者更改受监视会话时,会收到一条合并后的过期状态通知。
状态更改事件省略重复的 session/agent ID,并仅公开对模型有用的有效负载字段(outcome、channel 或 turns)。事件摘要和 actor/run 标识符仍然可用于调节。
完整模型请参见 会话状态感知:事件类型、监视者注册、反垃圾通知协议、对账流程以及当前限制。
sessions_yield 有意结束当前回合,因此下一条消息可以是已宣布的子完成事件。使用它来宣布子代理,而不是 Swarm 收集器:收集器需要通过 agents_wait 或 OpenClaw 代码模式中等待的 agents.run() 进行显式结果收集,并且不发送完成通知。
subagents 列出受控会话树中运行的本机子代理。将返回的runId与action: "wait"或action: "cancel"一起使用;取消不会授予对不相关会话的访问权限。 ACP、媒体、shell 进程和 cron 保留其自己的状态和取消所有者。
生成子代理
sessions_spawn 为后台任务创建单独的会话。默认情况下,非线程生成以隔离上下文开始;线程绑定的生成遵循下面描述的配置的上下文策略。当接受启动时,它返回 runId 和 childSessionKey,而不等待子任务完成。来自 OpenClaw 云工作线程的生成可以首先等待子配置和节点注册。本机子代理运行在任何分叉历史记录之后附加的用户消息中接收其委派任务;仅模型运行时上下文将继承的对话标记为背景,而不是当前子项的分配。 Control UI 显示没有此运行时上下文的任务。系统提示符仅携带子代理运行时规则和路由上下文。
关键选项:
runtime: "subagent"(默认)或"acp"用于外部宿主代理。model和thinking可覆盖子会话配置。runTimeoutSeconds用于覆盖已配置的子运行超时时间;0表示禁用。thread: true用于将 spawn 绑定到聊天线程(Discord、Slack 等)。sandbox: "require"用于强制对子代理进行沙箱化。worktree: true为原生子提供自己的 托管结帐 ,带有可选的projectId、worktreeName和worktreeBaseRef。隐藏子项支持这些字段,无需visible: true;隐藏的projectId和所有工作树 names/base 引用都需要worktree: true。第一轮等待异步准备。cleanup: "delete"使用会话删除来快照并移除结帐;"keep"在通常的空闲和存档生命周期下保留它。 ACP 不支持托管工作树参数。侧边栏group、projectGitUrl和云放置配置文件保持仅可见。context: "fork"当孩子需要当前请求者成绩单时;这需要runtime: "subagent"以及与请求者相同的代理,无论子级是隐藏的还是可见的。明确使用context: "isolated"作为干净的孩子。省略意味着非线程生成的隔离上下文;线程绑定本机子代理遵循threadBindings.defaultSpawnContext,默认为fork。visible: true创建持久可见的受监督子进程而不是隐藏的子代理会话。对于独立的人工请求的会话,请如上所述使用sessions_create。可见生成支持显式侧边栏group、模型、工作目录、同代理转录分叉和可选的 托管工作树;有关确切的兼容性限制,请参阅 Sub-agents。接受的结果是一个收据:它包括子会话密钥、运行 ID、Control UIsessionUrl(当 Control UI 禁用时省略)和命名存储所有者的owner记录。当活动的人类请求者与请求会话的经过验证的人类所有者相匹配时,新的可见子级将继承该人作为所有者。否则,所有者将退回到请求代理。请求代理通常是不可变的创建者;相反,所需的沙箱会保留父级的创建者来源作为隔离策略。当确认通道中的生成时,将会话 URL 放在第一行,将Owner: <label>放在第二行。所有权控制责任和显示,而不是基于创建者的访问;请参见 多用户模式。
低于默认深度限制 5 的子代理会收到 sessions_spawn、subagents、sessions_list 和 sessions_history,以便它们可以管理自己的子代理。设置较低的 maxSpawnDepth 可以更快地将该深度的会话转变为叶。
普通宣告运行将完成事件返回给请求者。遵循其他完成模式的接受收据:收集器需要显式收集,直接路由线程会话在绑定线程中回复,安静运行不发送完成通知。公告传递会在可用时保留绑定的 thread/topic 路由,并且如果完成源仅标识通道,则 OpenClaw 仍然可以重用请求者会话的存储路由 (lastChannel / lastTo) 进行直接传递。
有关 ACP- 特定行为,请参阅 ACP Agents。
可见性
会话工具的作用范围限制了代理可以看到的内容:
| 等级 | 范围 |
|---|---|
self |
仅当前会话 |
tree |
当前+产生;当从主调用时,所有同代理会话 |
agent |
该代理的所有会话 |
all |
所有会话(默认情况下跨代理访问处于启用状态) |
默认值为 all:非沙盒会话(包括保留的 cron 会话)可以列出、读取、搜索、发送消息和检查网关上代理的状态。这可以包括其他用户的成绩单。跨代理访问默认处于启用状态,并受 tools.agentToAgent 管辖;设置 enabled: false 以阻止普通的跨代理访问或使用 allow 限制允许的代理对;请求者拥有的本机子代理和 ACP 子会话在 tree 或 all 下保持可访问。将 agent 设置为仅同一代理访问,或将 tree 设置为当前加上生成的范围;其主要主会话例外仍然涵盖所有同一代理会话。设置 self 以进行严格的当前会话访问,包括 main。
这些范围仍然是读取和控制边界。显式的每代理 tools.agentToAgent.send 匹配只能允许在 self、tree 或 agent 下进行跨代理发送;它不会扩大同一智能体的范围或授权国家监视。
agent 范围不包括其他代理拥有的子项。当依赖其拥有的 native/ACP 子异常时,保持显式 tree,或者使用默认的 all 和适当的 tools.agentToAgent 策略。默认仅生成会话工具夹下的沙盒调用方仍仅限于其生成子树。隐身会话对每个跨会话工具都是隐藏的。氛围群表依然添加活动通知和提示提示;他们不授予访问权限。
相关内容
- Session Management:路由、生命周期、维护
- 会话修剪
- 子代理:子会话生命周期与交付
- ACP Agents:外部harness产卵
- 多代理:多代理架构
- Goal — 持久的每会话目标,通过专用
get_goal、create_goal和update_goal工具读取和更新 - Gateway Configuration:会话工具配置旋钮