Skip to main content
AgentSource answers one question: where does the agent list come from? Clawboo’s answer is that SQLite holds the record of every agent, and each upstream is one AgentSource that syncs into it. Reads come from SQLite, so the fleet renders even when a runtime is offline. Writes, agent-file reads and writes, and live session lists go to the source that owns the agent and mirror back. Use this page when you work on agent creation, deletion, sync, or the server’s Gateway connection. For what an agent is from a user’s point of view, see the agent model; for the REST surface, see the Agents API.

What it is, and what it isn’t

AgentSource is about who exists. How an agent runs is the RuntimeAdapter trait, and the two layers never reach into each other: a source produces and persists AgentRecords, an adapter executes a run. The board is a third, separate layer: it references agents by id and owns only task state. The trait and record types live in @clawboo/agent-registry, a pure, browser-safe package with no dependencies key at all. The concrete sources live server-side in apps/web/server/lib/agentSource/.

The five registered sources

The server registers five sources in one AgentRegistry (apps/web/server/lib/agentSource/registry.ts): getRegistry() returns a process-wide singleton that exposes them as .source (OpenClaw), .nativeSource, .runtimeSources, and the multiplexer as .registry. A SIGTERM or SIGINT handler stops the OpenClaw connection on shutdown. One rule shapes every operation: registry reads come from SQLite, and writes go to the owning upstream and mirror back. A disconnected Gateway therefore degrades a write on an OpenClaw agent (503), never a registry read: GET /api/agents still answers, flagged stale. Listing an OpenClaw agent’s sessions is the exception (see listSessions below).

The AgentSource trait

The contracts worth pinning down:
  • listSessions is the one read that can fail on a disconnect. Sessions change too fast to cache, so the OpenClaw source asks the Gateway live and throws gateway_disconnected when it is down. The SQLite-backed sources read the sessions table.
  • AgentFileName is a local literal. The package keeps its own copy of the seven names (AGENTS.md, SOUL.md, IDENTITY.md, USER.md, TOOLS.md, HEARTBEAT.md, MEMORY.md) so it stays dependency-free. Which files each runtime actually consumes is AGENT_FILE_RUNTIME_SUPPORT in @clawboo/protocol.
  • events() is consumer-terminated, like RuntimeAdapter.events(). The AgentEvent union is agent-upserted, agent-status, agent-archived, sync-complete and connection.
  • health() reports a connection state (connected, connecting, reconnecting, disconnected) plus the last sync time. The SQLite-backed sources always report connected. The OpenClaw source also reports inUse, false while it holds no connection because nothing has needed one yet (see Connection lifecycle).
  • sync() is idempotent and must preserve every column Clawboo owns. That rule is the core of the OpenClaw source.

The record types

AgentRecord is Clawboo’s own shape, not an OpenClaw protocol shape, and a source adapts its upstream into it in both directions. Each field is annotated in packages/agent-registry/src/records.ts with who owns it:
  • Upstream-owned (overwritten on every OpenClaw sync): displayName, emoji, avatarUrl, sessionKey, isDefault, sourceAgentId. status is marked Gateway-synced, but the sync writes it only as 'idle' on first insert and 'archived' when the agent leaves the list.
  • Clawboo-owned (set by Clawboo and preserved across a sync): teamId, personalityConfig, execConfig, avatarSeed, participantKind, runtime, capabilities, tenantId.
  • Clawboo’s column, managed by sync: archivedAt. The OpenClaw sync sets it when an agent leaves the Gateway’s list and clears it when the agent returns.
  • Optional, per source: model? (the configured model, surfaced for the native and coding-runtime sources) and providerReady? (native only: whether a key, a fallback key, or a set-up keyless Ollama resolves for the agent’s provider).
