第五章消息循環與事件驅動：Agent的心跳與脈搏

核心提示：如果說工具系統是Agent的手腳，提示詞系統是它的大腦，那麼消息循環就是它的心跳——持續不斷、節律分明地驅動着整個系統運轉。這一章我們將理解Agent是如何持續運轉的，以及OpenClaw如何在複雜環境中保持穩定運行。

1. 引言：從"靜態應答"到"動態生命"

1.1 傳統軟件的侷限

想象一個傳統的命令行工具：你輸入一個命令，它執行，返回結果，然後退出。整個過程是線性的、一次性的、被動的。

用戶輸入 → 程序處理 → 輸出結果 → 程序結束
    ↑                              |
    └──────────────────────────────┘ (下次再從頭開始)

這種模式適用於簡單任務，但面對複雜問題時顯得力不從心：

它沒有"記憶"——每次都要重新開始
它沒有"主動性"——你不問它就不答
它沒有"適應性"——遇到錯誤只能崩潰

1.2 Agent的生命特徵

OpenClaw的Agent表現出完全不同的生命特徵：

持續性：它不會"退出"，而是持續運行，等待下一次交互

記憶性：它記得你們之前的對話、你的偏好、項目的上下文

主動性：即使沒有你的指令，它也會在特定時間醒來執行任務

適應性：遇到錯誤時，它會重試、調整策略、或者優雅地降級

這些特徵的核心，是一個永不停息的消息循環系統。

1.3 爲什麼是"心跳"

"心跳"這個詞不只是比喻。在OpenClaw的架構中，消息循環確實像一個生物的心臟：

節律性：它按照固定的節奏檢查、處理、響應
持續性：從啓動到關閉，它從不停止
關鍵性：如果心跳停止，整個系統就"死亡"了
適應性：它可以根據負載調整節奏（快/慢、忙/閒）

理解這個消息循環，就是理解Agent的"生命機制"。

2. 思考-行動循環：Agent的工作方式

2.1 從人類認知到機器實現

思考-行動循環是Agent行爲的核心模式。它反映了人類解決問題的方式。

人類如何解決複雜問題：

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

觀察：你站在街頭，看到路牌、建築、行人
思考："根據地圖，這家店應該在東邊兩個街區"
行動：你開始向東走
觀察：走了兩分鐘，你發現走錯了方向
思考："地圖顯示我應該左轉，但路牌指向右邊。也許地圖過時了？"
行動：你決定問路
觀察：路人指了另一個方向
思考："看來確實是我理解錯了地圖的方向"
行動：你調整方向，繼續前進
...直到找到咖啡店

注意這個過程的關鍵特徵：

不是線性的——你需要多次調整
依賴反饋——每一步行動的結果影響下一步決策
容忍不確定性——你會犯錯，但能從錯誤中恢復

思考-行動循環的定義：

思考-行動循環 = （觀察、思考、行動）的重複序列

其中：
- 觀察: 感知當前環境狀態
- 思考: 基於觀察和目標進行推理
- 行動: 執行改變環境的操作
- 重複直到任務完成

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使用兩個層次的隊列系統：

任務分類隊列：
- 用於序列化命令執行
- 按任務類型分類（主任務、定時任務、子代理任務等）
- 控制總體併發度
會話隊列：
- 用於管理會話級別的消息排隊
- 通過sessionKey實現會話隔離
- 支持多種隊列模式（合併、插隊、排隊等）

Gateway接收外部消息後，根據消息類型和會話標識決定加入哪個隊列：

新消息進入任務分類隊列等待執行
同一會話的後續消息進入會話隊列，按順序處理

這種架構的好處：

序列化：按順序處理，避免競態條件
可擴展：可以添加新的消費者而不影響現有組件
流量控制：通過隊列深度和併發限制保護系統
會話隔離：同一會話的消息按順序處理，不會混亂

3.3 消息的結構

在OpenClaw中，消息的結構如下：

typescript

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	將消息加入隊列，按順序處理

配置示例：

json5

{
  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 隊列深度與監控

通過日誌可以監控隊列狀態：

bash

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作業適用於需要精確時間或隔離會話的任務：

bash

# 每天早上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的格式非常簡單——它就是一個檢查清單：

markdown

# 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調用

配置與內容的分離

心跳的行爲由兩部分決定：

配置文件（~/.openclaw/openclaw.json）控制何時和如何運行：

json5

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m",        // 觸發間隔（示例）
        target: "last",      // 投遞到最近聯繫的渠道
        activeHours: {       // 可選：活躍時間段
          start: "08:00",
          end: "22:00"
        }
      }
    }
  }
}

HEARTBEAT.md控制做什麼：

markdown

- 掃描收件箱查看緊急郵件
- 檢查接下來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提供了查看當前循環狀態的命令：

bash

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一直在"思考"，但不出結果

診斷步驟：

檢查當前會話狀態：
bash
```
openclaw status --usage
```
查看會話的Token使用情況和運行狀態

檢查工具調用：是否在某個工具調用上反覆失敗？

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

這表明Agent陷入了循環

查看日誌：
bash
```
openclaw logs --follow
```
實時跟蹤Agent的運行日誌

解決方案：

主動取消：/cancel命令
簡化請求：把複雜任務拆分成多個簡單任務
增加限制：調高最大輪數或Token限制（如果確實需要）

7.3 優化循環效率

減少循環輪數：

低效請求："幫我看看這個項目"

Agent需要多輪探索才能理解"看什麼"

高效請求："幫我檢查這個項目的TypeScript配置是否正確"

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

避免循環陷阱：

Agent有時會陷入"思考-再思考"的無限循環：

