Heartbeat
心跳轮询消息和通知规则
注意
Heartbeat runs periodic agent turns in the main session so the model can
surface anything that needs attention without spamming you.
Quick start (beginner)
1. Heartbeat 启用在执行（Anthropic OAuth/setup-token 的場合、默认 ''30m'' 或 ''1h''）或独自的頻度设置执行。
2. Create a tiny ''HEARTBEAT.md'' checklist in the agent workspace (optional but recommended).
3. Decide where heartbeat messages should go (''target: "last"'' is the default).
4. Optional: enable heartbeat reasoning delivery for transparency.
5. 选项：Heartbeat 活跃时间（本地时间）在限制执行。
设置例：
{
agents: {
defaults: {
heartbeat: {
every: "30m",
target: "last",
// activeHours: { start: "08:00", end: "24:00" },
// includeReasoning: true, // optional: send separate `Reasoning:` message too
},
},
},
}默认值
- Interval: ''30m'' (or ''1h'' when Anthropic OAuth/setup-token is the detected auth mode). Set ''agents.defaults.heartbeat.every'' or per-agent ''agents.list[].heartbeat.every''; use ''0m'' to disable.
- 提示词正文（''agents.defaults.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.''
- Heartbeat 提示词是用户消息作为逐語发送被。系统
prompt includes a "Heartbeat" section and the run is flagged internally.
- Active hours (''heartbeat.activeHours'') are checked in the configured timezone.
Outside the window, heartbeats are skipped until the next tick inside the window.
Heartbeat 提示词的目的
默认提示有意设计得很宽泛：
- 后台任务：「未完成的任务検討执行」是代理在审查促执行
follow-ups (inbox, calendar, reminders, queued work) and surface anything urgent.
- Human check-in: "Checkup sometimes on your human during day time" nudges an
occasional lightweight "anything you need?" message, but avoids night-time spam
by using your configured local timezone (see ''/concepts/timezone'').
如果您希望心跳执行非常特定的操作（例如「检查 Gmail PubSub
stats」或「网关的健全性确认」）、''agents.defaults.heartbeat.prompt'' （或
''agents.list[].heartbeat.prompt''）自定义正文（逐語发送）在设置执行。
响应契約
- 注意需要那也的没有場合、''''HEARTBEAT_OK'''' 和回复请。
- During heartbeat runs, OpenClaw treats ''HEARTBEAT_OK'' as an ack when it appears
at the start or end of the reply. The token is stripped and the reply is
残里的内容但 ''≤ ''ackMaxChars'''' （默认：300）的場合、删除被。
- If ''HEARTBEAT_OK'' appears in the ''middle'' of a reply, it is not treated
specially.
- For alerts, ''do not'' include ''HEARTBEAT_OK''; return only the alert text.
Outside heartbeats, stray ''HEARTBEAT_OK'' at the start/end of a message is stripped
記録被。''HEARTBEAT_OK'' 仅的消息是破棄被。
设置
{
agents: {
defaults: {
heartbeat: {
every: "30m", // default: 30m (0m disables)
model: "anthropic/claude-opus-4-5",
includeReasoning: false, // default: false (deliver separate Reasoning: message when available)
target: "last", // last | none | <channel id> (core or plugin, e.g. "bluebubbles")
to: "+15551234567", // optional channel-specific override
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.",
ackMaxChars: 300, // max chars allowed after HEARTBEAT_OK
},
},
},
}#
作用域和优先级
- ''agents.defaults.heartbeat'' 是全局那 Heartbeat 动作设置执行。
- ''agents.list[].heartbeat'' merges on top; if any agent has a ''heartbeat'' block, ''only those agents'' run heartbeats.
- ''channels.defaults.heartbeat'' 是所有渠道的可见性的默认设置执行。
- ''channels.'' 是渠道的默认上写机执行。
- ''channels.'' （多账户渠道）是渠道每个设置上写机执行。
#
代理每个 Heartbeat
If any ''agents.list[]'' entry includes a ''heartbeat'' block, ''only those agents''
Heartbeat 运行执行。每个代理块是 ''agents.defaults.heartbeat'' 的上在合并被
(so you can set shared defaults once and override per agent).
示示例：2 次的代理、2 番目的代理仅但 Heartbeat 运行执行。
{
agents: {
defaults: {
heartbeat: {
every: "30m",
target: "last",
},
},
list: [
{ id: "main", default: true },
{
id: "ops",
heartbeat: {
every: "1h",
target: "whatsapp",
to: "+15551234567",
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.",
},
},
],
},
}#
Field notes
- ''every''：Heartbeat 間隔（期间字符串；默认単位=分钟）。
- ''model''：Heartbeat 运行的选项的模型覆盖（''provider/model''）。
- ''includeReasoning''：启用在当执行、利用可能那場合在個別的 ''Reasoning:'' 消息也配信执行（''/reasoning on'' 和同自形状）。
- ''session''：Heartbeat 运行的选项的会话密钥。
- ''main'' （默认）：代理的主要会话。
- 明示的那会话密钥（''openclaw sessions --json'' 或 ''会话 CLI'' 从复制）。
- 会话密钥的形式：''会话'' 以及 ''群组'' 请参阅。
- ''target''：
- ''last'' (default): deliver to the last used external channel.
- 明示的那渠道：''whatsapp'' / ''telegram'' / ''discord'' / ''googlechat'' / ''slack'' / ''msteams'' / ''signal'' / ''imessage''。
- ''none''：Heartbeat 运行执行但''外部在配信不会执行''。
- ''to''：选项的接收者覆盖（渠道固有的 ID、示示例：WhatsApp 的 E.164 或 Telegram 聊天 ID）。
- ''prompt''：默认的提示词正文上写机执行（合并不会执行）。
- ''ackMaxChars'': max chars allowed after ''HEARTBEAT_OK'' before delivery.
配信动作
- 默认是、Heartbeat 是代理的主要会话（''agent:''）在被执行
or ''global'' when ''session.scope = "global"''. Set ''session'' to override to a
specific channel session (Discord/WhatsApp/etc.).
- ''session'' 是运行上下文仅在影響执行。配信是 ''target'' 和 ''to'' 由控制被。
- 特定的渠道/接收者在配信执行在是、''target'' + ''to'' 设置执行。
''target: "last"'' 的場合、配信是那个会话的最后一个外部渠道使用执行。
- If the main queue is busy, the heartbeat is skipped and retried later.
- If ''target'' resolves to no external destination, the run still happens but no
发送消息是发送不会被。
- Heartbeat 回复是会话''維持不会执行''。最后一个 ''updatedAt''
is restored so idle expiry behaves normally.
可见性的控制
By default, ''HEARTBEAT_OK'' acknowledgments are suppressed while alert content is delivered.
您可以按通道或按账户调整此设置：
channels:
defaults:
heartbeat:
showOk: false # Hide HEARTBEAT_OK (default)
showAlerts: true # Show alert messages (default)
useIndicator: true # Emit indicator events (default)
telegram:
heartbeat:
showOk: true # Show OK acknowledgments on Telegram
whatsapp:
accounts:
work:
heartbeat:
showAlerts: false # Suppress alert delivery for this accountPrecedence: per-account → per-channel → channel defaults → built-in defaults.
#
每个标志的作用
- ''showOk''：模型但 OK 仅的回复返已执行和机在 ''HEARTBEAT_OK'' 确认发送执行。
- ''showAlerts'': sends the alert content when the model returns a non-OK reply.
- ''useIndicator'': emits indicator events for UI status surfaces.
If <strong>all three</strong> are false, OpenClaw skips the heartbeat run entirely (no model call).
#
Per-channel vs per-account examples
channels:
defaults:
heartbeat:
showOk: false
showAlerts: true
useIndicator: true
slack:
heartbeat:
showOk: true # all Slack accounts
accounts:
ops:
heartbeat:
showAlerts: false # suppress alerts for ops account only
telegram:
heartbeat:
showOk: true#
一般的那模式
|目标|设置 |
| - |
| Default behavior (silent OKs, alerts on) | _(no config needed)_ |
| Fully silent (no messages, no indicator) | channels.defaults.heartbeat: { showOk: false, showAlerts: false, useIndicator: false }' |
| Indicator-only (no messages) | channels.defaults.heartbeat: { showOk: false, showAlerts: false, useIndicator: true }' |
|1 次的渠道在仅 OK| channels.telegram.heartbeat: { showOk: true }' |
HEARTBEAT.md（选项）
工作区在 ''HEARTBEAT.md'' 文件但存在执行場合、默认的提示词是
agent to read it. Think of it as your "heartbeat checklist": small, stable, and
safe to include every 30 minutes.
If ''HEARTBEAT.md'' exists but is effectively empty (only blank lines and markdown
headers like ''# Heading''), OpenClaw skips the heartbeat run to save API calls.
如果文件缺失，心跳仍然运行，模型决定做什么。
Keep it tiny (short checklist or reminders) to avoid prompt bloat.
例 '<code className="bg-white/10 px-1.5 py-0.5 rounded text-emerald-300 text-sm">'HEARTBEAT.md'</code>'：