Skip to content

LeoYeAI/agent-master-skills / skills/bengii-gemini-fix

openclaw

Flagged

Comprehensive guide for installing, configuring, operating, and troubleshooting OpenClaw — a self-hosted, multi-channel AI agent gateway. Use when the user asks about OpenClaw setup, configuration, channel management (WhatsApp/Telegram/Discord/Slack/iMessage/etc.), model provider setup, Gateway operations, multi-agent routing, security hardening, troubleshooting, or any maintenance task related to their local OpenClaw installation. Also use when encountering errors from `openclaw` CLI commands or the Gateway daemon.

FileKindSize
README.mdmarkdown7.5 KB
README_CN.mdmarkdown7.3 KB
SKILL.mdskill md18.7 KB
_meta.jsonconfig286 B
references/acp_agents.mdmarkdown12.6 KB
references/agent_runtime.mdmarkdown5.6 KB
references/architecture.mdmarkdown3.8 KB
references/automation.mdmarkdown5.8 KB
references/bonjour.mdmarkdown3.3 KB
references/browser.mdmarkdown8.5 KB
references/channel_routing.mdmarkdown4.0 KB
references/channel_troubleshooting.mdmarkdown11.6 KB
references/channels.mdmarkdown6.2 KB
references/clawhub.mdmarkdown3.6 KB
references/config_reference.mdmarkdown11.2 KB
references/diffs_firecrawl.mdmarkdown3.3 KB
references/elevated.mdmarkdown2.8 KB
references/exec.mdmarkdown6.5 KB
references/exec_approvals.mdmarkdown3.1 KB
references/gateway_internals.mdmarkdown7.7 KB
references/gateway_ops.mdmarkdown9.6 KB
references/heartbeat.mdmarkdown4.9 KB
references/hooks.mdmarkdown14.6 KB
references/install.mdmarkdown4.1 KB
references/llm_task.mdmarkdown2.6 KB
references/lobster.mdmarkdown7.8 KB
references/media.mdmarkdown4.2 KB
references/memory.mdmarkdown11.9 KB
references/model_failover.mdmarkdown3.1 KB
references/multi_agent.mdmarkdown4.4 KB
references/nodes.mdmarkdown8.8 KB
references/openprose.mdmarkdown2.6 KB
references/pairing.mdmarkdown3.1 KB
references/pdf_tool.mdmarkdown3.5 KB
references/platforms.mdmarkdown2.7 KB
references/plugins.mdmarkdown6.9 KB
references/polls.mdmarkdown2.2 KB
references/presence_discovery.mdmarkdown2.2 KB
references/providers.mdmarkdown6.0 KB
references/queue.mdmarkdown2.1 KB
references/remote_access.mdmarkdown4.7 KB
references/sandboxing.mdmarkdown5.6 KB
references/secrets.mdmarkdown5.4 KB
references/security.mdmarkdown24.5 KB
references/sessions.mdmarkdown8.9 KB
references/skills.mdmarkdown4.4 KB
references/slash_commands.mdmarkdown5.1 KB
references/streaming.mdmarkdown1.8 KB
references/subagents.mdmarkdown12.3 KB
references/thinking.mdmarkdown2.8 KB
references/tools.mdmarkdown13.3 KB
references/tui.mdmarkdown4.0 KB
references/voice.mdmarkdown2.7 KB
references/web_tools.mdmarkdown2.7 KB
references/web_ui.mdmarkdown4.5 KB

references/heartbeat.md

View on GitHub
# Heartbeat Reference

> Source: https://docs.openclaw.ai/gateway/heartbeat

## Overview

Heartbeat is a recurring, agent-driven background task. The Gateway fires a heartbeat prompt at a configurable interval, letting the agent check for pending work, follow up on tasks, or send health check-ins.

## Quick Start

1. Leave heartbeats enabled (default: `30m`, or `1h` for Anthropic OAuth/setup-token).
2. Create a `HEARTBEAT.md` checklist in the agent workspace (optional but recommended).
3. Set `target: "last"` to route heartbeat replies to the last contact (default: `"none"` — no delivery).
4. Optional: enable reasoning delivery for transparency.
5. Optional: use `lightContext: true` for minimal bootstrap context.
6. Optional: restrict to active hours (local time).

