命令队列

​

原因

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

​

工作原理

• 一个感知 lane 的 FIFO 队列会以可配置的并发上限清空每个 lane（未配置的 lane 默认值为 1；main 使用 min(16, max(8, available CPU parallelism))，而 subagent 默认为 8）。
• runEmbeddedAgent 按 会话键 入队（lane session:<key>），以确保每个会话同时只运行一个任务。
• 然后每个会话运行都会进入一个 全局 lane（默认是 main），从而将总体并行度限制为 agents.defaults.maxConcurrent。
• 启用详细日志时，如果排队的运行在开始前等待超过约 2 秒，会输出一条简短提示。
• 在入队时，输入中指示器仍会立即触发（当通道支持时），因此在运行等待轮到它时，用户体验不会改变。

​

默认值

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

​

队列模式

• steer：将消息注入活跃运行时。OpenClaw 会让已在运行的工具完成，跳过尚未启动的顺序调用，并确保 steer 消息在下一次工具启动或模型决策前可见。并行调用会在其批次通过启动检查点后继续执行。Codex app-server 会接收一条批量的 turn/steer，并在下一个模型边界应用它。如果运行当前未处于主动流式传输状态，或 steer 不可用，OpenClaw 会等待活跃运行结束后再启动该提示。
• followup：不进行 steer。将每条消息排队，待当前运行结束后再开启一次后续代理轮次。
• collect：不进行 steer。将排队的消息合并为一次单独的后续轮次，并在静默窗口结束后执行。如果消息针对不同的渠道／线程，则会分别处理，以保留路由信息。
• interrupt：中止该会话的活跃运行，然后运行最新消息。

{
  messages: {
    queue: {
      mode: "steer",
      cap: 20,
      drop: "summarize",
      byChannel: { discord: "collect" },
      debounceMsByChannel: { discord: 1000 },
    },
  },
}

​

队列选项

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

​

引导与流式输出

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

​

优先级

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

​

按会话覆盖

• 发送 /queue <steer|followup|collect|interrupt> 作为独立命令，以存储当前会话的队列模式。
• 选项可以组合：/queue collect debounce:0.5s cap:25 drop:summarize
• /queue default 或 /queue reset 会清除会话覆盖。

​

排队轮次取消

• 如果请求方已获授权（与活动运行相同的所有权规则），chat.abort 携带特定 runId 时，会在该轮次仍处于排队状态时取消它。
• 不带 runId 的会话级 chat.abort 会先取消已获授权的排队轮次，然后再中止已获授权的活动运行。这个顺序可以防止队列清空时把工作推进到一个半停止的会话中。
• 不经过逐请求方检查而清空整个会话队列，并不是多所有者会话的停止路径。
• 排队等待不会在 sessions.list 中被投影为活动代理运行，也不适用活动运行的超时语义；只有活动阶段才适用。

​

范围与保证

• 适用于通过网关回复管线的所有入站渠道中的自动回复代理运行（WhatsApp web、Telegram、Slack、Discord、Signal、iMessage、webchat 等）。
• 默认通道（main）在整个进程范围内用于入站 + 主心跳；设置 agents.defaults.maxConcurrent 可允许多个会话并行。
• 可能还存在额外通道（例如 cron、cron-nested、nested、subagent），因此后台任务可以并行运行而不会阻塞入站回复。隔离的 cron 代理轮次会占用一个 cron 槽位，而其内部代理执行则使用 cron-nested。共享的非 cron nested 流程保持其自身的通道行为。这些分离的运行会被跟踪为后台任务。
• 按会话划分的通道可保证同一时间只有一个代理运行会接触到给定会话。
• 不依赖外部库或后台工作线程；仅使用纯 TypeScript + promises。

​

故障排查

• 如果命令看起来卡住了，请启用详细日志，并查找 “queued for …ms” 行，以确认队列正在被清空。
• Codex app-server 运行在接受一个 turn 之后便停止输出进度时，会被 Codex adapter 中断，这样当前会话 lane 就能释放，而不是一直等待外层运行超时。
• 当启用诊断时，对于那些在内置警告阈值之后仍停留在 processing 状态、且未观察到回复、工具、状态、阻塞或 ACP 进度的会话，会根据当前活动分类：
  • 有近期进度日志的活跃工作归类为 session.long_running。有所有权的静默模型调用也会保持为 session.long_running，直到内置中止阈值，因此不会过早将缓慢或非流式提供方报告为卡住。
  • 没有近期进度日志的活跃工作归类为 session.stalled；有所有权的模型调用、被阻塞的工具调用以及卡住的嵌入式运行会在中止阈值处或之后切换为 session.stalled。无所有者的过期模型／工具活动只要尚未处于 long-running，就不会被隐藏。
  • session.stuck 专用于可恢复的过期会话账本状态，包括处于空闲队列中的、且存在过期无所有者模型／工具活动的会话。
  • session.stuck 总是会触发恢复，并可释放受影响的会话 lane。超过中止阈值的 session.stalled 分类（被阻塞的工具调用、卡住的模型调用或卡住的嵌入式运行）也可能触发主动中止恢复，因此这两种分类都能让队列恢复，而不只是 session.stuck。
  • 当会话保持不变时，重复出现的 session.stuck 和 session.long_running 警告日志行会指数退避；但无论该退避如何，恢复尝试仍会在每个 heartbeat tick 上运行。

​

相关内容

• 会话管理
• 转向队列
• 转向
• 重试策略