命令队列
OpenClaw 通过一个微型进程内队列将所有渠道的入站自动回复运行序列化,以防止多个代理运行相互冲突,同时仍允许跨会话的安全并行。
为什么¶
- 自动回复运行可能开销较大(涉及 LLM 调用),当多条入站消息在短时间内相继到达时,可能会相互冲突。
- 序列化可以避免对共享资源(会话状态、日志、CLI 标准输入)的争用,并降低上游速率限制的可能性。
工作原理¶
- 一种感知通道的 FIFO 队列以可配置的并发上限排空每个通道(未配置的通道默认为 1;
main使用max(8, 可用 CPU 并行度 * 4),普通子代理队列默认为每个生成会话 8,Swarm 收集器队列默认为每组 32)。 - 优先级具有有界的领先优势:前台工作最多可超越普通工作 15 秒,最多可超越后台工作 30 秒。超过该时间后,较新的前台到达项无法继续越过较早的工作。通道和共享容量组使用相同的顺序,在每个优先级内保持 FIFO。已占用的槽位和更早排队的任务仍可能延迟准入;正在运行的轮次永远不会被抢占。
- CLI、嵌入式和 Codex 运行共享同一条会话键通道(
session:<key>)。每一轮在获取会话的执行声明之前都要在此等待,因此更换运行时不会启动竞争的轮次。 - 入站消息可以在其轮次进入通道之前持久化。正在运行的轮次会读取一致的对话记录前缀,因此较后入队的消息不会使其上下文读取失效。重写、压缩、删除和分支变更仍会使该读取失效。
- 入站会话运行随后进入全局
main通道,其并行度由agents.defaults.maxConcurrent限制。普通子代理运行则使用其直接生成/控制会话的预算,由agents.defaults.subagents.maxConcurrent设置。Swarm 收集器的子级使用其所属组的独立预算,由tools.swarm.maxConcurrent设置。 - 嵌入式尝试准备在每个时间片内完成 16 次阶段启动或至少 8 毫秒的同步调度工作后,会让出事件循环,以便并发启动为 Gateway 请求留出空间。正在运行的阶段不会被抢占。异步阶段工作仍然可以重叠,且不计入该时间预算;这不会降低运行并发限制,也不会改变会话序列化。
- 启用详细日志后,如果排队的运行在启动前等待超过约 2 秒,会发出简短通知。
queueAhead记录的是入队时的积压情况,而非经过优先级和老化处理后的准入顺序预测。 - 打字指示器仍然会在入队时立即触发(当渠道支持时),因此在运行等待期间用户体验不变。
默认配置¶
未设置时,所有入站渠道均使用:
mode: "steer"- 内置 500 毫秒防抖,用于 steer、followup 和 collect 批处理
cap: 20drop: "summarize"
同轮引导是默认行为。当运行可以接受引导时,运行中途到达的提示会被注入到活动运行时中,因此不会启动第二个会话运行。如果活动运行无法接受引导,OpenClaw 会等待活动运行结束后再启动该提示。
队列模式¶
/queue 控制当会话已有活动运行时,普通入站消息的行为:
steer:将消息注入活动运行时,包括在其正在执行工具时。OpenClaw 会先让助手消息的第一个可执行调用启动,之后引导才能跳过其尚未启动的顺序尾部。正在运行的工具会执行完毕,并行批次绝不会为了引导而跳过调用。每个批次结束后,OpenClaw 会在停止钩子之前检查引导,并在工具结果之后、下一次模型决策之前使其可见。Codex 应用服务器会收到一个批量的turn/steer事件,并在下一个模型边界应用它。如果引导不可用,OpenClaw 会等待活动运行结束后再启动该提示。followup:不进行引导。将每条消息入队,在当前运行结束后再执行后续代理轮次。collect:不进行引导。在静默窗口之后,将兼容的排队消息合并为单个后续轮次。消息必须共享路由、授权和执行设置,并且不能具有不同的独占准入生命周期。interrupt:中止该会话的活动运行,然后运行最新的消息。此取消不会通过 Gateway 重启恢复来恢复旧轮次。
来自使用持久化入口准入的渠道(包括 Discord 和 Telegram)的消息会保持独立的后续轮次:在这些渠道中,collect 的行为与 followup 相同。每条消息都拥有独占的准入生命周期,因此一个来源无法在另一个来源拒绝合并轮次之前提交。兼容的 Gateway chat.send 输入使用非独占生命周期,仍然可以进行 collect。
有关运行时特定的时序和依赖行为,请参阅引导队列。有关显式的 /steer <message> 命令,请参阅 Steer。
Gateway 输入在排队或委派给子级时,会保留其经过身份验证的操作者和原始作用域上限。收集消息或引导活动运行需要兼容的操作者来源和工具权限;其他输入则按 FIFO 顺序等待,而不会借用活动发送者或最新发送者的权限。
已接受的轮次可以在其请求返回或客户端断开后继续执行。但这不会延续已撤销的设备权限或由当前操作者角色移除的权限。后续操作仍会检查原始来源,包括由已接受的子级持有的工作。
通过 messages.queue 进行全局或按渠道配置:
{
messages: {
queue: {
mode: "steer",
cap: 20,
drop: "summarize",
byChannel: { discord: "collect", x: "followup" },
debounceMsByChannel: { discord: 1000, x: 500 },
},
},
}
两个映射都接受来自内置和已安装插件的渠道 ID。例如,messages.queue.byChannel.x 设置 X 插件的队列模式。配置验证会警告渠道注册表中不存在的 ID;请安装相应的插件或更正键名。队列模式和非负整数防抖值仍然会经过验证。
队列选项¶
每会话的 /queue 选项适用于排队投递。debounce 选项还会在 steer 模式下设置 Codex 转向静默窗口:
debounce:排空排队中的后续消息或 collect 批次之前的静默窗口;在 Codexsteer模式下,发送批量turn/steer之前的静默窗口。纯数字表示毫秒;接受ms、s、m、h和d单位。cap:每个会话的最大排队消息数。低于1的值会被忽略。drop: "summarize"(默认):按需丢弃最旧的排队条目,保留紧凑摘要,并将其作为合成后续提示注入。drop: "old":按需丢弃最旧的排队条目,不保留摘要。drop: "new":当队列已满时,拒绝最新消息。
队列使用内置的 500ms 防抖。cap 默认为 20,drop 默认为 summarize。
转向与流式传输¶
当频道流式为 partial 或 block 时,在活跃运行到达运行时边界时,转向可能表现为多个简短的可见回复:
partial:预览可能提前定稿,然后在转向被接受后开始新的预览。block:草稿大小的块可能产生相同的顺序外观。- 如果没有流式传输,当运行时无法接受同轮转向时,转向会回退为活跃运行后的后续消息。
steer 不会中止正在运行的工具。被跳过的 OpenClaw 工具调用会收到合成的成对错误结果,以保持转录有效。当最新消息应中止当前运行时,请使用 /queue interrupt。
回答待处理问题¶
对代理待处理问题的纯文本回答会先于普通队列处理发送到该问题,包括原生 CLI 无法接受转向的情况。 OpenClaw 会根据问题创建者的权限和活跃运行来检查该回答,而不是根据你下一轮选择的模型。权限变更或创建者已关闭会产生明确的拒绝,而不是开始另一轮。
如果回答可能已提交但确认丢失,OpenClaw 会报告该不确定性,并且不会将其作为转向或后续消息重新发送。重试前请检查对话。后续的投递或源清理失败不会使该回答可重放,仅凭不确定性也不会取消原始代理运行。
优先级¶
对于模式选择,OpenClaw 按以下顺序解析:
- 内联或已存储的每会话
/queue覆盖。 messages.queue.byChannel.<channel>。messages.queue.mode。- 默认
steer。
对于选项,内联或已存储的 /queue 选项优先于配置。然后按顺序应用频道特定防抖(messages.queue.debounceMsByChannel)、插件防抖默认值和内置默认值。cap 和 drop 是全局/会话选项,不是每频道配置键。
每会话覆盖¶
- 将
/queue <steer|followup|collect|interrupt>作为独立命令发送,以存储当前会话的队列模式。 - 选项可以组合:
/queue collect debounce:0.5s cap:25 drop:summarize /queue default或/queue reset会清除会话覆盖。
排队轮次取消¶
当提示位于 followup/collect 队列中时(例如在另一个轮次活跃时,TUI 或 webchat 的 chat.send 到达),Gateway 会为该客户端 runId 保留一个 Gateway 拥有的取消标识,直到排队内容运行或被丢弃。该标识会跟随被折叠到溢出摘要中的内容。
- 带有特定
runId的chat.abort会在该轮次仍排队时取消它,前提是请求者已获授权(与活跃运行相同的归属规则)。 - 对于没有
runId的会话,chat.abort会先取消已授权的排队轮次,然后中止已授权的活跃运行,包括在没有 Gateway 聊天控制器的情况下启动的会话活跃运行(例如 OpenAI 兼容的 HTTP 请求或频道回复)。该顺序可防止队列排空将工作提升到半停止的会话中。 - 在没有按请求者检查的情况下清除整个会话队列,不是多所有者会话的停止路径。
- 排队等待不会作为活跃代理运行投影到
sessions.list,也不拥有活跃运行超时语义;只有活跃阶段才拥有。 - 在执行前过期或被取消的排队请求只会结算该请求。其保存的输入仍标记为已取消;它不会结束活跃轮次、暂停其目标,或向对话添加活跃运行失败。
- 在 Control UI 中删除特定排队消息也会隐藏该待处理提示及其附件。取消记录可防止重连后重放。停止和超时取消会保留其恢复消息。
Gateway 支持的客户端(包括 openclaw tui)会转发运行中的提示,并让 Gateway 应用队列模式。Esc//stop 使用会话范围的中止,因此丢失的本地句柄不会让仍排队的提示继续运行。
openclaw chat 和 openclaw tui --local 在嵌入式运行时中应用相同的四种模式。本地 steer 在该运行时接受转向时注入到活跃的嵌入式运行中,否则成为后续消息;followup 和 collect 保持为本地待处理工作;interrupt 在开始最新消息之前中止活跃的本地运行。显式的 /steer <message> 命令不是本地模式命令。
输入持久性¶
通过 chat.send 发送到现有会话的普通用户输入会在 Gateway 确认之前存储到每代理数据库中。
这包括 Control UI、TUI、CLI、原生应用和 RPC 客户端。
其他已连接客户端可以在输入等待时显示已接受的输入,而无需等待新的代理轮次。
在 collect 模式下,追加合并后的轮次并将其源输入标记为已消耗会在一个事务中完成。即使浏览器重连错过了它们的最终事件,也可以对账这些源输入。
聊天会将记录的非 Web 客户端来源与发送者分开显示,例如 Alice · via CLI。这些标签中会省略 Web 来源,包括同时包含来自另一客户端输入的收集消息。
报告的应用名称描述提交客户端;它们不会确立人类身份或授予权限。
收集消息会保留其贡献客户端来源,而没有记录来源的旧消息会保留其现有归属。
这会保留输入,而不是执行权限。如果 Gateway 在排队输入到达会话记录之前停止,重启后它会显示为中断的输入,并需要显式重发。内存队列不会被重放。保留进程的主机休眠可以正常继续现有队列。
由持久化 ingress 保留的通道消息,在排队的尝试于 agent 回合采纳之前被放弃时,仍可重试。放弃操作会在 ingress 重试之前释放该尝试的入站和队列去重条目。已被采纳或消费的消息保留去重抑制,因此传输重发不会重复其效果。
通道与范围¶
- 适用于所有使用网关回复管道的入站通道上的自动回复 agent 运行(WhatsApp web、Telegram、Slack、Discord、Signal、iMessage、webchat 等)。
- 默认通道(
main)对入站回合是进程范围的;设置agents.defaults.maxConcurrent以允许多个会话并行。 - Heartbeat 嵌入运行使用有界的
cron-nested通道进行全局准入,以便缓慢的后台工作不会阻塞入站回复,同时其配置的 heartbeat 会话通道仍会串行化该会话的工作。 - 可能存在其他通道(例如
cron、cron-nested、nested),以便后台任务并行运行而不阻塞入站回复。隔离的 cron agent 回合持有cron槽位,而其内部 agent 执行使用cron-nested。共享的非 cronnested流程保留其自身的通道行为。这些分离的运行仍由其原生运行时拥有。 - 普通子 agent 执行使用
subagent:<immediate session>。agents.defaults.subagents.maxConcurrent对每个会话默认为8;独立会话和嵌套编排器不共享这些槽位。单独的maxChildrenPerAgent准入限制仍然适用。Codex 原生子 agent 使用 Codex 自己的调度器。 - Swarm 收集器子项使用
subagent:swarm:<schedulerGroupKey>,受该组解析后的tools.swarm.maxConcurrent限制(默认32)。它们不占用其父级的普通子 agent 通道。由收集器生成的普通子项使用该收集器自身的会话通道。Swarm 的maxChildrenPerGroup和maxTotalPerGroup仍是单独的准入限制。通道诊断会识别 swarm 通道及其组键。 - 每会话通道保证同一时间只有一个 agent 运行触及给定会话。
- 无外部依赖或后台工作线程;纯 TypeScript + promises。
后台工作¶
Skill Workshop 审查和插件后台完成(包括 dreaming)共享一个独立的 三个并发运行 预算。Workshop 审查最多使用一个槽位;每个插件最多可使用三个可用槽位。这使维护工作不占用前台回复容量,同时限制其总并发。这些限制是内置的,无需配置。
等待后台工作的调度器本身不占用此预算。只有被分派的工作持有槽位,直到完成或取消清理,因此调度器不会阻塞它正在等待的子项。已取消的排队工作会在开始前被移除;Gateway 重启或运行时退役可防止过期完成开始或返回结果。
Control UI 的 System busyness 覆盖层和 diagnostics.lanes 将此工作报告为一行 background。其活动数和排队数包括每个所有者;所有者通道不会在动态会话通道总数中再次计数。
故障排查¶
- 如果命令似乎卡住,请启用详细日志并查找 "queued for ...ms" 行,以确认队列正在排空。
- 在
lane wait exceeded中,activeAhead统计条目入队时的活动任务数;activeNow统计其即将开始前的活动任务数。activeAhead=1 activeNow=0可能表示前一个任务刚刚完成,即使经过长时间等待。这并不证明存在泄漏的槽位。准入失败和已完成任务会释放其槽位并排空排队的后继任务,即使诊断抛出异常;lane task diagnostics failed after settlement标识一个任务,其完成日志在其调用方结算后失败。 - Codex app-server 运行在接受一个回合后停止发出进度时,会被 Codex 适配器中断,以便活动会话通道可以释放,而不是等待外层运行超时。
- 当启用诊断时,如果在内置警告阈值后仍停留在
processing且未观察到回复、工具、状态、阻塞或 ACP 进度,会话会按当前活动分类: - 具有近期进度的活动工作记录为
session.long_running。拥有的静默模型调用也会保持session.long_running,直到内置中止阈值,以免过早将缓慢或非流式提供商报告为停滞。 - 没有近期进度的活动工作记录为
session.stalled;拥有的模型调用、被阻塞的工具调用和停滞的嵌入运行在中止阈值时或之后切换为session.stalled。无所有者的过期模型/工具活动不会被隐藏为长时间运行。 session.stuck保留给可恢复的过期会话簿记,包括具有过期无所有者模型/工具活动的空闲排队会话。session.stuck始终触发可释放受影响会话通道的恢复。超过中止阈值的session.stalled分类(被阻塞的工具调用、停滞的模型调用或停滞的嵌入运行)也可触发主动中止恢复,因此两种分类都可以解除队列卡住,而不仅仅是session.stuck。- 没有语义进展的重复模型请求共享一个停滞时钟,从第一次重试开始。因此,达到输出限制的长初始响应会为纠正请求保留完整的恢复窗口。成功完成的嵌入工具会在其当前运行所有者下重置时钟,即使外层响应随后达到其输出限制。失败、被阻塞或所有者已退役的工具不会重置它。新的传输字节或后续重试不能无限续期它。恢复在中止前会重新检查该证据,遵守拥有的工具和提供商重试期限,并让现有运行所有者在队列排空前结算。
- 当恢复中止一个尚未回复的交互回合,且其请求已保存到会话记录时,OpenClaw 会尝试一次继续,而不是立即要求用户重试。当下一个排队的后续消息来自同一发送者和路由(例如带有
queueMode: "followup"的chat.send)时,它会接管未决请求;否则恢复回合会在停滞回合的路由上开始。恢复回复会以与该来源任何排队后续消息相同的方式投递;Web UI(chat.send)恢复会作为聊天中其自身的运行到达。群组线程参与者回合会收到该通知,因为排队的参与者回复没有投递所有者。两者都使用现有会话记录,并被指示不要重复已完成的操作。其他发送者的排队消息以及在停滞回合期间到达的通道消息随后作为其自身的回合运行。如果该继续也停滞或无法调度,包括原始请求尚未保存时,"stopped making progress" 通知是最后手段。Heartbeat 和 cron 回合不受影响。 - 重复的
session.stuck和session.long_running警告日志行会在会话保持不变时指数退避;恢复尝试仍会在每个 heartbeat tick 运行,无论该退避如何。
相关¶
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw