Script + Heartbeat

[ionic needle]

Hello, I have a script that must complete its full execution before every heartbeat. (Runtime: approx. 2 minutes.) Immediately thereafter, the heartbeat must trigger. This process is intended to run once per hour. I haven't found a direct solution yet; what is the best way to implement this?

[sly ore]

To help others find answers, you can mark your question as solved via Right click solution message -> Apps -> ✅ Mark Solution

[burnt urchin]

Best pattern: don’t try to make the built-in heartbeat interval do the orchestration. Make your script the thing that owns the hourly schedule, then wake OpenClaw immediately after the script exits successfully.

So the flow is:

#!/usr/bin/env bash
set -euo pipefail

/path/to/your-script.sh

curl -X POST http://127.0.0.1:18789/hooks/wake \
  -H "Authorization: Bearer $OPENCLAW_HOOK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"text":"Hourly script finished successfully; run the heartbeat check now.","mode":"now"}'

Then schedule that wrapper hourly with systemd timer/cron. This guarantees ordering: script finishes → wake event fires → main session runs right away.

In OpenClaw, enable hooks with a dedicated token, e.g.:

{
  hooks: {
    enabled: true,
    token: "shared-secret",
    path: "/hooks",
  },
  agents: {
    defaults: {
      heartbeat: {
        every: "0m" // optional: disable regular interval heartbeats if this wrapper is the only trigger
      }
    }
  }