跳转至

心跳

Note

心跳是一种自动化。 关于选择系统拥有的监控器还是独立计划的作业,请参阅自动化。

心跳是一种系统拥有的自动化,会在主会话中运行周期性代理回合,让模型能够主动呈现任何需要注意的事项,而不会频繁打扰你。

心跳是一个计划中的主会话回合。ACP 运行、子代理和隔离的自动化作业使用各自的执行所有者。

在底层,心跳节奏由 Automations 调度器拥有:网关为每个启用心跳的代理维护一个系统拥有的自动化作业(在 openclaw cron list --all 中显示为 Heartbeat (agent-id))。心跳配置仍然是期望状态的输入,而持久化的监控器调度负责实际的 tick 以及运行器随后的冷却时间。网关会在启动时和配置重载时将配置更改写入。openclaw doctor --fix 可以在下次网关启动前生成缺失或过期的监控器记录。请编辑 agents.*.heartbeat,而不是自动化作业。如果配置更改被接受后保存监控器记录失败,网关会保留已接受的配置并报告需要恢复。监控器重试使用当前已接受的配置。被拒绝的更改永远不会成为重试目标。

计划心跳需要自动化功能。当 cron.enabled 为 false 或设置了 OPENCLAW_SKIP_CRON=1 时,网关会记录一条启动警告,并且不会运行计划心跳。手动和事件驱动的心跳唤醒仍然可用。没有单独的心跳回退定时器。

将 heartbeat.every 设置为 "0m" 只会禁用循环节奏。定向事件驱动唤醒仍可运行一个代理回合,例如后台 exec 完成。它不会创建或重新启用循环计划。如果希望保留后台 exec 功能,但不希望自动完成回合或其模型调用,请设置 tools.exec.notifyOnExit: false;若要按代理覆盖,请检查 agents.entries.<id>.tools.exec.notifyOnExit。使用 process poll 收集结果。另请参阅后台 exec 通知。工具策略和沙箱控制代理回合是否可以执行命令。

当循环节奏被禁用时,由心跳拥有的事件唤醒仍保持相同的按代理速率限制。这些限制包括:事件回合之间至少间隔 30 秒,以及在 60 秒内启动五次后触发洪泛保护。当保护期结束后,延迟的工作会恢复。配置重载会保留这一统计记录,而不会将代理纳入循环或广播心跳中。

转录标记会将 [OpenClaw heartbeat poll] 与 exec 完成、cron 唤醒或会话事件区分开来。计划轮询使用配置的心跳会话,默认情况下该会话是代理的主会话。定向完成事件会返回到拥有该工作的会话。事件标记会保留其来源出处,而不会将内部指令复制到聊天历史中。静默确认配对保持隐藏。

故障排查:自动化

快速开始(初学者)

1. 选择节奏

保持心跳启用(默认为 30m;当配置了 Anthropic OAuth/token 认证时,包括复用 Claude CLI,默认为 1h),或设置你自己的节奏。

2. 添加监控器暂存区(可选)

使用 openclaw cron scratch <jobId> --set "..." 在心跳监控器的暂存区中存放一个简短的检查清单。

3. 决定心跳消息应发送到哪里

心跳提醒默认发送到操作员的私信。将 commands.ownerAllowFrom 设置为数组,例如 ["telegram:123456789"],或使用具体的频道 allowFrom。仅包含通配符的允许列表无法识别所有者。

4. 可选调优

  • 如果心跳运行只需要监控器暂存区,可使用轻量级 bootstrap 上下文。
  • 启用隔离会话,避免每次心跳都发送完整对话历史。
  • 将心跳限制在活跃时间段(本地时间)内。

示例配置:

{
  commands: {
    ownerAllowFrom: ["telegram:123456789"],
  },
  agents: {
    defaults: {
      heartbeat: {
        every: "30m",
        target: "owner", // default: operator DM from ownerAllowFrom or channel allowFrom
        directPolicy: "allow", // default: allow direct/DM targets; set "block" to suppress
        lightContext: true, // optional: skip workspace bootstrap files for heartbeat runs
        isolatedSession: true, // optional: fresh session each run (no conversation history)
        // activeHours: { start: "08:00", end: "24:00" },
      },
    },
  },
}

对于已配置的 Telegram 机器人,请使用 JSON 数组设置所有者,即使只有一个条目。将 123456789 替换为你的 Telegram 用户 ID,并包含你想保留的任何现有所有者:

openclaw config set commands.ownerAllowFrom '["telegram:123456789"]'

要显式选择接收者,请分别设置频道和接收者:

openclaw config set agents.defaults.heartbeat.to '"123456789"'
openclaw config set agents.defaults.heartbeat.target telegram

请保留数字聊天 ID 周围的内层双引号,这样 to 会以字符串形式存储。heartbeat.target 接受 owner、last、none 或频道 ID(如 telegram);telegram:123456789 应放在 commands.ownerAllowFrom 中,而不是 target 中。

默认值

  • 间隔:30m。在应用 Anthropic 提供程序默认设置时,如果解析后的认证模式为 OAuth/token(包括 Claude CLI 复用),该值会提升为 1h;但仅在 heartbeat.every 未设置时如此。可设置 agents.defaults.heartbeat.every 或按代理设置 agents.entries.*.heartbeat.every。使用 0m 可禁用循环节奏。
  • 投递目标:owner。OpenClaw 会先使用第一条具体的 commands.ownerAllowFrom 条目,然后使用频道 allowFrom,并且绝不会将此路由发送到群组。如果无法解析出所有者的私信,后台轮询会以 reason=no-route 跳过。设置 target: "last" 可跟随最近的对话(包括群组),或设置 target: "none" 以仅进行内部运行。
  • 提示正文(可通过 agents.defaults.heartbeat.prompt 配置):Follow the heartbeat monitor scratch context when provided. Recurring tasks are automations; create or change their schedules with the automations tool, not heartbeat scratch. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply NO_REPLY.
  • 超时:未设置超时时,如果配置了 agents.defaults.timeoutSeconds,心跳回合会使用该值;否则,它们使用心跳节奏,上限为 600 秒。如需更长的心跳工作,可设置 agents.defaults.heartbeat.timeoutSeconds 或按代理设置 agents.entries.*.heartbeat.timeoutSeconds。在后台命令完成、process background-task review、阻塞任务事件以及恢复的重启工作之后恢复执行的回合,使用普通代理超时(默认 48 小时);心跳节奏和超时设置不会缩短这些后续回合。事件必须包含在该回合中;隔离的监控器不会继承其基础会话中待处理工作的预算。
  • 心跳提示会作为计划的用户消息原样发送。心跳运行使用与普通代理回合相同的系统提示。没有专门针对心跳的系统提示部分。
  • 使用 0m 禁用循环心跳时,自动化作业会保留但处于禁用状态。Doctor 在创建或更新该作业时会报告其为已禁用的监控器,而不会将其保留的间隔显示为活动节奏。其监控器暂存区会被保留,供你重新启用节奏时使用。定向事件驱动唤醒仍然可用。
  • 当自动化功能被完全禁用时,即使心跳节奏保持启用,计划心跳也不会运行。
  • 活跃时间段(heartbeat.activeHours)会在配置的时区中检查。在窗口之外,心跳会一直跳过,直到窗口内的下一个 tick。
  • 当主队列或自动化工作处于活动或排队状态、同一代理的任何回复或嵌入运行处于活动状态、或解析后的目标会话有活动或排队的工作时,计划心跳会推迟。尚未开始准备且无事件的普通监控器轮询会被记录为已跳过,并等待下一个持久化节奏 tick,而不会在繁忙工作后面保持运行中的自动化处于打开状态。携带排队事件或计划任务的唤醒,以及已准入或在执行后被保留的工作,仍会重试。即时和手动唤醒会绕过宽泛的同一代理活动运行检查,但仍会遵守主队列、自动化和目标会话的忙碌保护。同级代理之间不会互相暂停。
  • 宿主机后台命令完成使用普通会话执行,并且只等待其自身会话。由心跳拥有的节点完成会保留其现有的忙碌保护和投递恢复保护。

心跳提示词的作用

默认提示词被刻意设计得范围很窄:在提供心跳监控草稿上下文时遵循它,将重复性工作保留在自动化任务中,并在无需处理时回复 NO_REPLY。它明确告诉代理不要从先前聊天中推断或重复旧任务,因此默认安装会保持安静,而不是反复讨论过时的对话上下文。

主动的心跳行为需要显式启用:

  • 重复检查:为收件箱检查、日历扫描或排队中的后续事项创建 自动化。每个任务都会按照自己的计划执行其配置的负载。默认心跳不会从先前聊天中推断重复性工作。
  • 人工检查:如果你希望偶尔收到一条轻量的“有什么需要吗?”消息,请创建一个计划任务,并限制其计划,以避免在你配置的本地时区夜间发送提醒(参见 时区)。

心跳仍会处理节点完成事件。Host exec、CLI watchdog、ACP parent relay、即时 HTTP hooks、重启续接和会话状态通知使用普通会话执行。携带已捕获投递路由的完成事件会返回到该账户、会话和线程;监控器配置的 target、to 或 accountId 无法将其重定向。有意设置的 target: "none"、直接消息限制、通知退出选项以及禁用的心跳控制仍然适用。如果插件规范化会更改已捕获的路由,则会失败关闭。普通计划心跳保留其配置的目标。

由心跳拥有的、具有不同投递路由的节点完成事件会在独立的轮次中运行,包括不同账户或主题。相同的完成文本不会抑制不同的完成事件。

如果由心跳拥有的完成事件无法进入投递,其原始路由事件仍可用于现有的有界唤醒重试。一旦持久化投递队列拥有某次尝试,该队列就拥有传输重试;无关的唤醒不得重新生成其结果。未确认投递所有权的未解决尝试会被保留,不进入模型重放。使用 process poll 收集执行结果,并在手动重发模糊投递之前验证消息是否已到达。这不会改变节点协议协商或旧版通知行为。

如果你希望心跳执行非常具体的操作(例如“检查 Gmail PubSub 统计”或“验证网关健康状态”),请将 agents.defaults.heartbeat.prompt(或 agents.entries.*.heartbeat.prompt)设置为自定义正文(按原文发送)。

即时会话事件

Host 后台命令、CLI watchdog 完成事件、ACP parent notifications、即时 HTTP hook 唤醒、重启续接和会话状态通知会进入普通回复队列。它们保留源会话的历史和已捕获的投递路由,排在该会话现有工作之后,并使用其当前权限。心跳频率、活跃时间、模型和可见性设置不会控制这些事件。源运行的自动投递退出选项仍然有效。

同一 watcher 和同一已捕获投递路由的会话状态通知会收集最多 20 秒,并进入一个协调轮次。该轮次保留每个通知的权限限制,并且只有在被采纳时才确认被监视的会话。如果一个通知在被采纳前被消费,则其余原始通知保留它们自己的协调工作。

每个事件只有一个执行所有者。周期性心跳轮询和传入的用户轮次无法消费正在普通队列中等待的事件。接受确认表示所有者已保留该事件;它并不证明执行或投递已完成。重置或删除目标会话会取消已保留的事件,而不是将其移动到替换会话中。NO_REPLY 结果保持静默。

响应契约

  • 如果无需处理,请回复 NO_REPLY。
  • 心跳运行也可以调用 heartbeat_respond,使用 notify: false 表示不产生可见更新,或使用 notify: true 加上 notificationText 表示告警。如果存在,结构化工具响应优先于文本回退。
  • 带有 notify: false 的有意义 heartbeat_respond 结果保持静默,但会被记住为该会话下一个用户轮次的有界内部上下文。如果生成的 notify: true 告警投递被阻止或未确认,也会被记录,包括其告警文本和投递原因。这是该会话的最新结果,而不是告警历史或精确投递重放队列。no_change 确认和已确认的可见通知不会以这种方式存储。
  • 现有自定义提示词仍可能返回旧版 HEARTBEAT_OK 确认。OpenClaw 会在回复的开头或结尾接受它,并在剩余内容最多为 300 个字符时丢弃该回复。抑制预算是固定的。
  • 位于回复中间的旧版 HEARTBEAT_OK 不会被特殊处理。
  • 对于告警,只返回告警文本。不要包含静默确认。
  • 投递会选择最后一个可外发的非推理负载。单独的推理或思考负载保持内部状态。仅包含推理的结果不会产生告警。
  • 在心跳轮次期间,工具错误警告保持启用。
  • openclaw system heartbeat last --json 会将已确认的、通过消息工具发送给心跳接收方的发送报告为 sent,而不会发送另一个确认。
  • 如果心跳启动了后台工作但没有发送更新,其状态事件会报告 skipped,原因为 background-work。请检查任务是否完成。这不是全部正常的确认。

在心跳之外,消息开头/结尾出现的多余 HEARTBEAT_OK 会被移除并记录日志。如果消息仅包含 HEARTBEAT_OK,则会被丢弃。

配置

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m", // default: 30m (0m disables)
        model: "anthropic/claude-opus-4-6",
        lightContext: false, // default: false; true skips workspace bootstrap files for heartbeat runs
        isolatedSession: false, // default: false; true runs each heartbeat in a fresh session (no conversation history)
        target: "owner", // default | options: last | none | <channel id>
        accountId: "ops-bot", // optional multi-account channel id
        prompt: "Follow the heartbeat monitor scratch context when provided. Recurring tasks are automations; create or change their schedules with the automations tool, not heartbeat scratch. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply NO_REPLY.",
      },
    },
  },
}

范围与优先级

  • agents.defaults.heartbeat 设置全局心跳行为。
  • agents.entries.*.heartbeat 在其上合并。如果任何代理具有 heartbeat 块,只有这些代理会运行心跳。
  • 环境归属通过 agents.defaults.heartbeat.agentId、agents.defaults.systemAgent.agentId,然后唯一代理解析。当没有按代理或默认心跳块适用,并且该链使多代理名册无所有者时,心跳保持禁用并发出验证和 Gateway 警告。
  • channels.defaults.heartbeatVisibility 为所有渠道设置可见性默认值。
  • channels.<channel>.heartbeatVisibility 覆盖渠道默认值。
  • channels.<channel>.accounts.<id>.heartbeatVisibility(多账户渠道)覆盖按渠道设置。

按代理的心跳

如果任何 agents.entries.* 条目包含 heartbeat 块,只有这些代理会运行心跳。按代理的块会合并到 agents.defaults.heartbeat 之上(因此你可以一次性设置共享默认值,并按代理覆盖)。

示例:两个代理,只有第二个代理运行心跳。

{
  agents: {
    ownership: "explicit",
    defaults: {
      systemAgent: { agentId: "main" },
      heartbeat: {
        every: "30m",
        target: "owner", // default: operator DM
      },
    },
    entries: {
      main: { workspace: "~/.openclaw/workspace" },
      ops: {
        heartbeat: {
          every: "1h",
          target: "whatsapp",
          to: "+15551234567",
          timeoutSeconds: 45,
          prompt: "Follow the heartbeat monitor scratch context when provided. Recurring tasks are automations; create or change their schedules with the automations tool, not heartbeat scratch. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply NO_REPLY.",
        },
      },
    },
  },
  talk: { agentId: "main" },
}

活跃时间示例

将心跳限制在特定时区的营业时间内:

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m",
        target: "owner", // default: operator DM
        activeHours: {
          start: "09:00",
          end: "22:00",
          timezone: "America/New_York", // optional; uses your userTimezone if set, otherwise host tz
        },
      },
    },
  },
}

在此窗口之外(东部时间上午 9 点之前或晚上 10 点之后),心跳会被跳过。窗口内下一次计划触发将正常运行。

全天候设置

如果你希望心跳全天运行,请使用以下模式之一:

  • 完全省略 activeHours(没有时间窗口限制,这是默认行为)。
  • 设置全天窗口:activeHours: { start: "00:00", end: "24:00" }。

Warning

不要将 start 和 end 设置为相同时间(例如 08:00 到 08:00)。这会被视为零宽度窗口,因此心跳始终被跳过。

多账户示例

使用 accountId 来定位 Telegram 等多账户渠道上的特定账户:

{
  agents: {
    entries: {
      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" },
      },
    },
  },
}

字段说明

