第五章 消息循环与事件驱动：Agent的心跳与脉搏

核心提示：如果说工具系统是Agent的手脚，提示词系统是它的大脑，那么消息循环就是它的心跳——持续不断、节律分明地驱动着整个系统运转。这一章我们将理解Agent是如何持续运转的，以及OpenClaw如何在复杂环境中保持稳定运行。

1. 引言：从"静态应答"到"动态生命"

1.1 传统软件的局限

想象一个传统的命令行工具：你输入一个命令，它执行，返回结果，然后退出。整个过程是线性的、一次性的、被动的。

用户输入 → 程序处理 → 输出结果 → 程序结束
    ↑                              |
    └──────────────────────────────┘ (下次再从头开始)

这种模式适用于简单任务，但面对复杂问题时显得力不从心：

• 它没有"记忆"——每次都要重新开始
• 它没有"主动性"——你不问它就不答
• 它没有"适应性"——遇到错误只能崩溃

1.2 Agent的生命特征

OpenClaw的Agent表现出完全不同的生命特征：

持续性：它不会"退出"，而是持续运行，等待下一次交互

记忆性：它记得你们之前的对话、你的偏好、项目的上下文

主动性：即使没有你的指令，它也会在特定时间醒来执行任务

适应性：遇到错误时，它会重试、调整策略、或者优雅地降级

这些特征的核心，是一个永不停息的消息循环系统。

1.3 为什么是"心跳"

"心跳"这个词不只是比喻。在OpenClaw的架构中，消息循环确实像一个生物的心脏：

• 节律性：它按照固定的节奏检查、处理、响应
• 持续性：从启动到关闭，它从不停止
• 关键性：如果心跳停止，整个系统就"死亡"了
• 适应性：它可以根据负载调整节奏（快/慢、忙/闲）

理解这个消息循环，就是理解Agent的"生命机制"。

---

2. 思考-行动循环：Agent的工作方式

2.1 从人类认知到机器实现

思考-行动循环是Agent行为的核心模式。它反映了人类解决问题的方式。

人类如何解决复杂问题：

想象你要在一个陌生的城市找到一家特定的咖啡店：

1. 观察：你站在街头，看到路牌、建筑、行人
2. 思考："根据地图，这家店应该在东边两个街区"
3. 行动：你开始向东走
4. 观察：走了两分钟，你发现走错了方向
5. 思考："地图显示我应该左转，但路牌指向右边。也许地图过时了？"
6. 行动：你决定问路
7. 观察：路人指了另一个方向
8. 思考："看来确实是我理解错了地图的方向"
9. 行动：你调整方向，继续前进
10. ...直到找到咖啡店

注意这个过程的关键特征：

• 不是线性的——你需要多次调整
• 依赖反馈——每一步行动的结果影响下一步决策
• 容忍不确定性——你会犯错，但能从错误中恢复

思考-行动循环的定义：

思考-行动循环 = （观察、思考、行动）的重复序列

其中：
- 观察: 感知当前环境状态
- 思考: 基于观察和目标进行推理
- 行动: 执行改变环境的操作
- 重复直到任务完成

2.2 OpenClaw中的循环实现

在OpenClaw中，一次完整的循环流程是：

┌─────────────────────────────────────────────────────────────────┐
│ 步骤1：观察                                                      │
├─────────────────────────────────────────────────────────────────┤
│ 输入来源：                                                       │
│ - 用户的最新消息                                                 │
│ - 上一轮行动的结果（工具返回值）                                 │
│ - 系统状态（时间、环境变量等）                                   │
│ - 持久化记忆（MEMORY.md中的相关事实）                            │
│                                                                  │
│ 处理：整合所有输入，构建当前世界状态的内部表示                    │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│ 步骤2：思考                                                      │
├─────────────────────────────────────────────────────────────────┤
│ 推理过程：                                                       │
│ - 理解用户意图                                                   │
│ - 评估当前进度（已完成什么，还需做什么）                         │
│ - 选择下一步策略（调用什么工具，说什么话）                       │
│ - 或者决定任务完成，生成最终回复                                 │
│                                                                  │
│ 关键：这一步是纯粹的思考，不产生外部副作用                       │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│ 步骤3：行动                                                      │
├─────────────────────────────────────────────────────────────────┤
│ 可能的行动类型：                                                 │
│                                                                  │
│ A. 工具调用：{"tool": "glob", "args": {"pattern": "**/*.ts"}}    │
│    → 系统执行工具，返回值成为下一轮观察                          │
│                                                                  │
│ B. 回复用户：{"response": "我已经找到了5个文件..."}              │
│    → 循环终止，等待用户下一次输入                                 │
│                                                                  │
│ C. 思考继续：{"thought": "我需要先了解项目结构..."}               │
│    → 继续下一轮循环                                               │
└─────────────────────────────────────────────────────────────────┘
                              ↓
                              │ (如果不是终止回复)
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│ 回到步骤1，开始下一轮循环                                        │
└─────────────────────────────────────────────────────────────────┘

