Schedule recurring team work

Use this page when you want an agent to do something on a clock, a nightly cleanup, an hourly check, a one-off run at a future time, without sitting in front of the dashboard. Clawboo’s scheduler runs that work as Routines: durable, recurring fires that drop a team task onto the board and dispatch it through the normal executor path. The Scheduler tab is a unified surface. It shows two kinds of schedule side by side and never conflates them:

• Team work: clawboo Routines. The team-task domain: a fire materializes a board task and runs it. Clawboo fully owns these rows.
• Runtime’s own life: the OpenClaw Gateway’s own cron jobs. The runtime-own-life domain: an OpenClaw agent’s standalone scheduled wake, which lives on the Gateway, not in Clawboo’s ledger. Clawboo reads and writes these through the Gateway as an operator surface.

Everything on this tab runs from the SchedulerPanel, backed by /api/schedules. This page covers what each control does, the create dialog’s options, and the error-halts policy that parks a failing routine instead of retry-burning it.

​

Prerequisites

• At least one agent exists (the create dialog populates its agent picker from GET /api/agents).
• Scheduling an OpenClaw agent’s own life (a Gateway cron job) additionally requires the OpenClaw Gateway connected and this device paired; that write rides the operator connection. Every other runtime, and the team-task domain, has no such requirement.

​

The Scheduler tab

The panel header shows a Scheduler title, an N schedules count pill, a Schedule button (opens the create dialog), and a Refresh button. Below the header, schedules are grouped by domain: Each row shows the schedule’s label (falling back to its agentId), a status pill, the human-readable cron, the time until the next run, when it last ran, and, if a fire failed, the last error in red. The status pill maps to one of running, queued, claimed (all rendered as the “working” tone), paused (idle tone), error (error tone), or idle. The row’s action buttons are a pure function of the schedule’s manageability. A managed Routine and an external-write Gateway cron are both writable, so they show Pause/Resume (managed) or Enable/Disable (external-write), Run now, and Delete. An observe-only schedule shows a read-only marker and no actions; the UI never offers a write the owning system forbids.

​

Steps

​

Create a routine

1. Click Schedule to open the create dialog.
2. Pick an Agent from the dropdown (each option shows the agent name and its runtime).
3. Choose the Schedule intent:
   • A team task: a clawboo Routine (team-task domain). Available for every agent.
   • Its own life: an OpenClaw Gateway cron job (runtime-own-life domain). This chip is enabled only when the selected agent’s runtime is openclaw; for any other runtime it reads “OpenClaw only” and is disabled. (If you switch to a non-OpenClaw agent while “Its own life” is selected, the dialog snaps the intent back to “A team task”.)
4. Pick when it Runs from the cron presets (see Options below).
5. Give it a Label (optional; defaults to “Scheduled task” for a team task or “Scheduled wake” for own-life).
6. Click Create schedule.

A team-task create posts { source: 'clawboo-routine', domain: 'team-task', agentId, cronSpec, label, teamId, taskTemplate }. An own-life create posts { source: 'openclaw-gateway-cron', domain: 'runtime-own-life', agentId, cronSpec, label, payload }. On success (201) the dialog closes and the list refreshes.

​

Pause or resume

Click the pause/play button on a writable row. For a Routine this is Pause → Resume; for a Gateway cron it’s labeled Disable → Enable (the same PATCH /api/schedules/:id with { action: 'pause' | 'resume' }, just different wording for the external system). A paused schedule never auto-fires until you resume it.

​

Run now

Click the refresh-arrow button to force-fire immediately. This POST /api/schedules/:id/run returns 202 (an enqueue-style acknowledgement): for a Routine it flips the row to queued so the ticker picks it up on the next pass; for a Gateway cron it asks the Gateway to run that job now. It does not wait for the run to finish.

​

Delete

Click the trash button. The panel confirms first; the wording differs by domain (a Gateway cron job warns that it “removes the agent’s own scheduled wake on the OpenClaw Gateway”; a Routine warns it “is removed permanently”). Delete sends DELETE /api/schedules/:id.

​

Options

​

Schedule presets (cron expressions)

The create dialog offers eight cron-expression presets. A cron expression is the one spec dialect both sources accept, so the same preset works whether you target a Routine or a Gateway cron: The dialog defaults to Every hour.

​

One-shot runs (once@<ISO>)

A Routine’s cronSpec also accepts a one-shot form, once@<ISO-8601> (for example once@2026-07-01T09:00:00Z), parsed by the scheduler package. The create dialog’s preset chips only emit recurring cron expressions, so to schedule a one-shot you post a once@… spec to POST /api/schedules directly. After it fires successfully the row re-enters idle with nextRunAt set to null, so it self-disables and never repeats.

​

Domain and manageability

​

The error-halts policy

A failed recurring fire parks the routine; it does not silently retry. When a recurring Routine errors, its status goes to error and its nextRunAt is set to null, so the due-pass (which only queues rows with a non-null nextRunAt) skips it. The row stays disarmed, with the failure shown as lastError on the row, until a human resumes it. This is deliberate: autonomous scheduled work that retries a broken fire on every tick would burn budget and noise without progress. The fire itself flows through the standard executor path, so budgets, circuit breakers, verification, the worktree, and the observability trace all apply to a scheduled run exactly as they do to a manually dispatched task.

​

Verify it worked

• The new schedule appears under its domain group with a live nextRunAt countdown (in 5m, in 1h, …).
• When a fire is due, the status pill flips to queued → claimed → running, then back to idle (re-armed) on success.
• After a fire, the row shows ran <relative time>.
• A team-task fire materializes a task on the board for the routine’s team; open the board to see it.
• If a recurring fire fails, the row goes to the error pill with a lastError line and an empty next-run countdown; resume it to re-arm.

​

Troubleshooting

​

Related

• Scheduling: the model: team-task cron vs. runtime-own-life cron, the ledger, the ticker
• The board: where a team-task fire lands
• /api/schedules reference: full request/response shapes and status codes
• Connecting runtimes: get a runtime online so it can run scheduled work
• Observability dashboard: see a scheduled run’s trace