forked from Selig/openclaw-skill
Selig
4c966a3ad2
6 custom skills (assign-task, dispatch-webhook, daily-briefing, task-capture, qmd-brain, tts-voice) with technical documentation. Compatible with Claude Code, OpenClaw, Codex CLI, and OpenCode.
109 lines
17 KiB
JSON
Executable File
109 lines
17 KiB
JSON
Executable File
{
|
||
"title": "Heartbeat (Gateway)",
|
||
"content": "> **Heartbeat vs Cron?** See [Cron vs Heartbeat](/automation/cron-vs-heartbeat) for guidance on when to use each.\n\nHeartbeat runs **periodic agent turns** in the main session so the model can\nsurface anything that needs attention without spamming you.\n\n## Quick start (beginner)\n\n1. Leave heartbeats enabled (default is `30m`, or `1h` for Anthropic OAuth/setup-token) or set your own cadence.\n2. Create a tiny `HEARTBEAT.md` checklist in the agent workspace (optional but recommended).\n3. Decide where heartbeat messages should go (`target: \"last\"` is the default).\n4. Optional: enable heartbeat reasoning delivery for transparency.\n5. Optional: restrict heartbeats to active hours (local time).\n\n* Interval: `30m` (or `1h` when Anthropic OAuth/setup-token is the detected auth mode). Set `agents.defaults.heartbeat.every` or per-agent `agents.list[].heartbeat.every`; use `0m` to disable.\n* Prompt body (configurable via `agents.defaults.heartbeat.prompt`):\n `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.`\n* The heartbeat prompt is sent **verbatim** as the user message. The system\n prompt includes a “Heartbeat” section and the run is flagged internally.\n* Active hours (`heartbeat.activeHours`) are checked in the configured timezone.\n Outside the window, heartbeats are skipped until the next tick inside the window.\n\n## What the heartbeat prompt is for\n\nThe default prompt is intentionally broad:\n\n* **Background tasks**: “Consider outstanding tasks” nudges the agent to review\n follow-ups (inbox, calendar, reminders, queued work) and surface anything urgent.\n* **Human check-in**: “Checkup sometimes on your human during day time” nudges an\n occasional lightweight “anything you need?” message, but avoids night-time spam\n by using your configured local timezone (see [/concepts/timezone](/concepts/timezone)).\n\nIf you want a heartbeat to do something very specific (e.g. “check Gmail PubSub\nstats” or “verify gateway health”), set `agents.defaults.heartbeat.prompt` (or\n`agents.list[].heartbeat.prompt`) to a custom body (sent verbatim).\n\n* If nothing needs attention, reply with **`HEARTBEAT_OK`**.\n* During heartbeat runs, OpenClaw treats `HEARTBEAT_OK` as an ack when it appears\n at the **start or end** of the reply. The token is stripped and the reply is\n dropped if the remaining content is **≤ `ackMaxChars`** (default: 300).\n* If `HEARTBEAT_OK` appears in the **middle** of a reply, it is not treated\n specially.\n* For alerts, **do not** include `HEARTBEAT_OK`; return only the alert text.\n\nOutside heartbeats, stray `HEARTBEAT_OK` at the start/end of a message is stripped\nand logged; a message that is only `HEARTBEAT_OK` is dropped.\n\n### Scope and precedence\n\n* `agents.defaults.heartbeat` sets global heartbeat behavior.\n* `agents.list[].heartbeat` merges on top; if any agent has a `heartbeat` block, **only those agents** run heartbeats.\n* `channels.defaults.heartbeat` sets visibility defaults for all channels.\n* `channels.<channel>.heartbeat` overrides channel defaults.\n* `channels.<channel>.accounts.<id>.heartbeat` (multi-account channels) overrides per-channel settings.\n\n### Per-agent heartbeats\n\nIf any `agents.list[]` entry includes a `heartbeat` block, **only those agents**\nrun heartbeats. The per-agent block merges on top of `agents.defaults.heartbeat`\n(so you can set shared defaults once and override per agent).\n\nExample: two agents, only the second agent runs heartbeats.\n\n### Multi account example\n\nUse `accountId` to target a specific account on multi-account channels like Telegram:\n\n* `every`: heartbeat interval (duration string; default unit = minutes).\n* `model`: optional model override for heartbeat runs (`provider/model`).\n* `includeReasoning`: when enabled, also deliver the separate `Reasoning:` message when available (same shape as `/reasoning on`).\n* `session`: optional session key for heartbeat runs.\n * `main` (default): agent main session.\n * Explicit session key (copy from `openclaw sessions --json` or the [sessions CLI](/cli/sessions)).\n * Session key formats: see [Sessions](/concepts/session) and [Groups](/concepts/groups).\n* `target`:\n * `last` (default): deliver to the last used external channel.\n * explicit channel: `whatsapp` / `telegram` / `discord` / `googlechat` / `slack` / `msteams` / `signal` / `imessage`.\n * `none`: run the heartbeat but **do not deliver** externally.\n* `to`: optional recipient override (channel-specific id, e.g. E.164 for WhatsApp or a Telegram chat id).\n* `accountId`: optional account id for multi-account channels. When `target: \"last\"`, the account id applies to the resolved last channel if it supports accounts; otherwise it is ignored. If the account id does not match a configured account for the resolved channel, delivery is skipped.\n* `prompt`: overrides the default prompt body (not merged).\n* `ackMaxChars`: max chars allowed after `HEARTBEAT_OK` before delivery.\n\n* Heartbeats run in the agent’s main session by default (`agent:<id>:<mainKey>`),\n or `global` when `session.scope = \"global\"`. Set `session` to override to a\n specific channel session (Discord/WhatsApp/etc.).\n* `session` only affects the run context; delivery is controlled by `target` and `to`.\n* To deliver to a specific channel/recipient, set `target` + `to`. With\n `target: \"last\"`, delivery uses the last external channel for that session.\n* If the main queue is busy, the heartbeat is skipped and retried later.\n* If `target` resolves to no external destination, the run still happens but no\n outbound message is sent.\n* Heartbeat-only replies do **not** keep the session alive; the last `updatedAt`\n is restored so idle expiry behaves normally.\n\n## Visibility controls\n\nBy default, `HEARTBEAT_OK` acknowledgments are suppressed while alert content is\ndelivered. You can adjust this per channel or per account:\n\nPrecedence: per-account → per-channel → channel defaults → built-in defaults.\n\n### What each flag does\n\n* `showOk`: sends a `HEARTBEAT_OK` acknowledgment when the model returns an OK-only reply.\n* `showAlerts`: sends the alert content when the model returns a non-OK reply.\n* `useIndicator`: emits indicator events for UI status surfaces.\n\nIf **all three** are false, OpenClaw skips the heartbeat run entirely (no model call).\n\n### Per-channel vs per-account examples\n\n| Goal | Config |\n| ---------------------------------------- | ---------------------------------------------------------------------------------------- |\n| Default behavior (silent OKs, alerts on) | *(no config needed)* |\n| Fully silent (no messages, no indicator) | `channels.defaults.heartbeat: { showOk: false, showAlerts: false, useIndicator: false }` |\n| Indicator-only (no messages) | `channels.defaults.heartbeat: { showOk: false, showAlerts: false, useIndicator: true }` |\n| OKs in one channel only | `channels.telegram.heartbeat: { showOk: true }` |\n\n## HEARTBEAT.md (optional)\n\nIf a `HEARTBEAT.md` file exists in the workspace, the default prompt tells the\nagent to read it. Think of it as your “heartbeat checklist”: small, stable, and\nsafe to include every 30 minutes.\n\nIf `HEARTBEAT.md` exists but is effectively empty (only blank lines and markdown\nheaders like `# Heading`), OpenClaw skips the heartbeat run to save API calls.\nIf the file is missing, the heartbeat still runs and the model decides what to do.\n\nKeep it tiny (short checklist or reminders) to avoid prompt bloat.\n\nExample `HEARTBEAT.md`:",
|
||
"code_samples": [
|
||
{
|
||
"code": "## Defaults\n\n* Interval: `30m` (or `1h` when Anthropic OAuth/setup-token is the detected auth mode). Set `agents.defaults.heartbeat.every` or per-agent `agents.list[].heartbeat.every`; use `0m` to disable.\n* Prompt body (configurable via `agents.defaults.heartbeat.prompt`):\n `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.`\n* The heartbeat prompt is sent **verbatim** as the user message. The system\n prompt includes a “Heartbeat” section and the run is flagged internally.\n* Active hours (`heartbeat.activeHours`) are checked in the configured timezone.\n Outside the window, heartbeats are skipped until the next tick inside the window.\n\n## What the heartbeat prompt is for\n\nThe default prompt is intentionally broad:\n\n* **Background tasks**: “Consider outstanding tasks” nudges the agent to review\n follow-ups (inbox, calendar, reminders, queued work) and surface anything urgent.\n* **Human check-in**: “Checkup sometimes on your human during day time” nudges an\n occasional lightweight “anything you need?” message, but avoids night-time spam\n by using your configured local timezone (see [/concepts/timezone](/concepts/timezone)).\n\nIf you want a heartbeat to do something very specific (e.g. “check Gmail PubSub\nstats” or “verify gateway health”), set `agents.defaults.heartbeat.prompt` (or\n`agents.list[].heartbeat.prompt`) to a custom body (sent verbatim).\n\n## Response contract\n\n* If nothing needs attention, reply with **`HEARTBEAT_OK`**.\n* During heartbeat runs, OpenClaw treats `HEARTBEAT_OK` as an ack when it appears\n at the **start or end** of the reply. The token is stripped and the reply is\n dropped if the remaining content is **≤ `ackMaxChars`** (default: 300).\n* If `HEARTBEAT_OK` appears in the **middle** of a reply, it is not treated\n specially.\n* For alerts, **do not** include `HEARTBEAT_OK`; return only the alert text.\n\nOutside heartbeats, stray `HEARTBEAT_OK` at the start/end of a message is stripped\nand logged; a message that is only `HEARTBEAT_OK` is dropped.\n\n## Config",
|
||
"language": "unknown"
|
||
},
|
||
{
|
||
"code": "### Scope and precedence\n\n* `agents.defaults.heartbeat` sets global heartbeat behavior.\n* `agents.list[].heartbeat` merges on top; if any agent has a `heartbeat` block, **only those agents** run heartbeats.\n* `channels.defaults.heartbeat` sets visibility defaults for all channels.\n* `channels.<channel>.heartbeat` overrides channel defaults.\n* `channels.<channel>.accounts.<id>.heartbeat` (multi-account channels) overrides per-channel settings.\n\n### Per-agent heartbeats\n\nIf any `agents.list[]` entry includes a `heartbeat` block, **only those agents**\nrun heartbeats. The per-agent block merges on top of `agents.defaults.heartbeat`\n(so you can set shared defaults once and override per agent).\n\nExample: two agents, only the second agent runs heartbeats.",
|
||
"language": "unknown"
|
||
},
|
||
{
|
||
"code": "### Multi account example\n\nUse `accountId` to target a specific account on multi-account channels like Telegram:",
|
||
"language": "unknown"
|
||
},
|
||
{
|
||
"code": "### Field notes\n\n* `every`: heartbeat interval (duration string; default unit = minutes).\n* `model`: optional model override for heartbeat runs (`provider/model`).\n* `includeReasoning`: when enabled, also deliver the separate `Reasoning:` message when available (same shape as `/reasoning on`).\n* `session`: optional session key for heartbeat runs.\n * `main` (default): agent main session.\n * Explicit session key (copy from `openclaw sessions --json` or the [sessions CLI](/cli/sessions)).\n * Session key formats: see [Sessions](/concepts/session) and [Groups](/concepts/groups).\n* `target`:\n * `last` (default): deliver to the last used external channel.\n * explicit channel: `whatsapp` / `telegram` / `discord` / `googlechat` / `slack` / `msteams` / `signal` / `imessage`.\n * `none`: run the heartbeat but **do not deliver** externally.\n* `to`: optional recipient override (channel-specific id, e.g. E.164 for WhatsApp or a Telegram chat id).\n* `accountId`: optional account id for multi-account channels. When `target: \"last\"`, the account id applies to the resolved last channel if it supports accounts; otherwise it is ignored. If the account id does not match a configured account for the resolved channel, delivery is skipped.\n* `prompt`: overrides the default prompt body (not merged).\n* `ackMaxChars`: max chars allowed after `HEARTBEAT_OK` before delivery.\n\n## Delivery behavior\n\n* Heartbeats run in the agent’s main session by default (`agent:<id>:<mainKey>`),\n or `global` when `session.scope = \"global\"`. Set `session` to override to a\n specific channel session (Discord/WhatsApp/etc.).\n* `session` only affects the run context; delivery is controlled by `target` and `to`.\n* To deliver to a specific channel/recipient, set `target` + `to`. With\n `target: \"last\"`, delivery uses the last external channel for that session.\n* If the main queue is busy, the heartbeat is skipped and retried later.\n* If `target` resolves to no external destination, the run still happens but no\n outbound message is sent.\n* Heartbeat-only replies do **not** keep the session alive; the last `updatedAt`\n is restored so idle expiry behaves normally.\n\n## Visibility controls\n\nBy default, `HEARTBEAT_OK` acknowledgments are suppressed while alert content is\ndelivered. You can adjust this per channel or per account:",
|
||
"language": "unknown"
|
||
},
|
||
{
|
||
"code": "Precedence: per-account → per-channel → channel defaults → built-in defaults.\n\n### What each flag does\n\n* `showOk`: sends a `HEARTBEAT_OK` acknowledgment when the model returns an OK-only reply.\n* `showAlerts`: sends the alert content when the model returns a non-OK reply.\n* `useIndicator`: emits indicator events for UI status surfaces.\n\nIf **all three** are false, OpenClaw skips the heartbeat run entirely (no model call).\n\n### Per-channel vs per-account examples",
|
||
"language": "unknown"
|
||
},
|
||
{
|
||
"code": "### Common patterns\n\n| Goal | Config |\n| ---------------------------------------- | ---------------------------------------------------------------------------------------- |\n| Default behavior (silent OKs, alerts on) | *(no config needed)* |\n| Fully silent (no messages, no indicator) | `channels.defaults.heartbeat: { showOk: false, showAlerts: false, useIndicator: false }` |\n| Indicator-only (no messages) | `channels.defaults.heartbeat: { showOk: false, showAlerts: false, useIndicator: true }` |\n| OKs in one channel only | `channels.telegram.heartbeat: { showOk: true }` |\n\n## HEARTBEAT.md (optional)\n\nIf a `HEARTBEAT.md` file exists in the workspace, the default prompt tells the\nagent to read it. Think of it as your “heartbeat checklist”: small, stable, and\nsafe to include every 30 minutes.\n\nIf `HEARTBEAT.md` exists but is effectively empty (only blank lines and markdown\nheaders like `# Heading`), OpenClaw skips the heartbeat run to save API calls.\nIf the file is missing, the heartbeat still runs and the model decides what to do.\n\nKeep it tiny (short checklist or reminders) to avoid prompt bloat.\n\nExample `HEARTBEAT.md`:",
|
||
"language": "unknown"
|
||
}
|
||
],
|
||
"headings": [
|
||
{
|
||
"level": "h2",
|
||
"text": "Quick start (beginner)",
|
||
"id": "quick-start-(beginner)"
|
||
},
|
||
{
|
||
"level": "h2",
|
||
"text": "Defaults",
|
||
"id": "defaults"
|
||
},
|
||
{
|
||
"level": "h2",
|
||
"text": "What the heartbeat prompt is for",
|
||
"id": "what-the-heartbeat-prompt-is-for"
|
||
},
|
||
{
|
||
"level": "h2",
|
||
"text": "Response contract",
|
||
"id": "response-contract"
|
||
},
|
||
{
|
||
"level": "h2",
|
||
"text": "Config",
|
||
"id": "config"
|
||
},
|
||
{
|
||
"level": "h3",
|
||
"text": "Scope and precedence",
|
||
"id": "scope-and-precedence"
|
||
},
|
||
{
|
||
"level": "h3",
|
||
"text": "Per-agent heartbeats",
|
||
"id": "per-agent-heartbeats"
|
||
},
|
||
{
|
||
"level": "h3",
|
||
"text": "Multi account example",
|
||
"id": "multi-account-example"
|
||
},
|
||
{
|
||
"level": "h3",
|
||
"text": "Field notes",
|
||
"id": "field-notes"
|
||
},
|
||
{
|
||
"level": "h2",
|
||
"text": "Delivery behavior",
|
||
"id": "delivery-behavior"
|
||
},
|
||
{
|
||
"level": "h2",
|
||
"text": "Visibility controls",
|
||
"id": "visibility-controls"
|
||
},
|
||
{
|
||
"level": "h3",
|
||
"text": "What each flag does",
|
||
"id": "what-each-flag-does"
|
||
},
|
||
{
|
||
"level": "h3",
|
||
"text": "Per-channel vs per-account examples",
|
||
"id": "per-channel-vs-per-account-examples"
|
||
},
|
||
{
|
||
"level": "h3",
|
||
"text": "Common patterns",
|
||
"id": "common-patterns"
|
||
},
|
||
{
|
||
"level": "h2",
|
||
"text": "HEARTBEAT.md (optional)",
|
||
"id": "heartbeat.md-(optional)"
|
||
}
|
||
],
|
||
"url": "llms-txt#heartbeat-(gateway)",
|
||
"links": []
|
||
} |