- `every`: duration string (ms/s/m/h). Default: `30m` (API-key auth) or `1h` (OAuth auth). Set to `0m` to disable.

- `includeSystemPromptSection`: when false, omits the Heartbeat section from the system prompt and skips `HEARTBEAT.md` injection into bootstrap context. Default: `true`.

- `suppressToolErrorWarnings`: when true, suppresses tool error warning payloads during heartbeat runs.

- `timeoutSeconds`: maximum time in seconds allowed for a heartbeat agent turn before it is aborted. Leave unset to use `agents.defaults.timeoutSeconds`.

- `timeoutSeconds`: maximum time in seconds allowed for a heartbeat agent turn before it is aborted. Leave unset to use `agents.defaults.timeoutSeconds` when set, otherwise the heartbeat cadence capped at 600 seconds.

- `directPolicy`: direct/DM delivery policy. `allow` (default) permits direct-target delivery. `block` suppresses direct-target delivery and emits `reason=dm-blocked`.

- `lightContext`: when true, heartbeat runs use lightweight bootstrap context and keep only `HEARTBEAT.md` from workspace bootstrap files.

- `isolatedSession`: when true, each heartbeat runs in a fresh session with no prior conversation history. Same isolation pattern as cron `sessionTarget: "isolated"`. Reduces per-heartbeat token cost from ~100K to ~2-5K tokens.

- Interval: `30m` (or `1h` when Anthropic OAuth/token auth is the detected auth mode, including Claude CLI reuse). Set `agents.defaults.heartbeat.every` or per-agent `agents.list[].heartbeat.every`; use `0m` to disable.

