心跳（网关）

## 默认设置

- 间隔：`30m`（当检测到 Anthropic OAuth/setup-token 认证模式时为 `1h`）。设置 `agents.defaults.heartbeat.every` 或每个代理的 `agents.list[].heartbeat.every`；使用 `0m` 来禁用。
- 心跳提示内容（可通过 `agents.defaults.heartbeat.prompt` 配置）：
  `如果存在 HEARTBEAT.md（工作区上下文），请阅读它。严格遵循提示。不要推断或重复之前的聊天中的旧任务。如果没有需要关注的内容，请回复 HEARTBEAT_OK。`
- 心跳提示内容会**原样**作为用户消息发送。系统提示中包含一个“心跳”部分，并且该运行会在内部被标记。

- 活动时段（`heartbeat.activeHours`）会在配置的时区中进行检查。在时段外时，心跳会被跳过，直到下一个在时段内的时间点。

## 心跳提示的用途

默认提示是故意设计得比较宽泛的：
- **后台任务**：“考虑未完成的任务”会提示代理检查跟进事项（收件箱、日历、提醒、排队任务），并突出显示任何紧急事项。
- **人工检查**：“在白天有时检查你的用户”会提示代理偶尔发送一个轻量级的“你有什么需要吗？”消息，但通过使用你配置的本地时区避免夜间骚扰（参见 [/concepts/timezone](/concepts/timezone)）。

如果你希望心跳执行非常特定的任务（例如“检查 Gmail PubSub 统计”或“验证网关健康”），请将 `agents.defaults.heartbeat.prompt`（或 `agents.list[].heartbeat.prompt`）设置为自定义内容（原样发送）。

## 响应协议

- 如果没有需要关注的内容，请回复 **`HEARTBEAT_OK`**。
- 在心跳运行期间，Clawdbot 会将 `HEARTBEAT_OK` 视为确认信号，当它出现在回复的**开头或结尾**时。如果剩余内容**≤ `ackMaxChars`**（默认：300），则会移除该标记并丢弃回复。
- 如果 `HEARTBEAT_OK` 出现在回复的**中间**，则不会被特殊处理。
- 对于警报信息，**不要**包含 `HEARTBEAT_OK`；只返回警报文本。

在非心跳时段，如果消息的开头或结尾出现了多余的 `HEARTBEAT_OK`，则会被移除并记录；如果消息仅包含 `HEARTBEAT_OK`，则会被丢弃。```json5
{
  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` 设置全局的心跳行为。
- `agents.list[].heartbeat` 会在其上合并；如果任何代理有 `heartbeat` 块，**只有这些代理** 会运行心跳。
- `channels.defaults.heartbeat` 为所有频道设置默认可见性。
- `channels.<channel>.heartbeat` 覆盖频道的默认设置。
- `channels.<channel>.accounts.<id>.heartbeat`（多账号频道）覆盖频道级别的设置。

### 每个代理的心跳

如果任何 `agents.list[]` 条目包含 `heartbeat` 块，**只有这些代理** 会运行心跳。每个代理的块会合并到 `agents.defaults.heartbeat` 上（因此你可以统一设置共享默认值，并根据需要逐个代理进行覆盖）。

示例：两个代理，只有第二个代理运行心跳。
json5
{
  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."
        }
      }
    ]
  }
}

优先级：按账户 → 按频道 → 频道默认 → 内置默认。

### 每个标志的作用

- `showOk`：当模型返回仅 OK 的回复时，发送 `HEARTBEAT_OK` 确认消息。
- `showAlerts`：当模型返回非 OK 的回复时，发送警报内容。
- `useIndicator`：为 UI 状态面板发出指示器事件。

如果 **全部三个** 都为 false，Clawdbot 将完全跳过心跳检测（不调用模型）。

### 按频道与按账户的示例
yaml
channels:
  defaults:
    heartbeat:
      showOk: false
      showAlerts: true
      useIndicator: true
  slack:
    heartbeat:
      showOk: true # 所有 Slack 账户
    accounts:
      ops:
        heartbeat:
          showAlerts: false # 仅对 ops 账户抑制警报
  telegram:
    heartbeat:
      showOk: true