子代理并发、恢复和停止
并发¶
每个派生会话都有自己的进程内队列,用于普通子代理。设置
agents.defaults.subagents.maxConcurrent 会限制该会话的并发子运行
(默认 8)。独立会话拥有独立预算,因此一个
繁忙会话不会消耗另一个会话的子代理槽位。嵌套
编排器的子项使用该编排器的预算,而不是其父级的预算。
预算属于子代理的直接派生/控制会话。 更改子代理完成投递的位置不会将其执行 转移到另一个会话的预算中。超过执行上限的已接受运行会排队,直到 有可用槽位。
Swarm 收集器子代理(collect: true)则使用专用
subagent:swarm:<schedulerGroupKey> 通道。其上限是该组解析后的
tools.swarm.maxConcurrent(默认 32),独立于父级的普通
subagent:<immediate session> 通道。即使其 Swarm 通道已满,来自同一父级的普通派生
也可以启动。由收集器派生的普通子代理使用
该收集器自己的会话通道。每个运行中的收集器消耗一个模型流
和一个 Code Mode 工作隔离实例;请根据 Gateway 的资源调整 Swarm 上限。
maxChildrenPerAgent 是每会话活动子代理的独立准入限制
(默认 5);提高执行并发不会提高该
限制。收集器准入则使用 Swarm 的 maxChildrenPerGroup(默认
50)和 maxTotalPerGroup(默认 200);提高执行并发不会
提高任一组限制。Codex 原生子代理 独立于这些 OpenClaw 队列,使用 Codex 自己的调度器
和限制。
挂起的完成投递不会阻塞新工作。原生子代理、ACP 会话和可见会话独立于投递积压,保留其正常的活动运行限制和 授权检查。
当投递积压达到 25 时,OpenClaw 会发出警告。在 Gateway 进程内, 未变化的积压计数不会在每次扫描时重复警告。计数在 25 及以上发生变化,或恢复后重新达到该阈值,都会产生新 警告。积压大小不会丢弃结果,也不会改变其保留策略。
挂起的投递会在七天后过期。警告会记录其运行和
会话标识符、原始投递错误以及挂起时间。过期会终止
自动投递;它不会将成功的子执行变为失败。
对于保留的运行,/subagents info <runId> 会显示捕获的结果、已丢弃的
投递状态和原始错误,即使该运行已离开最近列表。
检查该结果或可用的子会话历史,并要求请求方
继续。清理和保留仍然适用:cleanup: "delete" 可以删除该
运行,隐藏会话清理可以删除其会话记录。过期不保证
已删除的结果仍可恢复。
存活与恢复¶
OpenClaw 不会将 endedAt 缺失视为子代理仍然存活的永久证明。当读取进程能够验证当前
执行所有者或精确的已排队收集器预留时,未结束的运行无论存在多久都会继续计入。仅凭持久化元数据无法在另一个进程中确立该所有权。其他未结束的运行在过期运行窗口
(2 小时,或配置的运行超时加上短暂宽限期,
以较长者为准)之后,不再计为活动/待定。这些保留的计数用于控制 /subagents list、
状态摘要、后代完成门控和每会话并发检查;它们不是执行器存活的证明。
在优雅重启或 Gateway 挂起期间,已准入运行的生命周期事件 会通过重启保留和完成处理继续被跟踪。已准入的替换运行可以在关闭前完成对延迟 子结果的刷新。刷新会持续被跟踪,直到捕获和 持久化完成;它不会准入新运行。
完成等待在关闭时随其原始注册表数据库一起失效。 延迟的清理恢复会为下一个 Gateway 保留状态,而不是 对已关闭的存储进行重试。结果未知的写入失败仍会 报告错误,并保持隔离,直到恢复读取到规范状态。
Gateway 重启后,父级负责继续用户的任务。 被中断的子代理会通过正常完成路径终结,而不是 自动重新启动。它们的结果会告知父级执行已被 中断,并且部分完成的操作需要检查。等待其子代理批次的父级 会收到已确定的结果,包括在重启前已完成的子代理,并决定剩余工作。
对于已让出的嵌套请求方,已准入的完成轮次不同于 孤立的子代理启动。其冻结的子结果批次会在重启中保留精确的 已保存延续。注册表恢复会等待该所有者,而不是 在同一延续被重放时报告中断。这不会授权自动重新启动无关的中断子工作。
恢复会在恢复剩余声明之前,使被取代的请求方转移代际失效。 当前代际保留其完成托管;过时的转移不会无限重试。瞬时持久化失败仍会重试。
恢复会处理标记为 abortedLastRun: true 的会话,以及阻止关闭标记写入的强制终止。对于强制终止,子会话仍必须识别来自已退役 Gateway 的精确运行,并且没有更新的运行或已准入工作拥有该会话。活动执行和已排队收集器保留其现有所有者。孤立运行会在清理前确定其原生执行状态,因此保留的子会话不会留下幻影运行活动。如果确定失败,完成仍可供重试。
恢复会记住活动会话所有权,而不保留已保存的提示快照。 未变化的已拥有行会跳过会话读取;所有权释放或已发布的会话变更会请求在一秒内进行另一次扫描。不可用的恢复读取会按行重试,退避时间从一秒到一分钟指数增加。注册表生命周期变更和会话发布会清除该退避。没有活动所有者的持久化行在恢复更改其状态前仍需要一次新读取。
Startup session maintenance reports retained run/task owners in one informational summary. Those rows remain with registry recovery; the session-only orphan repair does not compete for their ownership. Ownership changes during a repair and failed ownership checks still produce warnings.
The parent can inspect a retained child transcript and use sessions_send to
continue that session, or spawn a replacement after confirming the old execution
has stopped. Reusing a child restores its conversation context; it does not replay
an interrupted command. Existing cleanup and retention settings still apply.
When a detached cleanup attempt logs subagent cleanup finalize failed, its
retries use bounded backoff in the current Gateway process. If those retries are
exhausted, the run remains recorded with incomplete cleanup; inspect the warning
to identify the failing operation. Unrelated
sub-agent completions do not restart failed cleanup or reset its retry budget.
Descendant completion still wakes the current requester ancestors waiting on that
work. These cleanup retries are separate from completion delivery.
When required registration has an unknown outcome or retained registry state forbids deleting the child session, a Gateway-hosted ordinary spawn's error keeps the child's session and run identifiers. If the first cancellation attempt also fails, the error reports unconfirmed termination and whether Gateway cleanup was scheduled. The Gateway retains the child's admission slot while retrying and rechecks the exact run owner before each attempt. If database admission retires while that child still runs, cancellation stops but its slot stays reserved until the child controller retires or Gateway shutdown takes over. The child session stays intact. Provisional session rollback, collector FIFO cleanup, and local embedded cleanup remain joined. Inspect the retained child before retrying the spawn.
Note
If a sub-agent spawn fails with Gateway PAIRING_REQUIRED /
scope-upgrade, check the RPC caller before editing pairing state.
Internal sessions_spawn coordination dispatches in process when the
caller is already running inside the gateway request context, so it does
not open a loopback WebSocket or depend on the CLI's paired-device scope
baseline. Callers outside the gateway process still use the WebSocket
fallback as client.id: "gateway-client" with client.mode: "backend"
over direct loopback shared-token/password auth. Remote callers, explicit
deviceIdentity, explicit device-token paths, and browser/node clients
still need normal device approval for scope upgrades.
Stopping¶
An explicit Stop targeting a parent run cancels the children associated with that run and their descendants, including ordinary sub-agents and Swarm collectors. Successful cancellation keeps selected queued collectors from starting while running children stop. Exact-run cancellation does not cancel unrelated turns or clear unrelated session-wide queues.
For raw child session keys such as global, registration records the known
owning agent as childAgentId. Child cancellation derives that agent's session
store from current configuration, just as it does for agent-qualified keys,
which need no recorded binding. Clearing the child's queued follow-ups and
commands stays within that agent, even when another agent uses the same raw
session key. Legacy runs without a recorded owner use current configuration to
resolve one agent and clear only that agent's queues. The optional binding stays
in payload_json when an older build rewrites the run.
Owner-aware child lookups keep watched follow-ups, steering, run generations, completion transcripts, and timeout reconciliation separate when agents share a raw key. Terminal events and session timing updates use that same child owner. Rows without a recorded owner and callers without an explicit owner retain their existing key-only lookup behavior.
Stop also retires pending completion continuations for the selected work, even when a child has already finished. Cancelling a completion turn retires its matching child batch, so automatic delivery retries cannot start it again under a new run ID. Captured child results and their execution outcomes remain intact; you can inspect them or send a new instruction afterward.
A parent Stop also drains ordinary commands retained by its selected native
children, even after their model execution has completed. Completed child results
remain completed; command cleanup does not add canceled model runs to the result.
Commands deliberately started with background: true remain independent.
A live command continuation retains the original request's child ownership when
it runs in another session. Stop selects only that request's bound native children,
leaving newer human work and replacement child generations alone.
A fresh session Stop can still select those children after the continuation has
completed and its notification has been consumed. It uses the current original
session's authority and generation; a historical exact-run Stop does not regain
authority after that request's active, process, and event ownership has ended.
For Gateway callers, chat.abort with a runId uses this exact-parent scope.
sessions.abort with a runId also targets that run. When it resolves a recovered
native run without a chat controller, it cancels children only if the captured
active parent accepts Stop; a declined or no-active-run result, including an
already-finalizing parent, leaves those children alone.
Sending /stop in the requester chat has broader scope: it aborts requester
session work, clears its queues, and cancels its active child tree. Session-wide
sessions.abort also requests descendant cancellation; clearing queued follow-ups
requires clearQueued: true. Ordinary chat.abort without a runId does not
cascade to children. These operations retain their normal authorization checks.
通过 chat.send 发送的带类型的 /stop 会遵循 expectedLeafEntryId,并且当该分支检查存在时,还会遵循 sessionId。如果在后代取消期间该检查失败,Gateway 会拒绝进一步取消,并报告 active-leaf-changed。已被子会话接受的取消仍会完成。取消结果会等待待处理的子会话元数据写入,然后再检查原始会话是否仍拥有该结果。
不完整的取消会作为错误报告,而不是正常成功。/stop 会报告实际已停止和失败的子会话数量。如果后续清理失败或父会话被替换,已提交的子取消仍会计入已停止数量。清理错误仍会可见;替换运行需要其自身的 Stop 请求。使用 subagents 检查剩余的原生子代理运行,并重试它们的取消;请求确认并不意味着所有运行时清理都是即时完成的。
已接受的子会话在普通父会话完成、让出或超时后仍保持独立。这些事件不会自动取消它们。
限制¶
- 直接 announce 尝试是尽力而为的,但已准入的会话排队完成交接及其原生子代理记录会在共享 SQLite 状态数据库中保留,并能在 Gateway 重启后存活。
- 子代理仍共享相同的 Gateway 进程资源;并发上限按生成会话或 Swarm 组应用,而不是按 Gateway 总并发应用。
sessions_spawn在启动被接受时返回{ status: "accepted", runId, childSessionKey },而不会等待子任务完成。Cloud-worker 生成可以在返回此回执前等待资源配置完成。- 子代理上下文仅注入
AGENTS.md(不注入SOUL.md、IDENTITY.md、USER.md、MEMORY.md或BOOTSTRAP.md)。其## Tools部分包含环境特定说明。Codex 原生子代理通过原生AGENTS.md发现遵循相同边界,而仅父级的人格、身份和用户文件会作为轮次范围的协作指令注入,以免子代理克隆它们。 - 默认启用递归生成,最大深度为
5。将maxSpawnDepth设置为1到5可降低该边界。 maxChildrenPerAgent限制每个会话的活跃子会话数量(默认5,范围1-20)。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw