When an OpenClaw cron job has outgrown the clock

May 2, 2026 · Evidence checked September 13, 2026

A cron job can be correct and still be the wrong interface for the work. If an OpenClaw job checks a build system every fifteen minutes, the schedule is doing two jobs: waking the agent and discovering whether anything happened. Once the build system knows that a build finished, the clock is only an indirect way to receive that fact.

That does not mean every recurring job should become a webhook. An inbound event changes the authentication boundary, retry behavior, payload contract, session choice, and failure investigation. The useful question is not whether webhooks sound faster. It is whether the event source owns a fact that OpenClaw is currently trying to discover by polling.

The site already has a basic trigger comparison covering heartbeat, cron, and webhook. This guide takes the next step: what evidence justifies changing an existing cron job, how to migrate in stages, and why a small reconciliation schedule often deserves to stay.

The short answer is this. Keep cron when the work is due because of a clock. Consider an event-driven redesign when another system knows the event first, lateness matters, most scheduled runs find nothing, and each event can be identified and safely retried. Keep a low-frequency cron check when missing an event would be worse than processing it late.

The current OpenClaw documentation calls these scheduled jobs Automations and keeps openclaw cron as a command alias. The examples below use the familiar cron spelling. They are documentation-derived examples and proposed checks, not a report of commands run against a live Gateway.

The first question is who owns the clock

OpenClaw uses the word webhook for two different directions. An automation can send its finished output to an external webhook. That changes delivery, not the reason the job runs. An inbound Gateway hook lets an external service call OpenClaw to wake an agent or submit an agent turn. The inbound webhook reference describes the second case, while the CLI reference documents outbound webhook delivery for scheduled jobs.

That distinction matters during migration. A cron job that runs at 09:00 and posts its result to another service is still clock-owned. A build provider calling OpenClaw after a completed build is event-owned. The first can remain a perfectly good cron design even if its output travels over HTTP.

This table is a decision heuristic, not an OpenClaw API contract. The documentation supplies the scheduler and hook behavior. The migration thresholds are operational judgments that you should test against the workload.

Signals that justify the change

The useful fact exists before the next tick

Suppose a cron job runs every fifteen minutes and a completed build should be investigated within one minute. Even with a healthy Gateway, a clock-based design can wait almost a full interval before it notices the build. Reducing the interval to one minute may improve response time, but it also makes the agent ask the same question many more times.

This is simple timing arithmetic, not a benchmark. Measure the actual arrival pattern and the acceptable delay first. If a ten-minute delay is fine, a webhook may add integration work without solving a real problem. If a minute matters, the source that already knows the build ended is a better trigger owner.

Most scheduled runs are empty polls

OpenClaw's scheduler persists jobs and wakes the agent for recurring work, according to the automation guide. If the prompt then asks an agent to check a queue that is empty most of the time, the job spends its run budget discovering that there is nothing to do.

Do not turn that observation into an invented cost calculation. Record the no-op rate, run duration, provider usage, and Gateway load for the current job. A high empty-run rate is evidence for a redesign only when the source can provide a reliable event and the event path can be constrained. Otherwise, a deterministic command job or a slower cron interval may be enough.

Retry safety now depends on an event identifier

A polling job can often work from a timestamp or a cursor. That becomes fragile when records are updated out of order, a cursor is reset, or a retry reads the same item again. An event path needs a stable identifier such as build-7841, plus a rule for what happens when that identifier arrives twice.

OpenClaw's direct agent hook accepts an Idempotency-Key. Its documentation says that a retried request with the same key and payload can replay the admitted run and completion result without dispatching the agent again. That protects the hook admission path. It does not make every external side effect exactly once. A message sent by a tool, a ticket update, or a deployment action still needs its own idempotency decision.

A missed event is more damaging than a late report

Cron is often valuable because it can rediscover state. If a provider never sends a notification, the next poll may still find the failed build. A pure webhook path loses that safety net unless the sender supports replay or another system keeps an event log.

This is the strongest reason to keep a hybrid design. Let the webhook handle the fast path, then let a low-frequency cron job look for events that have no recorded outcome. The reconciliation job should be explicit about whether it may act, notify, or only create an operator review item. It should not silently run the same side effect that the event path may already have completed.

The sender can be a narrow, trustworthy caller

OpenClaw's generic HTTP hooks are disabled by default. The documented setup uses a dedicated hook token, an allowlist for effective agent IDs, and a dedicated path. The hook configuration reference also makes an important distinction: a hook token grants ingress access but does not make the payload trustworthy.

Keep the endpoint behind loopback, a tailnet, or a trusted reverse proxy while proving the flow. Do not let a caller choose arbitrary session keys unless the use case requires it. Treat event content as data and restrict the target agent's tools and workspace separately. If the sender cannot be authenticated or its payload cannot be validated, keep the poller or put a small adapter in front of the hook.

Bursts and ordering now matter

A cron job samples the source at a known pace. An event stream can arrive in a burst. OpenClaw's hook documentation says isolated requests use fresh run sessions by default, while requests sharing a fixed logical session key are serialized. Reusing a persistent key can therefore preserve ordering, but it can also make a later request wait while an earlier run is active.

Choose the session policy from the workflow rather than from habit. Independent build events usually fit isolated runs. A sequence that genuinely needs shared context may need a stable key, a bounded queue, and a rule for what happens when admission times out. If you cannot explain the ordering behavior on paper, the cron job may still be easier to operate.

When cron is still the right answer

Keep the cron trigger when the request starts with a time: a weekday report, a monthly cleanup review, or a reminder at a local hour. OpenClaw's schedule documentation supports one-shot times, fixed intervals, and cron expressions, with explicit timezone handling for calendar rules. A top-of-hour expression may be staggered unless you request exact timing. See the schedule reference before changing a production expression.

Cron is also the safer default when the source has no dependable push mechanism, the data can be rediscovered, or a missed notification is acceptable. You may be able to reduce waste by using a deterministic command payload rather than an agent turn. The current CLI documentation describes command jobs, isolated sessions, run history, and the separate delivery modes.

Do not migrate solely because a webhook removes a timer. A timer is often the clearest ownership model for work that is actually time-based.

A worked migration: CI build failures

Imagine a job named build-failure-digest. Every fifteen minutes it asks the CI provider for failed builds since the last check, asks OpenClaw to summarize them, and posts a message. It has three weaknesses: the response can be late, the agent runs when there is no new failure, and the cursor can be difficult to reconcile after an outage.

The event version starts with a provider notification such as build.completed. A small adapter verifies the provider's signature if one exists, checks that the payload contains the expected build identifier and status, records the event identifier in a durable inbox, and forwards only the normalized fields to OpenClaw. The verification and inbox are proposed integration components, not features claimed by the generic OpenClaw hook.

The adapter can submit a restricted isolated agent request with the build identifier in both the message and the idempotency key. A documentation-shaped smoke test would look like this:

curl --include http://127.0.0.1:18789/hooks/agent -H 'Authorization: Bearer <long-random-hook-token>' -H 'Content-Type: application/json' -H 'Idempotency-Key: build-7841' --data '{"message":"Summarize the completed CI build 7841. Do not change files or rerun the build.","name":"CI build event 7841","agentId":"main","deliver":false}'

The documented HTTP 200 response means that the run was admitted. It does not prove that the model finished, a tool succeeded, or a message was delivered. Add waitForCompletion: true only when the sender needs bounded terminal execution and delivery facts in the same response. For the production flow, keep a nightly reconciliation cron that finds completed builds without a recorded terminal outcome.

Migrate with a reversible cutover

1. Inventory the current job. Record its schedule, timezone, session mode, prompt, tools, side effects, delivery route, and recent run history. The documented troubleshooting ladder starts with status, scheduler status, job listing, run history, logs, and Doctor; use that sequence to establish a baseline.

2. Write the event contract. Define the event identifier, event type, source, occurrence time, resource identifier, payload version, and allowed side effects. Decide where processed identifiers live and how long they remain useful. This is your integration contract, not an OpenClaw setting.

3. Add the ingress boundary. Enable hooks with a dedicated token, restrict the agent allowlist, keep caller-selected session keys disabled unless required, validate the configuration, restart the Gateway, and watch logs. The official hook walkthrough documents this setup.

4. Run a harmless shadow test. Use a synthetic event, an isolated session, and deliver: false. Reuse the same idempotency key once to confirm that the sender's retry handling does not create a second admitted run. This is a proposed test plan, not a test result from this article.

5. Run both paths without double action. Let the event path produce an internal receipt while the old cron job remains read-only or only reconciles missing receipts. Do not allow both paths to send the same customer-facing message until the deduplication rule has been checked.

6. Cut over the trigger, not the safety net. Pause the high-frequency polling job after the event path has stable receipts. Keep the slower reconciliation schedule. If the hook path fails, disable the hooks, restart the Gateway, and restore the original cron job from its saved definition.

Failure paths to design before switching

A 400 response means the hook request or its routing policy is invalid. Correct the payload or destination before retrying. A 401 points to authentication. Repeated failed authentication can be throttled with 429, so the sender should honor Retry-After instead of increasing its retry rate. The configuration reference lists these status meanings and the separate 503 admission timeout.

A 200 response without a visible message is not automatically a failed run. OpenClaw separates admission, execution, and delivery. Inspect the hook run identifier in the logs and then inspect the agent run session. If deliver: false was used, successful announcement was intentionally suppressed. For a delivery-enabled request, verify the actual channel and recipient.

If the sender stops calling, the reconciliation schedule should identify the gap. If the sender retries after losing a response, retain the same event identifier and apply the same idempotency policy. If several events arrive together, record whether they may be coalesced, processed independently, or rejected for later replay. These policies belong in the adapter and workflow design; the hook endpoint alone is not a durable event ledger.

The decision

I would approve the migration only when the external system owns the useful fact, the latency target makes polling inadequate, the sender can be authenticated, the event has a stable identifier, and a missed notification has a recovery path. If one of those answers is still unknown, keep cron or use a hybrid design while you measure it.

The safest default is a staged cutover: add the event path, test it without side effects, compare receipts, then pause the fast cron job while leaving reconciliation in place. A webhook is justified when it removes a demonstrated polling problem. If it only changes the vocabulary around a job that is naturally due at a time, the clock is still doing the right work.

Sources

• Automation - OpenClaw: separates user-authored automations, heartbeat monitoring, and external webhook triggers.
• Automation schedules - OpenClaw: documents cron expressions, intervals, timezone handling, exact timing, and schedule behavior.
• Automations (cron) - OpenClaw: documents the CLI, sessions, command jobs, run history, and outbound delivery modes.
• Inbound webhooks - OpenClaw: documents hook setup, authentication, idempotency, admission responses, sessions, and delivery checks.
• Configuration - hooks - OpenClaw: documents hook policy, agent allowlists, session-key controls, request limits, and HTTP status meanings.
• Automation troubleshooting - OpenClaw: documents the operator command ladder and common scheduling and delivery failure paths.