2.3 循环的终止条件

思考-行动循环不会无限进行。OpenClaw设置了多层终止条件：

正常终止：

• 任务完成：Agent判断目标已达成，生成最终回复
• 用户满意：Agent询问"还需要我做什么吗"，用户表示不用了
• 无进一步行动：Agent认为已经提供了所有能提供的帮助

安全终止：

• 最大轮数限制：防止无限循环
• Token限制：上下文长度限制
• 最大执行时间：通过timeoutSeconds配置

异常终止：

• 工具调用失败：关键工具连续失败，无法恢复
• 服务不可用：模型调用失败
• 用户主动取消：用户发送/cancel或Ctrl+C
• 取消信号：运行被中断信号终止

2.4 状态管理：循环的记忆力

思考-行动循环需要维护状态才能在多轮中保持连贯。OpenClaw维护了以下状态：

对话上下文：

• 用户和Agent的完整对话历史
• 每一轮的观察、思考、行动记录
• 用于让Agent理解"我们在哪"、"已经做了什么"

任务栈：

• 当前主任务和子任务的层级关系
• 例如：主任务"部署应用" → 子任务1"构建镜像" → 子任务2"推送仓库"
• 支持任务的中断和恢复

工具结果缓存：

• 最近调用的工具及其返回值
• 避免重复调用相同工具
• 支持工具结果的引用和比较

环境快照：

• 工作目录、环境变量、系统状态
• 在循环开始时捕获，用于检测环境变化

2.5 循环的深度：单轮 vs 多轮

浅层循环（单轮）：

有些简单的请求只需要一轮循环：

用户："现在几点了？"
      ↓
观察: 用户询问当前时间
思考: "我需要获取当前时间"
行动: 调用Bash("date")
      ↓
观察: 工具返回"2024-03-09 14:30:00"
思考: "我得到了时间，可以直接回复"
行动: 回复用户"现在是2024年3月9日14点30分"
      ↓
终止

深层循环（多轮）：

复杂任务需要多轮循环：

用户："帮我分析这个项目的依赖健康状况"
      ↓
第1轮：
观察: 用户要求分析依赖
思考: "我需要先了解这是什么项目，有哪些依赖文件"
行动: Glob("**/package.json") + Glob("**/requirements.txt")
      ↓
第2轮：
观察: 找到了3个package.json，1个requirements.txt
思考: "这是一个混合项目。我先分析Node.js部分"
行动: Read("package.json")
      ↓
第3轮：
观察: 有20个依赖，其中5个是开发依赖
思考: "我需要检查这些依赖的最新版本和已知漏洞"
行动: Bash("npm audit") + Bash("npm outdated")
      ↓
第4-8轮：
...逐条分析结果...
      ↓
第9轮：
思考: "分析完成，我需要整理成报告"
行动: 生成结构化分析报告
      ↓
终止

深层循环是Agent能力的真正体现——它能像人类一样，将复杂任务分解为多个步骤，逐步推进，直到完成。

---

3. 任务队列：命令调度系统

如果说思考-行动循环是心脏的跳动，那么任务队列就是血液循环系统——负责有序地调度"养分"（命令）输送到各个"器官"（组件）。

3.1 为什么需要任务队列

在简单系统中，组件之间可以直接调用：

Gateway → Agent
   ↑___________|

但这种方式有几个问题：

