本页内容

本页内容

消息和传递

命令队列

OpenClaw 通过一个轻量级的进程内队列对传入的自动回复运行(所有渠道)进行串行化处理,以防止多个代理运行相互冲突,同时仍允许在不同会话之间安全并行。

为什么

  • 自动回复运行可能成本较高(LLM 调用),并且当多个传入消息几乎同时到达时可能发生冲突。
  • 串行化可以避免对共享资源(会话状态、日志、CLI stdin)的竞争,并降低触发上游速率限制的可能性。

工作原理

  • A 通道感知 FIFO 队列通过可配置的并发上限耗尽每个通道(未配置的通道默认为 1;main 使用 max(8, available CPU parallelism * 4),普通子代理队列默认为每个生成会话 8 个,Swarm 收集器队列默认为每组 32 个)。
  • Priority 具有有限的领先优势:前台工作最多可以比正常工作快 15 秒,后台工作最多可以快 30 秒。此后,较新的前台人员无法继续超越较旧的工作。通道和共享容量组使用相同的顺序,在每个优先级中保留 FIFO。被占用的时隙和较早排队的工作仍然会延迟入场;跑步转弯永远不会被抢占。
  • CLI(嵌入式)和 Codex 运行共享相同的 会话密钥通道 (session:<key>)。每个轮次都会在获取会话的执行声明之前等待,因此更改运行时间无法启动竞争轮次。
  • Inbound 消息可以在轮到其进入通道之前保留。正在运行的轮次读取一致的转录本前缀,因此稍后排队的消息不会使其上下文读取无效。重写、压缩、删除和分支更改仍然会使读取无效。
  • Inbound 会话运行,然后进入 global main 通道,其并行度受 agents.defaults.maxConcurrent 限制。普通子代理运行改为使用由 agents.defaults.subagents.maxConcurrent 设置的直接 spawning/controller 会话预算。群体收集者儿童使用由 tools.swarm.maxConcurrent 设置的小组单独预算。
  • 嵌入式尝试准备在 16 个阶段启动或每个切片至少 8 毫秒的同步调度工作后屈服于事件循环,因此并发启动为网关请求留出空间。正在运行的阶段不会被抢占。异步阶段工作仍然可以重叠,并且不计入该时间预算;这不会降低运行并发限制或更改会话序列化。
  • 启用详细日志记录后,如果排队运行在开始前等待超过 2 秒,则会发出简短通知。 queueAhead 记录入队时间积压,而不是优先级和老化后的准入顺序的预测。
  • 在入队时,输入中指示器仍会立即触发(当通道支持时),因此在运行等待轮到它时,用户体验不会改变。

默认值

未设置时,所有传入渠道表面使用:

  • mode: "steer"
  • 内置的 500ms 防抖,用于 steer、followup 和 collect 批处理
  • cap: 20
  • drop: "summarize"

同轮转向是默认行为。运行过程中途到达的提示会在运行可接受转向时注入到当前活动运行中,因此不会启动第二个会话运行。如果当前活动运行无法接受转向,OpenClaw 会等待当前活动运行完成后再开始该提示。

队列模式

/queue 控制在会话已经有一个活跃运行时,普通传入消息应如何处理:

  • steer:将消息注入活动运行时,包括在执行工具时。 OpenClaw 让辅助消息的第一个可执行调用在转向可以跳过其未启动的顺序尾部之前启动。运行工具完成,并行批次永远不会跳过转向调用。每个批次稳定后,OpenClaw 在停止挂钩之前检查转向,并在工具结果后、下一个模型决策之前使其可见。 Codex 应用程序服务器接收一个批处理的 turn/steer 并将其应用于下一个模型边界。如果转向不可用,OpenClaw 会等到活动运行结束后再启动提示。
  • followup:不进行 steer。将每条消息排队,待当前运行结束后再开启一次后续代理轮次。
  • collect:不转向。将兼容的排队消息合并到安静窗口后的 single 后续轮流中。消息必须共享路由、授权和执行设置,并且不得具有不同的独占准入生命周期。
  • interrupt:中止该会话的活动运行,然后运行最新消息。此取消不会通过网关重新启动恢复来恢复旧的轮次。

来自使用持久入口准入的通道(包括 Discord 和 Telegram)的消息保持单独的后续轮次:collect 的行为与 followup 类似。每条消息都拥有独占的准入生命周期,因此一个源无法在另一个源拒绝组合轮次之前提交。兼容网关 chat.send 输入使用非独占生命周期,仍然可以收集。

