Skip to main content
Clawboo records what its agents do in an append-only event log inside its SQLite database (the 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/run and 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 an error 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, an error 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.
A harness bug is not something your agent did wrong. It usually means a runtime returned an error message Clawboo does not recognize. If one keeps appearing, note the message (task-runner runs also write an error-level server log line with "action": "harness_bug") and open an issue.

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 in taskId 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:
An event with no 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, and person names them when a sign-in proxy vouched for them.
  • reason says 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 through release_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), reply or wake (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, so to is where it still is), room_archived (its chat room was archived and it moved to the team’s own chat, so to is where it still is), or workspace_complete (a person completed its worktree). result_reported moves nothing: an agent said how its task went with report_result, outcome says which, and to is the status the task is still in. The report’s words stay on the run’s row. plan_written moves nothing either: an agent wrote a new revision of its task’s plan with write_plan, revision says which, and its words stay on the document’s row. The Activity feeds badge these two report and plan, not status.

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 is taskId.

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).
On task-runner runs, 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.
Team chat runs write no 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_drafted and goal_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? }. revertedFrom names the revision a revert copied.
actor is { kind: 'person' | 'agent', id, name }.

Approval events

Every approval card is a row in the tool_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.
A connector call that a remembered Always answers opens no card and writes no 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/resolve or POST /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).
A second answer to the same card changes nothing and writes nothing.
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: null and fatal: true) when a run ends in an error.
  • The team engine writes one for each error a runtime reports during team chat.
  • Classification joins code and message, and the rules are tried in the order of the classes table, first match wins. ContextOverflow is tried before InvalidArgs, 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, named run:<taskId>, with spanKind: 'task'. A child task’s run nests under its parent task’s run.

span_end

The run’s span closed.
Team chat runs, OpenClaw routine fires and board API events carry no trace, so they never appear in the Traces list. When OpenTelemetry export is set up, task-runner spans also go to your collector; see Observability.

Routine events

Routine events carry the routine’s ledger row in data.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 as RateLimited, 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 (the team_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 no tool_call.
The Activity feed shows it as <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:
The harness-bug alert is an 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.
Last modified on November 18, 2026