orchestration_events table). The Observability and Fleet panels and the Activity feeds on tasks, agents and teams all read it. This page lists every event kind with its data, the classes Clawboo sorts failures into, and the codes you may find in the log.
These are the orchestration events defined in @clawboo/obs. The OpenClaw Gateway’s own events, which the dashboard handles in the browser, are a separate stream (see Event pipeline).
Event kinds
There are 38 kinds. New kinds are only ever added, so older logs keep parsing.- Board API means the board routes the dashboard calls. Tasks MCP tools write the same board events, with an
actor. - Task runner runs serve
POST /api/runtimes/:id/runand agent routine fires on runtimes other than OpenClaw. Team engine runs serve team chat and the tasks it delegates. See How a team works for the two paths. - Peer room events concern the agents’ peer room behind the TeamChat server, not the team chat you use in the dashboard.
- Only the server and the Tasks stdio bins write events. No API route adds them from outside.
Error classes
Every failure anerror event records is sorted into one class by matching its code and message. Anything that matches no class is Unknown, which Clawboo treats as a harness bug: a failure its run machinery could not explain, worth a look rather than routine noise.
An exact typed code decides first, before any number in the message can:
context_overflow, auth, authentication_failed, authentication_error, invalid_api_key, billing_error, rate_limit, rate_limit_error, overloaded, overloaded_error, server_overloaded, server_error, network and network_error. A typed rate limit, or a message that opens with a 429, still reads as Billing when it names an empty balance in words. Otherwise the classes are tried in the order of the table. Billing and Auth come first: a provider can send an empty balance as a 429 that names its quota, a revoked key as a 400, and an account on hold as a 403. A code in snake_case is also read word by word, so rate_limit_error matches rate limit. The runtimes put the cause they know on the error’s code: Claude Code the SDK’s (authentication_failed, billing_error, rate_limit, …), Codex the app-server’s, in the same words where they mean the same thing, and Hermes the code or type of the provider error it printed.
Two groups of classes change what happens next:
- Account failures (
Auth,Billing): a retry fails the same way until a person fixes the sign-in or the account. The task runner never refires the task, the team engine tells the delegator not to hand it out again, and the board shows Fix sign-in on the task in Needs you. The class is stored on the run’s ledger row (execution_processes.error_class). - Failures that may pass (
RateLimited,Timeout,ProviderError): a team chat task waits and runs again twice, after 30 and 60 seconds of awake time, then goes to Needs you. A task on the task runner waits the same before each automatic rerun. A routine keeps its schedule through up to three of these in a row. See Routines.
PolicyDenied
In a task-runner run, anerror whose code is policy_denied, permission_denied, denied, forbidden, unauthorized, eperm or eacces (in any case) is recorded with errorClass: 'PolicyDenied' and harnessBug: false. That is how a Clawboo Native agent’s refused tool call (a broker denial, or a Tasks creation cap) is logged. Two such denials in a row in one run trip the circuit breaker (repeat-policy-denied).
The team engine does not have this rule: it runs every error through the classifier. A tool denial in team chat therefore gets whichever class its message matches, often Unknown, and is then counted as a harness bug.
Where errors show up
The error lists read the latest 500
error events, and the harness-bug count covers those 500 only.
The event envelope
Every event has the same envelope, whatever its kind:
That is 13 fields plus
data. Before a row is stored, secrets in data are scrubbed, and an unrecognized kind is stored as error. Writing an event never fails the work that produced it: a failed write is dropped. Nothing deletes rows from the log, so it grows until you reset or trim the database (see Data and state).
Board events
Board events carry the task intaskId and its team in teamId. Those written by the board routes the dashboard calls also carry person, { id: string; name: string | null; role: string | null }, when the request came through a sign-in proxy whose identity token Clawboo verified. Without one there is no person field.
Board events also say who made the write, as actor:
actor was written by Clawboo itself (the team engine, the task runner, a sweep), or by an older release. See the person check and Who made a write.
task_created
A task was created.task_claimed
An agent was given a task, by a claim or an assignment.status_changed
A task moved to another status.to is always present.
Person is the person shape above. Some writers add fields the typed shape does not declare:
by: 'person'marks a move a person made on the board, andpersonnames them when a sign-in proxy vouched for them.reasonsays why the server moved it:retry(a person pressed Retry),assigned(a person assigned the task),blocker_failed(a task it waited on failed or was cancelled, so it was cancelled too),verification_exhausted(its checks failed and the fix attempts ran out),agent_blocked(a task runner run’s own agent blocked the task),check_interrupted(a task runner’s check never reached a verdict),rerun_not_started(a rerun through the task runner could not start),routine_fire_failed(a routine’s run failed and its task was set aside),released(an agent released the task throughrelease_task),plan_answered(a person’s answer closed a card that only held a plan),plan_stopped(a person’s Stop ended a plan waiting for its answer),plan_replaced(a newer plan replaced the card holding this one),replyorwake(a person’s reply, or a saved wake, moved it back to To do),no_summary(a request’s lead could not write its summary, so it went to Blocked),request_closed(its request closed, which cancelled it),stopped_while_waiting(a Stop reached a task waiting on other work),check_waiting(a check began waiting for teammates to leave the team folder),routine_fire_paused(a pause covered a routine’s run, so its task was cancelled),waiting_on(what it waits on changed with no move, sotois where it still is),room_archived(its chat room was archived and it moved to the team’s own chat, sotois where it still is), orworkspace_complete(a person completed its worktree).result_reportedmoves nothing: an agent said how its task went withreport_result,outcomesays which, andtois the status the task is still in. The report’s words stay on the run’s row.plan_writtenmoves nothing either: an agent wrote a new revision of its task’s plan withwrite_plan,revisionsays which, and its words stay on the document’s row. The Activity feeds badge these tworeportandplan, notstatus.
comment_added
A comment or system note landed on a task.dep_linked
A task was made to wait for another. The task that waits istaskId.
Run events
execution_started
A run of a task started.execId is the row in the execution_processes table.
execution_completed
A run finished. The cost and token fields carry the run’s final totals (see Cost totals).error holds a code when Clawboo stopped or refused the run:
cancelled means a person. The two budget rows also carry errorClass BudgetRefused, and a raised cap lets a wake on the task go out. A held budget clears by itself, so that task runs again when it does.
Breaker reasons, also posted on the task as a comment that begins [stopped: <reason>]:
Budgets and breakers are explained in Governance; their defaults are in Limits and defaults.
tool_call
An agent called a tool.toolCallId matches the call’s tool_result. Secrets in input are scrubbed.
grantId and connectorId are declared for attribution, but Clawboo’s own writers leave them out. Grant attribution for connector calls is in grant_decision events and the tool audit.
tool_result
A tool returned.isError feeds the tool error rate in the trace metrics.
cost
Spend and tokens reported during a run. Several can arrive for one run; see Cost totals.cost events; their spend is charged to budgets directly. See Budgets and spend for which runtimes report real cost and which are estimated.
session_rotated
A task-runner run reached its turn limit or filled its context, and continued in a fresh session. The new session starts from a short handoff note, not the old transcript.Pause events
pause_placed and pause_lifted carry { scope, id, reason?, person?, actor? }, where scope is agent, team or task_tree. The envelope names the agent, the team or the root task. A second pause of something already paused writes nothing. The dashboard reads these to keep what it shows as paused up to date. A task a pause holds back raises no Needs you alert, since a person placed the pause.
Home events
From 0.9.0. What agents and people change on a team’s Home. The envelope names the team, and the agent when one wrote it. None carries words: no update body, page text or KPI note.kpi_reported:{ kpiId, value, asOf, executionId?, actor? }, with the bound task as the envelope’s task.goal_update_draftedandgoal_update_published:{ goalId, updateId, health?, executionId?, actor? }. A published update that names a health set the goal’s health.page_revised:{ pageId, revision, revertedFrom?, executionId?, actor? }.revertedFromnames the revision a revert copied.
actor is { kind: 'person' | 'agent', id, name }.
Approval events
Every approval card is a row in thetool_call_approvals table, shown under Needs you on the Board (see Approvals). Each row writes one approval_requested when it is created and one approval_resolved when it settles. The events name the call but never carry its arguments, its reason or the command text: those stay on the row, because nothing prunes the event log and every Activity feed reads it.
The envelope carries the agent that asked, its team when Clawboo has a row for that agent, the task the approval gates when known, and the tenant.
To follow approvals as they happen instead of polling the queue, open GET /api/obs/stream?kinds=approval_requested,approval_resolved. See Following approvals.
approval_requested
An approval card opened: a connector call the tool broker paused, a Clawboo Native command, a risky hand-off, or an OpenClaw command the server copied from the Gateway. A request the Gateway delivers twice writes one event.approval_requested. Its grant_decision carries the rule’s ruleId.
approval_resolved
An approval card settled. Written by whichever of these got there first:- A person’s answer through
POST /api/tools/approvals/:id/resolveorPOST /api/capabilities/approve. For an OpenClaw command, only once the Gateway has accepted it. - Another surface’s answer to an OpenClaw command, which the Gateway reports to Clawboo’s server.
- An OpenClaw deadline. Every 30 seconds the server expires copied commands past the Gateway’s deadline.
- A wait that ended unanswered. A connector call, Clawboo Native command or risky hand-off that nobody answered is expired as soon as its wait ends, normally at the card’s
expiresAt. - A stopped run. A Clawboo Native command whose run stopped before anyone answered is expired.
- The approval reaper, which runs hourly and expires pending approvals older than 24 hours (
CLAWBOO_APPROVAL_TTL_MS).
resolvedBy names the person who answered, when their request came through a sign-in proxy whose identity token Clawboo verified. It is absent otherwise, and on an OpenClaw command’s event when the Gateway’s own report settled the card before Clawboo heard back; the approval row still records who answered then.
A connector call, Native command or hand-off card (kind: 'tool') stays pending past its expiresAt only when nothing was left waiting on it, for example because Clawboo stopped while the card was open. The dashboard stops showing it at expiresAt. A late answer to it is refused and expires it at once; otherwise the reaper expires it 24 to 25 hours after it was created, with the default CLAWBOO_APPROVAL_TTL_MS. An OpenClaw command’s copy (kind: 'exec') can stay pending for up to 30 seconds past its expiresAt, until the next sweep. An answer to it in that time goes to the Gateway, which decides whether it still counts.
Error events
error
A failure during a run, with its error class.- The task runner writes one for each error a runtime reports, and one more (with
code: nullandfatal: true) when a run ends in an error. - The team engine writes one for each error a runtime reports during team chat.
- Classification joins
codeandmessage, and the rules are tried in the order of the classes table, first match wins.ContextOverflowis tried beforeInvalidArgs, so an oversized prompt that a provider rejects with a 400 counts as a context overflow.
Trace events
span_start
The task runner opens one span per run, namedrun:<taskId>, with spanKind: 'task'. A child task’s run nests under its parent task’s run.
span_end
The run’s span closed.Routine events
Routine events carry the routine’s ledger row indata.scheduledRunId (a scheduled_runs row). See Routines.
routine_fired
A due routine was picked up for firing.routine_dispatched
The fire was handed to its target.dispatchPath is one-shot when the task runner ran it, connected when it went to the OpenClaw Gateway, and team-chat when a team routine posted its message to the team chat. The type also allows human, which nothing writes.
routine_completed
The fire succeeded and the routine re-armed.status is idle. nextRunAt is the next fire time, or null when nothing is left to fire (a spent one-time routine).
routine_paused
A pause stopped this fire or refused it after the ticker claimed it. It is no failure and no run: the routine’s last run, failure streak and next run are unchanged, and it runs again on resume. A fire a pause held back before it was claimed writes nothing.routine_error
The fire failed. A failure that may pass by itself (a run that failed asRateLimited, Timeout or ProviderError) leaves the routine on its schedule, up to three in a row; any other failure stops it in an error state until someone resumes it. stopped says which happened.
Peer room events
These concern the agents’ peer room (theteam_chat table), which the dashboard does not show. See Peer chat.
team_chat_post
A bound agent posted through the TeamChat MCP server over HTTP, so this covers Claude Code, Codex and Hermes agents. Posts that Clawboo Native agents make in-process are not logged.seq is the post’s position in its room. authorAgentId comes from the session’s signed binding, never from tool arguments.
speaker_selected
The agents’ exchange (POST /api/team-chat/exchange) picked the next agent to speak.
turn_bound_hit
An agents’ exchange ended.reason is max_turns (the turn cap was reached with replies still owed), no_pending_obligation (nobody owed a reply), budget_paused (a paused hard-cap budget refused a turn, or a turn’s spend paused one) or aborted (the caller disconnected). The typed shape lists only the first two.
Connector events
grant_decision
The tool broker checked a connector tool call against the caller’s grants. Builtin tools are not governed by grants and write none. It is its own kind because a refused call produces notool_call.
<decision>: <reason> under a grant badge. Reasons, in the order the check applies them:
A call the grant check allows can still ask for approval later in the broker, for example a destructive tool. See Connectors and Approvals.
connector_health
A connector’s health changed.health is one of unknown, ok, needs-auth, degraded, error or drift. The server writes this event with health: 'error' and detail: 'the connector process exited' when a connector’s process stops; it writes no other value today. drift means the connector’s tools no longer match what was approved, so review what changed before trusting it again.
task_wake_recorded
Something happened on a task and its agent is to hear it: a saved wake.reason is person_comment, dependency_done, subtasks_closed, question_answered, reopened or agent_comment. A wake a stdio bin saved has no event: the bus is in-process.
task_wake_skipped
A saved wake did not start a run. One event each time the reason changes, however many pump passes it spans.wakeReason is why it was saved. reason is what it waits for:
finished means the task closed first, and the wake was settled. The task drawer shows the waiting reason beside the reply box.
task_wake_given_up
A saved wake’s run failed 3 times over, so it stopped being sent. The team’s chat was told first; the comments and results stay on the task.task_braked
A task released with no visible progress on its last runs waits before it starts again by itself. See the no-progress brake.job_limit_reached
A job has started as many runs by itself as it may, and something was refused. Written once until a person carries on.job_limit_carried_on has the same shape, with the new limit and who said so. See the job’s count.
Cost totals
cost events add up during a run, and execution_completed carries the run’s total. Some runtimes report cost only when the run ends. So the trace metrics and the graph take, for each run (keyed by taskId), the larger of the summed cost events and the completed total. Nothing is counted twice, and a run with no cost events still shows its total.
Fleet health
The Fleet health list in the Observability panel gives each agent a status from its recent events:
The panel reads the latest 5,000 events, and a single trace returns at most 5,000 events.
Structured log lines
Alerts such as the harness-bug alert are written to the server log as structured entries in this shape, with secrets scrubbed:error entry with component: 'runtime', action: 'harness_bug', error: '[<class>] <message>' and the run’s execution id in correlationId. Only task-runner runs write it. Where the server log lives is in the CLI reference.
Related
- Observability: what Clawboo records and how to read it.
- Observability API: the routes that serve the log, traces, errors and fleet health.
- Governance: budgets, caps and circuit breakers.
- MCP tools: the tools whose calls and refusals appear here.
- Database schema: the table that stores the log.