From 28b25e8abb88918388a7ea0f5098d8437a7b4b47 Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Sun, 11 Jan 2026 10:57:30 +0000 Subject: [PATCH] docs: expand cron jobs guidance --- docs/automation/cron-jobs.md | 29 +++++++++++++++++++++++++++++ 1 file changed, 29 insertions(+) diff --git a/docs/automation/cron-jobs.md b/docs/automation/cron-jobs.md index 055d320a1..6b36c4505 100644 --- a/docs/automation/cron-jobs.md +++ b/docs/automation/cron-jobs.md @@ -64,6 +64,23 @@ Key behaviors: Use isolated jobs for noisy, frequent, or "background chores" that shouldn't spam your main chat history. +### Payload shapes (what runs) +Two payload kinds are supported: +- `systemEvent`: main-session only, routed through the heartbeat prompt. +- `agentTurn`: isolated-session only, runs a dedicated agent turn. + +Common `agentTurn` fields: +- `message`: required text prompt. +- `model` / `thinking`: optional overrides (see below). +- `timeoutSeconds`: optional timeout override. +- `deliver`: `true` to send output to a provider target. +- `provider`: `last` or a specific provider. +- `to`: provider-specific target (phone/chat/channel id). +- `bestEffortDeliver`: avoid failing the job if delivery fails. + +Isolation options (only for `session=isolated`): +- `postToMainPrefix` (CLI: `--post-prefix`): prefix for the summary system event in main. + ### Model and thinking overrides Isolated jobs (`agentTurn`) can override the model and thinking level: - `model`: Provider/model string (e.g., `anthropic/claude-sonnet-4-20250514`) or alias (e.g., `opus`) @@ -86,6 +103,10 @@ Isolated jobs can deliver output to a provider. The job payload can specify: If `provider` or `to` is omitted, cron can fall back to the main session’s “last route” (the last place the agent replied). +Target format reminders: +- Slack/Discord targets should use explicit prefixes (e.g. `channel:`, `user:`) to avoid ambiguity. +- Telegram topics should use the `:topic:` form (see below). + #### Telegram delivery targets (topics / forum threads) Telegram supports forum topics via `message_thread_id`. For cron delivery, you can encode the topic/thread into the `to` field: @@ -176,6 +197,14 @@ Manual run (debug): clawdbot cron run --force ``` +Edit an existing job (patch fields): +```bash +clawdbot cron edit \ + --message "Updated prompt" \ + --model "opus" \ + --thinking low +``` + Run history: ```bash clawdbot cron runs --id --limit 50