心跳（网关）

心跳 vs Cron？ 何时用哪个见 Cron vs 心跳。

心跳在主会话中运行周期性代理轮次，使模型能呈现需关注事项而不刷屏。

快速开始（入门）

1. 保持心跳启用（默认 30m，Anthropic OAuth/setup-token 为 1h）或自定义节奏。
2. 在代理工作区创建简短的 HEARTBEAT.md 清单（可选但推荐）。
3. 决定心跳消息发往何处（默认 target: "last"）。
4. 可选：启用心跳推理投递以透明化。
5. 可选：将心跳限制在活跃时段（本地时间）。

示例配置：agents.defaults.heartbeat: { every: "30m", target: "last" }。

默认值

• 间隔：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）在配置的时区下检查；窗口外跳过心跳直至窗口内下一拍。

响应约定

• 若无事项需关注，回复 HEARTBEAT_OK。
• 心跳运行期间，当 HEARTBEAT_OK 出现在回复开头或结尾时，Moltbot 将其视为确认；若剩余内容 ≤ ackMaxChars（默认 300）则剥离该 token 并丢弃回复。
• 若 HEARTBEAT_OK 出现在回复中间则不特殊处理。
• 告警时不要包含 HEARTBEAT_OK；仅返回告警文本。

作用域与优先级

• agents.defaults.heartbeat 设置全局心跳行为。
• agents.list[].heartbeat 在其上合并；若任一代理有 heartbeat 块，仅这些代理运行心跳。
• channels.defaults.heartbeat 设置所有频道的可见性默认。
• channels.<channel>.heartbeat 覆盖频道默认。
• channels.<channel>.accounts.<id>.heartbeat（多账户频道）覆盖每频道设置。

投递行为、可见性控制

心跳默认在代理主会话中运行（agent:<id>:<mainKey>），或当 session.scope = "global" 时为 global。投递由 target 与 to 控制。target: "last" 时投递到该会话最后使用的外部频道。若主队列忙则跳过心跳并稍后重试。仅心跳的回复不会保持会话活跃。可见性：showOk、showAlerts、useIndicator。优先级：每账户 → 每频道 → 频道默认 → 内置默认。完整配置字段与示例见英文文档。参见 时区。