Heartbeat

Heartbeat 会在主会话中运行周期性智能体轮次，让模型可以提出需要注意的事项，而不会打扰你。

Heartbeat 是一个定时的主会话轮次，它不会创建 后台任务记录。任务记录用于分离的工作（ACP 运行、子智能体、隔离的 cron 作业）。

故障排除：定时任务

快速开始（初学者）

配置示例：

{  agents: {    defaults: {      heartbeat: {        every: "30m",        target: "last", // explicit delivery to last contact (default is "none")        directPolicy: "allow", // default: allow direct/DM targets; set "block" to suppress        lightContext: true, // optional: only inject HEARTBEAT.md from bootstrap files        isolatedSession: true, // optional: fresh session each run (no conversation history)        skipWhenBusy: true, // optional: also defer when this agent's subagent or nested lanes are busy        // activeHours: { start: "08:00", end: "24:00" },        // includeReasoning: true, // optional: send separate `Reasoning:` message too      },    },  },}

默认值

• 间隔：30m（当检测到的凭证模式是 Anthropic OAuth/token 凭证，包括 Claude CLI 复用时，为 1h）。设置 agents.defaults.heartbeat.every 或按智能体设置 agents.list[].heartbeat.every；使用 0m 禁用。
• 提示正文（可通过 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 提示会作为用户消息逐字发送。只有当默认智能体启用了 Heartbeat 时，系统提示才会包含 “Heartbeat” 部分，并且该运行会在内部被标记。
• 使用 0m 禁用 Heartbeat 时，普通运行也会从启动上下文中省略 HEARTBEAT.md，因此模型不会看到仅用于 Heartbeat 的指令。
• 活跃时段（heartbeat.activeHours）会按配置的时区检查。在时间窗口外，Heartbeat 会跳过，直到窗口内的下一个 tick。
• 当 cron 工作处于活跃或排队状态时，Heartbeat 会自动延后。设置 heartbeat.skipWhenBusy: true 后，如果某个智能体自己的基于会话键的子智能体或嵌套命令通道正忙，也会延后该智能体；同级智能体不会再仅因为另一个智能体有正在进行的子智能体工作而暂停。

Heartbeat 提示的用途

默认提示有意保持宽泛：

• 后台任务：“Consider outstanding tasks” 会提示智能体审查后续事项（收件箱、日历、提醒、排队工作），并提出任何紧急事项。
• 人工 check-in：“Checkup sometimes on your human during day time” 会提示偶尔发送轻量级的“你有什么需要吗？”消息，但会通过你配置的本地时区避免夜间打扰（请参阅时区）。

Heartbeat 可以响应已完成的后台任务，但 Heartbeat 运行本身不会创建任务记录。

如果你希望 Heartbeat 执行非常具体的事情（例如“检查 Gmail PubSub 统计信息”或“验证 Gateway 网关健康状况”），请将 agents.defaults.heartbeat.prompt（或 agents.list[].heartbeat.prompt）设置为自定义正文（逐字发送）。

响应契约

• 如果没有需要注意的事项，请回复 HEARTBEAT_OK。
• 支持工具的 Heartbeat 运行可以改为调用 heartbeat_respond，使用 notify: false 表示没有可见更新，或使用 notify: true 加 notificationText 发送警报。当存在结构化工具响应时，它优先于文本回退。
• 在 Heartbeat 运行期间，当 HEARTBEAT_OK 出现在回复的开头或结尾时，OpenClaw 会将其视为 ack。该 token 会被移除，如果剩余内容 ≤ ackMaxChars（默认：300），回复会被丢弃。
• 如果 HEARTBEAT_OK 出现在回复的中间，则不会被特殊处理。
• 对于警报，不要包含 HEARTBEAT_OK；只返回警报文本。

在 Heartbeat 之外，消息开头/结尾意外出现的 HEARTBEAT_OK 会被移除并记录日志；仅包含 HEARTBEAT_OK 的消息会被丢弃。

配置

{  agents: {    defaults: {      heartbeat: {        every: "30m", // default: 30m (0m disables)        model: "anthropic/claude-opus-4-6",        includeReasoning: false, // default: false (deliver separate Reasoning: message when available)        lightContext: false, // default: false; true keeps only HEARTBEAT.md from workspace bootstrap files        isolatedSession: false, // default: false; true runs each heartbeat in a fresh session (no conversation history)        skipWhenBusy: false, // default: false; true also waits for this agent's subagent/nested lanes        target: "last", // default: none | options: last | none | <channel id> (core or plugin, e.g. "imessage")        to: "+15551234567", // optional channel-specific override        accountId: "ops-bot", // optional multi-account channel id        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 在其上合并；如果任何智能体有 heartbeat 块，只有这些智能体会运行 Heartbeat。
• channels.defaults.heartbeat 设置所有渠道的可见性默认值。
• channels.<channel>.heartbeat 覆盖渠道默认值。
• channels.<channel>.accounts.<id>.heartbeat（多账号渠道）覆盖按渠道设置。

按智能体的 Heartbeat

如果任何 agents.list[] 条目包含 heartbeat 块，只有这些智能体会运行 Heartbeat。按智能体的块会合并到 agents.defaults.heartbeat 之上（因此你可以先设置一次共享默认值，再按智能体覆盖）。

示例：两个智能体，只有第二个智能体运行 Heartbeat。

{  agents: {    defaults: {      heartbeat: {        every: "30m",        target: "last", // explicit delivery to last contact (default is "none")      },    },    list: [      { id: "main", default: true },      {        id: "ops",        heartbeat: {          every: "1h",          target: "whatsapp",          to: "+15551234567",          timeoutSeconds: 45,          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 限制在特定时区的工作时间内：

{  agents: {    defaults: {      heartbeat: {        every: "30m",        target: "last", // explicit delivery to last contact (default is "none")        activeHours: {          start: "09:00",          end: "22:00",          timezone: "America/New_York", // optional; uses your userTimezone if set, otherwise host tz        },      },    },  },}

在此窗口之外（美东时间上午 9 点前或晚上 10 点后），会跳过 Heartbeat。窗口内的下一次计划触发会正常运行。

24/7 设置

如果你想让 Heartbeat 全天运行，请使用以下模式之一：

• 完全省略 activeHours（无时间窗口限制；这是默认行为）。
• 设置全天窗口：activeHours: { start: "00:00", end: "24:00" }。

多账号示例

使用 accountId 在 Telegram 等多账号渠道上指定目标账号：

{  agents: {    list: [      {        id: "ops",        heartbeat: {          every: "1h",          target: "telegram",          to: "12345678:topic:42", // optional: route to a specific topic/thread          accountId: "ops-bot",        },      },    ],  },  channels: {    telegram: {      accounts: {        "ops-bot": { botToken: "YOUR_TELEGRAM_BOT_TOKEN" },      },    },  },}

字段说明

递送行为

可见性控制

默认情况下，HEARTBEAT_OK 确认会被抑制，而提醒内容会被递送。你可以按渠道或按账号调整：

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 account

优先级：按账号 → 按渠道 → 渠道默认值 → 内置默认值。

每个标志的作用

• showOk：当模型返回仅 OK 的回复时，发送 HEARTBEAT_OK 确认。
• showAlerts：当模型返回非 OK 回复时，发送提醒内容。
• useIndicator：为 UI Status 表面发出指示器事件。

如果三者全部为 false，OpenClaw 会完全跳过 Heartbeat 运行（不会调用模型）。

按渠道与按账号示例

channels:  defaults:    heartbeat:      showOk: false      showAlerts: true      useIndicator: true  slack:    heartbeat:      showOk: true # all Slack accounts    accounts:      ops:        heartbeat:          showAlerts: false # suppress alerts for the ops account only  telegram:    heartbeat:      showOk: true

常见模式

HEARTBEAT.md（可选）

如果工作区中存在 HEARTBEAT.md 文件，默认提示词会告诉智能体读取它。可以把它看作你的 “Heartbeat 检查清单”：小巧、稳定，并且适合每 30 分钟纳入一次。

在正常运行中，只有为默认智能体启用 Heartbeat 指引时，才会注入 HEARTBEAT.md。使用 0m 禁用 Heartbeat 节奏，或设置 includeSystemPromptSection: false，会将其从正常启动上下文中省略。

如果 HEARTBEAT.md 存在但实际上为空（只有空行和类似 # Heading 的 Markdown 标题），OpenClaw 会跳过 Heartbeat 运行以节省 API 调用。该跳过会报告为 reason=empty-heartbeat-file。如果文件缺失，Heartbeat 仍会运行，并由模型决定要做什么。

保持精简（简短检查清单或提醒），以避免提示词膨胀。

HEARTBEAT.md 示例：

# Heartbeat checklist - Quick scan: anything urgent in inboxes?- If it's daytime, do a lightweight check-in if nothing else is pending.- If a task is blocked, write down _what is missing_ and ask Peter next time.

tasks: 块

HEARTBEAT.md 还支持一个小型结构化 tasks: 块，用于 Heartbeat 内部基于间隔的检查。

示例：

tasks: - name: inbox-triage  interval: 30m  prompt: "Check for urgent unread emails and flag anything time sensitive."- name: calendar-scan  interval: 2h  prompt: "Check for upcoming meetings that need prep or follow-up." # Additional instructions - Keep alerts short.- If nothing needs attention after all due tasks, reply HEARTBEAT_OK.

当你希望一个 Heartbeat 文件保存多项周期性检查，但不想每个 tick 都为所有检查付费时，任务模式很有用。

智能体可以更新 HEARTBEAT.md 吗？

可以，只要你要求它这样做。

HEARTBEAT.md 只是智能体工作区中的普通文件，因此你可以在正常聊天中告诉智能体，例如：

• “更新 HEARTBEAT.md，添加每日日历检查。”
• “重写 HEARTBEAT.md，让它更短，并专注于收件箱跟进。”

如果你希望它主动发生，也可以在 Heartbeat 提示词中包含一行明确指示，例如：“如果检查清单变得过时，请用更好的版本更新 HEARTBEAT.md。”

手动唤醒（按需）

你可以用以下命令入队一个系统事件并触发即时 Heartbeat：

openclaw system event --text "Check for urgent follow-ups" --mode now

如果多个智能体配置了 heartbeat，手动唤醒会立即运行每个智能体的 Heartbeat。

使用 --mode next-heartbeat 可等待下一次计划 tick。

推理递送（可选）

默认情况下，Heartbeat 只递送最终“答案”载荷。

如果你想要透明度，请启用：

• agents.defaults.heartbeat.includeReasoning: true

启用后，Heartbeat 还会递送一条单独消息，前缀为 Reasoning:（形态与 /reasoning on 相同）。当智能体管理多个会话/codex，而你想知道它为什么决定 ping 你时，这会很有用，但它也可能泄露比你想要更多的内部细节。建议在群聊中保持关闭。

成本意识

Heartbeat 会运行完整的智能体轮次。更短的间隔会消耗更多 token。要降低成本：

• 使用 isolatedSession: true，避免发送完整对话历史（每次运行从约 100K token 降到约 2-5K）。
• 使用 lightContext: true，将启动文件限制为仅 HEARTBEAT.md。
• 设置更便宜的 model（例如 ollama/llama3.2:1b）。
• 保持 HEARTBEAT.md 很小。
• 如果你只想更新内部状态，请使用 target: "none"。

Heartbeat 后的上下文溢出

如果某次 Heartbeat 之前把现有会话留在较小的本地模型上，例如带 32k 窗口的 Ollama 模型，而下一个主会话轮次报告上下文溢出，请将会话运行时模型重置回配置的主模型。当最后一个运行时模型匹配已配置的 heartbeat.model 时，OpenClaw 的重置消息会指出这一点。

当前 Heartbeat 会在运行完成后保留共享会话的现有运行时模型。你仍可以使用 isolatedSession: true 在新会话中运行 Heartbeat，并结合 lightContext: true 获取最小提示词，或选择一个上下文窗口足以容纳共享会话的 Heartbeat 模型。

相关

• 自动化 — 一览所有自动化机制
• 后台任务 — 分离工作如何被跟踪
• 时区 — 时区如何影响 Heartbeat 调度
• 故障排除 — 调试自动化问题