vultr/openclaw
1
0
Fork 0
mirror of https://github.com/openclaw/openclaw.git synced 2026-04-21 14:11:26 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: rebuild automation section for coherence and readability

Browse Source
This commit is contained in:
Vincent Koc
2026-04-03 13:11:13 +09:00
parent d5ea5f27ac
commit a2b6fdc3df
5 changed files with 240 additions and 1323 deletions
Download Patch File Download Diff File Expand all files Collapse all files

121
docs/automation/cron-jobs.md
View File

@@ -37,9 +37,7 @@ openclaw cron runs --id <job-id>
- All cron executions create [background task](/automation/tasks) records.
- One-shot jobs (`--at`) auto-delete after success by default.
## Adding jobs
### Schedule types
## Schedule types
| Kind | CLI flag | Description |
| ------- | --------- | ------------------------------------------------------- |
@@ -51,7 +49,35 @@ Timestamps without a timezone are treated as UTC. Add `--tz America/New_York` fo
Recurring top-of-hour expressions are automatically staggered by up to 5 minutes to reduce load spikes. Use `--exact` to force precise timing or `--stagger 30s` for an explicit window.
### CLI examples
## Execution styles
| Style | `--session` value | Runs in | Best for |
| --------------- | ------------------- | ------------------------ | ------------------------------- |
| Main session | `main` | Next heartbeat turn | Reminders, system events |
| Isolated | `isolated` | Dedicated `cron:<jobId>` | Reports, background chores |
| Current session | `current` | Bound at creation time | Context-aware recurring work |
| Custom session | `session:custom-id` | Persistent named session | Workflows that build on history |
**Main session** jobs enqueue a system event and optionally wake the heartbeat (`--wake now` or `--wake next-heartbeat`). **Isolated** jobs run a dedicated agent turn with a fresh session. **Custom sessions** (`session:xxx`) persist context across runs, enabling workflows like daily standups that build on previous summaries.
### Payload options for isolated jobs
- `--message`: prompt text (required for isolated)
- `--model` / `--thinking`: model and thinking level overrides
- `--light-context`: skip workspace bootstrap file injection
- `--tools exec,read`: restrict which tools the job can use
## Delivery and output
| Mode | What happens |
| ---------- | -------------------------------------------------------- |
| `announce` | Deliver summary to target channel (default for isolated) |
| `webhook` | POST finished event payload to a URL |
| `none` | Internal only, no delivery |
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:<id>`, `user:<id>`).
## CLI examples
One-shot reminder (main session):
@@ -92,40 +118,6 @@ openclaw cron add \
--announce
```
## Execution styles
| Style | `--session` value | Runs in | Best for |
| --------------- | ------------------- | ------------------------ | ------------------------------- |
| Main session | `main` | Next heartbeat turn | Reminders, system events |
| Isolated | `isolated` | Dedicated `cron:<jobId>` | Reports, background chores |
| Current session | `current` | Bound at creation time | Context-aware recurring work |
| Custom session | `session:custom-id` | Persistent named session | Workflows that build on history |
**Main session** jobs enqueue a system event and optionally wake the heartbeat (`--wake now` or `--wake next-heartbeat`). They use `payload.kind = "systemEvent"`.
**Isolated** jobs run a dedicated agent turn. Each run starts a fresh session (no carry-over) unless using a custom session. Default delivery is `announce` (summary to chat).
**Custom sessions** (`session:xxx`) persist context across runs, enabling workflows like daily standups that build on previous summaries.
### Payload options for isolated jobs
- `--message`: prompt text (required for isolated)
- `--model` / `--thinking`: model and thinking level overrides
- `--light-context`: skip workspace bootstrap file injection
- `--tools exec,read`: restrict which tools the job can use
## Delivery and output
| Mode | What happens |
| ---------- | -------------------------------------------------------- |
| `announce` | Deliver summary to target channel (default for isolated) |
| `webhook` | POST finished event payload to a URL |
| `none` | Internal only, no delivery |
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:<id>`, `user:<id>`).
## Webhooks
Gateway can expose HTTP webhook endpoints for external triggers. Enable in config:
@@ -247,13 +239,6 @@ gog gmail watch start \
}
```
### Test
```bash
gog gmail send --account openclaw@gmail.com --to openclaw@gmail.com --subject "watch test" --body "ping"
gog gmail watch status --account openclaw@gmail.com
```
## Managing jobs
```bash
@@ -280,33 +265,6 @@ openclaw cron add --name "Ops sweep" --cron "0 6 * * *" --session isolated --mes
openclaw cron edit <jobId> --clear-agent
```
## JSON schema for tool calls
One-shot main session job:
```json
{
"name": "Reminder",
"schedule": { "kind": "at", "at": "2026-02-01T16:00:00Z" },
"sessionTarget": "main",
"wakeMode": "now",
"payload": { "kind": "systemEvent", "text": "Reminder text" },
"deleteAfterRun": true
}
```
Recurring isolated job with delivery:
```json
{
"name": "Morning brief",
"schedule": { "kind": "cron", "expr": "0 7 * * *", "tz": "America/Los_Angeles" },
"sessionTarget": "isolated",
"payload": { "kind": "agentTurn", "message": "Summarize overnight updates." },
"delivery": { "mode": "announce", "channel": "slack", "to": "channel:C1234567890" }
}
```
## Configuration
```json5
@@ -329,16 +287,11 @@ Recurring isolated job with delivery:
Disable cron: `cron.enabled: false` or `OPENCLAW_SKIP_CRON=1`.
### Retry policy
**One-shot retry**: transient errors (rate limit, overload, network, server error) retry up to 3 times with exponential backoff. Permanent errors disable immediately.
**One-shot jobs**: retry transient errors (rate limit, overload, network, server error) up to 3 times with exponential backoff. Permanent errors disable immediately.
**Recurring retry**: exponential backoff (30s to 60m) between retries. Backoff resets after the next successful run.
**Recurring jobs**: exponential backoff (30s to 60m) between retries. Backoff resets after the next successful run.
### Maintenance
- `cron.sessionRetention` (default `24h`): prune isolated run-session entries.
- `cron.runLog.maxBytes` / `cron.runLog.keepLines`: auto-prune run-log files.
**Maintenance**: `cron.sessionRetention` (default `24h`) prunes isolated run-session entries. `cron.runLog.maxBytes` / `cron.runLog.keepLines` auto-prune run-log files.
## Troubleshooting
@@ -364,16 +317,10 @@ openclaw doctor
### Cron fired but no delivery
- Run succeeded but delivery mode is `none` means no external message is expected.
- 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.
### Heartbeat suppressed or skipped
- `reason=quiet-hours`: outside `activeHours`.
- `requests-in-flight`: main lane busy, heartbeat deferred.
- `empty-heartbeat-file`: `HEARTBEAT.md` has no actionable content and no cron event is queued.
### Timezone gotchas
- Cron without `--tz` uses the gateway host timezone.

1339
docs/automation/hooks.md
View File

File diff suppressed because it is too large Load Diff

50
docs/automation/index.md
View File

@@ -33,48 +33,60 @@ flowchart TD
| React to commands or lifecycle | Hooks | Event-driven, runs custom scripts |
| Persistent agent instructions | Standing orders | Injected into every session |
### Cron vs heartbeat
| Dimension | Cron | Heartbeat |
| --------------- | ----------------------------------- | ------------------------------------- |
| Timing | Exact (cron expressions, one-shot) | Approximate (default every 30 min) |
| Session context | Fresh (isolated) or shared | Full main-session context |
| Task records | Always created | Never created |
| Delivery | Channel, webhook, or silent | Inline in main session |
| Best for | Reports, reminders, background jobs | Inbox checks, calendar, notifications |
Use cron when you need precise timing or isolated execution. Use heartbeat when the work benefits from full session context and approximate timing is fine.
## Core concepts
### Scheduled tasks (cron)
Cron is the Gateway's built-in scheduler for precise timing. It persists jobs, wakes the agent at the right time, and can deliver output to a chat channel or webhook endpoint. Supports one-shot reminders, recurring expressions, and inbound webhook triggers.
See [Scheduled Tasks](/automation/cron-jobs).
### Tasks
The background task ledger tracks all detached work: ACP runs, subagent spawns, isolated cron executions, and CLI operations. Tasks are records, not schedulers. Use `openclaw tasks list` and `openclaw tasks audit` to inspect them.
See [Background Tasks](/automation/tasks).
### Scheduled tasks (cron)
Cron is the Gateway's built-in scheduler for precise timing. It persists jobs, wakes the agent at the right time, and can deliver output to a chat channel or webhook. Supports one-shot reminders, recurring expressions, and inbound webhook triggers.
See [Scheduled Tasks](/automation/cron-jobs).
### Task Flow
Task Flow is the flow orchestration substrate above background tasks. It manages durable multi-step flows with managed and mirrored sync modes, revision tracking, and `openclaw tasks flow list|show|cancel` for inspection.
See [Task Flow](/automation/taskflow).
### Heartbeat
Heartbeat is a periodic main-session turn (default every 30 minutes). It batches multiple checks (inbox, calendar, notifications) in one agent turn with full session context. Heartbeat turns do not create task records. Use `HEARTBEAT.md` to define what the agent checks.
See [Heartbeat](/gateway/heartbeat).
### Hooks
Hooks are event-driven scripts triggered by agent lifecycle events (`/new`, `/reset`, `/stop`), session compaction, gateway startup, message flow, and tool calls. Hooks are automatically discovered from directories and can be managed with `openclaw hooks`.
See [Hooks](/automation/hooks).
### Standing orders
Standing orders grant the agent permanent operating authority for defined programs. They live in workspace files (typically `AGENTS.md`) and are injected into every session. Combine with cron for time-based enforcement.
See [Standing Orders](/automation/standing-orders).
### Hooks
Hooks are event-driven scripts triggered by agent lifecycle events (`/new`, `/reset`, `/stop`), session compaction, gateway startup, message flow, and tool calls. Hooks are automatically discovered from directories and can be managed with `openclaw hooks`.
See [Hooks](/automation/hooks).
### Heartbeat
Heartbeat is a periodic main-session turn (default every 30 minutes). It batches multiple checks (inbox, calendar, notifications) in one agent turn with full session context. Heartbeat turns do not create task records. Use `HEARTBEAT.md` to define what the agent checks.
See [Heartbeat](/gateway/heartbeat).
## How they work together
- **Heartbeat** handles routine monitoring (inbox, calendar, notifications) in one batched turn every 30 minutes.
- **Cron** handles precise schedules (daily reports, weekly reviews) and one-shot reminders. All cron executions create task records.
- **Heartbeat** handles routine monitoring (inbox, calendar, notifications) in one batched turn every 30 minutes.
- **Hooks** react to specific events (tool calls, session resets, compaction) with custom scripts.
- **Standing orders** give the agent persistent context and authority boundaries.
- **Task Flow** coordinates multi-step flows above individual tasks.

47
docs/automation/taskflow.md
View File

@@ -11,16 +11,45 @@ title: "Task Flow"
Task Flow is the flow orchestration substrate that sits above [background tasks](/automation/tasks). It manages durable multi-step flows with their own state, revision tracking, and sync semantics while individual tasks remain the unit of detached work.
## When to use Task Flow
Use Task Flow when work spans multiple sequential or branching steps and you need durable progress tracking across gateway restarts. For single background operations, a plain [task](/automation/tasks) is sufficient.
| Scenario | Use |
| ------------------------------------- | -------------------- |
| Single background job | Plain task |
| Multi-step pipeline (A then B then C) | Task Flow (managed) |
| Observe externally created tasks | Task Flow (mirrored) |
| One-shot reminder | Cron job |
## Sync modes
Task Flow supports two sync modes:
### Managed mode
- **Managed** — Task Flow owns the lifecycle end-to-end, creating and driving tasks as flow steps progress.
- **Mirrored** — Task Flow observes externally created tasks and keeps flow state in sync without taking ownership of task creation.
Task Flow owns the lifecycle end-to-end. It creates tasks as flow steps, drives them to completion, and advances the flow state automatically.
Example: a weekly report flow that (1) gathers data, (2) generates the report, and (3) delivers it. Task Flow creates each step as a background task, waits for completion, then moves to the next step.
```
Flow: weekly-report
Step 1: gather-data → task created → succeeded
Step 2: generate-report → task created → succeeded
Step 3: deliver → task created → running
```
### Mirrored mode
Task Flow observes externally created tasks and keeps flow state in sync without taking ownership of task creation. This is useful when tasks originate from cron jobs, CLI commands, or other sources and you want a unified view of their progress as a flow.
Example: three independent cron jobs that together form a "morning ops" routine. A mirrored flow tracks their collective progress without controlling when or how they run.
## Durable state and revision tracking
Each flow persists its own state and tracks revisions so progress survives gateway restarts. Revision tracking enables conflict detection when multiple sources attempt to advance the same flow.
Each flow persists its own state and tracks revisions so progress survives gateway restarts. Revision tracking enables conflict detection when multiple sources attempt to advance the same flow concurrently.
## Cancel behavior
`openclaw tasks flow cancel` sets a sticky cancel intent on the flow. Active tasks within the flow are cancelled, and no new steps are started. The cancel intent persists across restarts, so a cancelled flow stays cancelled even if the gateway restarts before all child tasks have terminated.
## CLI commands
@@ -31,13 +60,15 @@ openclaw tasks flow list
# Show details for a specific flow
openclaw tasks flow show <lookup>
# Cancel a running flow
# Cancel a running flow and its active tasks
openclaw tasks flow cancel <lookup>
```
- `openclaw tasks flow list` — shows tracked flows with status and sync mode
- `openclaw tasks flow show <lookup>` — inspect one flow by flow id or lookup key
- `openclaw tasks flow cancel <lookup>` — cancel a running flow and its active tasks
| Command | Description |
| --------------------------------- | --------------------------------------------- |
| `openclaw tasks flow list` | Shows tracked flows with status and sync mode |
| `openclaw tasks flow show <id>` | Inspect one flow by flow id or lookup key |
| `openclaw tasks flow cancel <id>` | Cancel a running flow and its active tasks |
## How flows relate to tasks

6
docs/docs.json
View File

@@ -1145,11 +1145,11 @@
"group": "Automation & Tasks",
"pages": [
"automation/index",
"automation/tasks",
"automation/cron-jobs",
"automation/tasks",
"automation/taskflow",
"automation/hooks",
"automation/standing-orders"
"automation/standing-orders",
"automation/hooks"
]
},
{