Thought: "我需要更多信息"
Action: 搜索
Observation: 找到一些信息
Thought: "但還不夠確定，我需要再搜索..."
...循環...

可以在AGENTS.md中設置規則防止這種情況：

規則: 搜索最多3輪，如果還找不到答案就基於已有信息給出最佳建議

8. 總結

這一章我們深入探討了OpenClaw的消息循環與事件驅動機制——這套讓Agent從"靜態程序"進化爲"動態生命"的核心架構。

核心洞察回顧：

思考-行動循環：觀察-思考-行動的永動引擎，讓Agent能像人類一樣分步解決複雜問題
任務隊列：命令隊列序列化入站運行，實現可靠的調度和負載均衡
任務分類模型：通道內串行保證因果一致性，通道間並行提高吞吐量
容錯設計：分層容錯、智能重試、優雅降級、工具循環檢測，確保系統在故障中保持韌性
心跳機制：Cron和Heartbeat機制賦予Agent主動性，從被動應答進化到主動服務

架構的哲學思考：

消息循環的設計體現了"有序中的靈活"：

思考-行動循環提供了固定的處理框架，但每輪的具體行動是靈活的
任務分類模型強制了處理順序，但不同分類之間的調度是靈活的
心跳機制固定了觸發節奏，但執行的任務內容是靈活的

這種"有約束的自由"是複雜系統設計的精髓——既保證可預測性，又保留適應性。

OpenClaw的消息循環不是簡單的"while true"，而是一個精心設計的狀態機、調度器、緩衝區和容錯系統的綜合體。它讓Agent能夠：

持續運轉：7×24小時不間斷服務
有序處理：保證任務之間的因果關係
彈性應對：在故障中自愈，在過載中保持響應
主動服務：不僅是工具，更是夥伴

這就是現代Agent系統區別於傳統軟件的本質特徵——它是有生命的。

下一步：

在下一章，我們將探討如何讓這個強大的心臟連接到更廣闊的世界——多渠道接入架構。

第五章 消息循環與事件驅動：Agent的心跳與脈搏 ​

1. 引言：從"靜態應答"到"動態生命" ​

1.1 傳統軟件的侷限 ​

1.2 Agent的生命特徵 ​

1.3 爲什麼是"心跳" ​

2. 思考-行動循環：Agent的工作方式 ​

2.1 從人類認知到機器實現 ​

2.2 OpenClaw中的循環實現 ​

2.3 循環的終止條件 ​

2.4 狀態管理：循環的記憶力 ​

2.5 循環的深度：單輪 vs 多輪 ​

3. 任務隊列：命令調度系統 ​

3.1 爲什麼需要任務隊列 ​

3.2 任務隊列架構 ​

3.3 消息的結構 ​

3.4 隊列模式 ​

3.5 任務分類 ​

4. 併發控制：任務隔離與排隊 ​

4.1 任務分類模型 ​

4.2 爲什麼串行在通道內是必要的 ​

4.3 流量控制 ​

4.4 隊列深度與監控 ​

5. 容錯與自愈：彈性架構設計 ​

5.1 分層容錯策略 ​

5.2 重試策略：何時重試、如何重試 ​

5.3 錯誤反饋：Agent的自我糾正 ​

5.4 降級策略：優雅地失敗 ​

5.5 工具循環檢測：防止重複調用 ​

6. 心跳機制：Agent的生物鐘 ​

6.1 爲什麼需要心跳 ​

6.2 Cron與Heartbeat：兩種定時機制 ​

Cron作業 ​

Heartbeat ​

如何選擇 ​

6.3 HEARTBEAT.md：心跳的劇本 ​

簡單清單格式 ​

配置與內容的分離 ​

HEARTBEAT_OK響應 ​

心跳的運行特性 ​

6.4 從心跳到事件驅動 ​

7. 實踐：調試消息循環 ​

7.1 觀察循環狀態 ​

7.2 診斷循環卡住 ​

7.3 優化循環效率 ​

8. 總結 ​

第五章消息循環與事件驅動：Agent的心跳與脈搏

1. 引言：從"靜態應答"到"動態生命"

1.1 傳統軟件的侷限

1.2 Agent的生命特徵

1.3 爲什麼是"心跳"

2. 思考-行動循環：Agent的工作方式

2.1 從人類認知到機器實現

2.2 OpenClaw中的循環實現

2.3 循環的終止條件

2.4 狀態管理：循環的記憶力

2.5 循環的深度：單輪 vs 多輪

3. 任務隊列：命令調度系統

3.1 爲什麼需要任務隊列

3.2 任務隊列架構

3.3 消息的結構

3.4 隊列模式

3.5 任務分類

4. 併發控制：任務隔離與排隊

4.1 任務分類模型

4.2 爲什麼串行在通道內是必要的

4.3 流量控制

4.4 隊列深度與監控

5. 容錯與自愈：彈性架構設計

5.1 分層容錯策略

5.2 重試策略：何時重試、如何重試

5.3 錯誤反饋：Agent的自我糾正

5.4 降級策略：優雅地失敗

5.5 工具循環檢測：防止重複調用

6. 心跳機制：Agent的生物鐘

6.1 爲什麼需要心跳

6.2 Cron與Heartbeat：兩種定時機制

Cron作業

Heartbeat

如何選擇

6.3 HEARTBEAT.md：心跳的劇本

簡單清單格式

配置與內容的分離

HEARTBEAT_OK響應

心跳的運行特性

6.4 從心跳到事件驅動

7. 實踐：調試消息循環

7.1 觀察循環狀態

7.2 診斷循環卡住

7.3 優化循環效率

8. 總結