every string (path)
心跳间隔(时长字符串,默认单位为分钟)。
model string (path)
心跳运行的可选模型覆盖(provider/model)。
lightContext boolean (path) 默认:false
为 true 时,心跳运行使用轻量级引导上下文,并跳过工作区引导文件。无论如何,监控草稿都会由心跳运行器注入。会话自身的后台命令完成会保留该会话的完整上下文。
isolatedSession boolean (path) 默认:false
为 true 时,每次心跳都在一个全新的会话中运行,没有先前对话历史。使用与 sessionTarget: "isolated" 自动化任务相同的隔离模式。可大幅降低每次心跳的 Token 成本。与 lightContext: true 结合可获得最大节省。投递路由和会话上下文仍遵循所选会话,包括其渠道、账户和主题。如果该会话之后移动,后台命令的完成会保留其原始事件路由。它不会借用新房间的描述或激活策略。会话自身的后台命令完成不会被隔离;参见 会话与目标路由。
session string (path)

心跳运行的可选会话键。

  • main(默认):代理主会话。
  • 显式会话键(从 openclaw sessions --json 或 sessions CLI 复制)。
  • 会话键格式:参见 Sessions 和 Groups。
target string (path)
  • owner(默认):投递到从 commands.ownerAllowFrom 解析出的第一个可解析操作员 DM,然后是渠道 allowFrom。此路由永远不会解析到群组或渠道。
  • last:显式遵循最后使用的外部会话,包括群组和渠道。
  • 显式渠道:任何已配置的渠道或插件 id,例如 discord、matrix、telegram 或 whatsapp。
  • none:仅为内部状态运行心跳。不要将其投递到外部。

对于显式 Telegram 接收者,使用 target: "telegram" 和 to: "123456789"。 target 字段不接受渠道和接收者组合值,例如 "telegram:123456789"。

directPolicy "allow" | "block" (path) 默认:allow
控制直接/DM 投递行为。allow:允许直接/DM 心跳投递。block:抑制直接/DM 投递(reason=dm-blocked)。
to string (path)
显式渠道目标的接收者(例如,WhatsApp 的 E.164 或 Telegram 聊天 id)。owner 和未设置的目标会忽略 to。对于 Telegram 主题/线程,使用 <chatId>:topic:<messageThreadId>。
accountId string (path)
多账户通道的可选账户 ID。当 target: "last" 时,如果解析出的最后通道支持账户,则账户 ID 应用于该最后通道。否则会被忽略。如果账户 ID 与解析出的通道中已配置的账户不匹配,则跳过投递。
prompt string (path)
覆盖默认提示词正文(不会合并)。
timeoutSeconds number (path) 默认值:global timeout or min(every, 600)
心跳代理回合在被中止前允许的最大秒数。留空时,如果已设置 agents.defaults.timeoutSeconds,则使用它;否则使用上限为 600 秒的心跳周期。 Exec-completion、后台任务以及恢复后的重启续接使用普通代理超时,包括显式将 agents.defaults.timeoutSeconds 设为 0 表示无超时。
activeHours object (path)

将心跳运行限制在时间窗口内。对象包含 start(HH:MM,包含,00:00 表示当天开始)、end(HH:MM 不包含,允许 24:00 表示当天结束),以及可选的 timezone。

  • 省略或 "user":如果已设置 agents.defaults.userTimezone,则使用它;否则回退到主机系统时区。
  • "local":始终使用主机系统时区。
  • 任何 IANA 标识符(例如 America/New_York):直接使用该值。如果无效,则回退到上述 "user" 行为。
  • 对于活动窗口,start 和 end 不得相等。相等的值被视为零宽度(始终在窗口外)。
  • 在活动窗口外,心跳会被跳过,直到窗口内的下一个 tick。

Note

心跳配置是严格的:只接受上面列出的字段。确认抑制、推理可见性、系统提示词指导、忙碌延迟以及工具错误警告行为是固定的运行时策略,而不是心跳配置字段。

投递行为