有关运行时特定的时序和依赖行为,请参见 Steering queue。关于显式的 /steer <message> 命令,请参见 Steer。

网关输入在排队或委托给子级时保留其经过身份验证的操作员和原始范围上限。收集消息或引导主动运行需要兼容的操作员来源和工具权限;其他输入按 FIFO 顺序等待,而不是借用活动或最新发件人的权限。

已接受的轮次可以在请求返回或客户端断开连接后继续。这不会延长已撤销的设备权限或由当前 操作员角色 删除的权限。后续操作仍然会检查原始来源,包括被接受的孩子所持有的作品。

通过 messages.queue 全局配置或按渠道配置:

json5
{  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:在排空排队的后续消息或收集批次之前的静默窗口;在 Codex steer 模式下,是发送批量 turn/steer 之前的静默窗口。纯数字表示毫秒;接受的单位包括 ms、s、m、h 和 d。
  • cap:每个会话排队消息的最大数量。小于 1 的值会被忽略。
  • drop: "summarize"(默认):根据需要丢弃最早的排队条目,保留简要摘要,并将其作为合成的后续提示注入。
  • drop: "old":根据需要丢弃最早的排队条目,不保留摘要。
  • drop: "new":当队列已满时,拒绝最新消息。

队列使用内置的 500ms 防抖。cap 默认为 20,drop 默认为 summarize。

引导与流式输出

当 channel streaming 为 partial 或 block 时,steering 可能表现为几段短的可见回复,而当前运行会到达运行时边界:

  • partial:预览可能会提前完成,然后在接受 steering 后启动新的预览。
  • block:草稿大小的分块也可能产生相同的连续外观。
  • 在没有流式输出时,当运行时无法接受同轮 steering,steering 会回退为在当前运行结束后的后续消息。

steer 不会中止正在进行的工具调用。被跳过的 OpenClaw 工具调用会收到成对的合成错误结果,以确保记录保持有效。当最新消息应中止当前运行时,请使用 /queue interrupt。

回答待决问题

在普通队列处理之前,包括当本机 CLI 无法接受转向时,对待处理代理问题的纯文本答案会转到该问题。 OpenClaw 根据问题创建者的权限和活动运行检查答案,而不是为下一轮选择的模型。更改的权限或关闭的创建者会产生明确的拒绝,而不是开始另一个回合。

如果答案可能已提交但确认丢失,OpenClaw 会报告该不确定性,并且不会将其作为指导或后续内容重新发送。重试之前请检查对话。稍后的交付或源清理失败并不会使答案可重播,而且不确定性本身并不会取消原始代理的运行。

优先级

对于模式选择,OpenClaw 的解析顺序是:

  1. 内联或已存储的按会话 /queue 覆盖。
  2. messages.queue.byChannel.<channel>.
  3. messages.queue.mode.
  4. 默认 steer。

对于选项,内联或存储的 /queue 选项胜过配置。然后按顺序应用特定于通道的去抖 (messages.queue.debounceMsByChannel)、插件去抖默认值和内置默认值。 cap 和 drop 是 global/session 选项,而不是每通道配置键。

按会话覆盖

  • 发送 /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 拥有的取消标识,直到排队内容开始运行或被丢弃。该标识会随着折叠进溢出摘要的内容一并传递。

一旦兼容输入被接纳为一个集合回合,最新的可取消输入将拥有客户端取消。取消旧的输入不再停止组合回合。原始操作员访问权限仍然控制执行:撤销该访问权限会取消收集的回合并阻止进一步的影响。

  • 如果请求方已获授权(与活动运行相同的所有权规则),chat.abort 携带特定 runId 时,会在该轮次仍处于排队状态时取消它。
  • 对于没有 runId 的会话,chat.abort 首先取消 授权的排队轮次,然后中止授权的活动运行,包括在其运行器启动之前允许或排队的无控制器运行(例如 OpenAI- 兼容的 HTTP)请求),以及活跃的频道回复。该命令可防止队列耗尽将工作推进到半停止的会话中。
  • 不经过逐请求方检查而清空整个会话队列,并不是多所有者会话的停止路径。
  • Stop保留自己的取消和队列保管后接受新的提示。如果停止的转弯仍在准备中,则新的提示会等待该所有者完成后再运行;它不会继承之前的 Stop。
  • 排队等待不会在 sessions.list 中被投影为活动代理运行,也不适用活动运行的超时语义;只有活动阶段才适用。
  • 在执行之前过期或取消的排队请求仅解决该请求。其保存的输入保持标记为已取消;它不会结束活动回合、暂停其目标或向对话添加活动运行失败。
  • 删除 Control UI 中的特定排队消息还会隐藏该待处理提示及其附件。取消记录可防止重新连接后重播。停止和超时取消保留其恢复消息。

