心跳
心跳（Heartbeat）是 Gateway 的定期状态脉冲机制，用于维持连接活跃、执行周期性任务和生成状态报告。
工作原理
Gateway 以固定间隔执行心跳，每次心跳会：
text
┌─────────────────────────────────────────┐
│ Heartbeat Cycle │
│ │
│ 1. 更新 HEARTBEAT.md 状态文件 │
│ 2. 检查 Channel 连接健康 │
│ 3. 清理过期会话 │
│ 4. 执行周期性自动化任务 │
│ 5. 发送心跳事件给已连接客户端 │
│ 6. 记录状态日志 │
│ │
│ 间隔: 60 秒（默认） │
└─────────────────────────────────────────┘HEARTBEAT.md 文件
Gateway 在每次心跳时更新 HEARTBEAT.md 文件，记录当前运行状态的人类可读快照。
文件位置
text
~/.openclaw/HEARTBEAT.md文件内容示例
markdown
# OpenClaw Gateway Heartbeat
Last beat: 2025-01-15 13:05:00 UTC
Uptime: 2h 35m
Status: healthy
## Channels
- openai-main: connected (45ms latency)
- anthropic: connected (120ms latency)
## Sessions
- Active: 2
- Total today: 15
## Resources
- Memory: 85 MB
- CPU: 1.2%
- Disk: 45 GB free用途
HEARTBEAT.md 文件适合人工快速查看 Gateway 状态，也可以被外部监控脚本读取。
心跳间隔
配置
json5
{
"automation": {
"heartbeat": {
"enabled": true,
"interval": 60000 // 毫秒，默认 60 秒
}
}
}bash
# CLI 设置
openclaw config set automation.heartbeat.interval 30000 # 30 秒推荐间隔
| 场景 | 间隔 | 说明 |
|---|---|---|
| 开发环境 | 60s (默认) | 足够的监控粒度 |
| 生产环境 | 30s | 更快的异常检测 |
| 低资源 | 120s | 减少系统开销 |
心跳事件
每次心跳时，Gateway 向所有已连接的客户端广播心跳事件：
json
{
"type": "event",
"payload": {
"event": "heartbeat",
"timestamp": "2025-01-15T13:05:00Z",
"status": "healthy",
"channels": {
"openai-main": "connected",
"anthropic": "connected"
},
"sessions": {
"active": 2
}
}
}心跳执行的任务
连接检查
每次心跳检查所有 Channel 的连接状态。如果发现连接断开，尝试自动重连。
text
Heartbeat → Channel Check
├─ openai: connected ✓
├─ anthropic: disconnected ✗
│ └─ Auto-reconnecting...
│ └─ Reconnected ✓
└─ ollama: connected ✓会话清理
清理超时或不活跃的会话，释放资源：
text
Heartbeat → Session Cleanup
├─ sess_001: active (last activity: 5m ago) → keep
├─ sess_002: idle (last activity: 25h ago) → cleanup
└─ sess_003: active (last activity: 30s ago) → keep自动化任务
执行用户配置的周期性自动化任务：
json5
{
"automation": {
"heartbeat": {
"enabled": true,
"interval": 60000,
"tasks": [
{
"name": "log-rotation",
"every": 3600000, // 每小时
"action": "rotate-logs"
},
{
"name": "cache-cleanup",
"every": 86400000, // 每天
"action": "cleanup-cache"
}
]
}
}
}心跳 vs Cron 对比
| 特性 | 心跳 (Heartbeat) | Cron |
|---|---|---|
| 集成度 | 内置于 Gateway | 外部系统 |
| 最小间隔 | 10 秒 | 1 分钟 |
| 状态感知 | ✅ 了解 Gateway 状态 | ❌ 黑盒调用 |
| 故障检测 | ✅ 心跳停止 = 进程异常 | 需额外检查 |
| 配置方式 | JSON 配置文件 | crontab |
| 任务类型 | Gateway 内部任务 | 任意命令 |
何时用心跳，何时用 Cron
- 心跳：Gateway 内部的维护任务（连接检查、会话清理等）
- Cron：外部任务（备份、告警通知、日志分析等）
禁用心跳
bash
openclaw config set automation.heartbeat.enabled false不建议禁用
禁用心跳会导致 Channel 断连无法自动恢复、过期会话无法清理。仅在特殊调试场景下临时禁用。
监控心跳
bash
# 查看最近的心跳时间
openclaw status | grep heartbeat
# 查看 HEARTBEAT.md 文件
cat ~/.openclaw/HEARTBEAT.md
# 监控心跳日志
openclaw logs --filter heartbeat --follow