​

心跳（Gateway）

心跳 vs 定时任务？ 请参阅 Cron vs Heartbeat 了解何时使用哪种。

​

快速开始（初学者）

1. 保持心跳启用（默认是 30m，Anthropic OAuth/setup-token 则默认 1h），或者设置你自己的频率。
2. 在代理工作区创建一个小型的 HEARTBEAT.md 清单（可选但推荐）。
3. 决定心跳消息的发送目标（默认是 target: "none"；设置为 target: "last" 可发送给最后的联系人）。
4. 可选：启用心跳推理交付以增加透明度。
5. 可选：如果心跳仅需 HEARTBEAT.md，可使用轻量级引导上下文。
6. 可选：限制心跳仅在活跃时间（本地时间）运行。

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m",
        target: "last", // 明确推送到最后联络人（默认是 "none"）
        directPolicy: "allow", // 默认：允许直接私信；设置为 "block" 可以禁止
        lightContext: true, // 可选：仅注入工作区引导文件中的 HEARTBEAT.md
        // 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 配置）： 如果存在 HEARTBEAT.md（工作区上下文），请阅读并严格遵循。不要推测或重复之前聊天中的旧任务。如果没有需要关注的事项，回复 HEARTBEAT_OK。
• 心跳提示作为用户消息逐字发送。系统提示包含“Heartbeat”部分，运行时内部会标记。
• 活跃时间（heartbeat.activeHours）在配置的时区检查。窗口外跳过心跳，直到下一个窗口内的时刻。

​

心跳提示的用途

• 后台任务：“考虑未完成任务”促使代理复查待办事项（收件箱、日历、提醒、排队工作），并提示任何紧急事项。
• 人工检查：“白天时偶尔检查你的人工”促使代理偶尔发送轻量的“有什么需要吗？”消息，但通过你的本地时区配置避免夜间骚扰（详见 /concepts/timezone）。

​

回复协议

• 如果没有需要关注的事项，回复 HEARTBEAT_OK。
• 心跳运行时，当 HEARTBEAT_OK 出现在回复的开头或结尾时，OpenClaw 视为确认。该标记会被剥离，如果剩余内容长度 ≤ ackMaxChars（默认 300 字符），则回复丢弃。
• 如果 HEARTBEAT_OK 出现在回复的中间，不会有特殊处理。
• 对于警报消息，不要包含 HEARTBEAT_OK，只返回警报文本。

​

配置示例

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m", // 默认：30 分钟（0m 表示禁用）
        model: "anthropic/claude-opus-4-6",
        includeReasoning: false, // 默认：false（可选启用时会单独发送 Reasoning: 消息）
        lightContext: false, // 默认：false；true 仅保持工作区引导文件中的 HEARTBEAT.md
        target: "last", // 默认：none；选项：last | none | <频道 id>（核心或插件，如 "bluebubbles"）
        to: "+15551234567", // 可选频道特定覆盖
        accountId: "ops-bot", // 可选多账户频道 id
        prompt: "如果存在 HEARTBEAT.md（工作区上下文），请阅读并严格遵循。不要推测或重复之前聊天中的旧任务。如果没有需要关注的事项，回复 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", // 明确推送到最后联系人（默认是 "none"）
      },
    },
    list: [
      { id: "main", default: true },
      {
        id: "ops",
        heartbeat: {
          every: "1h",
          target: "whatsapp",
          to: "+15551234567",
          prompt: "如果存在 HEARTBEAT.md（工作区上下文），请阅读并严格遵循。不要推测或重复之前聊天中的旧任务。如果没有需要关注的事项，回复 HEARTBEAT_OK。",
        },
      },
    ],
  },
}

​

活跃时段示例

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m",
        target: "last", // 明确推送至最后联系人（默认为 "none"）
        activeHours: {
          start: "09:00",
          end: "22:00",
          timezone: "America/New_York", // 可选；使用你的 userTimezone（若已设置），否则使用宿主时区
        },
      },
    },
  },
}

​

24/7 配置

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

​

多账户示例

