How a routine fires
- The routine is a row in Clawboo’s database. It holds who the routine goes to, its schedule, its instructions, its status and the time of its next run.
- The schedule is a cron expression, such as
0 9 * * 1-5for weekdays at 9:00, or a single time written asonce@followed by an ISO date and time. Cron times use the routine time zone: the zone of the machine the Clawboo server runs on, until you pick another in the routine dialog (see Routines). - The ticker, a timer inside the Clawboo server, wakes when the next routine is due, and at least once a minute. Each time, it finds the routines that are due, claims each one so that it fires only once, and hands it on. Routines that fall due together fire side by side. Nothing fires while the Clawboo server is stopped.
- Run now queues a routine immediately, and the ticker fires it straight away.
Missed and overlapping runs
- Missed times are not made up. If Clawboo was stopped, or the machine was asleep, when a routine was due, the routine fires once when the ticker next checks. It then carries on from its next scheduled time after that run.
- A routine never overlaps itself. Scheduled times that pass while a run is still going are skipped.
- A restart in the middle of a fire leaves a recurring routine waiting for its next scheduled time, and stops a one-time routine with an error for you to check. A fire that was claimed but had not started yet runs as soon as the server is back. The cut-off run shows as interrupted in the routine’s history after its next fire.
- A one-time routine fires once, then shows as finished and never runs again.
What a team routine does
A team routine posts its instructions into the team’s General chat, never into a room. The message is labelled Routine with the routine’s name instead of You, and it is routed like a message you type: if it starts with@Name, it goes to that teammate; otherwise it goes to the team’s lead (Boo Zero when you have one, else the team’s Leader, else its first active member).
The lead is told the message came from a routine and that you may not be watching, so it should carry the work out and make reasonable assumptions instead of asking questions and waiting. The fire counts as done, shown as posted, once the message reaches the lead, even if the lead’s turn waits behind one already running. From there it is ordinary team chat, with the same hand-offs, Board tasks, Stop button and guardrails as a message you typed. A team routine creates no Board task of its own.
A team fire fails when the team no longer exists, is archived, has no active members, or does not take messages from routines. It also fails when a paused hard-cap budget on the team or on the agent it goes to refuses that agent’s turn as it starts. If the agent was busy when the routine fired, the fire already counted as posted, so a refusal when its turn comes shows only in the chat.
What an agent routine does
An agent routine creates a new Board task for its agent on every fire, with the routine recorded as the task’s scheduler. (A routine bound to an existing task through the API runs that task instead.) Then it runs the task in one of two ways, depending on the agent’s runtime:
On OpenClaw, a fire goes through the Gateway, for an agent routine on an OpenClaw agent and for a team routine whose message goes to one. A routine that falls due while the Gateway is set up but not connected waits for it, for up to 5 minutes from when Clawboo finds it due, and fires as soon as the connection is up. So a routine that came due while Clawboo was stopped or the computer was asleep still runs after the next start, when the Gateway connects a few seconds after Clawboo does. Clawboo connects to the Gateway only once something needs it, and a due OpenClaw routine is such a need: if nothing had connected yet, the wait starts the connection (see How Clawboo connects). A Run now waits the same way. The wait is kept across a restart, so stopping and starting Clawboo does not start it again, and while a routine waits,
GET /api/system/idle counts it as work under way (Sleep and wake). A Gateway still not connected after those 5 minutes fails the fire, as a failure that may pass (below). With no Gateway set up at all, the fire fails at once. A finished OpenClaw run gets a comment on its task saying it completed without verification. If a person moves the task’s card out of In progress on the Board while it runs, the run stops at once. That counts as the outcome, not as a failure, and the routine stays on its schedule.
The Routines dialog sets who a routine goes to, its schedule, its name and its instructions. The other task template fields are set only through the Schedules API: a repository path (repoPath), the task kind, the model, the priority, a per-run cost cap (maxNodeCents) and an existing task to bind to (teamTaskId). An agent routine made in the dashboard therefore has no repository. It runs as a research task without a worktree, the same way the agent works in team chat: see What agents can do for where Claude Code, Codex and Hermes start in that case.
When a fire fails
A routine keeps its schedule through a run that failed for a reason that may pass by itself: a rate limit, a timeout, a provider error or a dropped connection, such as an OpenClaw Gateway that is not connected (theRateLimited, Timeout and ProviderError classes in Events and errors). It records the error and runs at its next time; a success clears the error. The third such failure in a row stops it, and so does any failure of a one-time routine.
Any other failure stops the routine at once. Its dialog shows Stopped after a failed run. with the error, and it does not run again until you press Resume, which also starts the count of failures again. Common causes:
- an agent routine’s run is refused before it starts, because a hard-cap budget for the agent, the team or the task’s delegation tree is already paused;
- a team routine’s message is refused the same way, because a hard-cap budget for the team or the agent it goes to is already paused;
- a circuit breaker or a hard cap stopped an agent routine’s run while it was still working (a Claude Code or Codex run whose last cost report crosses a hard cap keeps its result, and the paused budget refuses the routine’s next run instead);
- the runtime’s sign-in or the provider account was refused, which shows as Fix sign-in on the set-aside task;
- the run itself failed in a way that does not pass by waiting, or ran out of room;
- the agent was removed, or the team was deleted or archived. An agent routine outlives its team’s deletion: it files its tasks with no team from then on, unless it runs one of the tasks that team left behind.
One scheduler per task
Every Board task has one scheduler on record: you (a task made by hand), Clawboo’s routines, or OpenClaw. Two schedulers firing the same task would run it twice, so Clawboo keeps it to one:- Binding to an existing task (
teamTaskId, through the API) is refused when another scheduler already owns the task. A task you made by hand is taken over by the routine. - A bound routine must be one-time. A task can be claimed only once, so a recurring schedule on a bound task is refused. A team routine cannot be bound to a task at all.
- The claim is the backstop. If two fires ever reach one task, only one of them can claim and run it.
OpenClaw’s own cron jobs
The OpenClaw Gateway has its own scheduler, which an OpenClaw agent can use to wake itself. The Routines view lists those jobs in a separate section, OpenClaw’s own cron jobs, so everything scheduled is in one place. You can enable, disable, run or delete a Gateway job there, but not edit it. While the Gateway is disconnected, the section shows the last list it sent, or hides the jobs until it reconnects. Your own routines are not affected. Clawboo never uses the Gateway’s scheduler for routines, and refuses to schedule team work through it.Hermes’s own jobs
Hermes has its own scheduler too, in the Hermes gateway Clawboo runs, and a Hermes agent can use it to schedule jobs of its own. The Routines view lists them in a section of their own, Hermes’s own jobs. As with OpenClaw’s, you can enable, disable, run or delete a Hermes job there, but not edit it. They are the agent’s own life, not team work: they run in the agent’s own Hermes sessions, not in a team chat, and their output stays in Hermes. Clawboo refuses to schedule team work through Hermes’s scheduler. Hermes runs a job only while its gateway runs. Clawboo starts the gateway at launch when you have Hermes agents, so their jobs keep firing; while it is not running, the section shows the last list it sent, or hides the jobs until it runs again. Run now runs a job at Hermes’s next scheduler tick, within a minute. See Hermes’s own jobs. Claude Code, Codex and Clawboo Native have no scheduler of their own, so a routine is how you schedule them, and how you schedule team work on any runtime. The Board’s calendar shows the upcoming runs of your routines, but not of OpenClaw’s or Hermes’s own jobs.Under the hood
Under the hood
- A routine’s statuses are
idle,queued,claimed(shown as starting),running,pausedanderror. The ticker picks up onlyidleroutines whose next run is due.pausedanderrorwait for a person. - Each fire is claimed with a conditional database update, so two tickers, or two server processes, cannot both fire it. A lost claim is dropped and never retried.
- After a restart, a
claimedfire is queued again, a recurringrunningfire is re-armed for its next time with the noteorphaned mid-dispatch (restart), and a one-timerunningfire moves toerror. - The part that hands a fire on, by posting to the team or by creating and running the agent’s task, is the wake bridge. It picks the agent path from the runtime’s declared capabilities, never from its name.
- Each fire writes
routine_fired, thenroutine_dispatched(with the pathteam-chat,one-shotorconnected), thenroutine_completedorroutine_errorto the event log. CLAWBOO_ROUTINE_OPENCLAW_TIMEOUT_MSchanges the 10-minute limit for OpenClaw runs. The Schedules API lists the template fields and the error codes for ownership conflicts and bound schedules.
Related
- Routines: create, edit, pause, resume and run routines.
- Budgets and guardrails: which guardrails cover team routines and agent routines.
- Worktrees and handoff: when a routine’s task gets a worktree.
- What agents can do: where an agent routine without a repository runs.
- Schedules API: template fields, one-time schedules and error codes.