会话与目标路由
  • 心跳默认在代理的主会话中运行(agent:<id>:main),当 session.scope = "global" 时为 global。设置 session 可覆盖为特定通道会话(Discord/WhatsApp 等)。
  • session 只影响运行上下文。投递由 target 和 to 控制,会话拥有的事件除外(见下文)。
  • 如果心跳拥有的节点完成所捕获的路由仍是其会话自身的对话(例如代理启动命令所在的 Telegram 话题),则会继续该对话。它会在该会话中带着完整上下文运行,忽略 isolatedSession 和 lightContext,并且回复会发送到该对话,无论 target、to、directPolicy 以及通道 heartbeatVisibility 如何设置。在该完成回合中启动的命令属于同一对话。这些完成不会等待下一个心跳间隔,但事件回合之间仍至少间隔 30 秒,且每分钟最多 5 次。当结果不值得报告时,模型仍保持沉默。OpenClaw 自身在该回合发出的通知,例如运行失败通知、工具失败警告、状态行或截断标签,仍遵循心跳的 target、isolatedSession 和 showAlerts 设置,因此 target: "none" 或 showAlerts: false 会将它们排除在聊天之外,同时模型的回复仍会投递。这些设置继续控制定期轮询和心跳拥有的工作。没有此类路由的完成,例如来自 delivery: "none" 的自动化,仍遵循 target/to。要关闭完成回合,请设置 tools.exec.notifyOnExit: false。
  • 如果心跳唤醒的待处理事件全部是内部会话中的会话拥有的节点完成(Control UI/WebChat,或另一个没有外部路由的操作员拥有会话),则回复会发布到该会话的记录中,而不是 target/to 通道。target: "none" 仍会抑制它。如果会话写入失败,事件会保留在队列中等待后续唤醒,并且不会回退到通道。同时包含其他事件的批次仍按常规使用 target/to。
  • 默认 owner 目标会选择显式配置的 owner 身份。只有当会话的最后路由是到该 owner 的直接聊天时,才会复用确切的账户/线程。
  • 携带通道和接收者的唤醒会在 owner 发现之前使用该指定来源。由于该事件目标是显式指定的而非推断的,因此可以是群组。
  • 要投递到特定通道/接收者,请设置通道 target 以及 to。target: "last" 是显式选择最后的外部对话,包括群组。
  • 心跳投递默认允许直接/DM 目标。设置 directPolicy: "block" 可抑制直接目标发送,同时仍运行心跳回合。
  • 当主队列或自动化工作繁忙、同一代理的任何回复或嵌入运行处于活动状态,或解析出的目标会话存在活动或排队工作时,计划心跳会跳过。尚未开始准备的无事件普通监控轮询会等待下一个持久化周期 tick。排队事件、计划任务以及执行后已被接纳或保留的工作会保留其重试。即时唤醒和手动唤醒仅绕过宽泛的同一代理活动运行预检查。
  • 如果 owner 没有具体的、支持 DM 的 owner 或已配置通道,轮询会在代理运行前以 reason=no-route 跳过。显式 last 在会话没有外部路由时也会跳过。
  • 由隐式 owner 默认值投递的第一个警报会解释定期检查以及如何选择 target: "none"。后续警报会省略该行。
可见性与跳过行为
  • 如果心跳回合在模型能够回复之前失败,只要 OpenClaw 自身拒绝了运行,失败通知就会指明原因。一个例子是会话运行时在另一个 runner 中仍然繁忙。原始 provider 或运行时错误仍受详细失败详情设置(/verbose on 或 /verbose full)控制,与普通聊天相同。
  • 如果 showOk、showAlerts 和 useIndicator 全部禁用,运行会提前以 reason=alerts-disabled 跳过。
  • 如果仅禁用警报投递,OpenClaw 仍可以运行心跳、更新到期任务时间戳、恢复会话空闲时间戳,并抑制向外的警报负载。
  • 如果通道就绪检查阻止了警报,OpenClaw 会记录未投递。它会在 1 分钟宽限期后重试心跳,而不消耗其周期槽位。此重试会再次运行心跳。它不会重放之前完全相同的警报。一旦发送进入持久投递队列,该队列负责传输重试。
  • 如果解析出的心跳目标支持 typing,OpenClaw 会在心跳运行活动期间显示 typing。它使用心跳本应发送聊天输出的同一目标,并可通过 typingMode: "never" 禁用。
会话生命周期与审计
  • 仅心跳的回复不会保持会话存活。心跳元数据可能会更新会话行,但空闲过期使用来自最后一条真实用户/渠道消息的 lastInteractionAt,而每日过期使用 sessionStartedAt。
  • 控制 UI 和 WebChat 历史会隐藏心跳 Prompt 和仅 OK 的确认。底层会话记录仍可能包含这些回合,用于审计/重放。
  • 主机后台执行通过普通会话执行来恢复。由心跳拥有的节点通知和延迟钩子继续使用心跳队列。