- Prompt body (configurable via `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.`

- Timeout: unset heartbeat turns use `agents.defaults.timeoutSeconds` when set. Otherwise, they use the heartbeat cadence capped at 600 seconds. Set `agents.defaults.heartbeat.timeoutSeconds` or per-agent `agents.list[].heartbeat.timeoutSeconds` for longer heartbeat work.

- The heartbeat prompt is sent **verbatim** as the user message. The system prompt includes a "Heartbeat" section only when heartbeats are enabled for the default agent, and the run is flagged internally.

- When heartbeats are disabled with `0m`, normal runs also omit `HEARTBEAT.md` from bootstrap context so the model does not see heartbeat-only instructions.

- Active hours (`heartbeat.activeHours`) are checked in the configured timezone. Outside the window, heartbeats are skipped until the next tick inside the window.

<ParamField path="suppressToolErrorWarnings" type="boolean">

When true, suppresses tool error warning payloads during heartbeat runs.

</ParamField>

<ParamField path="timeoutSeconds" type="number" default="global timeout or min(every, 600)">

Maximum seconds allowed for a heartbeat agent turn before it is aborted. Leave unset to use `agents.defaults.timeoutSeconds` when set, otherwise the heartbeat cadence capped at 600 seconds.

</ParamField>

<ParamField path="activeHours" type="object">

Restricts heartbeat runs to a time window. Object with `start` (HH:MM, inclusive; use `00:00` for start-of-day), `end` (HH:MM exclusive; `24:00` allowed for end-of-day), and optional `timezone`.

"agents.list[].heartbeat.suppressToolErrorWarnings":

"Suppress tool error warning payloads during heartbeat runs.",

"agents.defaults.heartbeat.timeoutSeconds":

"Maximum time in seconds allowed for a heartbeat agent turn before it is aborted. Leave unset to use agents.defaults.timeoutSeconds.",

"Maximum time in seconds allowed for a heartbeat agent turn before it is aborted. Leave unset to use agents.defaults.timeoutSeconds when set, otherwise the heartbeat cadence capped at 600 seconds.",

"agents.list[].heartbeat.timeoutSeconds":

"Per-agent maximum time in seconds allowed for a heartbeat agent turn before it is aborted. Leave unset to inherit the merged heartbeat/default agent timeout.",

"Per-agent maximum time in seconds allowed for a heartbeat agent turn before it is aborted. Leave unset to inherit the merged heartbeat timeout, then agents.defaults.timeoutSeconds when set, otherwise the heartbeat cadence capped at 600 seconds.",

"agents.defaults.heartbeat.skipWhenBusy":

"When true, defer heartbeat turns on this agent's extra busy lanes: its own session-keyed subagent or nested command work. Cron lanes always defer heartbeat turns.",

"agents.list[].heartbeat.skipWhenBusy":

ackMaxChars?: number;

/** Suppress tool error warning payloads during heartbeat runs. */

suppressToolErrorWarnings?: boolean;

/** Run timeout in seconds for heartbeat agent turns. */

/** Run timeout in seconds for heartbeat agent turns. Unset uses global timeout or heartbeat cadence capped at 600 seconds. */

timeoutSeconds?: number;

/**

* If true, run heartbeat turns with lightweight bootstrap context.

}

async function runDefaultsHeartbeat(params: {

every?: string;

defaultTimeoutSeconds?: number;

model?: string;

suppressToolErrorWarnings?: boolean;

timeoutSeconds?: number;

agents: {

defaults: {

workspace: tmpDir,

timeoutSeconds: params.defaultTimeoutSeconds,

heartbeat: {

every: "5m",

every: params.every ?? "5m",

target: "whatsapp",

model: params.model,

suppressToolErrorWarnings: params.suppressToolErrorWarnings,

});

});

it("uses heartbeat cadence as the default reply-run timeout override", async () => {

const replyOpts = await runDefaultsHeartbeat({});

expectReplyOptions(replyOpts, {

isHeartbeat: true,

timeoutOverrideSeconds: 300,

});

});

it("caps the default heartbeat reply-run timeout override", async () => {

const replyOpts = await runDefaultsHeartbeat({ every: "30m" });

expectReplyOptions(replyOpts, {

isHeartbeat: true,

timeoutOverrideSeconds: 600,

});

});

it("preserves explicit default agent timeout for heartbeat runs", async () => {

const replyOpts = await runDefaultsHeartbeat({ defaultTimeoutSeconds: 60, every: "30m" });

expectReplyOptions(replyOpts, {

isHeartbeat: true,

timeoutOverrideSeconds: 60,

});

});

it("passes bootstrapContextMode when heartbeat lightContext is enabled", async () => {

const replyOpts = await runDefaultsHeartbeat({ lightContext: true });

expectReplyOptions(replyOpts, {

}

const HEARTBEAT_ALWAYS_BUSY_LANES = [CommandLane.Cron, CommandLane.CronNested] as const;

const DEFAULT_HEARTBEAT_TIMEOUT_SECONDS = 10 * 60;

function hasQueuedWorkInLanes(

lanes: readonly string[],

return activePlugin ?? getChannelPlugin(channel as ChannelId);

}

function resolveHeartbeatTimeoutOverrideSeconds(cfg: OpenClawConfig, heartbeat?: HeartbeatConfig) {

if (typeof heartbeat?.timeoutSeconds === "number") {

return heartbeat.timeoutSeconds;

}

const agentDefaultTimeoutSeconds = cfg.agents?.defaults?.timeoutSeconds;

if (

typeof agentDefaultTimeoutSeconds === "number" &&

Number.isFinite(agentDefaultTimeoutSeconds)

) {

return Math.max(1, Math.floor(agentDefaultTimeoutSeconds));

}

// The wake dispatcher awaits heartbeat turns serially. Keep unset heartbeat

// timeouts tied to the cadence instead of the 48h built-in agent default.

const intervalMs = resolveHeartbeatIntervalMs(cfg, undefined, heartbeat);

if (!intervalMs) {

return DEFAULT_HEARTBEAT_TIMEOUT_SECONDS;

}

return Math.max(1, Math.min(DEFAULT_HEARTBEAT_TIMEOUT_SECONDS, Math.ceil(intervalMs / 1000)));

}

export { areHeartbeatsEnabled, setHeartbeatsEnabled };

export {

isHeartbeatEnabledForAgent,

await heartbeatTyping?.onReplyStart();

const heartbeatModelOverride = normalizeOptionalString(heartbeat?.model);

const suppressToolErrorWarnings = heartbeat?.suppressToolErrorWarnings === true;

const timeoutOverrideSeconds =

typeof heartbeat?.timeoutSeconds === "number" ? heartbeat.timeoutSeconds : undefined;

const timeoutOverrideSeconds = resolveHeartbeatTimeoutOverrideSeconds(cfg, heartbeat);

const bootstrapContextMode: "lightweight" | undefined =

heartbeat?.lightContext === true ? "lightweight" : undefined;

const replyOpts = {