Skip to main content

wednesdayai cron

Manage cron jobs for the Gateway scheduler. openclaw cron (the legacy openclaw binary alias) runs the same commands. After upgrade, existing jobs import from ~/.openclaw/cron/jobs.json into the Gateway cron_jobs table on first start (SQLite or Postgres). On Postgres the epoch-ms columns are BIGINT; an older 32-bit table is widened on Gateway start. CLI commands are unchanged. Inspect pipeline fires with wednesdayai task status --task cron-run. Related: Tip: run wednesdayai cron --help for the full command surface. Note: wednesdayai cron run <id> runs in force mode by default. Force mode bypasses only the schedule due-time check; it still respects payload validity, wake gates, already-running protection, heartbeat/runtime guards, and delivery constraints. A disabled job is not run: the command returns success with ran: false and reason: "disabled" (it does not pretend the job is already running). Use --due to run only when the job is currently due. Note: isolated cron add jobs default to --announce delivery. Use --no-deliver to keep output internal. --deliver remains as a deprecated alias for --announce. Note: one-shot (--at) jobs delete after success by default. Use --keep-after-run to keep them. Note: recurring jobs now use exponential retry backoff after consecutive errors (30s → 1m → 5m → 15m → 60m), then return to normal schedule after the next successful run. Note: wednesdayai cron list prints a boxed table sized to the terminal width; long cells wrap instead of being truncated, and piped output assumes 120 columns. Scripts should use wednesdayai cron list --json, which is the stable format. The table includes a Created by column (clientId, or clientId/clientDisplayName; - when the job has no stamp). --json output includes the full createdBy object. The stamp is set by the Gateway from the creating connection and is read-only; see Cron jobs for field details and the troubleshooting entry on jobs you did not create. Note: retention/pruning is controlled in config:
  • cron.sessionRetention (default 24h) prunes completed isolated run sessions.
  • cron.runLog.maxBytes + cron.runLog.keepLines prune ~/.openclaw/cron/runs/<jobId>.jsonl.

Common edits

Create the three common job types:
Run a job now, then inspect the run history:
Run only if the schedule is due:
Update delivery settings without changing the message:
Disable delivery for an isolated job:
Announce to a specific channel:
Note: delivery targets are validated on cron add and cron edit; the gateway reports a rejected target as an INVALID_REQUEST error:
  • --to identity:<key> delivers through a session.identityLinks key. An unknown key is rejected; a configured key without exactly one link for the delivery channel fails at delivery time.
  • An unprefixed --to that equals an identityLinks key is rejected. Use the identity:<key> form or a channel-native id.
  • --to "" is the explicit clear value: the stored job drops delivery.to. Disabling delivery (--no-deliver) always succeeds too, so a job with a bad target can always be repaired.
  • A target rejection at run time is terminal even for --best-effort-deliver jobs: the summary is not relayed to the main session.
Capture and the full fail-closed rules: Cron jobs. Note: identity attribution for job runs:
  • Identity attribution is only supported for isolated assistant-task jobs (--session isolated with an agent-turn --message). Only those jobs run the turn themselves and can carry the identity. Main-session jobs (timeline messages and wake-gate checks) hand the work to a heartbeat turn that runs under the heartbeat’s own identity, so --identity is rejected on them rather than silently ignored.
  • --identity <key> on cron add / cron edit attributes the job’s runs to a session.identityLinks key (matched case-insensitively against the keys); an absent or unmatched value leaves runs as unattributed system runs — there is never a default or fallback identity.
  • --clear-identity on cron edit removes the attribution. Clear the identity in the same edit if you are switching an attributed job to a main-session shape, otherwise the edit is rejected.
  • A pre-existing job that already carries an identity on an unsupported shape is never locked: the attribution is stripped (with a warning) when the store is loaded, and cron enable|disable or any other edit that does not re-assert --identity still succeeds.
  • Attribution applies to agents backed by the embedded agent runtime. Agents backed by a CLI provider run cron turns through runCliAgent, which has no sender-identity plumbing, so their runs stay unattributed even with --identity set.
  • The agent-facing Gateway cron tool cannot set or patch identity; only operator surfaces (CLI, gateway RPC, Web UI) can.