竞态条件：多个消息同时到达时，可能竞争共享资源（会话文件、日志等）

无缓冲：如果Agent响应慢，新消息可能丢失或导致混乱

难以控制并发：无法限制同时运行的Agent数量

3.2 任务队列架构

OpenClaw采用任务队列来管理入站消息：

                    ┌─────────────┐
   ┌───────────────│  任务队列   │───────────────┐
   │               └──────┬──────┘               │
   │                      │                      │
   ▼                      ▼                      ▼
┌────────┐          ┌────────┐           ┌──────────┐
│Gateway │          │ Agent  │           │ Scheduler│
│(生产者)│          │(消费者)│           │(消费者)  │
└────────┘          └────────┘           └──────────┘

工作原理： OpenClaw使用两个层次的队列系统：

1. 任务分类队列：

   • 用于序列化命令执行
   • 按任务类型分类（主任务、定时任务、子代理任务等）
   • 控制总体并发度

2. 会话队列：

   • 用于管理会话级别的消息排队
   • 通过sessionKey实现会话隔离
   • 支持多种队列模式（合并、插队、排队等）

Gateway接收外部消息后，根据消息类型和会话标识决定加入哪个队列：

• 新消息进入任务分类队列等待执行
• 同一会话的后续消息进入会话队列，按顺序处理

这种架构的好处：

• 序列化：按顺序处理，避免竞态条件
• 可扩展：可以添加新的消费者而不影响现有组件
• 流量控制：通过队列深度和并发限制保护系统
• 会话隔离：同一会话的消息按顺序处理，不会混乱

3.3 消息的结构

在OpenClaw中，消息的结构如下：

type AgentEventStream = "lifecycle" | "tool" | "assistant" | "error" | (string & {});

type AgentEventPayload = {
  runId: string;
  seq: number;
  stream: AgentEventStream;
  ts: number;
  data: Record<string, unknown>;
  sessionKey?: string;
};

字段说明：

• runId：运行的唯一标识
• seq：序列号，保证事件顺序
• stream：事件流类型（生命周期/工具/助手/错误）
• ts：时间戳
• data：事件数据
• sessionKey：会话标识（可选）

3.4 队列模式

任务队列支持多种模式来控制消息处理方式：

模式	行为
collect	合并所有队列消息为单个后续回合
steer	立即注入当前运行，取消待处理的工具调用
followup	排队等待当前运行结束后的下一个回合
steer-backlog	立即插队并保留消息用于后续回合
interrupt	中断当前运行，立即处理新消息
queue	将消息加入队列，按顺序处理

配置示例：

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

注：上述配置中的数值仅为示例，实际配置请参考官方文档。

3.5 任务分类

任务队列使用任务分类来管理不同类型的任务：

                    ┌─────────────────┐
                    │    任务队列     │
                    └────────┬────────┘
                             │
        ┌────────────────────┼────────────────────┐
        │                    │                    │
   ┌────▼────┐          ┌────▼────┐          ┌────▼────┐
   │ 主任务  │          │ 定时任务│          │子代理   │
   │ Lane    │          │ Lane    │          │ Lane    │
   └────┬────┘          └────┬────┘          └────┬────┘
        │                    │                    │
   主任务执行            定时任务执行          子代理任务

任务类型：

• Main：主任务，处理常规的用户请求
• Cron：定时任务，处理Cron作业
• Subagent：子代理任务，处理子代理调用
• Nested：嵌套任务，处理嵌套任务

会话隔离：会话级别的消息隔离是通过sessionKey在会话队列中实现的。任务分类用于任务类型管理和并发控制。

---

4. 并发控制：任务隔离与排队

并发是Agent系统的核心挑战。OpenClaw需要在以下矛盾中寻找平衡：

• 并行性：多个用户的请求应该并行处理，互不等待
• 顺序性：同一用户的消息应该按顺序处理，保持因果
• 资源限制：系统不能同时处理无限多的任务

4.1 任务分类模型

OpenClaw采用任务分类模型来解决任务管理和并发控制问题：

┌─────────────────────────────────────────────────────────────┐
│                      任务队列                                │
└──────────────────┬──────────────────────────┬───────────────┘
                   │                          │
      ┌────────────▼─────────┐    ┌──────────▼──────────┐
      │   主任务通道         │    │   定时任务通道      │
      ├──────────────────────┤    ├─────────────────────┤
      │ 消息1: "写代码"      │    │ 消息1: "定时报告"   │
      │ 消息2: "现在几点了"  │    │ 消息2: "心跳检查"   │
      │ 消息3: "测试一下"    │    │                     │
      └──────────────────────┘    └─────────────────────┘
              │                           │
              ▼                           ▼
      主任务处理器                  定时任务处理器
      (串行处理主任务)              (串行处理定时任务)

任务分类的作用：

• Main：处理用户主会话中的请求
• Cron：处理定时触发的Cron作业
• Subagent：处理子代理调用
• Nested：处理嵌套任务

会话隔离的实现： 会话级别的消息隔离不是通过任务分类实现的，而是通过sessionKey在会话队列中管理。每个会话的消息按sessionKey分组，在同一组内串行处理。

通道内的串行保证：

• 同一通道内的消息严格按顺序处理
• 消息2必须等待消息1完成后才能开始
• 这防止了竞态条件和上下文混乱

通道间的并行处理：

• 不同通道互不等待
• 主任务不会阻塞定时任务
• 系统吞吐量随通道数增长

4.2 为什么串行在通道内是必要的

考虑这个场景：

用户快速发送两条消息：
1. "创建一个文件test.txt，内容是hello"
2. "读取文件test.txt的内容"

如果并行处理：
- 消息1开始执行，但文件还没创建完
- 消息2同时执行，读取文件，发现文件不存在，报错

如果串行处理：
- 消息1执行完成，文件创建成功
- 消息2开始执行，成功读取文件

串行处理确保了因果一致性——后发生的操作能看到先发生操作的结果。

4.3 流量控制

当系统负载过高时，需要流量控制机制来保护系统：

检测过载：

• 消息队列长度超过阈值
• Agent平均处理时间超过阈值
• 内存/CPU使用率超过阈值

应对策略：

层级	策略	效果
Gateway层	返回429 Too Many Requests	告诉客户端稍后再试
Queue层	队列容量限制和溢出策略	防止内存耗尽
Agent层	通过maxConcurrent限制并发	控制处理能力

队列选项：

• debounceMs：等待安静期后开始后续回合
• cap：每会话最大排队消息数
• drop：溢出策略

4.4 队列深度与监控

通过日志可以监控队列状态：

openclaw logs --follow

关键指标：

• 队列深度：积压的消息数量
• 等待时间：消息在队列中等待的时间
• 活跃通道：当前并发的任务数

---

5. 容错与自愈：弹性架构设计

在真实世界中，故障是不可避免的：

• 网络抖动导致API调用失败
• 服务偶尔返回乱码
• 磁盘空间满了导致无法写入

一个好的Agent系统必须具备容错和自愈能力。

5.1 分层容错策略

OpenClaw在多个层面实施容错：

┌─────────────────────────────────────────────────────────────┐
│ 第1层：任务级容错                                           │
│ ─────────────────                                           │
│ 单个工具调用失败 → 重试 → 换策略 → 报告用户                 │
└─────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────┐
│ 第2层：会话级容错                                           │
│ ─────────────────                                           │
│ 单次尝试失败 → 隔离影响 → 保持会话 → 下次重试               │
└─────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────┐
│ 第3层：服务级容错                                           │
│ ─────────────────                                           │
│ 服务提供商失败 → 切换备用 → 降级模式 → 优雅退出             │
└─────────────────────────────────────────────────────────────┘

5.2 重试策略：何时重试、如何重试

不是所有失败都应该重试，也不是所有重试都该用同样的方式。

可重试的失败：

• 网络超时（可能临时恢复）
• 服务暂时不可用（503错误）
• 频率限制（等一下就好）

不可重试的失败：

• 认证失败（密钥错误，重试也没用）
• 无效参数（逻辑错误，重试也没用）
• 资源不存在（404错误，重试也没用）

重试策略：

