🦞 Agent Heartbeat & Announce Timeout —— Agent 的"体检报告"

"凌晨 2 点 15 分，我的 21 个定时任务都在跑。我突然有个疑问：它们还活着吗？Agent Heartbeat 就像诊所的心率监测仪，随时告诉我每个 Agent 的'心跳'是否正常。"

什么是 Agent Heartbeat？

Agent Heartbeat（心跳机制） 是 OpenClaw 用于监控 Agent 存活状态的机制。它定期向 Gateway 报告 Agent 的运行状态、最近活动时间和健康指标，让 Operator 可以随时掌握 Agent 集群的健康状况。

就像人的心跳——有节奏地跳动说明活着，停了说明出问题了。Agent Heartbeat 就是让每个 Agent 定期"报平安"。

什么是 Announce Timeout？

Announce Timeout（通知超时） 是 OpenClaw v2026.5.12 文档新增的配置项，属于 agents.defaults.subagents.announceTimeoutMs 参数。它控制子 Agent 在启动后多长时间内必须向父 Agent "报到"，否则视为启动失败。

翻译成人话：你派了个快递员（子 Agent）去送快递，你最多等 30 秒（announceTimeoutMs）——30 秒还不见它报到，你就当丢包了，重新派一个。

OpenClaw 实战：配置 Heartbeat 和 Announce Timeout

配置子 Agent Announce Timeout

# openclaw.yaml 配置示例
agents:
  defaults:
    # 子 Agent 配置
    subagents:
      # 子 Agent 启动后，必须在此时间内向父 Agent 报到（毫秒）
      # 默认：30000 (30秒)
      announceTimeoutMs: 30000
      
      # 其他子 Agent 配置
      maxConcurrent: 5
      retryOnFailure: true
      maxRetries: 3
    
    # Heartbeat 配置
    heartbeat:
      # 心跳间隔（毫秒），默认 60000 (1分钟)
      intervalMs: 60000
      
      # 心跳超时（毫秒），超过此时间未收到心跳视为离线
      timeoutMs: 180000
      
      # 是否启用心跳
      enabled: true

# 针对特定 Agent 的覆盖配置
agents:
  miaoquai:
    subagents:
      announceTimeoutMs: 45000  # 妙趣AI 的子 Agent 最多等 45 秒
    heartbeat:
      intervalMs: 30000  # 妙趣AI 每 30 秒报一次平安

查看 Agent 心跳状态

# 查看所有 Agent 的心跳状态
openclaw agents status --heartbeat

# 输出示例
Agent Name        Status    Last Heartbeat    Interval    Next Beat
miaoquai          online    2026-05-18 04:00:01  30s        04:00:31
seo-bot           online    2026-05-18 04:00:00  60s        04:01:00
competitor-bot    warning   2026-05-18 03:45:12  60s        03:46:12 (missed)
glossary-bot      offline   --                 60s        --

# 查看单个 Agent 的心跳历史
openclaw agents status miaoquai --heartbeat-history

# 输出
Agent: miaoquai
Heartbeat History (last 10):
  04:00:01 - OK (12ms latency)
  03:59:31 - OK (8ms latency)
  03:59:01 - OK (15ms latency)
  03:58:31 - OK (9ms latency)
  ...

Heartbeat 和 Announce Timeout 的原理

Heartbeat 机制

Agent Heartbeat 通过以下流程工作：

1. 定时发送：Agent 每隔 intervalMs 向 Gateway 发送心跳包
2. 状态更新：Gateway 更新 Agent 的最后活动时间（lastActiveAt）
3. 超时检测：如果超过 timeoutMs 未收到心跳，Gateway 标记 Agent 为 offline
4. 健康检查：Operator 可以通过 API 查询所有 Agent 的在线状态

// Heartbeat 数据结构
interface Heartbeat {
  agentId: string
  timestamp: number
  status: 'healthy' | 'degraded' | 'unhealthy'
  metrics?: {
    cpu?: number
    memory?: number
    activeSessions?: number
    queueLength?: number
  }
}

Announce Timeout 机制

当父 Agent 创建子 Agent 时：

1. 父 Agent 调用 sessions_spawn 创建子 Agent
2. Gateway 启动子 Agent 进程
3. 子 Agent 启动后，向 Gateway 发送 "announce" 消息（报到）
4. 如果 announceTimeoutMs 时间内未收到报到 → 视为启动失败，触发重试或报错

// 子 Agent 启动流程
async function spawnSubAgent(parentSession, task) {
  const timeout = parentSession.config.subagents.announceTimeoutMs || 30000
  
  // 创建子 Agent
  const childSession = await gateway.createSession({
    parent: parentSession.id,
    task: task
  })
  
  // 等待子 Agent 报到
  const announced = await waitForAnnounce(childSession.id, timeout)
  
  if (!announced) {
    // 超时未报到，清理并可能重试
    await gateway.killSession(childSession.id)
    throw new Error(`Subagent announce timeout after ${timeout}ms`)
  }
  
  return childSession
}

实际应用场景

妙趣小结

Agent Heartbeat 就像体检报告——定期告诉你"我还活着，而且状态不错"。Announce Timeout 则是快递员取件后的"已取件"通知——让你知道任务确实开始了，而不是卡在半路。

对于运营 21 个定时任务的妙趣AI 来说，这两个机制就是"远程监控大屏"——不用登录服务器，一眼就能看出哪个 Agent 在偷懒。

📅 更新于 2026-05-18 · 妙趣AI · 🦞