{
  agents: {
    list: [
      {
        id: "ops",
        heartbeat: {
          every: "1h",
          target: "telegram",
          to: "12345678:topic:42", // 可选：路由到特定主题/线程
          accountId: "ops-bot",
        },
      },
    ],
  },
  channels: {
    telegram: {
      accounts: {
        "ops-bot": { botToken: "YOUR_TELEGRAM_BOT_TOKEN" },
      },
    },
  },
}

​

字段说明

• every：心跳间隔（持续时间字符串；默认单位：分钟）。
• model：心跳运行时的模型覆盖（provider/model 格式）。
• includeReasoning：启用时，当有推理消息时，也会发送单独的 Reasoning: 消息（格式同 /reasoning on）。
• lightContext：为 true 时，心跳运行只使用轻量引导上下文，保留工作区引导文件中的 HEARTBEAT.md。
• session：心跳运行时使用的会话密钥。
  • main（默认）：代理主会话。
  • 显式会话键（从 openclaw sessions --json 或 sessions CLI 复制）。
  • 会话键格式详见 会话 和 群组。
• target：
  • last：发送至最后使用的外部频道。
  • 明确频道：whatsapp / telegram / discord / googlechat / slack / msteams / signal / imessage；
  • none（默认）：运行心跳但不向外部发送消息。
• directPolicy：控制是否允许直接/私信发送：
  • allow（默认）：允许直接/私信发送心跳消息。
  • block：禁止直接私信发送 (reason=dm-blocked)。
• to：可选收件人覆盖（频道特定 ID，例如 WhatsApp 的 E.164 格式，或 Telegram 的聊天 ID）。Telegram 主题/线程格式为 <chatId>:topic:<messageThreadId>。
• accountId：多账户频道的账号 ID。若 target: "last"，账户 ID 适用于解析出的最后一个频道（若支持账户），否则忽略；若账户 ID 不匹配配置账户，则跳过发送。
• prompt：覆盖默认提示内容（不做合并）。
• ackMaxChars：HEARTBEAT_OK 后允许的最大字符数。
• suppressToolErrorWarnings：为 true 时，心跳运行期间抑制工具错误警告负载。
• activeHours：限制心跳仅在指定时间窗口运行。对象含 start（HH:MM，含起始时分，00:00 表示当天开始）、end（HH:MM，排除结束时分，24:00 允许表示当天结束）和可选的 timezone。
  • 省略或 "user"：使用 agents.defaults.userTimezone（若设置），否则使用宿主系统时区。
  • "local"：始终使用宿主系统时区。
  • 任何 IANA 标识符（例如 America/New_York）：直接使用；若无效，则退回上述 "user" 行为。
  • start 和 end 不得相同，否则视作零窗口（总是窗口外）。
  • 窗口外心跳跳过，直到下一窗口内时刻。

​

交付行为

• 心跳默认在代理主会话运行（agent:<id>:<mainKey>），当 session.scope = "global" 时为 global。通过 session 可以切换到特定频道会话（Discord/WhatsApp 等）。
• session 只影响运行上下文；消息发送受 target 和 to 控制。
• 发送至特定频道/收件人需设置 target 和 to。在使用 target: "last" 时，发送到该会话最后一个外部渠道。
• 默认为心跳发送允许直接/私信目标。设置 directPolicy: "block" 可抑制直接私信发送，但仍运行心跳回合。
• 如果主队列繁忙，心跳会跳过并稍后重试。
• 如果 target 无法解析到外部发送目标，仍运行回合但不发送外部消息。
• 仅心跳回复不会延长会话活跃时间；最后的 updatedAt 时间恢复，空闲超时正常生效。

​

可见性控制

channels:
  defaults:
    heartbeat:
      showOk: false # 隐藏 HEARTBEAT_OK（默认）
      showAlerts: true # 显示警报消息（默认）
      useIndicator: true # 发出状态指示事件（默认）
  telegram:
    heartbeat:
      showOk: true # 在 Telegram 上显示确认消息
  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

- 快速检查：收件箱有什么紧急事项吗？
- 如果是白天，且无待办，发送一个轻量检查。
- 如果任务被阻塞，写下_缺少什么_，下次询问 Peter。

​

代理可以更新 HEARTBEAT.md 吗？

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

​

手动触发（按需）

openclaw system event --text "检查紧急跟进" --mode now

​

推理交付（可选）

• agents.defaults.heartbeat.includeReasoning: true

​

成本意识