命令队列

Message Queue（消息队列）确保 Agent 按序处理消息，避免并发冲突。每个 Session 维护独立的消息队列。

为什么需要队列

串行化保证

LLM 调用是有状态的——每次调用依赖之前的对话历史。并发调用同一会话会导致历史不一致。消息队列通过串行化确保一致性。

用户快速发送多条消息：

消息 1: "帮我写个函数"        ──▶ ┌──────────┐
消息 2: "要用 TypeScript"     ──▶ │  Queue   │ ──▶ Agent Loop
消息 3: "加上类型注解"        ──▶ │  消息队列 │     (逐条处理)
                                   └──────────┘

队列模式

OpenClaw 支持三种队列处理模式，通过 steering 配置：

steer — 逐条模式（默认）

每条消息独立触发一次完整的 Agent Loop：

steering: steer

Queue: [消息1] [消息2] [消息3]
        │
        ▼
   处理消息1 → 回复1
        │
        ▼
   处理消息2 → 回复2
        │
        ▼
   处理消息3 → 回复3

适用场景：每条消息都是独立问题。

followup — 追加模式

后续消息作为追加上下文注入当前正在处理的 Agent Loop：

steering: followup

Queue: [消息1] → Agent Loop 开始处理
       [消息2] → 追加到当前上下文
       [消息3] → 追加到当前上下文
                         │
                         ▼
                   综合回复（考虑所有消息）

适用场景：用户分多条消息表达一个完整需求。

人性化体验

followup 模式更接近人类对话习惯——人们经常分多条消息发送一个完整想法。

collect — 收集模式

在指定时间窗口内收集所有消息，然后一次性处理：

steering: collect
collectWindow: 5000    # 收集窗口 5 秒

00:00 - 消息1 到达 → 开始收集窗口
00:02 - 消息2 到达 → 继续收集
00:04 - 消息3 到达 → 继续收集
00:05 - 窗口关闭  → 打包 [消息1, 消息2, 消息3] 一次性处理

适用场景：已知用户会快速连发消息的场景。

模式对比

特性	steer	followup	collect
处理方式	逐条独立	追加合并	批量打包
回复数量	每条消息一个回复	综合回复	一个批量回复
延迟	最低	中等	最高（等待窗口）
Token 效率	较低	较高	最高
最佳场景	独立问题	连续对话	快速连发

队列溢出处理

当队列积累过多消息时的处理策略：

queue:
  maxSize: 50              # 队列最大消息数
  overflowStrategy: drop   # 溢出策略

溢出策略：

策略	说明
drop	丢弃最旧的消息
reject	拒绝新消息，通知发送者
compact	压缩队列中的旧消息为摘要

消息丢失

drop 策略会导致消息丢失。生产环境建议使用 reject 或增大 maxSize。

优先级消息

某些消息可以优先处理，跳过正常排队：

queue:
  priorityMessages:
    - pattern: "^/.*"          # 斜杠命令优先处理
    - pattern: "^URGENT:"      # URGENT 前缀优先处理
    - sender: "admin_user"     # 管理员消息优先

优先级消息直接插入队列头部：

普通队列: [消息A] [消息B] [消息C]
                                    ←  [优先消息D]
处理顺序: [优先消息D] → [消息A] → [消息B] → [消息C]

队列状态监控

# 查看队列状态
openclaw queue status

# 输出示例：
# SESSION                    PENDING  PROCESSING  MODE
# general::user_12345        3        1           steer
# coder::user_67890          0        0           followup
# writer::admin              1        1           collect

Per-Session + Global 队列

OpenClaw 使用两级队列保证系统稳定：

                    ┌─────────────────────┐
消息 → Session Queue│  Per-Session Queue  │
       (每会话)     │  串行化同一会话     │
                    └─────────┬───────────┘
                              │
                              ▼
                    ┌─────────────────────┐
                    │   Global Queue      │
                    │  限制并发 LLM 调用  │
                    └─────────┬───────────┘
                              │
                              ▼
                         LLM API 调用

• Per-Session Queue — 确保同一会话内消息按序处理
• Global Queue — 限制全局并发 LLM 调用数量，防止 API 速率限制

queue:
  global:
    maxConcurrent: 5          # 最大并发 LLM 调用数

配置示例

聊天场景

steering: followup
queue:
  maxSize: 100
  overflowStrategy: reject

客服场景

steering: steer
queue:
  maxSize: 200
  overflowStrategy: compact
  priorityMessages:
    - sender: "vip_*"

群聊场景

steering: collect
collectWindow: 3000
queue:
  maxSize: 50
  overflowStrategy: drop

下一步

• 了解 Agent 循环 中队列的处理流程
• 查看 Agent 运行时 了解 steering 模式
• 探索 会话管理 了解队列与会话的关系