由 Gateway 支持的客户端(包括 openclaw tui)会转发运行中的提示,并让 Gateway 应用队列模式。Esc//stop 使用会话范围的 abort,因此丢失本地句柄也不会让仍处于队列中的提示继续运行。

openclaw chat 和 openclaw tui --local 在嵌入式运行时中应用相同的四种模式。本地 steer 会在该运行时接受 steering 时注入到一个活动的嵌入式运行中,否则会变成 followup;followup 和 collect 仍然是本地待处理工作;interrupt 会在启动最新消息之前中止活动的本地运行。显式的 /steer <message> 命令不是本地模式命令。

输入耐久性

在网关确认之前,通过 chat.send 发送到现有会话的普通用户输入将存储在每个代理数据库中。这包括 Control UI、TUI、CLI、本机应用程序和 RPC 客户端。其他连接的客户端可以在等待时显示接受的输入,而无需等待新的代理轮流。在 collect 模式下,附加组合回合并标记其消耗的源输入发生在一次事务中。浏览器重新连接可以协调这些源输入,即使它错过了最终事件。

聊天显示与发送者分开的记录的非 Web 客户端源,例如 Alice · via CLI。这些标签中省略了 Web 源,包括在还包含来自另一个客户端的输入的收集消息中。报告的应用程序名称描述了提交客户端;他们不建立人类身份或授予权限。收集的消息保留其贡献的客户来源,而没有记录来源的旧消息保留其现有的归属。

这保留了输入,而不是执行权限。如果网关在排队的输入到达记录之前停止,则重新启动后它将显示为中断的输入,并且需要显式重新发送。内存中的队列不会重播。保留进程的主机睡眠可以正常继续现有队列。

当队列尝试在代理轮流采用之前被放弃时,由持久入口保留的通道消息仍然是可重试的。放弃会在入口重试之前释放该尝试的入站和队列重复数据删除条目。已经采用或消耗的消息会保留重复抑制,因此传输重新传递不会重复其效果。

仅当会话所有者接受持久输入和恢复托管后,才会采用排队通道输入。验收前准备失败,保持入口可重试;接受后的失败会产生终端错误回复,而不重播输入。单独进入会话通道并不能完成入口。重复的准备错误会停止更新等待的心跳,从而允许现有的入口看门狗应用其重试和死信策略。正常的容量等待让他们保持心跳。

车道和范围

  • 适用于通过网关回复管线的所有入站渠道中的自动回复代理运行(WhatsApp web、Telegram、Slack、Discord、Signal、iMessage、webchat 等)。
  • 默认车道 (main) 是入站转弯的流程范围内的;设置 agents.defaults.maxConcurrent 以允许并行多个会话。
  • Heartbeat 嵌入式运行使用有界 cron-nested 通道进行全局准入,因此缓慢的后台工作不会阻止入站回复,而其配置的心跳会话通道仍会序列化该会话的工作。
  • 可能存在其他通道(e.g. cron、cron-nested、nested),因此后台作业可以并行运行,而不会阻止入站回复。隔离的 cron 代理轮流持有 cron 插槽,而其内部代理执行则使用 cron-nested。共享非 cron nested 流保持其自己的通道行为。这些分离的运行仍归其本机运行时所有。
  • 普通子代理执行使用subagent:<immediate session>。 agents.defaults.subagents.maxConcurrent 每个会话默认为 8;独立会话和嵌套协调器不共享这些插槽。单独的 maxChildrenPerAgent 入场限制仍然适用。 Codex 原生子代理 使用 Codex 自己的调度程序。
  • Swarm 收集器子级使用 subagent:swarm:<schedulerGroupKey>,上限为组解析的 tools.swarm.maxConcurrent(默认 32)。他们不占用其父母的普通分代理通道。由收集器生成的普通子级使用该收集器自己的会话通道。 Swarm 的 maxChildrenPerGroup 和 maxTotalPerGroup 仍然有单独的入场限制。车道诊断可识别群体车道及其组密钥。
  • 按会话划分的通道可保证同一时间只有一个代理运行会接触到给定会话。
  • 不依赖外部库或后台工作线程;仅使用纯 TypeScript + promises。