RuntimeId is the same open set as the executor’s ('openclaw' | 'claude-code' | 'codex' | 'hermes' | (string & {})). AgentRecordStatus is idle | running | error | sleeping | archived, a superset of the Gateway’s status that adds the archived tombstone. TeamRecord carries a computed agentCount; SessionRecord carries the upstream session key as sourceSessionId and a status of active, idle or closed. The write inputs are thin. CreateAgentInput is { name, teamId?, personalityConfig?, execConfig?, avatarSeed?, files?, tenantId? }, where files maps agent-file names to content written at create time and tenantId is resolved at the REST handler. UpdateAgentInput is { displayName?, teamId?, personalityConfig?, execConfig?, avatarSeed?, status? }.
participantKind ('agent' | 'human') and tenantId are reserved fields. The only branch on participantKind is the wake bridge, which throws NotImplementedError for a human Routine target. No request filters by tenant: every row carries tenantId: null.

The registry

AgentRegistry is a thin catalog keyed by RuntimeId:
default() returns the first registered source, which is the OpenClaw source. REST handlers route a per-agent operation by the row’s sourceId (sourceForAgent in apps/web/server/api/agents.ts): look up the row, take registry.get(row.sourceId), and fall back to the OpenClaw source for an unknown id so its 404 semantics hold. GET /api/agents calls listAgents() on every registered source and flattens the result. Alongside the list it returns defaultId (the runtime-neutral Boo Zero from resolveBooZero: an override, else the native Boo Zero, else the OpenClaw default), mainKey, stale and lastSyncedAt (both from the OpenClaw connection), and pendingDeleteIds (see Pending deletes).

OpenClawAgentSource

The OpenClaw source holds the server’s own GatewayClient, separate from any browser tab, and reconciles the Gateway’s agent list into SQLite. The client is injected through a makeClient dependency, so tests pass a fake that implements only the OpenClawClientLike slice the source uses.

Reads and writes

Reads (listAgents, getAgent, listTeams) select from SQLite (listAgents is scoped to sourceId = 'openclaw', getAgent looks a row up by id alone, and teams are shared), parse the stored identityJson for the display name, emoji and avatar, and build the sessionKey as agent:<sourceAgentId>:<mainKey>. They work whether or not the Gateway is up. createAgent, archiveAgent and the file calls go through the Gateway and guard on a live connection with requireClient(), which throws Error('gateway_disconnected'); the REST layer maps that to 503.
  • createAgent asks the Gateway for its config path, derives a workspace-<slug> directory beside it, calls agents.create, clears any pending-delete marker the returned id still carries, writes SOUL.md, IDENTITY.md and AGENTS.md through agents.files.set (the OpenClaw 2026.9 Gateway refuses TOOLS.md, so any TOOLS.md content is folded into a ## Tools section of AGENTS.md by foldToolsIntoAgentsMd, and the browsing guidance is appended there too), tries CLAWBOO.md best-effort, applies the command-approval posture (below), and only then inserts the SQLite row.
  • updateAgent patches the Clawboo-owned columns in SQLite and does not touch the Gateway.
  • archiveAgent is a hard delete: it deletes the agent upstream, then removes the SQLite row, its cost records, its approval history, and its boo-zero:display-name:<id> setting.
  • readFile and writeFile call agents.files.read and agents.files.set.
The reversible archivedAt tombstone and the archiveAgent hard delete are different paths. Sync sets the tombstone when an agent disappears upstream and clears it if the agent comes back. archiveAgent is the delete a person asks for.

The posture write that can fail a create

The command-approval posture is written between the file writes and the SQLite insert, and it is the one step that can fail the whole call.
  • What is written. The caller’s execConfig.execAsk, or DEFAULT_EXEC_ASK ('on-miss', labelled Ask for Unknown in the dashboard) when the caller sends no execConfig at all. It goes through applyExecApprovalPolicy and upsertExecApprovalPolicy (exec.approvals.set under the Gateway’s compare-and-swap, retried against a fresh read up to three attempts in all), keyed by OpenClaw’s agent id, because the Gateway keys its policy by its own ids.
  • When it is skipped. When the value fails isExecAsk (it is not 'off', 'on-miss' or 'always'), including an execConfig with no execAsk. The agent is then created with no posture sent.
  • What a refusal does. The source deletes the agent it just created upstream (best-effort; a failure there is logged) and throws Could not set this agent's command permissions on the Gateway, so it was not created: <error>. The SQLite insert never runs, so there is no half-created row. POST /api/agents answers 500 with that message. A Gateway that is simply down never gets this far: requireClient() throws first and the route answers 503.
Nothing re-asserts a posture later. The only other write site is POST /api/exec-settings, and there a Gateway refusal answers 502 { ok: false, savedLocally: true }, leaving the refused value in Clawboo’s exec_config. sync() never touches the approvals store. See Command permissions.

The idempotent sync

sync() first sends any deletes it owes (see Pending deletes), then calls agents.list() and hands the result to upsertFromList, which runs the whole reconcile in one transaction:
  1. Upsert. Each listed agent is inserted, or on conflict updated with a set clause that touches only Gateway-owned columns: name, gatewayId, sourceAgentId, identityJson, archivedAt: null (revival) and updatedAt. It never writes teamId, personalityConfig, execConfig, avatarSeed, participantKind, runtime, capabilities or tenantId, so a re-sync can never clobber an agent’s team, personality or avatar.
  2. Archive. Any live openclaw row missing from the list gets archivedAt and status = 'archived', and an agent-archived event fires.
  3. Metadata. The list’s defaultId, mainKey and scope, plus the sync time, are upserted into the settings table inline (the transaction handle is not typed as a ClawbooDb, so setSetting cannot be reused there).
Re-running the sync against an unchanged Gateway leaves every Clawboo-owned column exactly as it was. The dashboard pushes the list it reads from the Gateway to POST /api/agents/sync, which runs the same upsertFromList, so SQLite stays current even when the server’s own connection is degraded.

Pending deletes

DELETE /api/agents/:agentId with the Gateway down still removes the local row, and for an OpenClaw agent it records an agent-source:openclaw:pendingDelete:<gatewayId> row in settings. The response is { ok: true, upstreamDeleted: false, upstreamDeletePending: true }.
  • What sync does. sync() sends agents.delete for every pending id before it lists. While a marker exists, upsertFromList skips that id, so the agent is never revived or re-created, whether the list came from the server’s sync or the dashboard’s POST /api/agents/sync push. POST /api/teams/:id/agents refuses to assign a pending agent with 409 agent is being deleted.
  • What clears a marker. The delete lands; a list arrives without the agent; the Gateway refuses the delete outright (a GatewayResponseError with code INVALID_REQUEST or retryable: false, logged as a warning, after which the agent comes back on that same sync); or createAgent gets the same id back from agents.create.
  • What keeps it. A transport failure leaves the marker for the next sync.
GET /api/agents exposes the markers as pendingDeleteIds, and the dashboard’s Gateway hydrate leaves those agents out of the fleet.

Connection lifecycle

The source connects on demand. start() opens the connection only when the install needs the Gateway by itself: the registry’s hasStandingNeed dep (hasStandingGatewayNeed) answers whether an agents row with sourceId = 'openclaw' exists that is not archived, or a delete of one is still owed to the Gateway (a pendingDelete row) while a Gateway is still set up. Otherwise the source stays disconnected with inUse: false, until one of these calls markInUse(reason):
  • POST /api/agents/registry/connect, which the dashboard sends when a person opens OpenClaw’s row in Runtimes, and markInUseAndWait behind it, which answers once the first attempt settles or after 5 seconds. The dashboard then reads the registry health every 2 seconds for up to 90 (openClawOnDemand.ts, outside the panel so closing Settings does not end it) and opens its own Gateway client once the server is connected;
  • the Gateway proxy, as it dials the Gateway for a browser connection (gatewayProxyUpstreamSettings);
  • the routines ticker, for a due OpenClaw routine that waits for the connection (GatewayState.markInUse; the idle read’s routinesDue never calls it);
  • POST /api/system/gateway with start or restart, and, when a Gateway is set up and not yet in use, POST /api/agents aimed at the OpenClaw source and POST /api/agents/sync without a body, which wait for the connection through markInUseAndWait;
  • isInUse(), which every health() calls: it reads the standing need again while the source is not in use, so an OpenClaw row written some other way later is noticed on the next read.
reconnect() (a settings change, a Gateway start, an OpenClaw delivery) marks the source in use too. A stop() while a connect is in flight clears the in-flight flag and leaves that connect to the torn-down client, whose late answer is ignored: a disconnected GatewayClient never settles its pending connect, so otherwise the next start() would never connect. In use is sticky: the connection is then held and retried as below until the process stops. A need noted before start() connects at start(), once the MCP base URL is known. A standing need that cannot be read is assumed, which is what every server did before. While the source is not in use, GET /api/system/status and the status action of POST /api/system/gateway skip their port probe, the openclaw-gateway-cron schedule source and the OpenClaw capability source read not_in_use, and the idle read skips its listening probe: each of those is a connection, and would start a Gateway that a service manager starts on its first connection. With no Gateway URL configured, a connect attempt leaves the source disconnected, and reads still serve SQLite. On a successful connect it:
  1. registers Clawboo’s MCP servers in the Gateway config, at the top-level mcp.servers key: clawboo-memory, clawboo-tasks and clawboo-tools, all unbound (one process-wide config cannot carry a per-agent identity). TeamChat is deliberately not registered, and a stale clawboo-teamchat entry is pruned;
  2. in the same config.patch, unions sessions_spawn and sessions_yield (plus any ids the operator listed) into the Gateway’s top-level tools.deny, so a team agent cannot launch its own throwaway sub-agents. Clawboo records the ids it wrote so it can later take back only its own;
  3. runs an initial sync().
The patch is skipped when nothing changed, because the Gateway rate-limits control-plane writes. The onStatus callback flips the connection state and schedules a resync on reconnect; onGatewayEvent schedules one on every presence, heartbeat or agent frame. Resyncs are debounced by 750 ms, so the registry tracks fleet changes without polling. Reconnect ownership is split. The source owns only the retry after an initial connect fails: exponential backoff from 2 s to 60 s, .unref()’d so it never holds the process open. An auth-class failure (bad token, unpaired device, bad connect params, a lockout) backs off to at least 2 minutes, honouring the Gateway’s retryAfterMs, so retries never trip the Gateway’s failed-auth lockout. Once a connection has opened, the GatewayClient’s own reconnect loop (800 ms to 15 s) owns later drops. The two are gated on disjoint conditions, so they never race.

The operator surface

Beyond the trait, the source exposes operatorCall, onGatewayBroadcast, onConnectionChange, operatorClient and reconnectAndWait. They ride the same single connection, and they are what makes OpenClaw the runtime Clawboo drives over a live connection rather than a spawned process. Their consumers:
  • the team engine, which runs every OpenClaw team-chat turn through buildOpenClawServerAdapter();
  • the Routines wake bridge, which runs OpenClaw routine fires through a thin dispatcher;
  • the openclaw-gateway-cron schedule source and the OpenClaw capability source;
  • the exec-approval surface and the session activity watcher (see Gateway connection internals).
reconnectAndWait(timeoutMs) (default 8,000 ms) is the delivery-resilience primitive. When a team-chat send finds the connection down, the engine reconnects, waits for it, and retries the delivery once, persisting a visible “could not reach your OpenClaw agents” message only if that also fails. This works because the Gateway Clawboo starts is spawned detached with its output in gateway.log in the Clawboo state directory, so it survives a server restart.

ClawbooNativeAgentSource

The native source has no remote upstream: SQLite is its upstream. Reads and writes are direct SQL, start() and sync() do nothing, stop() only drops event listeners, health() always reports connected, and writes never throw gateway_disconnected, so a native agent can be created, edited and deleted with no Gateway at all.
  • Storage. Agent files and the per-agent AgentConfig live in settings rows under a per-agent key prefix; sessions come from the sessions table the native harness writes.
  • SOUL.md is the persona. writeFile('SOUL.md', ...) re-derives AgentConfig.systemPrompt, which is what a native run reads; an emptied file falls back to the default prompt, and the same resolved text is stored, so the editor never shows one thing while the agent runs another.
  • createAgent mints a native-<slug>-<6 chars> id, validates the config with agentConfigSchema, inserts the row, stores the config and files, and, when the config sets budgetUsd, creates an agent-scope budget in cap mode.
  • archiveAgent is a hard delete of the row, its cost records, approval history and sessions, its config and file rows, and its team-session resume pointers. The archivedAt tombstone is unused, because a source with no remote upstream can never see an agent “gone upstream”.
  • getAgent is scoped. It returns null for a row owned by another source, which is what lets the registry aggregate every source’s list without overlap.

RuntimeAgentSource

One RuntimeAgentSource (apps/web/server/lib/agentSource/runtimeAgentSource.ts) is registered for each coding runtime in CODING_RUNTIME_SOURCE_IDS (claude-code, codex, hermes, listed in registry.ts). Like the native source, SQLite is its upstream: reads and writes are direct, start() and sync() do nothing, and it is always connected. Unlike the native source it keeps no AgentConfig. The server runs these agents from the row’s runtime, the runtime’s own credentials, and the task or message it delivers. Files given at create time (filtered to the seven agent-file names) are stored in settings under runtime-agent-file:<agentId>:<name>. Of those, only SOUL.md reaches a prompt: the server injects it as a [Your persona] block on both the team-chat and board paths (runtimes/personaBlock.ts). AGENTS.md draws the agent’s routing edges on the Org chart. A coding-runtime agent’s model, when set, lives in execConfig and is surfaced as model. archiveAgent hard-deletes the row and its cost records, approval history, sessions, file rows and team-session resume pointers.

Cleanup is scoped to OpenClaw rows

POST /api/agents/cleanup-ghosts deletes local rows that are missing from a supplied list of live Gateway ids. It compares only rows with sourceId = 'openclaw', and so does the sync’s archive step.
Keep that scoping on any sweep that reconciles against a Gateway list. The list comes from the Gateway, so only Gateway-owned rows may be compared against it. An unscoped sweep would delete every native and coding-runtime agent the moment a Gateway list arrived.

Server connect requirements (OpenClaw 2026.5 and later)

A headless Node connection to the Gateway is not a browser connection, and the differences are easy to break. Four options in the registry’s connectOptions() are load-bearing:
These options travel together. Changing clientName away from an allowlisted programmatic id, or dropping the injected WebSocket or origin, leaves the server’s connection permanently disconnected. That shows up not as a connection error but as 503s on every OpenClaw agent write and a fleet that renders from stale SQLite. Verify against a running Gateway, not only a typecheck.

Design rationale

The central decision: SQLite is the source of truth for who exists, and each upstream is the source of truth for how its runtime runs. That buys an offline-tolerant dashboard (reads never need the Gateway), lets a new runtime plug in as a new source behind the same interface, and keeps Clawboo’s own configuration (team, personality, avatar) in columns no upstream can overwrite. The cost is a second persistence layer and a sync discipline that must be exact. Restricting the upsert’s set clause to Gateway-owned columns is what keeps a routine resync from overwriting Clawboo’s configuration. The SQLite-backed sources pay a different price: they get offline writes for free but use hard deletes rather than a reversible tombstone, because nothing remote can go missing.

Boundaries

  • Not the runtime. A source never executes a turn; that is RuntimeAdapter.
  • Not the board. No agent identity, files or session state live in board tables.
  • One team per agent. An agent row has a single teamId.
  • Reserved fields. participantKind: 'human' and per-tenant filtering are not implemented.
Last modified on November 15, 2026