​

心跳（Gateway网关）

心跳还是定时任务？ 参见 定时任务与心跳对比 了解何时使用哪种方式。

​

快速入门（新手）

1. 保持心跳启用（默认间隔为 30m，Anthropic OAuth/setup-token 模式下为 1h），或设置自定义频率。
2. 在智能体工作区中创建一个简短的 HEARTBEAT.md 检查清单（可选但推荐）。
3. 决定心跳消息发送到哪里（默认为 target: "last"）。
4. 可选：启用心跳推理内容投递以提高透明度。
5. 可选：将心跳限制在活跃时段（本地时间）。

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m",
        target: "last",
        // activeHours: { start: "08:00", end: "24:00" },
        // includeReasoning: true, // 可选：同时发送单独的 `Reasoning:` 消息
      },
    },
  },
}

​

默认值

• 间隔：30m（当检测到 Anthropic OAuth/setup-token 认证模式时为 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.activeHours）按配置的时区检查。在窗口外，心跳将被跳过，直到下一个处于窗口内的时刻。

​

心跳提示词的用途

• 后台任务：“Consider outstanding tasks” 促使智能体检查待办事项（收件箱、日历、提醒、排队工作）并呈现紧急事项。
• 关怀用户：“Checkup sometimes on your human during day time” 促使偶尔发送一条轻量级的”需要什么帮助吗？“消息，但通过使用你配置的本地时区避免夜间打扰（参见 /concepts/timezone）。

​

响应约定

• 如果没有需要关注的事项，回复 HEARTBEAT_OK。
• 在心跳运行期间，当 HEARTBEAT_OK 出现在回复的开头或结尾时，OpenClaw 将其视为确认。该标记会被移除，如果剩余内容 ≤ ackMaxChars（默认：300），则整条回复被丢弃。
• 如果 HEARTBEAT_OK 出现在回复的中间，则不做特殊处理。
• 对于告警，不要包含 HEARTBEAT_OK；只返回告警文本。

​

配置

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m", // 默认：30m（0m 禁用）
        model: "anthropic/claude-opus-4-5",
        includeReasoning: false, // 默认：false（可用时投递单独的 Reasoning: 消息）
        target: "last", // last | none | <渠道 id>（核心或插件，例如 "bluebubbles"）
        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.",
        ackMaxChars: 300, // HEARTBEAT_OK 之后允许的最大字符数
      },
    },
  },
}

​

作用域和优先级

• agents.defaults.heartbeat 设置全局心跳行为。
• agents.list[].heartbeat 在其之上合并；如果任何智能体有 heartbeat 块，则只有这些智能体运行心跳。
• channels.defaults.heartbeat 为所有渠道设置可见性默认值。
• channels.<channel>.heartbeat 覆盖渠道默认值。
• channels.<channel>.accounts.<id>.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.",
        },
      },
    ],
  },
}

​

字段说明

• every：心跳间隔（时长字符串；默认单位 = 分钟）。
• model：可选的心跳运行模型覆盖（provider/model）。
• includeReasoning：启用后，在可用时还会投递一条以 Reasoning: 为前缀的单独消息（与 /reasoning on 格式相同）。
• session：可选的心跳运行会话键。
  • main（默认）：智能体主会话。
  • 显式会话键（从 openclaw sessions --json 或会话 CLI 复制）。
  • 会话键格式：参见会话和群组。
• target：
  • last（默认）：投递到最近使用的外部渠道。
  • 显式渠道：whatsapp / telegram / discord / googlechat / slack / msteams / signal / imessage。
  • none：运行心跳但不投递到外部。
• to：可选的接收者覆盖（渠道特定 ID，例如 WhatsApp 的 E.164 格式或 Telegram 聊天 ID）。
• prompt：覆盖默认提示词正文（不合并）。
• ackMaxChars：HEARTBEAT_OK 之后在投递前允许的最大字符数。

​

投递行为

• 心跳默认在智能体的主会话中运行（agent:<id>:<mainKey>），或在 session.scope = "global" 时为 global。设置 session 可覆盖为特定渠道会话（Discord/WhatsApp 等）。
• session 仅影响运行上下文；投递由 target 和 to 控制。
• 要投递到特定渠道/接收者，设置 target + to。使用 target: "last" 时，投递使用该会话的最近外部渠道。
• 如果主队列繁忙，心跳将被跳过并稍后重试。
• 如果 target 解析不到外部目标，运行仍会执行但不发送出站消息。
• 仅包含心跳的回复不会保持会话活跃；updatedAt 会被恢复，因此空闲过期行为正常。

​

可见性控制

channels:
  defaults:
    heartbeat:
      showOk: false # 隐藏 HEARTBEAT_OK（默认）
      showAlerts: true # 显示告警消息（默认）
      useIndicator: true # 发送指示器事件（默认）
  telegram:
    heartbeat:
      showOk: true # 在 Telegram 上显示 OK 确认
  whatsapp:
    accounts:
      work:
        heartbeat:
          showAlerts: false # 抑制该账户的告警投递

​

各标志的作用

• showOk：当模型返回仅含 OK 的回复时，发送 HEARTBEAT_OK 确认。
• showAlerts：当模型返回非 OK 回复时，发送告警内容。
• useIndicator：为 UI 状态展示面板发送指示器事件。

​

按渠道与按账户示例

channels:
  defaults:
    heartbeat:
      showOk: false
      showAlerts: true
      useIndicator: true
  slack:
    heartbeat:
      showOk: true # 所有 Slack 账户
    accounts:
      ops:
        heartbeat:
          showAlerts: false # 仅抑制 ops 账户的告警
  telegram:
    heartbeat:
      showOk: true

​

常见模式

​

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.

​

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

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

​

手动唤醒（按需）

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

​

推理内容投递（可选）

• agents.defaults.heartbeat.includeReasoning: true

​

成本意识