可见性控制

默认情况下,静默的心跳确认会被抑制,而警报内容会被发送。你可以按渠道或按账户调整此设置:

{
  channels: {
    defaults: {
      heartbeatVisibility: {
        showOk: false, // Hide HEARTBEAT_OK (default)
        showAlerts: true, // Show alert messages (default)
        useIndicator: true, // Emit indicator events (default)
      },
    },
    telegram: {
      heartbeatVisibility: {
        showOk: true, // Show OK acknowledgments on Telegram
      },
    },
    whatsapp: {
      accounts: {
        work: {
          heartbeatVisibility: {
            showAlerts: false, // Suppress alert delivery for this account
          },
        },
      },
    },
  },
}

优先级:按账户 → 按渠道 → 渠道默认值 → 内置默认值。

每个标志的作用

  • showOk:当模型返回仅 OK 的回复时,发送 HEARTBEAT_OK 确认。
  • showAlerts:当模型返回非 OK 回复时,发送警报内容。
  • useIndicator:为 UI 状态界面发出指示器事件。

如果三者均为 false,OpenClaw 将完全跳过心跳运行(不调用模型)。

按渠道与按账户示例

{
  channels: {
    defaults: {
      heartbeatVisibility: {
        showOk: false,
        showAlerts: true,
        useIndicator: true,
      },
    },
    slack: {
      heartbeatVisibility: {
        showOk: true, // all Slack accounts
      },
      accounts: {
        ops: {
          heartbeatVisibility: {
            showAlerts: false, // suppress alerts for the ops account only
          },
        },
      },
    },
    telegram: {
      heartbeatVisibility: {
        showOk: true,
      },
    },
  },
}

常见模式

目标 配置
默认行为(静默 OK,启用警报) (无需配置)
完全静默(无消息、无指示器) channels.defaults.heartbeatVisibility: { showOk: false, showAlerts: false, useIndicator: false }
仅指示器(无消息) channels.defaults.heartbeatVisibility: { showOk: false, showAlerts: false, useIndicator: true }
仅在一个渠道显示 OK channels.telegram.heartbeatVisibility: { showOk: true }

监控草稿(可选)

每个心跳自动化任务都拥有一个私有的监控草稿,存储在共享状态数据库中。可以把它看作你的“心跳检查清单”:小巧、稳定,并且适合每 30 分钟检查一次。当草稿存在时,其内容会被追加到心跳 Prompt 中。

使用自动化 CLI 管理它(任务 id 来自 openclaw cron list --all):

openclaw cron scratch <jobId>                 # print the current scratch
openclaw cron scratch <jobId> --set "..."     # replace it with exact text
openclaw cron scratch <jobId> --file notes.md # replace it from a file (- for stdin)
openclaw cron scratch <jobId> --unset         # remove it

写入受比较并交换(compare-and-swap)保护:传入 --expected-revision <n> 可在并发编辑时失败,而不是覆盖。草稿上限为 256 KiB,并且不会出现在 cron list/cron runs 输出中。

代理也可以更新自己的草稿:在心跳回合中,heartbeat_respond 接受一个可选的 scratch 字符串,它会完全替换监控器未来心跳使用的草稿。

Note

正在从 HEARTBEAT.md 或仅配置周期迁移吗? 运行 openclaw doctor --fix。Doctor 会先从 agents.*.heartbeat 创建或更新系统拥有的监控行。然后它将每个代理的工作区 HEARTBEAT.md 导入监控草稿。它会将任何有效的旧版 tasks: 条目转换为自动化任务。它会将原始文件归档到状态目录(backups/heartbeat-migration/)下并删除该文件。运行时心跳指令仅来自数据库草稿。运行时从不读取 HEARTBEAT.md。

如果工作区和状态目录位于不同的文件系统上,Doctor 会将原始文件保留在位于其原位置旁边的私有 HEARTBEAT.md.doctor-archived.* 目录中。状态目录中的备份仍为不可变快照。通过已打开的文件描述符进行的后续写入仍可在工作区归档中恢复。

