Skip to main content
HQ uses Supabase tables as durable queues. Everything the UI tells a gateway to do — and everything agents do in the background — flows through these queues.

​
The two queues

Commands

agent_commands — consumed by the runner. Handles lifecycle and operations: provision, update, remove, provider auth, gateway restart, and pairing approval.

Inbox

agent_inbox_items — consumed by agents. Represents background work from task assignments, comment @-mentions, routines, and other workspace events.

​
How it flows

UI writes rows  →  Daemons lease rows  →  Agents / gateway processes execute  →  Results written back to Supabase
Commands and inbox items are never deleted — they persist as durable history. You can review them from Settings → System.
Both queues use atomic leasing so parallel daemons on different gateways never steal each other’s work.

​
How the dispatcher wakes agents

When a new inbox item arrives (via Realtime or the periodic reconciliation sweep), the dispatcher calls: 
openclaw agent --agent <workspace>/<agent-slug> [--model <model-id>] [--thinking <level>] --message "[inbox] <reason> ..."
The --model and --thinking flags are included when the inbox item’s context contains per-task overrides. This lets individual tasks run with different reasoning depth without changing the agent’s default configuration. For task_assignment events, the dispatcher enriches the message with unresolved blocker information from task_relations. If the assigned task has active blocked_by dependencies (blocking tasks not yet done or cancelled), a note is appended to the summary so the agent knows what dependencies exist before starting work. This is fire-and-forget — the dispatcher doesn’t wait for the agent to respond. Before waking, the dispatcher checks:
  • The agent is not paused or hibernating
  • No active lease already exists for this agent (it’s not already processing)
  • The agent’s budget hasn’t hit a hard cutoff
  • There’s actually actionable work (pending or retryable failed items)
  • The cooldown period has elapsed since the last wake
Inbox items are not leased by the dispatcher — the agent’s background session leases them directly when it starts processing. The dispatcher only signals that work is available. If the Realtime connection drops, the dispatcher’s reconciliation sweep (every RECONCILE_INTERVAL seconds, default 120) acts as a safety net and wakes any agents with pending work that were missed. See Command lifecycle for the command state machine and Inbox dispatch for full dispatcher details.