概念

Heartbeat 是 OpenClaw 的「心跳」— 定期喚醒 agent，讓它主動做事。

與 Cron 不同，Heartbeat 是在 main session 執行，保留完整對話 context。

Heartbeat vs Cron

特性	Heartbeat	Cron
Session	Main（有歷史）	Isolated（無歷史）
觸發	定期（每 N 分鐘）	精確時間
Context	完整對話	乾淨
用途	批次檢查、輪詢	定時任務

Heartbeat 流程

Heartbeat 觸發（每 30 分鐘）
        ↓
讀取 HEARTBEAT.md
        ↓
執行 heartbeat prompt
        ↓
Agent 決定做什麼
        ↓
如果沒事做 → 回覆 HEARTBEAT_OK
如果有事做 → 執行任務並回覆

核心代碼

1. Heartbeat 觸發

// Gateway 定期觸發 heartbeat
async function runHeartbeat() {
  const session = getMainSession();
  
  const prompt = config.heartbeat.prompt || `
Read HEARTBEAT.md if it exists (workspace context). 
Follow it strictly. Do not infer or repeat old tasks from prior chats. 
If nothing needs attention, reply HEARTBEAT_OK.
`;
  
  const response = await runAgent(session, prompt);
  
  // HEARTBEAT_OK = 沒事做，不發送給用戶
  if (response.trim() === 'HEARTBEAT_OK') {
    return;  // 靜默處理
  }
  
  // 有輸出 = 發送給用戶
  await sendReply(session.lastRoute, response);
}

// 定期執行
setInterval(runHeartbeat, config.heartbeat.intervalMinutes * 60 * 1000);

2. HEARTBEAT.md 範例

# HEARTBEAT.md

## 每次 Heartbeat 檢查
1. 確認 cron jobs 狀態
2. 如果有 error → 回報

## Rotating Checks（輪流做）
- git status
- email 檢查
- calendar 檢查

## 追蹤狀態
用 memory/heartbeat-state.json 記錄上次檢查時間

3. 設定

// openclaw.json
{
  "gateway": {
    "heartbeat": {
      "enabled": true,
      "intervalMinutes": 30,
      "prompt": "Read HEARTBEAT.md and execute any pending tasks.",
      "silent": true  // HEARTBEAT_OK 不發送
    }
  }
}

輪詢系統設計

// heartbeat-state.json
{
  "lastChecks": {
    "email": 1771200000000,
    "calendar": 1771190000000,
    "git-status": 1771180000000
  }
}

// 輪詢邏輯
function getNextCheck(state) {
  const checks = ['email', 'calendar', 'git-status'];
  
  // 找出最久沒檢查的
  let oldest = checks[0];
  let oldestTime = Infinity;
  
  for (const check of checks) {
    const lastTime = state.lastChecks[check] || 0;
    if (lastTime < oldestTime) {
      oldest = check;
      oldestTime = lastTime;
    }
  }
  
  return oldest;
}

Auto-reply 路由

// 訊息路由流程
async function handleIncomingMessage(msg) {
  // 1. 找 binding
  const binding = findBinding(msg.channel, msg.from);
  
  if (!binding) {
    // 2. 沒有 binding = 用 default agent
    binding = { agentId: config.agents.default };
  }
  
  // 3. 取得 session
  const sessionKey = deriveSessionKey(binding.agentId, msg);
  const session = await getSession(sessionKey);
  
  // 4. 執行 agent
  const response = await runAgent(session, msg.text);
  
  // 5. 回覆
  await sendReply(msg.channel, msg.from, response);
}

💡 關鍵洞察

Heartbeat 是「主動」的
- 不需要用戶訊息觸發
- 定期自己醒來
- 可以主動報告、提醒
HEARTBEAT.md 是「任務清單」
- Agent 每次 heartbeat 讀這個
- 放短期任務、檢查項目
- 不要放長期指令（那是 AGENTS.md）
HEARTBEAT_OK 是「沒事做」
- 回這個 = 不打擾用戶
- 靜默處理
- 避免每 30 分鐘都收到訊息
輪詢避免 token 浪費
- 不要每次都檢查所有東西
- 輪流檢查不同項目
- 用 state file 記錄

🔗 核心檔案

Heartbeat 文檔：/opt/homebrew/lib/node_modules/openclaw/docs/gateway/heartbeat.md
Cron vs Heartbeat：/opt/homebrew/lib/node_modules/openclaw/docs/automation/cron-vs-heartbeat.md

明天： Subagents（sessions_spawn）

Day 10: Auto-reply 機制（heartbeat, routing）