从框架到应用：OpenClaw 源码拆解——当一个 Agent 要服务 20 个聊天渠道时

reasoning → acting → reasoning → acting → ... → exit

你在 WhatsApp 发了一条 "帮我查一下明天北京的天气"
  │
  ▼
┌─────────────────────────────────────────────────────┐
│ 1. WhatsApp Channel Adapter 收到消息                  │
│ 2. 路由引擎根据规则确定目标 Agent                       │
│ 3. Session Manager 找到/创建对应会话                   │
│ 4. 消息入队（per-session 队列，严格串行）                │
│ 5. 返回 { runId, acceptedAt } — 你看到"已收到"        │
└────────────────────┬────────────────────────────────┘
                     ▼
┌─────────────────────────────────────────────────────┐
│ 6. agentCommand 开始执行一个 turn                      │
│    ├── 解析 model + 默认参数                           │
│    ├── 加载 Skills 快照（SKILL.md 指令包）              │
│    └── 调用 runEmbeddedAgent                          │
│          ├── 组装 system prompt（基础 + skills + 上下文）│
│          ├── 加载历史 transcript                       │
│          └── 进入 ReAct 循环 ← 和 AgentScope 一样      │
│                ├── reasoning（调用 LLM）                │
│                ├── acting（执行工具）                    │
│                └── ... → 最终回复                      │
└────────────────────┬────────────────────────────────┘
                     ▼
┌─────────────────────────────────────────────────────┐
│ 7. 回复整形（Reply Shaping）                          │
│    ├── 过滤特殊 token（如 NO_REPLY）                   │
│    ├── 去除工具调用的重复确认                           │
│    └── 组装最终 payload                               │
│ 8. 通过原渠道（WhatsApp）回推消息                       │
│ 9. transcript 写入 SQLite                             │
└─────────────────────────────────────────────────────┘

         WhatsApp ─┐
         Telegram ─┤
          Discord ─┤
           Slack  ─┤  ┌────────────┐
          Signal  ─┼──┤  Gateway   ├──→ Agent Runtime
         iMessage ─┤  │ (单进程)    │
            Web   ─┤  └────────────┘
            CLI   ─┤
        微信/飞书  ─┘

// 同一个 session 内的 run 严格按顺序执行
// 不同 session 可以并行
class SessionQueue {
  private lanes = new Map<string, TaskQueue>();

  async enqueue(sessionKey: string, task: () => Promise<void>) {
    const lane = this.getOrCreateLane(sessionKey);
    return lane.push(task);  // FIFO，前一个 run 完成后才执行下一个
  }
}

1. exact peer      → 精确匹配某个用户/群
2. parent peer     → 匹配父级
3. peer wildcard   → 通配符匹配
4. guild + roles   → 服务器 + 角色组合
5. guild           → 整个服务器
6. team            → 整个团队
7. account         → 整个账号
8. channel         → 整个渠道（如 "所有 Telegram 消息"）
9. default agent   → 兜底

agents/
├── default/
│   └── sessions.sqlite    ← 默认 Agent 的所有会话
├── code-assistant/
│   └── sessions.sqlite    ← 代码助手 Agent 的所有会话

上下文接近窗口限制（或模型返回 context-overflow 错误）
  │
  ▼
1. Memory Flush（记忆冲刷）
   ├── 提醒 Agent："你即将进入压缩阶段"
   ├── "如果有重要的笔记/发现，现在保存到 memory 文件"
   └── Agent 可以调用 write 工具把关键信息写入持久文件
  │
  ▼
2. Compaction 执行
   ├── 旧 turn 被总结为紧凑条目
   ├── 最近 N 条消息保持完整
   ├── 保持 tool_call ↔ tool_result 配对完整
   └── 可插拔的 compaction provider（插件可自定义总结策略）
  │
  ▼
3. 质量审计（safeguard 模式）
   ├── 检查摘要是否丢失关键信息
   └── 不满足质量标准则重试

# Weather Checker

## When to Use
When the user asks about weather, temperature, or forecast.

## Instructions
1. Use the `web_search` tool to find current weather data
2. Summarize the temperature, humidity, and conditions
3. If the user asks about tomorrow, also search for forecast
4. Always mention the data source

## Examples
User: "北京明天天气怎么样？"
Action: web_search("北京 天气预报 明天")

// 每 30 分钟（可配置）唤醒一次 Agent
heartbeat: {
  interval: "30m",
  prompt: "检查一下有没有需要主动处理的事情"
}

// before_tool_call 返回 block → 停止后续处理器，工具不执行
{ block: true, reason: "This tool is not allowed" }

// message_sending 返回 cancel → 消息不发送
{ cancel: true }

LLM 原始输出
  │
  ├── 过滤 NO_REPLY token（Agent 决定不回复）
  ├── 去除重复确认（Agent 调了 message 工具后又文字确认了一遍）
  ├── 内联工具摘要（搜索结果的简要总结）
  ├── 可选附加 reasoning 摘要
  └── 最终 payload → 通过渠道发送

# LLM 原始输出：
"我来帮你查一下天气。
[调用 web_search 工具]
根据搜索结果，明天北京晴，25°C，适合出行。"

# 整形后（去除工具调用确认）：
"明天北京晴，25°C，适合出行。"

                        Agent Loop 的认知地图

  ┌─────────────────────────────────────────────────────────┐
  │                     核心循环层                           │
  │          while True: reasoning → acting → exit           │
  │    （两篇文章的共识：所有 Agent 框架的内核都是 ReAct）       │
  └───────────────────────┬─────────────────────────────────┘
                          │
            ┌─────────────┼─────────────┐
            ▼                           ▼
  ┌─────────────────┐          ┌─────────────────┐
  │   框架路线        │          │   应用路线        │
  │  (AgentScope)    │          │  (OpenClaw)      │
  ├─────────────────┤          ├─────────────────┤
  │ 洋葱中间件        │          │ 管道钩子 + 短路   │
  │ 工具并发策略       │          │ per-session 队列  │
  │ 决策器三选一       │          │ 回复整形          │
  │ 上下文压缩        │          │ Compaction +      │
  │                  │          │   Memory Flush    │
  │ Leader-Worker    │          │ Heartbeat 心跳     │
  │ 事件流生成器       │          │ 路由引擎          │
  └─────────────────┘          │ SKILL.md          │
                               │ 多渠道网关          │
                               └─────────────────┘