> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ironclaw.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 心跳系统

> 周期性检查与自动执行

心跳系统让 IronClaw 在对话间隙也能主动执行任务。默认每 30 分钟读取工作区根目录的 `HEARTBEAT.md`，按清单执行。

<Tip>
  你可以自定义心跳检查频率。
</Tip>

***

## 心跳会做什么

每次心跳触发时：

1. 读取 `HEARTBEAT.md`
2. 作为任务执行清单项
3. 若有结果或发现，发送到已配置通知频道
4. 将运行写入 `heartbeat_state` 表

如果 `HEARTBEAT.md` 不存在或为空，本次触发不执行任何动作。

***

## HEARTBEAT.md 格式

建议使用 checklist：

```markdown theme={null}
# Heartbeat Checklist

## Daily Tasks
- [ ] Check memory at daily/ for yesterday's notes. If missing, remind the user.
- [ ] Search memory for any items tagged as "follow-up" or "urgent" and list them.
- [ ] Read ops/stuck-jobs.md if it exists and summarize any unresolved incidents.

## Weekly Tasks (run only on Mondays)
- [ ] Summarize the week's daily notes into a weekly summary at weekly/<date>.md
- [ ] Check for any routines that haven't run in the past 7 days and flag them.

## Always
- [ ] If any of the above produce findings, write a summary to memory at heartbeat/latest.md
- [ ] Only notify the user if there are actionable items — do not send empty pings.
```

条件语句（例如“仅周一执行”）由 LLM 结合当前日期解释。

***

## 通知行为

只有存在可行动信息时才发送通知；无结果时保持安静。可将摘要写入 `heartbeat/latest.md` 以便后续检索。

***

## 配置

```bash theme={null}
# 启用心跳（默认 true）
HEARTBEAT_ENABLED=true

# 触发间隔（秒，默认 1800）
HEARTBEAT_INTERVAL_SECS=1800

# 通知频道
HEARTBEAT_NOTIFY_CHANNEL=tui   # tui, web, telegram, webhook

# 通知用户 ID
HEARTBEAT_NOTIFY_USER=default
```

<Note>
  如果频率过高导致 token 或 API 配额压力，建议将 `HEARTBEAT_INTERVAL_SECS` 调高到 3600 及以上。
</Note>

***

## 常见问题

<AccordionGroup>
  <Accordion title="心跳没有触发" icon="clock">
    * 确认 `HEARTBEAT_ENABLED=true`
    * 检查启动日志是否包含 heartbeat 启动信息
    * 检查 `HEARTBEAT_INTERVAL_SECS` 是否合理
    * 确认根目录存在 `HEARTBEAT.md`
  </Accordion>

  <Accordion title="通知太频繁" icon="bell">
    * 在 HEARTBEAT.md 中增加“仅有可执行项才通知”
    * 提高 `HEARTBEAT_INTERVAL_SECS`
    * 让清单更具体，减少噪声输出
  </Accordion>

  <Accordion title="心跳任务耗费 token 过高" icon="coins">
    * 精简 HEARTBEAT.md 清单项
    * 提高触发间隔
    * 明确限制：例如“每次最多 5 次工具调用”
  </Accordion>
</AccordionGroup>