当草稿存在但实质为空时,OpenClaw 会跳过心跳运行以节省 API 调用。实质为空意味着仅包含空行、Markdown 或 HTML 注释、如 # Heading 的 Markdown 标题、围栏标记,或空清单占位项。该跳过会报告为 reason=empty-heartbeat-file。没有到期任务的计划间隔监控会在因繁忙的执行队列而延迟之前解决此跳过。如果不存在草稿,心跳仍会运行,并由模型决定要做什么。

保持它非常小(简短的检查清单或提醒),以避免 Prompt 膨胀。

草稿示例:

# 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.

使用自动化安排定期检查

Monitor scratch 是 Prompt 上下文,而不是调度器。将每个定期检查创建为一个自动化任务,使其拥有自己的执行频率、启用/禁用状态和运行历史。当检查需要使用正常对话上下文时,自动化任务仍可以指向主会话。

旧版 scratch 可能包含结构化的 tasks: 块。升级后运行一次 openclaw doctor --fix:Doctor 会将每个有效条目转换为独立调度的自动化任务。它会保留每个条目的间隔和之前的上次运行时间。它会移除已弃用的块,并保留周围的 scratch 文本。运行时心跳轮次不会将 tasks: 文本解析为调度。

Doctor 创建的心跳任务作业会保留心跳的活跃时段、冷却、洪泛和忙碌保护。同时到期的作业可以合并为一个心跳轮次。活跃时段之外的触发会被跳过,并在其下一个计划触发时间重试。

智能体可以更新其 scratch 吗?

可以。在心跳轮次期间,智能体可以向 heartbeat_respond 传递一个 scratch 值,以完全替换未来心跳使用的 monitor scratch。你也可以在普通聊天中要求它运行 openclaw cron scratch <jobId> --set ...,或者使用相同命令自行编辑 scratch。请使用自动化来管理重复调度,而不是将调度语法写入 scratch。

Warning

不要将机密信息(API 密钥、电话号码、私有 Token)放入 monitor scratch——它会成为 Prompt 上下文的一部分。

手动唤醒(按需)

使用 openclaw system event 入队一个系统事件,并可选地触发立即心跳:

openclaw system event --text "Check for urgent follow-ups" --mode now
标志 说明
--text <text> 系统事件文本(必填)。
--mode <mode> now 立即运行心跳;next-heartbeat(默认)等待下一个计划 tick。
--session-key <sessionKey> 将事件定向到特定会话;默认为智能体的主会话。
--json 输出 JSON。

如果未提供 --session-key,并且多个智能体配置了 heartbeat,则 --mode now 会立即运行这些智能体各自的心跳。

广播完成状态会报告某个智能体失败,即使另一个智能体成功或被静默跳过。忙碌重试和受保护延迟会保持其现有重试行为。

同一 CLI 组中的相关心跳控制:

openclaw system heartbeat last     # show the last heartbeat event
openclaw system heartbeat enable   # enable heartbeats
openclaw system heartbeat disable  # disable heartbeats

成本意识

心跳会运行完整的智能体轮次。间隔越短,消耗的 Token 越多。为降低成本:

  • 使用 isolatedSession: true 以避免发送完整对话历史(每次运行从约 100K Token 降至约 2-5K)。
  • 使用 lightContext: true 以在心跳运行中跳过工作区引导文件。
  • 设置更便宜的 model(例如 ollama/llama3.2:1b)。
  • 保持 monitor scratch 精简。
  • 如果只需要内部状态更新,请显式设置 target: "none"。

心跳后的上下文溢出

心跳在运行完成后会保留共享会话现有的运行时模型。因此,将某个会话切换到较小本地模型的心跳可能会使该模型保留到下一个主会话轮次。一个具有 32k 窗口的 Ollama 模型就是一个例子。下一个轮次可能会报告上下文溢出。如果会话的最后运行时模型也与配置的 heartbeat.model 匹配,OpenClaw 的恢复消息会将心跳模型泄漏列为可能原因。该消息还会建议修复方法。

为避免此问题,请使用 isolatedSession: true 在全新会话中运行心跳。你可以将其与 lightContext: true 组合以获得最小的 Prompt。否则,请选择一个上下文窗口足够容纳共享会话的心跳模型。

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw