---
doc-schema-version: 1
summary: "子代理队列通道、重新启动恢复、停止范围和站立限制"
title: "子代理并发、恢复和停止"
read_when:
  - "您正在调整子代理并发性或调查交付积压"
  - "网关重新启动中断了子代理运行"
  - "您需要 Stop 和 /stop 的确切范围"
---

## <a id="concurrency"></a> 并发

每个生成会话都有自己的普通子代理的进程内队列。设置 `agents.defaults.subagents.maxConcurrent` 限制该会话的并发子运行（默认 `8`）。独立会话具有独立的预算，因此一个繁忙的会话不会占用另一会话的子代理插槽。嵌套协调器的子级使用该协调器的预算，而不是其父级的预算。

该预算属于孩子的直接 spawning/controller 会话。更改子项的完成位置不会将其执行转移到另一个会话的预算中。接受的运行在执行限制队列之上，直到有可用槽为止。

[Swarm](/tools/swarm) 收集器子级 （`collect: true`） 使用专用的 `subagent:swarm:<schedulerGroupKey>` 通道。它的上限是组的已解析 `tools.swarm.maxConcurrent`（默认 `32`），独立于父级的普通 `subagent:<immediate session>` 通道。来自同一父代的普通生成可以在其群体通道已满时开始。由收集器生成的普通子级使用该收集器自己的会话通道。每个运行的收集器需要一个模型流和一个代码模式工作隔离；调整网关资源的 Swarm 上限。

`maxChildrenPerAgent` 是每个会话中活跃儿童的单独入场限制（默认 `5`）；增加执行并发度不会提高该限制。收集器准入改为使用 Swarm 的 `maxChildrenPerGroup`（默认 `50`）和 `maxTotalPerGroup`（默认 `200`）；提高执行并发度不会提高任一组限制。 [Codex 原生子代理](/plugins/codex-harness) 使用 Codex 自己的调度程序并独立于这些 OpenClaw 队列进行限制。

暂停的完成交付不会阻碍新的工作。本机子代理、ACP 会话和可见会话保留其正常的活动运行限制和授权检查，与交付积压无关。

当交付积压达到 25 时，OpenClaw 会发出警告。在网关进程中，未更改的积压计数不会在每次扫描时重复发出警告。计数变化等于或高于 25，或者恢复后返回到该阈值，会产生新的警告。待办事项大小不会丢弃结果或改变其保留。

暂停交付将在 7 天后到期。该警告记录其运行和会话标识符、原始传递错误和暂停时间。到期结束自动交割；它不会将成功的子执行变成失败。对于保留的运行，`/subagents info <runId>` 会显示捕获的结果、丢弃的交付状态和原始错误，即使运行离开最近的列表也是如此。检查该结果或可用的子会话历史记录并要求请求者继续。清理和保留仍然适用：`cleanup: "delete"` 可以删除运行，隐藏会话清理可以删除其转录本。过期并不保证删除的结果仍然可以恢复。

## <a id="liveness-and-recovery"></a> 活跃性与恢复

OpenClaw 不会将 `endedAt` 缺席视为子代理仍然活着的永久证据。当读取进程可以验证当前执行所有者或确切的排队收集器预留时，无论年龄如何，未结束的运行都会继续计数。仅保留元数据并不能在另一个进程中建立所有权。在过时运行窗口（2 小时，或配置的运行超时加上较短的宽限期，以较长者为准）之后，其他未结束的运行将停止计数为 active/pending。这些保留的计数管理 `/subagents list`、状态摘要、后代完成门控和每个会话并发检查；它们并不能证明执行者还活着。

在正常重启或网关挂起期间，已接纳运行的生命周期事件将通过重启保存和完成处理进行跟踪。已承认的替换运行可以在关闭之前完成刷新延迟子结果。刷新将持续被跟踪，直到捕获和持久化完成；它不承认新的运行。

在关闭期间，完成等待将随其原始注册表数据库一起退出。后期清理恢复会为下一个网关留下保留状态，而不是针对关闭的存储进行重试。结果未知的失败写入仍会报告错误并保持隔离状态，直到恢复读取存储的状态。

网关重新启动后，父级拥有用户任务的继续。中断的子代理通过其正常完成路径完成，而不是自动重新启动。他们的结果告诉家长，执行被中断，部分完成的操作需要检查。等待其子批次的父批次接收已确定的结果，包括在重新启动之前完成的子批次，并决定剩余的工作。

可见和私有的请求者结算完成在重新启动后保留其处理结果。同一冻结子批次的重播会确认已完成的请求者轮次，而无需再次执行或交付它。未完成的主会话轮流将通过正常的重新启动恢复以及原始操作员限制继续进行。如果原始权限不可用，则该任务将保留，而不是使用更广泛的权限运行。

对于已产生的嵌套请求者来说，已承认的完成轮次与孤立子项启动不同。其冻结的子结果批次在重新启动时保留了准确保存的延续。注册表恢复会等待该所有者，而不是在重播同一连续过程时报告中断。这并不授权自动重新启动不相关的中断的子工作。

恢复会在恢复剩余声明之前淘汰被取代的请求者转移代。当前一代保留其完整托管权；过时的传输不会无限期地重试。注册表水合和启动传输每次尝试运行一次。水合失败会记录其错误，并可以通过下一次注册表访问重试；不完整的启动传输仍会记录下来以供下次激活或重新启动。恢复不保留单独的重试计时器。请求者恢复选择每个保留回合的子级，而无需重复扫描不相关的运行历史记录。当需要交付收据时，已完成的子项仍保留在已保存的批次中，以防止重播已交付的结果。持久完成的清理不会在重新启动时重播中断的子会话效果。保存的中断仍然拒绝迟到的子结果，并且待处理的请求者唤醒将通过其现有的解决所有者继续进行。

恢复处理标记为 `abortedLastRun: true` 的会话和阻止写入关闭标记的硬终止。对于硬杀，子会话仍必须识别来自已停用网关的确切运行，并且没有较新的运行或承认的工作拥有该会话。实时执行和排队收集器保留其现有所有者。孤立运行在清理之前确定其本机执行状态，因此保留的子会话不会留下幻像运行活动。如果结算失败，仍可重试完成。

恢复会记住实时会话所有权，而不保留已保存的提示快照。未更改的拥有行跳过会话读取；所有权释放或已发布的会话更改请求在一秒钟内进行另一次扫描。不可用恢复读取每行重试，指数退避从一秒到一分钟。注册表生命周期更改和会话发布清除了这种退避。没有实时所有者的持久行仍然需要重新读取，然后恢复才能更改其状态。

启动会话维护报告在一份信息摘要中保留了 run/task 所有者。这些行保留在注册表恢复中；仅会话孤儿修复不会竞争其所有权。维修过程中所有权发生变化且所有权检查失败仍会产生警告。

主会话重新启动恢复在解析其存储之前排除子代理会话；保留的子恢复由子代理注册表所有者保留。

父级可以检查保留的子级脚本并使用 `sessions_send` 继续该会话，或者在确认旧执行已停止后生成替换。重用孩子可以恢复其对话情境；它不会重播中断的命令。现有的清理和保留设置仍然适用。

当分离清理尝试记录 `subagent cleanup finalize failed` 时，其重试在当前网关进程中使用有界退避。如果这些重试已用尽，则运行仍会被记录，但清理不完整；检查警告以确定失败的操作。不相关的子代理完成不会重新启动失败的清理或重置其重试预算。后代完成仍然会唤醒当前等待该工作的请求者祖先。这些清理重试与 [ 完成交付 ](/tools/subagents/announce) 是分开的。