后台工作

插件后台完成(包括 dreaming)以后台优先级使用网关的 subagent 通道。其并发性在插件和工作区中遵循 agents.defaults.subagents.maxConcurrent(默认值:8)。将其设置为 1 以一次运行一个完成。普通生成的子代理队列保留其每个生成会话的预算。

技能研讨会审核使用单独的后台预算,一次最多运行一项审核。

等待后台工作的调度程序本身并不占用此预算。只有已分派的工作通过完成或取消清理来保留一个槽,因此调度程序无法阻止它正在等待的子项。取消的排队工作在开始之前被删除;网关重新启动或运行时停用可防止过时的完成启动或返回结果。

Control UI 系统繁忙度覆盖和diagnostics.lanes报告subagent行中的插件完成情况和background行中的创意工坊评论。后台所有者通道不会再次计入动态会话通道总数中。

故障排查

  • 如果命令看起来卡住了,请启用详细日志,并查找 “queued for ...ms” 行,以确认队列正在被清空。
  • 在lane wait exceeded中,activeAhead在条目排队时对活动任务进行计数; activeNow 在开始之前立即对它们进行计数。 activeAhead=1 activeNow=0 可以表示前面的任务刚刚完成,即使经过很长时间的等待。它不会建立泄漏槽。即使诊断抛出异常,准入失败和已完成的任务也会释放其插槽并排出排队的后继任务; lane task diagnostics failed after settlement 标识在其调用者解决后其完成记录失败的任务。
  • Codex app-server 运行在接受一个 turn 之后便停止输出进度时,会被 Codex adapter 中断,这样当前会话 lane 就能释放,而不是一直等待外层运行超时。
  • 当启用诊断时,对于那些在内置警告阈值之后仍停留在 processing 状态、且未观察到回复、工具、状态、阻塞或 ACP 进度的会话,会根据当前活动分类:
    • 有近期进度日志的活跃工作归类为 session.long_running。有所有权的静默模型调用也会保持为 session.long_running,直到内置中止阈值,因此不会过早将缓慢或非流式提供方报告为卡住。
    • 活动工作,没有最近的进度日志,如 session.stalled;拥有的模型调用、阻止的工具调用和停止的嵌入式运行在中止阈值或之后切换到 session.stalled。无所有者的陈旧 model/tool 活动不会像长期运行那样隐藏。
    • session.stuck 保留用于可恢复的过时会话簿记,包括具有过时无主 model/tool 活动的空闲排队会话。
    • session.stuck 总是会触发恢复,并可释放受影响的会话 lane。超过中止阈值的 session.stalled 分类(被阻塞的工具调用、卡住的模型调用或卡住的嵌入式运行)也可能触发主动中止恢复,因此这两种分类都能让队列恢复,而不只是 session.stuck。
    • 没有语义进展的重复模型请求共享一个停滞时钟,从第一次重试开始。因此,达到其输出限制的长初始响应会为纠正请求留下完整的恢复窗口。成功完成的嵌入式工具会在其当前运行所有者下重置时钟,即使封闭的响应稍后达到其输出限制也是如此。失败、被阻止或已退休的所有者工具不会重置它。新的传输字节或稍后的重试不能无限期地更新它。恢复在中止之前重新检查证据,尊重拥有的工具和提供者重试期限,并让现有的运行所有者在队列耗尽之前解决。
    • 当恢复在回复之前中止交互式回合并且其请求已保存在记录中时,OpenClaw 会尝试一次继续,而不是立即要求用户重试。当下一个排队的后续请求来自相同的发送者和路由(例如 chat.send 和 queueMode: "followup")时,它将接管未完成的请求;否则恢复转弯将从停滞转弯的路线开始。恢复回复的传递方式与来自该源的任何排队的后续回复的传递方式相同; Web UI (chat.send) 恢复在聊天中自行运行。组线程参与者轮流收到通知,因为排队的参与者回复没有传递所有者。两人都使用现有的记录,并被指示不要重复已完成的操作。在停顿轮次期间到达的其他发送方的排队消息和通道消息随后将作为自己的轮次运行。如果该延续也停止或无法安排,包括原始请求尚未保存时,“停止取得进展”通知是最后的手段。心跳和 cron 轮次不受影响。
    • 当会话保持不变时,重复出现的 session.stuck 和 session.long_running 警告日志行会指数退避;但无论该退避如何,恢复尝试仍会在每个 heartbeat tick 上运行。

相关内容

本页有帮助吗?