策略	适用场景	实现
立即重试	瞬时错误	失败后立刻再试
固定间隔	短暂不可用	固定时间间隔重试
智能重试	服务过载	指数退避策略
随机抖动	避免惊群	随机间隔重试

智能重试示例：

第1次重试: 等待较短时间
第2次重试: 等待更长时间
...
最大等待: 设置上限（防止无限增长）
最大重试: 设置上限（防止无限重试）

5.3 错误反馈：Agent的自我纠正

当工具调用失败时，OpenClaw不会默默失败，而是把错误信息反馈给Agent，让它决定如何处理：

Agent: 调用Bash("rm important.txt")
       ↓
系统: 错误！文件不存在
       ↓
Agent: 收到错误，重新思考
     "文件不存在，可能已经被删除了
      我应该告诉用户这个情况"
       ↓
Agent: 回复用户 "文件已经不存在了，可能之前已被删除"

这种错误即观察的设计，让Agent具备了自我纠正能力。

5.4 降级策略：优雅地失败

当最佳方案不可用时，系统应该退而求其次，而不是完全失败。

服务降级：

首选: GPT-4 (最聪明，但慢且贵)
  ↓ 失败
备用1: Claude-3 (也很聪明，快一点)
  ↓ 失败
备用2: GPT-3.5 (够用，便宜)
  ↓ 失败
备用3: 本地模型 (离线可用，质量一般)
  ↓ 失败
最终: 告诉用户"服务暂时不可用"

功能降级：

完整功能: 使用WebSearch搜索最新信息
  ↓ 网络不可用
降级1: 使用本地缓存的信息
  ↓ 缓存也没有
降级2: 基于训练数据的知识（可能过时）
  ↓ 完全不知道
最终: 诚实告知"我无法获取这方面信息"

5.5 工具循环检测：防止重复调用

如果Agent在工具调用中陷入循环（反复调用相同的工具或相同的模式），会造成资源浪费。OpenClaw通过工具循环检测来防止这种情况。

检测机制：

┌─────────────────────────────────────────────────────────────┐
│                    工具循环检测                              │
├─────────────────────────────────────────────────────────────┤
│ 1. 监控连续的工具调用模式                                    │
│ 2. 检测重复或循环的工具序列                                  │
│ 3. 当检测到循环时，中断执行并提示用户                        │
└─────────────────────────────────────────────────────────────┘

检测器类型：

• generic_repeat：检测通用重复模式
• known_poll_no_progress：检测已知的轮询无进展模式
• ping_pong：检测来回切换的模式
• global_circuit_breaker：全局断路器，防止系统级循环

阈值配置：

• warningThreshold：警告阈值
• criticalThreshold：严重阈值
• globalCircuitBreakerThreshold：全局断路器阈值

处理策略：

• 检测：识别重复的工具调用模式
• 中断：当循环被检测到时，停止当前运行
• 提示：向用户报告循环检测情况

这让Agent避免在复杂任务中陷入无意义的重复，提高效率和用户体验。

---

6. 心跳机制：Agent的生物钟

前面的机制都是"被动响应"——用户发消息，Agent回应。但一个真正的智能体应该具备主动性。

6.1 为什么需要心跳

想象一个只会在你问它时才说话的管家：

• 你不会知道烤箱已经预热好了
• 你不会知道外面下雨了
• 你不会知道预约的医生已经改期

你需要一个主动提醒你的管家。

在Agent的语境中，主动性体现在：

• 定时检查系统状态
• 按计划执行任务
• 对特定事件作出响应

6.2 Cron与Heartbeat：两种定时机制

OpenClaw提供两种定时任务机制：Cron作业和Heartbeat。

Cron作业

Cron作业适用于需要精确时间或隔离会话的任务：

# 每天早上9点发送日报
openclaw cron add \
  --name "Morning briefing" \
  --cron "0 9 * * *" \
  --session isolated \
  --message "Generate today's briefing" \
  --announce

# 20分钟后提醒我
openclaw cron add \
  --name "Reminder" \
  --at "20m" \
  --session main \
  --system-event "Meeting starts in 10 minutes" \
  --wake now

Cron作业的特点：

