命令队列

OpenClaw 通过一个轻量级进程内队列将所有渠道的入站自动回复串行化，在防止多个 agent 运行冲突的同时，仍然允许跨 session 的安全并行。

为什么需要队列

• 自动回复运行代价高昂（LLM 调用），多条入站消息同时到达时容易发生冲突。
• 串行化可避免对共享资源（session 文件、日志、CLI stdin）的竞争，并降低触发上游限流的概率。

工作原理

• 采用 lane-aware FIFO 队列，每个 lane 有可配置的并发上限（未配置的 lane 默认为 1；main 默认 4，subagent 默认 8）。
• runEmbeddedPiAgent 按 session key（lane session:<key>）入队，确保每个 session 同时只有一个活跃运行。
• 每个 session 运行随后进入全局 lane（默认 main），总并发由 agents.defaults.maxConcurrent 控制。
• 启用 verbose 日志后，等待超过约 2s 才开始的运行会输出简短提示。
• 打字指示器在入队时立即触发（若渠道支持），不影响等待期间的用户体验。

队列模式（per channel）

入站消息可以引导当前运行、等待下一轮，或两者兼得：

• steer：立即注入当前运行（在下一个工具边界后取消待处理的工具调用）。若非流式，回退到 followup。
• followup：在当前运行结束后入队等待 agent 下一轮处理。
• collect：将所有已排队的消息合并为单次 followup 轮（默认）。若消息面向不同渠道/线程，则单独排干以保留路由。
• steer-backlog（即 steer+backlog）：立即引导且保留消息用于后续 followup。
• interrupt（旧版）：中止该 session 的当前运行，然后运行最新消息。
• queue（旧版别名）：等同于 steer。

Steer-backlog 意味着引导后还会有 followup 回复，在流式界面看起来可能像重复。若希望每条入站消息只有一次回复，优先使用 collect/steer。

通过发送 /queue collect 作为独立命令（per-session），或设置 messages.queue.byChannel.discord: "collect" 来控制模式。

默认值（未在配置中设置时）：

• 所有界面 → collect

全局或按渠道配置：

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

队列选项

以下选项适用于 followup、collect 和 steer-backlog（以及 steer 回退到 followup 的情况）：

• debounceMs：在静默等待后再开始 followup 轮（防止连续"继续，继续"）。
• cap：每个 session 的最大排队消息数。
• drop：溢出策略（old、new、summarize）。

summarize 会保留被丢弃消息的简短要点列表，并作为合成 followup prompt 注入。默认值：debounceMs: 1000、cap: 20、drop: summarize。

Per-session 覆盖

• 发送 /queue <mode> 作为独立命令，为当前 session 存储该模式。
• 可组合选项：/queue collect debounce:2s cap:25 drop:summarize
• /queue default 或 /queue reset 清除 session 覆盖。

作用范围与保证

• 适用于所有使用 gateway 回复流水线的入站渠道的自动回复 agent 运行（WhatsApp web、Telegram、Slack、Discord、Signal、iMessage、webchat 等）。
• 默认 lane（main）是进程范围的，涵盖入站消息 + 主心跳；设置 agents.defaults.maxConcurrent 允许多个 session 并行。
• 额外的 lane（如 cron、subagent）允许后台任务在不阻塞入站回复的情况下并行运行。
• Per-session lane 确保每次只有一个 agent 运行接触某个给定 session。
• 无外部依赖或后台工作线程；纯 TypeScript + Promise 实现。

故障排查

• 若命令似乎卡住，启用 verbose 日志并查找"queued for …ms"行，确认队列正在排干。
• 若需要查看队列深度，启用 verbose 日志并观察队列时序行。

小龙虾处理消息的方式就像有序的流水线——前一条没处理完，后一条先排好队等着。