## Config

```json5
{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m",                    // default: 30m (0m disables)
        model: "anthropic/claude-opus-4-6",
        includeReasoning: false,         // deliver separate Reasoning: message
        lightContext: false,             // true: only HEARTBEAT.md from bootstrap
        target: "last",                  // none | last | <channel id>
        to: "+15551234567",              // optional channel-specific override
        accountId: "ops-bot",            // optional multi-account channel id
        directPolicy: "allow",          // "allow" (default) or "block"
        prompt: "Read HEARTBEAT.md if it exists...",
        ackMaxChars: 300,                // max chars after HEARTBEAT_OK
        // activeHours: { start: "08:00", end: "24:00" },
      },
    },
  },
}
```

### Defaults
- **Interval**: `30m` (or `1h` for Anthropic OAuth). 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."
- **Active hours** (`heartbeat.activeHours`) checked in configured timezone. Outside window, heartbeats are skipped.

## Response Contract

- If nothing needs attention: reply with `HEARTBEAT_OK`.
- Gateway treats `HEARTBEAT_OK` as an ack when it appears at start/end of reply. Token is stripped; reply dropped if remaining content ≤ `ackMaxChars` (default: 300).
- If `HEARTBEAT_OK` appears mid-reply, not treated specially.
- For alerts: do **not** include `HEARTBEAT_OK`; return only alert text.

## Delivery Behavior

- Heartbeats run in agent's main session by default (`agent:<id>:<mainKey>`), or `global` when `session.scope = "global"`.
- `session` affects run context; delivery is controlled by `target` and `to`.
- With `target: "last"`: delivery goes to last external channel for that session.
- `directPolicy: "block"` suppresses direct-target sends while still running heartbeat turn.
- If main queue is busy: heartbeat is skipped and retried later.
- Heartbeat-only replies **do not** keep session alive; `updatedAt` is restored so idle expiry behaves normally.

## Visibility Controls

```yaml
channels:
  defaults:
    heartbeat:
      showOk: false       # Hide HEARTBEAT_OK (default)
      showAlerts: true     # Show alert messages (default)
      useIndicator: true   # Emit indicator events (default)
  telegram:
    heartbeat:
      showOk: true         # Show OK acks on Telegram
  whatsapp:
    accounts:
      work:
        heartbeat:
          showAlerts: false # Suppress alerts for this account
```

### What Each Flag Does
| Flag | Default | Behavior |
|---|---|---|
| `showOk` | `false` | Whether to deliver `HEARTBEAT_OK` acks to the channel |
| `showAlerts` | `true` | Whether to deliver alert messages |
| `useIndicator` | `true` | Emit heartbeat indicator events |

## Per-Agent Heartbeats

Override per agent via `agents.list[].heartbeat`:
```json5
{
  agents: {
    list: [
      {
        id: "ops",
        heartbeat: {
          every: "15m",
          target: "last",
          prompt: "Check server metrics and alert if anything is critical.",
        },
      },
    ],
  },
}
```

## HEARTBEAT.md (Optional)

Create `HEARTBEAT.md` in the agent workspace with a checklist:
```markdown
## Tasks
- [ ] Check unread emails
- [ ] Review calendar for today
- [ ] Check monitoring dashboard
```

The agent can update `HEARTBEAT.md` itself (e.g., checking off tasks) if the workspace is writable.

## Manual Wake (On-Demand)

```bash
openclaw system heartbeat now           # Trigger immediately
openclaw system heartbeat last          # Show last heartbeat info
```

## Cost Awareness

Each heartbeat is a full agent run (system prompt + HEARTBEAT.md + user prompt). With `lightContext: true`, only `HEARTBEAT.md` is included from bootstrap files, reducing token cost significantly.

## See Also

- [automation.md](automation.md) — Cron jobs (scheduled triggers)
- [sessions.md](sessions.md) — Session lifecycle and idle expiry
- [agent_runtime.md](agent_runtime.md) — Agent loop and hooks
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall