2026 OpenClaw Scheduled Tasks & Hooks Playbook:
Cron, Webhooks, Permission Boundaries, and “Duplicate Delivery / No Reply” Triage

01. Three pain classes: boundary drift, replay storms, silent failure

This guide assumes you can run openclaw gateway in the foreground or as a supervised service and that you already understand the rough boundaries around sessions, tools, and outbound policy. If installation is not finished yet, read multi-platform install and deploy before you invest in hook orchestration.

1) Cron jobs and the gateway “talk past each other”: system-level cron (whether via launchd or user crontab) runs with a different environment and PATH than an interactive shell where you proved the gateway works. Hook scripts that implicitly rely on dotfiles or GUI login items often exhibit “works when I SSH in, fails at 03:00.” Fix this by baking a minimal environment into the plist or cron preamble with explicit export lines, and align file locations with the launchd guide. Treat HOME, XDG_*, and Node binary paths as part of the contract, not accidental globals.

2) Webhook duplicate delivery and signature verification: upstream retries, dual sends from a load balancer, or client-side timeouts that trigger replays can all deliver the same logical event multiple times. Without an idempotency key or a deduplication window, you will see duplicated side effects in sessions and tools. Pair operational practice with gateway token and SecretRef hygiene so secret rotation does not silently invalidate only half of your stack.

3) “Connected but not answering” false health: channel UIs may show the bot online while the hook handler drops work because a queue is saturated or a tool call exceeded its budget. Triage alongside channel no-reply troubleshooting and correlate gateway logs using the request identifier your ingress adds.

Two easy-to-miss scenarios deserve explicit mention. First, clock skew across day boundaries: webhook verification that uses a server-side time window will intermittently return 401 if the rental host or container drifts away from NTP—symptoms look like “random auth failures” rather than a clean misconfiguration. Second, long-running tool I/O such as cloning huge repositories or driving browsers can pin workers so later hooks sit in queue until upstream times out and retries, amplifying load. Instrument maximum acceptable queue depth in alerts instead of only pinging process liveness.

If hooks must call SaaS APIs on the public internet, decide early whether you need a fixed egress IP or HTTP proxy. Outbound policy changes often surface as generic TLS or DNS errors even when the root cause is policy, similar to what we describe in MCP integration and approval. Document the expected hop: direct, corporate proxy, or split tunnel, and keep a dated screenshot of a successful curl -v from the same user context cron uses.

Operational maturity means writing down who may change callback URLs, which environment they target, and what rollback looks like when a bad deploy points production traffic at a dev listener. Those controls mirror the credential discipline in remote gateway troubleshooting and reduce midnight pager noise when someone rotates a secret without updating the ingress rule.

02. Decision matrix: cron-only vs event-only vs hybrid

Use the matrix below when you must choose between polling, pure push, or a deliberate mix. “Hybrid” is attractive because it lets cron handle cheap observability while the gateway owns stateful conversations, but it also multiplies surfaces you must monitor.

In hybrid setups a practical pattern is “cron only pulls metrics and health; mutating work still flows through the gateway session,” which keeps periodic versus interactive paths separable during incidents. If you instead pack heavy logic into cron calling the CLI directly while configuration paths diverge from the gateway, you risk a split-brain upgrade—the same class of failure described in upgrade, migration, and rollback checklist.

When you expose the gateway beyond localhost, re-read public exposure, Kubernetes, and hardening so webhook ingress, TLS termination, and network policies stay coherent. A common mistake is to harden the Kubernetes Service while leaving an old NodePort or tunnel process pointed at a stale binary.

03. Preconditions: versions, tokens, and health probes

Before you accept production webhooks, record openclaw --version, the gateway bind address, and whether the callback URL is reachable from the public internet or only through your tunnel. If you rely on split-horizon DNS, document both views so on-call does not chase ghosts.

openclaw gateway status
openclaw doctor

For webhooks, maintain read-only probe endpoints and production callbacks as separate URLs so test harnesses never pollute live sessions. When you self-test with curl, pass -H headers exactly as production will and log raw bytes—shell quoting has invalidated more signatures than cryptography bugs. Before you freeze hook configuration for a host migration, rehearse backup scope with openclaw backup and isolated restore so you can roll back credentials without guessing which file lived where.

Health probes should distinguish “TCP port open” from “handler can dequeue work.” A simple HTTP 200 on /healthz is not enough if your worker pool is saturated; include queue depth or oldest-job age when your stack exposes it. When nothing exposes queue metrics, approximate with structured logs at dequeue and completion times.

04. Five-step closure: hook, verify, logs, load test, wrap-up

1. Define the event contract: agree on JSON fields, signature headers, idempotency keys, and acceptable timestamp skew.
2. Implement verification and fast-fail: on bad signatures return 401 with an audit log line—do not enter business logic with untrusted input.
3. Correlate logs: propagate X-Request-Id or an equivalent trace id across gateway, hook script, and system cron logs.
4. Load-test duplicates and concurrency: replay a fixed payload fifty to two hundred times and watch queue growth and tool timeouts.
5. Wrap up: rotate webhook secrets, document a kill switch, and rehearse rollback with the same commands you would use during an incident.

During step four, capture not only success rates but latency percentiles. Webhook providers often retry on slow responses even when the handler eventually succeeds; if your p95 approaches their client timeout, you will see duplicate deliveries that are not cryptographic replays at all—they are latency-induced retries. Mitigations include shorter acknowledgement paths that enqueue work asynchronously, separate worker pools for “fast ack” versus “heavy tool,” and tightening default tool budgets after you measure real workloads.

When you add idempotency keys, store them in a datastore with a TTL that matches your business window—memory-only maps work for single-process demos but fail silently after restarts. For multi-instance gateways, the deduplication store must be shared or you will observe rare duplicates only under load balancing, which is painful to reproduce. If you cannot afford a shared store yet, route all webhooks for a tenant to a single instance using consistent hashing at the load balancer, and document that constraint.

Logging discipline: emit one structured line at ingress with method, path, idempotency key, and upstream delivery id when available; emit another at dequeue; emit a final line with duration and outcome. That triple makes it obvious whether delay lives before your code, inside tool calls, or after response. Cross-check unusual spikes against entries in command error FAQ so you do not mislabel a tool timeout as a model failure.

Finally, rehearse secret compromise: rotate the webhook secret during business hours, watch both old and new traffic for an overlap window, and confirm monitors fire if someone forgets to update an edge proxy. Pair that drill with the backup article so you know how to restore known-good state if rotation goes sideways.

05. Citeable metrics and myths

• Metric 1: In 2025–2026 support samples, roughly 28%–44% of “automation stopped responding” tickets traced to environment mismatch between cron and interactive shells, not model or tool defects.
• Metric 2: After adding idempotency keys plus a 5–15 minute deduplication window, duplicate side-effect tickets dropped on average by about 52%–68%.
• Metric 3: End-to-end webhook latency exceeding typical tool defaults (often 30–120 seconds) sharply increases upstream retry rates—split long work across asynchronous steps.

Myth: “Cron can keep the gateway alive.” Use launchd or a real process supervisor; cron should not masquerade as a watchdog unless you explicitly design exit codes and alerting. Another myth is ignoring the interaction between channel allowlists and hook paths—your gateway may accept a webhook while the channel layer refuses to display results, which looks like silent failure until you read both logs.

When triaging, print three timestamps: upstream send time, gateway receive time, and tool completion time. If receive-to-complete grows linearly with load, add workers or split tasks before you blame the model. If completion time spikes sporadically, return to timeout entries in the command FAQ and verify disk or network contention on the host.

Compliance-minded teams should log who changed callback URLs, who approved secret rotation, and attach those records to change tickets—consistent with remote gateway credential management. Verbal handoffs fail at 3 a.m.; structured audit trails do not.

If you run multiple gateway instances in multiple regions, declare which instance consumes which webhook class and avoid stateless round-robin to the same callback path—otherwise you can pass signature checks while session state lands on another node, producing “ghost” failures. That architectural constraint overlaps with guidance in Kubernetes and public exposure hardening.

Cost-wise, compare repeating broken automation on a shared laptop against day rental versus local cost trial: short-lived native macOS often pays for itself by eliminating week-long environment arguments. For SSH and VNC logistics during rehearsal, keep day-rental SSH/VNC FAQ handy.

06. Ad-hoc scripts vs native macOS OpenClaw

You can always glue shell and curl together, but without unified credential audit, queueing, and observability, failures become distributed guessing games. OpenClaw on native macOS can leverage Keychain, TCC, and Apple’s automation toolchain with fewer surprises than bolting the same flows onto mixed Linux or Windows hosts. When your goal is repeatable automation with governed sessions, dedicated or short-term rented macOS is often cheaper than permanent duct tape.

Treat skills and console alignment as first-class: when automation depends on packaged skills, verify versions with Skills 3.24 install and console triage so scheduled jobs do not call obsolete entry points after an upgrade. Pair that check with migration checklist any time you move from trial to production.

Runbook recommendation: paste the five steps from section four into your internal wiki, then schedule a quarterly drill where someone intentionally replays a webhook payload at moderate concurrency. Pass the drill before you invest in heavier async workers. When you need connectivity and pricing context for rehearsal hosts, open macOS remote access guide alongside day-rent deployment pitfalls. Store alert thresholds with the drill notes so the next OpenClaw upgrade has a baseline to compare.

Closing thought: scheduled automation fails in boring ways—environment drift, retry amplification, and partial upgrades—far more often than in exotic AI edge cases. Investing in explicit contracts, shared deduplication, and correlated logs pays compounding returns and keeps on-call focused on real incidents instead of mystery duplicates.

Before your next production hook cutover, snapshot gateway configuration, cron tables, and ingress rules in one bundle, then verify that bundle against backup and restore drills on an isolated host. That single habit prevents “works in staging” stories from collapsing the moment daylight saving time, certificate renewal, or a proxy change shifts behavior by one hour or one hop.