diff --git a/docs/automation/cron-jobs.md b/docs/automation/cron-jobs.md index 1d735a9c99e..84594e46105 100644 --- a/docs/automation/cron-jobs.md +++ b/docs/automation/cron-jobs.md @@ -100,6 +100,15 @@ agent primary as a hidden extra retry target. Use `--announce --channel telegram --to "-1001234567890"` for channel delivery. For Telegram forum topics, use `-1001234567890:topic:123`. Slack/Discord/Mattermost targets should use explicit prefixes (`channel:`, `user:`). +For cron-owned isolated jobs, the runner owns the final delivery path. The +agent is prompted to return a plain-text summary, and that summary is then sent +through `announce`, `webhook`, or kept internal for `none`. `--no-deliver` +does not hand delivery back to the agent; it keeps the run internal. + +If the original task explicitly says to message some external recipient, the +agent should note who/where that message should go in its output instead of +trying to send it directly. + Failure notifications follow a separate destination path: - `cron.failureDestination` sets a global default for failure notifications. @@ -363,6 +372,9 @@ openclaw doctor - Delivery mode is `none` means no external message is expected. - Delivery target missing/invalid (`channel`/`to`) means outbound was skipped. - Channel auth errors (`unauthorized`, `Forbidden`) mean delivery was blocked by credentials. +- For cron-owned isolated jobs, do not expect the agent to use the message tool + as a fallback. The runner owns final delivery; `--no-deliver` keeps it + internal instead of allowing a direct send. ### Timezone gotchas diff --git a/docs/cli/cron.md b/docs/cli/cron.md index 407505787d3..f31c7ca6714 100644 --- a/docs/cli/cron.md +++ b/docs/cli/cron.md @@ -19,6 +19,10 @@ Tip: run `openclaw cron --help` for the full command surface. 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: cron-owned isolated runs expect a plain-text summary and the runner owns +the final send path. `--no-deliver` keeps the run internal; it does not hand +delivery back to the agent's message tool. + Note: one-shot (`--at`) jobs delete after success by default. Use `--keep-after-run` to keep them. Note: `--session` supports `main`, `isolated`, `current`, and `session:`. @@ -101,6 +105,14 @@ openclaw cron add \ `--light-context` applies to isolated agent-turn jobs only. For cron runs, lightweight mode keeps bootstrap context empty instead of injecting the full workspace bootstrap set. +Delivery ownership note: + +- Cron-owned isolated jobs always route final user-visible delivery through the + cron runner (`announce`, `webhook`, or internal-only `none`). +- If the task mentions messaging some external recipient, the agent should + describe the intended destination in its result instead of trying to send it + directly. + ## Common admin commands Manual run: diff --git a/docs/help/faq.md b/docs/help/faq.md index 32808c93881..d58cb5e2930 100644 --- a/docs/help/faq.md +++ b/docs/help/faq.md @@ -1023,6 +1023,29 @@ for usage/billing and raise limits as needed. + + Check the delivery mode first: + + - `--no-deliver` / `delivery.mode: "none"` means no external message is expected. + - Missing or invalid announce target (`channel` / `to`) means the runner skipped outbound delivery. + - Channel auth failures (`unauthorized`, `Forbidden`) mean the runner tried to deliver but credentials blocked it. + + For isolated cron jobs, the runner owns final delivery. The agent is expected + to return a plain-text summary for the runner to send. `--no-deliver` keeps + that result internal; it does not let the agent send directly with the + message tool instead. + + Debug: + + ```bash + openclaw cron runs --id --limit 50 + openclaw tasks show + ``` + + Docs: [Cron jobs](/automation/cron-jobs), [Background Tasks](/automation/tasks). + + + Use native `openclaw skills` commands or drop skills into your workspace. The macOS Skills UI isn't available on Linux. Browse skills at [https://clawhub.ai](https://clawhub.ai).