跳转至

OpenClaw 消息队列 / 任务队列分析报告

分析日期： 2026-05-01 分析范围： src/、extensions/、packages/、docs/

五层队列体系总览

graph TB
    subgraph 入站层
        A[入站消息] --> B{QueueMode?}
        B -->|steer| C[注入活跃 Run]
        B -->|followup/collect| D[Followup 队列]
        B -->|interrupt| E[中止当前 Run]
    end

    subgraph 调度层
        D --> F[FollowupQueueState]
        F -->|debounce 500ms| G[Drain 循环]
        G -->|collect 模式| H[合并多条消息]
        G -->|其他模式| I[逐条处理]
    end

    subgraph 执行层
        C --> J[Command Lane Queue]
        H --> J
        I --> J
        J -->|lane: session:<key>| K[串行执行]
        J -->|lane: main| L[并发≤4]
        J -->|lane: subagent| M[并发≤8]
    end

    subgraph 出站层
        K --> N[Agent Run 完成]
        N --> O[出站消息]
        O -->|成功| P[ackDelivery]
        O -->|失败| Q[Outbound 持久化队列]
        Q -->|指数退避| O
        Q -->|永久错误| R[failed/]
    end

    subgraph 通知层
        S[子 Agent] --> T[Announce 队列]
        T -->|指数退避| U[父 Session]
    end

核心模块对照表

层次 核心模块 文件路径 作用
命令车道队列 CommandQueue src/process/command-queue.ts (527行) 进程级序列化 agent 执行，多车道 + 并发上限
入站 Followup 队列 FollowupQueueState src/auto-reply/reply/queue/ 入站消息排队/合并/转向（Steer）等策略
Announce 队列 AnnounceQueueState src/agents/subagent-announce-queue.ts 子 agent 向父 session 推送通知
Outbound 持久化队列 QueuedDelivery src/infra/outbound/delivery-queue-storage.ts 出站消息落盘、重试、故障转移
插件扩展队列 各渠道独立实现 extensions/discord/、qqbot/、feishu/ 各渠道并发控制

进程级单例机制

所有队列状态通过 Symbol.for() 键挂载到 globalThis，保证多 bundled chunk 共享同一份状态：

Symbol 内容
openclaw.commandQueueState 所有车道 Map + gatewayDraining 标志
openclaw.followupQueues 所有 session 的 FollowupQueueState Map
openclaw.followupDrainCallbacks drain 回调缓存，支持空 drain 后重启
openclaw.recentQueueMessageIds 入站消息去重缓存（TTL 5min，上限 10000）

STER 结论

本仓库不存在名为"STER"的机制或缩写。 与 Steering 最相关的是 QueueMode.steer，文档称"Steering queue"（docs/concepts/queue-steering.md）。

报告目录