当所需的注册结果未知或保留的注册表状态禁止删除子会话时，网关托管的普通生成错误会保留子会话和运行标识符。如果第一次取消尝试也失败，则错误会报告未确认的终止以及是否计划了网关清理。网关最多进行一次跟踪的后续取消尝试，在调度之前重新检查确切的运行所有者。如果仍然无法确认终止，则会记录警告并保留子控制器的准入槽位，直到子控制器退出或网关关闭接管。子会话保持不变。临时清理运行一次；当失败无法解决时，失败的收集器启动将保留其 FIFO 插槽，直到关闭或重新启动恢复。已经进行的清理工作仍处于连接状态。在重试生成之前检查保留的子项和清理错误。

<Note>
如果子代理生成失败且网关 `PAIRING_REQUIRED` / `scope-upgrade`，请在编辑配对状态之前检查 RPC 调用方。当调用者已经在网关请求上下文中运行时，内部 `sessions_spawn` 协调正在调度，因此它不会打开环回 WebSocket 或依赖于 CLI 的配对设备范围基线。网关进程外部的调用者仍然使用 WebSocket 回退作为 `client.id: "gateway-client"` 和 `client.mode: "backend"` 通过直接环回共享 token/password 身份验证。远程调用方、显式 `deviceIdentity`、显式设备令牌路径和 browser/node 客户端仍然需要正常的设备批准才能进行范围升级。
</Note>

## <a id="stopping"></a> 停止

针对父运行的显式停止会取消与该运行及其后代关联的子进程，包括普通子代理和 [Swarm](/tools/swarm) 收集器。成功取消会阻止选定的排队收集器在运行子进程停止时启动。精确运行取消不会取消不相关的轮次或清除不相关的会话范围队列。

每个新注册都会将其选择的所属代理记录为 `childAgentId`，包括代理限定的子密钥和原始子会话身份。如果可见生成的创建收据省略了该标识，则生成将报告子项错误并运行标识符，而不是接受无法交付的子项。在重试之前检查保留的子项；不要产生替代品。

具有有效代理资格密钥的历史记录保留记录的所有权，无需迁移。显式所有者必须同意密钥的命名空间。当前的默认设置和请求者的代理从不提供缺失的子所有权。

子会话突变需要记录的所有权和原始子会话化身。其所有者未解析或其记录的化身与当前会话冲突的显式选择的运行将返回 `found: true`、`killed: false` 和说明，而不会触及子工作。批量取消报告未解决的成员并继续独立授权的兄弟姐妹。检查留存的运行及原始执行证据；不要将其绑定到当前占用相同密钥的任何会话。在普通清理截止日期之后，不会猜测未解决的子会话清理义务。子权限具有三种状态：已验证、遗留未验证或不匹配。未经验证的旧记录具有可解析的子所有者和请求者所有者，但缺少原始会话标识或生命周期修订。他们可以根据授权请求者的要求进行结算、交付、完成清理记账、恢复和停止。旧版停止会取消确切的任务及其注册的执行（如果可用）；它不会猜测要中断哪个当前会话或后继会话。 OpenClaw 在注册表恢复后对每个网关进程发出一次警告，并包含唯一旧运行 ID 的计数和一些示例 ID，并抑制子会话突变，包括删除、重置和转录清理。缺失的历史身份永远不会被填补。冲突的记录身份仍然是不匹配，而不是遗留异常。

当代理共享原始密钥时，注册表子查找将使用记录的所有权。终端事件和会话计时更新使用相同的子所有者。原始密钥查找需要明确的所有者。未知记录仍然可以通过运行 ID 检查，但不能取代拥有的运行或授权子操作。

明确拥有的原始密钥子级仍然会完成并唤醒其请求者。他们记录的代理还负责浏览器清理，因此成功的清理可以完成与代理合格的子密钥相同的簿记工作。

停止还会取消所选工作的待完成继续，即使子项已经完成也是如此。取消完成轮次会停用其匹配的子批次，因此自动交付重试无法在新运行 ID 下再次启动它。捕获的子结果及其执行结果保持不变；您可以检查它们或随后发送新的指令。

父 Stop 还会耗尽其选定的本机子级保留的普通命令，即使在模型执行完成后也是如此。已完成的子成绩仍保持完整状态；命令清理不会将取消的模型运行添加到结果中。故意以 `background: true` 开头的命令保持独立。当实时命令延续在另一个会话中运行时，它会保留原始请求的子所有权。 Stop 仅选择该请求所绑定的本地子代，而不会影响新的人类工作和替代子代。在延续完成并且其通知已被消耗之后，新的会话停止仍然可以选择那些子级。它使用当前原始会话的权限和生成；在该请求的活动、进程和事件所有权结束后，历史精确运行停止不会重新获得权限。

对于网关调用方，带有 `runId` 的 `chat.abort` 使用此精确父范围。 `sessions.abort` 和 `runId` 也以运行为目标。当它在没有聊天控制器的情况下解析恢复的本机运行时，仅当捕获的活动父级接受“停止”时，它才会取消子级；拒绝或不活跃的运行结果，包括已经最终确定的父母，会让这些孩子独自一人。

在请求者聊天中发送 `/stop` 具有更广泛的范围：它中止请求者会话工作，清除其队列，并取消其活动子树。会话范围内的 `sessions.abort` 也请求后代取消；清除排队的后续任务需要 `clearQueued: true`。没有 `runId` 的普通 `chat.abort` 不会级联到儿童。这些操作保留其正常的授权检查。

通过 `chat.send` 发送的类型化 `/stop` 遵循 `expectedLeafEntryId`，并且当存在该分支检查时，遵循 `sessionId`。如果在后代取消期间检查失败，则网关拒绝进一步取消并报告 `active-leaf-changed`。孩子已经接受的取消仍然有效。如果子所有权在分支检查运行之前拒绝取消，则网关将重新检查所请求的叶：已更改的叶优先，而未更改的叶保留所有权错误。这两种结果都不允许更换替代孩子。在检查原始会话是否仍然拥有结果之前，取消结果会等待挂起的子会话元数据写入。

不完全取消会被报告为错误，而不是完全成功。 `/stop` 报告实际停止和失败的子项计数。如果稍后清理失败或替换父级，则已提交的子级取消仍保留在停止计数中。清理错误仍然可见；替换运行需要其自己的停止请求。检查剩余的本机子代理运行 `subagents` 并重试取消它们；请求确认并不意味着所有运行时清理都是即时的。

在普通父级完成、屈服或超时后，接受的子级保持独立。这些事件不会自动取消。

## <a id="limitations"></a> 限制

- Direct 声明尝试是尽力而为的，但承认会话排队完成切换及其本机子代理记录在共享 SQLite 状态数据库中的网关重新启动后仍然存在。
- 子代理仍然共享相同的网关进程资源；并发上限适用于每个生成会话或 Swarm 组，而不是总网关并发数。
- 当接受启动时，`sessions_spawn` 返回 `{ status: "accepted", runId, childSessionKey }`，而不等待子任务完成。云工作者生成可以在返回此收据之前等待配置。
- Sub-agent 上下文仅注入 `AGENTS.md`（无 `SOUL.md`、`IDENTITY.md`、`USER.md`、`MEMORY.md` 或 `BOOTSTRAP.md`）。其 `## Tools` 部分包含特定于环境的注释。 Codex-native 子代理通过本机 `AGENTS.md` 发现遵循相同的边界，而仅限父级的角色、身份和用户文件作为轮次范围的协作指令注入，因此子代理不会克隆它们。
- 默认情况下，通过深度 `5` 启用递归生成。设置 `maxSpawnDepth` 从 `1` 到 `5` 以降低边界。
- `maxChildrenPerAgent` 限制每个会话的活动子级（默认 `5`，范围 `1-20`）。

子代理生命周期警告在文件日志中保留错误名称、消息、代码和完整堆栈；控制台输出包括前六个堆栈行。直接公告和请求者解决重试警告还包括请求者和传递幂等密钥，因此可以在不记录消息内容的情况下跟踪重试。