• 精确时间：使用标准cron表达式（5或6字段）
• 会话隔离：可以在隔离会话中运行，不污染主会话历史
• 模型覆盖：可以为特定任务指定不同的模型
• 负载分散：整点任务会自动分散在0-5分钟内执行

Heartbeat

Heartbeat适用于周期性检查和上下文感知的任务：

• 在主会话中运行，保持对话连续性
• 定期触发（可配置）
• 通过HEARTBEAT.md定义检查清单
• 如果返回HEARTBEAT_OK且内容简短，消息会被静默丢弃

如何选择

场景	推荐	原因
定期检查收件箱	Heartbeat	批量检查，上下文感知
每天早上9点发送日报	Cron	需要精确时间
20分钟后提醒	Cron (--at)	一次性精确提醒
每周深度分析	Cron (isolated)	长时间任务，隔离会话

6.3 HEARTBEAT.md：心跳的剧本

在第三章我们介绍过HEARTBEAT.md，现在深入理解它的工作机制。

简单清单格式

HEARTBEAT.md的格式非常简单——它就是一个检查清单：

# Heartbeat checklist

- Quick scan: anything urgent in inboxes?
- If it's daytime, do a lightweight check-in if nothing else is pending.
- If a task is blocked, write down _what is missing_ and ask Peter next time.

关键说明：

• 心跳的触发间隔和投递目标是在openclaw.json配置文件中设置的，不是在HEARTBEAT.md中
• 触发间隔可配置
• 如果HEARTBEAT.md为空或只有标题，心跳会跳过以节省API调用

配置与内容的分离

心跳的行为由两部分决定：

1. 配置文件（~/.openclaw/openclaw.json）控制何时和如何运行：

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m",        // 触发间隔（示例）
        target: "last",      // 投递到最近联系的渠道
        activeHours: {       // 可选：活跃时间段
          start: "08:00",
          end: "22:00"
        }
      }
    }
  }
}

2. HEARTBEAT.md控制做什么：

- 扫描收件箱查看紧急邮件
- 检查接下来2小时的日历事件
- 如果有待处理任务，提供状态更新

HEARTBEAT_OK响应

如果检查后没有需要关注的事情，Agent应该回复HEARTBEAT_OK。

这是一个特殊的响应信号：

• 当Agent返回HEARTBEAT_OK，且剩余内容在字符限制范围内时，消息会被静默丢弃
• 这样可以避免每次心跳都打扰用户
• 如果有重要发现，Agent应该直接返回消息内容，不要包含HEARTBEAT_OK

心跳的运行特性

重要：心跳运行在主会话中，具有与普通对话相同的工具权限——它可以：

• 读取文件、查询状态、分析数据
• 调用任何工具（read、write、edit、exec等）
• 发送通知到配置的渠道
• 生成报告、执行命令

心跳没有特殊的"安全边界"限制，它就是一个定时的Agent回合。

6.4 从心跳到事件驱动

心跳机制是事件驱动架构的一种实现。更广义地说，Agent可以对各种事件作出响应：

事件类型:
├── 定时事件 (Cron)
│   └── "每天早上9点"
│
├── 文件系统事件
│   └── "当~/Downloads有新文件时"
│
├── 外部服务事件
│   └── "当收到新邮件时"
│   └── "当GitHub PR被评论时"
│
└── 系统状态事件
    └── "当CPU使用率>90%时"
    └── "当磁盘空间<10%时"

这让Agent从"轮询模式"（不断询问"有变化吗"）进化到"订阅模式"（只在变化时响应），更加高效和实时。

---

7. 实践：调试消息循环

理解了原理，我们来看看如何调试和优化消息循环。

7.1 观察循环状态

OpenClaw提供了查看当前循环状态的命令：

openclaw status --verbose

输出示例：

Dashboard:      http://localhost:3000
OS:             Windows_NT (win32)
Tailscale:      Not connected
Channel:        cli
Gateway:        Running
Agents:         1 running
  - main: Running (model: claude-3-5-sonnet-20241022)
Memory:         2.1 MB / 100 MB
Heartbeat:      Enabled
Sessions:       1 active

关键指标：

• Gateway：网关运行状态
• Agents：正在运行的Agent数量和状态
• Memory：内存使用情况
• Heartbeat：心跳机制是否启用及触发间隔
• Sessions：活跃会话数

7.2 诊断循环卡住

症状：Agent一直在"思考"，但不出结果

诊断步骤：

1. 检查当前会话状态：

   openclaw status --usage

   查看会话的Token使用情况和运行状态

2. 检查工具调用： 是否在某个工具调用上反复失败？

   [Round 10] Calling: bash("find / -name config")
   [Round 11] Calling: bash("find / -name config")
   [Round 12] Calling: bash("find / -name config")

   这表明Agent陷入了循环

3. 查看日志：

   openclaw logs --follow

   实时跟踪Agent的运行日志

解决方案：

• 主动取消：/cancel命令
• 简化请求：把复杂任务拆分成多个简单任务
• 增加限制：调高最大轮数或Token限制（如果确实需要）

7.3 优化循环效率

减少循环轮数：

低效请求："帮我看看这个项目"

• Agent需要多轮探索才能理解"看什么"

高效请求："帮我检查这个项目的TypeScript配置是否正确"

• Agent知道要找tsconfig.json，一轮就能定位

避免循环陷阱：

Agent有时会陷入"思考-再思考"的无限循环：

Thought: "我需要更多信息"
Action: 搜索
Observation: 找到一些信息
Thought: "但还不够确定，我需要再搜索..."
...循环...

可以在AGENTS.md中设置规则防止这种情况：

规则: 搜索最多3轮，如果还找不到答案就基于已有信息给出最佳建议

---

8. 总结

这一章我们深入探讨了OpenClaw的消息循环与事件驱动机制——这套让Agent从"静态程序"进化为"动态生命"的核心架构。

核心洞察回顾：

1. 思考-行动循环：观察-思考-行动的永动引擎，让Agent能像人类一样分步解决复杂问题

2. 任务队列：命令队列序列化入站运行，实现可靠的调度和负载均衡

3. 任务分类模型：通道内串行保证因果一致性，通道间并行提高吞吐量

4. 容错设计：分层容错、智能重试、优雅降级、工具循环检测，确保系统在故障中保持韧性

5. 心跳机制：Cron和Heartbeat机制赋予Agent主动性，从被动应答进化到主动服务

架构的哲学思考：

消息循环的设计体现了"有序中的灵活"：

• Think-Action Loop provides a fixed processing framework, but the specific actions of each round are flexible
• कार्य वर्गीकरण मॉडल प्रसंस्करण क्रम को लागू करता है, लेकिन विभिन्न वर्गों के बीच शेड्यूलिंग लचीला है
• दिल की धड़कन तंत्र में एक निश्चित ट्रिगरिंग लय होती है, लेकिन किए गए कार्यों की सामग्री लचीली होती है

यह "बाधित स्वतंत्रता" जटिल सिस्टम डिज़ाइन का सार है - अनुकूलन क्षमता को बनाए रखते हुए पूर्वानुमेयता सुनिश्चित करना।

OpenClaw का संदेश लूप एक सरल "सत्य होते हुए भी" नहीं है, बल्कि राज्य मशीनों, शेड्यूलर, बफ़र्स और दोष-सहिष्णु प्रणालियों का सावधानीपूर्वक डिज़ाइन किया गया कॉम्प्लेक्स है। यह एजेंट को इसकी अनुमति देता है:

• निरंतर संचालन: 7×24 घंटे निर्बाध सेवा
• व्यवस्थित प्रसंस्करण: कार्यों के बीच कारणात्मक संबंध सुनिश्चित करें
• लचीली प्रतिक्रिया: दोषों में स्व-उपचार और ओवरलोड में प्रतिक्रियाशील बने रहना
• प्रोएक्टिव सर्विस: न केवल एक उपकरण, बल्कि एक भागीदार भी

यह आवश्यक विशेषता है जो आधुनिक एजेंट सिस्टम को पारंपरिक सॉफ़्टवेयर से अलग करती है - यह जीवित है।

---

अगला चरण:

अगले अध्याय में, हम पता लगाएंगे कि इस शक्तिशाली हृदय को व्यापक दुनिया से कैसे जोड़ा जाए - मल्टी-चैनल एक्सेस आर्किटेक्चर।