Skip to main content
These routes manage agents (each one appears as a Boo in the dashboard). SQLite is the source of truth for which agents exist. Every agent belongs to one source, named by its sourceId: openclaw agents mirror agents in the OpenClaw Gateway, while clawboo-native, claude-code, codex and hermes agents live only in SQLite. The agent list and single-agent reads serve SQLite, so they answer with the Gateway down (the list then reports stale: true). For an OpenClaw agent, creating it, a sync without a body, reading or writing its files, and listing its sessions need the Gateway, and answer 503 { "error": "gateway_disconnected" } without it. Agents on the other runtimes need no Gateway. The server connects to the Gateway only once something needs it (see How Clawboo connects). Until then GET /api/agents/registry/health reports inUse: false and the list reports stale: false. With a Gateway set up that nothing used yet, asking to create an OpenClaw agent, or for a sync without a body, is itself a need: the server starts connecting and the request waits up to about 5 seconds for it, then answers 503 if the connection is still not up. A retry a few seconds later lands. With no Gateway set up, or one already in use and down, these answer 503 at once.
These routes return Clawboo’s AgentRecord shape, not OpenClaw protocol shapes. See Agent model for the concept and Agent sources for how the Gateway is synced in.
A per-agent route goes to the source that owns the agent; an unknown id goes to the OpenClaw source, which answers its usual 404. Every route here is on the general rate tier except POST /api/agents/:agentId/shell, which is on the sensitive tier (see rate limits).

Routes

The AgentRecord shape (returned by GET /api/agents, GET /api/agents/:agentId, and inside the create 201):
runtime matches sourceId for every agent. participantKind and tenantId are reserved: agents Clawboo creates carry 'agent' and null.

GET /api/agents

Lists the agents of all five sources from SQLite, so the list answers even when the Gateway connection is down. defaultId is Boo Zero, resolved in this order: the override set with POST /api/boo-zero/override, then the native Boo Zero Clawboo creates, then the OpenClaw default agent. mainKey, stale and lastSyncedAt describe the OpenClaw connection; stale is true whenever the server’s OpenClaw connection is not connected.
  • Path params: none.
  • Query params:
  • Request body: none.

Responses

200 OK: the merged agent list:
An agent in pendingDeleteIds is already gone from agents, but the Gateway still lists it until the server’s next sync deletes it there. A client that reads the Gateway’s own agents.list() leaves those ids out. 500 Internal Server Error: any failure listing or probing health:

Example


POST /api/agents

Only part of this takes the person check. A caller that does not pass it gets 403 { "ok": false, "error": "person_only" } when the body names a teamId, carries any execConfig on the openclaw source, or on another source sets execConfig.execAsk or execConfig.tools.shell. Those choose who is on a team and whether anyone is asked before a command runs. A script can pass it with the two Sec-Fetch- headers. Creates an agent through a source. sourceId picks it: openclaw (the default), clawboo-native, claude-code, codex or hermes. An OpenClaw create makes the agent in the Gateway, writes its files there and mirrors it into SQLite, so it answers 503 while the Gateway connection is down. The other four write only to SQLite and work offline. name and every entry in files are scanned for prompt injection before anything is written. Instruction-override phrasing and hidden Unicode characters block the create with 422 and an install audit row. Text aimed at machines rather than the model (a DROP TABLE inside a code reviewer’s worked example) passes and comes back as findings.
  • Path/query params: none.
  • Request body:
Side effects of a successful create:
  • The new agent gets its own grants to the browser connectors.
  • Creating a clawboo-native agent in a team also creates the native Boo Zero, when none exists yet and a native provider is connected (best-effort).
  • A clawboo-native agent whose execConfig.budgetUsd is above 0 gets an agent budget in cap mode (a hard cap; see Governance).
  • An OpenClaw agent’s AGENTS.md gets a short section on how to open web pages, added once.

Responses

201 Created: the agent was created. findings is present only when the scan produced review-level findings:
422 Unprocessable Entity: name or a file carries a blocking prompt-injection finding. Nothing is written:
400 Bad Request: missing or blank name:
400 Bad Request: sourceId does not name a registered source:
503 Service Unavailable: an OpenClaw create while the Gateway connection is down, or not up yet (the create starts it, so a retry can land):
500 Internal Server Error: any other failure:

Example


POST /api/agents/sync

A body with an agents list takes the person check, because a list archives every OpenClaw agent it leaves out: anything else gets 403 { "ok": false, "error": "person_only" }. A sync with no body is open. Brings the OpenClaw agent list into SQLite. With a body that carries an agents array, it stores that list (the browser’s own agents.list result, sent while the server has no Gateway connection of its own). With no body, the server reads the list from the Gateway itself, which needs the connection and answers 503 while it is down.
  • Path/query params: none.
  • Request body (optional; a body with an agents array stores that list):
Without an agents array the body is ignored and the server syncs from the Gateway. Storing a list touches only the fields that come from the Gateway; Clawboo’s own fields (teamId, personalityConfig, execConfig, avatarSeed and so on) are kept.

Responses

200 OK: a list was stored (body with an agents array):
200 OK: server-side sync (no body):
archived counts agents present in SQLite but gone upstream (their archivedAt is set; the tombstone is reversible and cleared if the agent reappears). 503 Service Unavailable: a sync without a list while the Gateway connection is down, or not up yet (the sync starts it, so a retry can land):
500 Internal Server Error: any other failure:

Example


GET /api/agents/registry/health

Reports the state of the server’s own OpenClaw Gateway connection. It answers 200 whether or not the Gateway is connected.
  • Path/query params: none.
  • Request body: none.

Responses

200 OK: the OpenClaw source’s HealthResult:
inUse: false with connection: 'disconnected' means the server has not tried to connect, because nothing needs the Gateway yet: read it as “not in use”, not as “unreachable”. It turns true once something needs the Gateway (an OpenClaw agent exists, or a delete of one is owed to a Gateway still set up, a person opens OpenClaw’s views, a routine for an OpenClaw agent falls due) and stays true until the server stops. A read that finds an OpenClaw agent created since the last one turns it true and starts the connection. 500 Internal Server Error: a failure reading health:

Example


POST /api/agents/registry/connect

Something needs the OpenClaw Gateway now: the server connects to it, and stays connected (retrying as usual) until it stops. The dashboard sends it when a person opens OpenClaw’s row in Settings > Runtimes. It does not count as a person acting for GET /api/system/idle. The server answers once its first connect attempt settles, or after about five seconds while a Gateway is still starting, so connection may still be connecting. Read GET /api/agents/registry/health again for the outcome. Sending it again changes nothing.
  • Path/query params: none.
  • Request body: none.

Responses

200 OK: the health, as in GET /api/agents/registry/health, with inUse: true. 500 Internal Server Error: any failure:

Example


POST /api/agents/cleanup-ghosts

A person’s route. A caller that does not pass the person check gets 403 { "ok": false, "error": "person_only" }, and nothing changes. A script you run yourself can pass it with the two Sec-Fetch- headers in the example. A cleanup for scripts and manual recovery. The dashboard does not call it: it pushes the Gateway’s list to POST /api/agents/sync, which archives agents missing from the list and deletes nothing. Send the ids of every agent the Gateway has; the route deletes each local OpenClaw agent row that is not in the list, with its cost and approval-history rows, its per-agent settings and the routines that target it. Running it again changes nothing. Only rows with sourceId = 'openclaw' are compared, so agents on other runtimes are never removed.
  • Path params: none.
  • Query params:
  • Request body:

Responses

400 Bad Request: liveAgentIds is missing or not an array:
400 Bad Request: liveAgentIds is empty and ?allowEmpty=true was not passed (the message contains an em dash, written here as its JSON escape):
200 OK: no local rows were stale:
200 OK: stale rows were swept (remaining is the post-sweep agent count, or null):
500 Internal Server Error: a failure during the sweep:

Example


GET /api/agents/:agentId

Returns one agent record, routed to the source that owns the row.
  • Path params: agentId.
  • Request body: none.

Responses

200 OK: the record:
400 Bad Request: missing agentId segment:
404 Not Found: no agent with that id in its source:
500 Internal Server Error: a failure reading the record:

Example


DELETE /api/agents/:agentId

A person’s route. A caller that does not pass the person check gets 403 { "ok": false, "error": "person_only" }, and nothing changes. A script you run yourself can pass it with the two Sec-Fetch- headers in the example. Deletes the agent. The owning source deletes it upstream first (for OpenClaw, the Gateway’s agents.delete), then removes the local agent row along with the cost_records and approval_history rows that reference it, and deletes every routine that targets the agent (team routines target no agent and stay). If the Gateway connection is down, the local rows are removed anyway, but an OpenClaw agent’s routines stay until its Gateway delete settles (see the note below): the Gateway can refuse the delete and bring the agent back.
An OpenClaw agent deleted while the Gateway is down is recorded as a pending delete. On the next sync the server sends the Gateway’s agents.delete before it reads the list, and until that lands no sync re-creates the agent’s row. If the Gateway refuses the delete outright (it will not delete its only agent, or one that owns shared credentials), the pending delete is dropped and the agent comes back on that same sync. A connection failure is retried on the next sync.
  • Path params: agentId.
  • Request body: none.

Responses

200 OK: deleted upstream and locally. Agents on runtimes other than OpenClaw have nothing upstream, and also answer upstreamDeleted: true:
200 OK: the Gateway was disconnected, so the local rows were cleaned and, for an OpenClaw agent, the Gateway delete was recorded for the next sync (upstreamDeletePending: true). It is false when there was no OpenClaw row to delete:
400 Bad Request: missing agentId segment:
500 Internal Server Error: any failure other than a lost Gateway connection:

Example


POST /api/agents/:agentId/move

A person’s route. A caller that does not pass the person check gets 403 { "ok": false, "error": "person_only" }, and nothing changes. A script you run yourself can pass it with the two Sec-Fetch- headers in the example. Moves the agent to another team. It is what Move to team on the Org chart and team graphs sends. Everything below changes together in one transaction, or nothing does:
  • The agent’s teamId becomes the new team.
  • Its tasks on the old team that nobody has started (backlog, todo or blocked), whether assigned or handed to it, lose their assignee and stay on the old team’s board, unassigned. Done and cancelled tasks stay on the old board with the agent still named on them.
  • Its own routines, the agent routines that target it, move to the new team, except one bound to a specific task (teamTaskId in its template): that task is on the old team, so the routine is paused there instead. Team routines are not touched.
  • Its memberships in the old team’s chat rooms are removed.
  • Its resume pointers for the old team, in General and in each room, are cleared.
Not moved: the files it saved in the old team’s folder (from its next run it works in the new team’s folder), and memory and budgets scoped to the old team. Budgets set on the agent itself follow it. An OpenClaw agent’s AGENTS.md is not rewritten, so it still names its old teammates until you edit it. The route needs no Gateway. POST /api/teams/:id/agents on the Teams API sets only the team column and moves none of this.
  • Path params: agentId.
  • Request body: { "teamId": string } (required), the team to move to.

Responses

200 OK: the agent moved. fromTeamId is null for an agent that had no team. tasksHandedBack counts the unstarted tasks left unassigned on the old board, routinesMoved the agent’s routines now on the new team, and routinesPaused its routines bound to an old-team task, paused on the old team:
400 Bad Request: one of these messages: 404 Not Found: agent_not_found (no agent with that id, or it is archived) or team_not_found (no team with that id). 409 Conflict: the move is refused and nothing changes: 500 Internal Server Error: any other failure:

Example


GET /api/agents/:agentId/files/:name

Reads one agent file through the owning source. An OpenClaw agent’s files are read live from the Gateway (503 while it is down); the other runtimes keep their files in SQLite. The :name segment must be one of the seven agent file names; any other name is rejected before the read.
  • Path params: agentId, name.
:name is one of AGENTS.md, SOUL.md, IDENTITY.md, USER.md, TOOLS.md, HEARTBEAT.md, MEMORY.md. The route stores any of them on any agent, but which files actually shape an agent depends on its runtime: see Agents. The OpenClaw 2026.9 Gateway refuses to read or write TOOLS.md and HEARTBEAT.md, so on an OpenClaw agent the route fails for them; put tool guidance in AGENTS.md.
  • Request body: none.

Responses

200 OK: the file content:
400 Bad Request: missing agentId segment:
400 Bad Request: :name is not a recognized agent file:
503 Service Unavailable: an OpenClaw agent, and the Gateway connection is down:
500 Internal Server Error: any other failure:

Example


PUT /api/agents/:agentId/files/:name

Writes one agent file through the owning source. Same :name allowlist as the read; the body must carry a string content. content is scanned for prompt injection before the write, exactly as POST /api/agents scans its files. A blocking finding refuses the write with 422 and an install audit row; review-level findings come back on the 200.
  • Path params: agentId, name (same allowlist as the GET).
  • Request body:

Responses

200 OK: the file was written (echoes what was stored). findings is present only when the scan produced review-level findings:
422 Unprocessable Entity: content carries a blocking prompt-injection finding. Nothing is written:
400 Bad Request: missing agentId segment:
400 Bad Request: :name is not a recognized agent file:
400 Bad Request: content is missing or not a string:
503 Service Unavailable: an OpenClaw agent, and the Gateway connection is down:
500 Internal Server Error: any other failure:

Example


GET /api/agents/:agentId/sessions

Lists the agent’s sessions. For an OpenClaw agent the list is read live from the Gateway, so the route answers 503 while the connection is down. The other runtimes list the sessions stored in SQLite.
  • Path params: agentId.
  • Request body: none.

Responses

200 OK: the session list:
400 Bad Request: missing agentId segment:
503 Service Unavailable: an OpenClaw agent, and the Gateway connection is down:
500 Internal Server Error: any other failure:

Example


GET /api/agents/:agentId/workspaces

The task worktrees of this agent’s assigned tasks, newest first, the folders of its tasks that have no worktree, and the agent’s team folder. The agent’s Computer tab uses it to pick what to show, and to say so when the agent has nothing. Archived workspaces are left out. onDisk: false marks a checkout that was paused or cleaned up: the row and the branch remain, but the files are gone, and the tab says so rather than showing an empty tree. The files themselves come from the /api/board/:taskId/workspace/* routes on the Board API.
  • Path params: agentId.
  • Request body: none.

Responses

200 OK:
taskFolders lists the own folders of the agent’s assigned tasks that have no worktree, newest first: each one that is on disk and either holds a file or belongs to a task that is in_progress or in_review. It looks at the agent’s 200 newest tasks with no worktree and lists at most 50 folders. An older task’s folder is still readable through the folder routes, and the task drawer shows it. The folder is <team folder>/tasks/<task id>. Its files come from the /api/board/:taskId/folder/* routes in The task folder file view. Folders are not git checkouts, so they have no branch, change badges or diff. teamFolder is the folder the agent’s other runs start in (team-chat turns that hold no task, and its own chat): its team’s folder, or teams/_no-team with teamId: null for an agent with no team, in the work folder. onDisk is false until a run creates it. It is null for an OpenClaw agent. An agent with no worktree-backed tasks returns an empty workspaces list, and one with no task folder to show an empty taskFolders list. 500 Internal Server Error:

Example


GET /api/agents/:agentId/team-folder/tree and GET /api/agents/:agentId/team-folder/file

Read-only views of the agent’s team folder, behind the Team folder choice on its Computer tab. The folder comes from the agent’s row, never from the request. Both routes take the same dir and path query values, keep every path inside the folder the same way, and answer with the same shapes as the task worktree routes in The workspace file view. There is no diff or git status, because the folder is not a git checkout.
  • Path params: agentId.
  • 404 { "ok": false, "error": "workspace not found", "reason": "not_found" }: an unknown agent, or one whose runtime gets no team folder (OpenClaw).
  • 404 with "reason": "gone": the folder does not exist yet, because no run has created it.

Example


GET /api/agents/:agentId/screenshot

The newest browser screenshot for this agent, shown on its Browser card. A frame is kept whenever one of the agent’s browser tools returns an image, and when POST /api/agents/:agentId/screenshot/capture takes one. The route serves only this agent’s own frame, never another agent’s. From 0.9.0, with personCheck: verified, this route and POST /api/agents/:agentId/screenshot/capture need a person a verified token names, like the live screen, and refuse anyone else with 403 person_only. Frames are held in memory, one per agent: a new frame replaces the old one, and past 24 MB in total the oldest frames are dropped. They are also saved under <clawboo home>/frames/, so a restart brings them back, marked restored: true. A restored frame can be hours old.
  • Path params: agentId.
  • Query params: meta (any value) returns the frame’s details as JSON instead of the image.
  • Request body: none.

Responses

200 OK with ?meta: the frame’s details. restored is present only for a frame reloaded from disk:
200 OK without ?meta: the image bytes. Content-Type is image/png, image/jpeg, image/gif or image/webp (a frame that states any other type is served as image/png), with Content-Length, Cache-Control: no-store and X-Content-Type-Options: nosniff. 404 Not Found: this agent has no frame:
500 Internal Server Error: the stored frame could not be decoded:

Example


POST /api/agents/:agentId/screenshot/capture

Takes a fresh screenshot of a browser that is already open for this agent, so the Browser card can refresh without waiting for the agent’s next browser action. It never opens a browser and never navigates: with no browser open it fails, and the card stays as it was. The route tries each browser connector Clawboo runs (Playwright’s browser_take_screenshot, Chrome DevTools’ take_screenshot), and only where this agent’s own grant allows that tool and the agent’s browser is running. If none of those has a browser open and the agent runs on OpenClaw, it captures the newest browser tab OpenClaw tracks for that agent’s session (stored with toolName: "openclaw__browser"). Read the new frame with GET /api/agents/:agentId/screenshot.
  • Path params: agentId.
  • Request body: none.

Responses

200 OK: a new frame was stored:
409 Conflict: no browser is open for this agent:
400 Bad Request: missing agentId segment:
500 Internal Server Error: the capture itself failed. The message is redacted:

Example


An agent’s computer

The live view of an agent’s screen, take over, and links to it. See Watch a screen and take over for what each does in the dashboard. On Linux with TigerVNC’s Xvnc installed, each agent’s browser opens on a display of the agent’s own, and the live view sends what changes on it; a person in control sends mouse and key events to it. Elsewhere the live view sends a picture of the agent’s browser about once a second, and take over is refused. The /api/agents/:agentId/computer/* routes need the access cookie like every other route. The /api/computer-link/* routes take a link instead: send its token in the x-clawboo-computer-link header, never in the URL. The access gate admits those paths, and only those, when the token belongs to a link that still works. A link reaches its own agent only, and a view link can never take control. Making and revoking links and taking over are a person’s acts (see the person check: a caller that does not pass it gets 403 { "ok": false, "error": "person_only" }); handing back is not. POST /api/agents/:agentId/computer/links is on the sensitive rate tier. From 0.9.0, two operator switches add to this behind a sign-in proxy:
  • With personCheck: verified, every route below needs a person a verified token names, both ways in (a link needs the person as well as the link), and refuses anyone else with 403 person_only. Each live view belongs to the person who opened it: another person’s resume, take over or input does not reach it (404). A live stream ends every 5 minutes with a renew event.
  • With proxyIdentityControlClaim: required, a take over and every batch of input need a sign-in proxy token whose control claim names the agent (for a link, the link’s agent). Without it they get 403 { "ok": false, "error": "control_claim" }, and a refused batch hands the screen back to the agent. Control belongs to the person who took it.

GET /api/agents/:agentId/computer

200 OK:
displays is { "available": false, "code": "no-xvnc", "reason": "...", "installable": true } where agents get no display: code is platform (not Linux), off (CLAWBOO_AGENT_DISPLAYS=0) or no-xvnc, and installable is true only for no-xvnc on x86_64, where POST /api/computer/tools/install gives agents a screen (TigerVNC publishes no arm64 build). Where agents get displays, displays.problem says why the last display failed to start (a missing library), or is null, and displays.driverInstallable says whether Cua Driver can still be installed. display is { "running": false } while this agent has none. control.by is agent or person, and via says whether that person came through the dashboard or a link. browserOpen says whether one of the agent’s own browsers is open now. controlLinks.allowed is false, with the reason, unless agents run as their own OS user (CLAWBOO_AGENT_USER or CLAWBOO_AGENT_USERS). A link’s token is never listed. controlClaim (from 0.9.0) says whether a take over needs the proxy’s control claim, and whether this request’s token has it for this agent. 404: no such agent, or an archived one.

GET /api/agents/:agentId/computer/live and GET /api/computer-link/live

A Server-Sent Events stream. Events, each with JSON data: While control says other, another person has taken over, and this stream gets no rects or image until they hand back: only the view that took over sees the screen, so nobody else sees what they type. The first picture after that covers the whole screen. A watcher whose connection falls behind gets fewer, larger pictures of the current screen, never a backlog. To reconnect without losing control you hold, send the previous viewerId in the x-clawboo-viewer header within 30 seconds. At most 8 watchers per agent and 32 in all, of which links may use 6 per agent, 24 in all and 2 per link: the rest are kept for the dashboard. Past that the stream sends busy with the reason and closes; try again a little later (the dashboard and a link’s page do). A reconnect that names its viewerId replaces its own earlier stream if that one still looks open. Through a link: 401 when the link does not work, or its agent was archived, deleted, or deleted and made again under the same id.

POST /api/agents/:agentId/computer/control and POST /api/computer-link/control

  • Request body: { "viewerId": "...", "action": "take" | "release" }, with the viewerId your live view got in hello.
200 OK: { "ok": true, "control": "you" } after take, { "ok": true, "control": "agent" } after release. The newest take over wins. While a person has control, the agent’s own browser calls fail with a message telling it a person is using its computer. Control goes back to the agent on release, 30 seconds after the controlling live view closes, or after 10 minutes with no input from it. 400: a missing viewerId or action. 403: a view link, a control link while agents run as the server’s own user, (from the dashboard) a request the person check refuses, or, from 0.9.0, person_only under personCheck: verified without a verified person, or control_claim on a take without the proxy’s claim. 404: that live view is not open, or was opened another way. 409: the agent has no display of its own. release always answers 200, and hands control back only when that viewer holds it and asks the same way it took it, even after its live view closed.

POST /api/agents/:agentId/computer/input and POST /api/computer-link/input

  • Request body: { "viewerId": "...", "events": [...] }, at most 256 events, each { "t": "p", "x": 10, "y": 20, "b": 1 } (pointer at display pixel x, y with buttons b: bit 0 left, 1 middle, 2 right, 3 and 4 a wheel step up and down) or { "t": "k", "s": 65293, "d": true } (X keysym s pressed or released).
200 OK: { "ok": true, "control": "you" }. 400: a malformed event, and none of the batch is sent. 403 (from 0.9.0): person_only under personCheck: verified without a verified person; control_claim without the proxy’s claim, which also hands the screen back to the agent; or another person holds control. 404: that live view is not open. 409: this live view does not hold control, or the display stopped.

POST /api/agents/:agentId/computer/links

  • Request body: { "kind": "view" | "control", "ttlMinutes": 60 }. ttlMinutes is optional, between 1 and 1440; the default is 480 for a view link and 60 for a control link.
201 Created with Cache-Control: no-store. The token is in this answer only; Clawboo keeps a fingerprint of it:
The dashboard opens a link as <clawboo address>/computer-link#<token>. 400: an unknown kind or a ttlMinutes out of range. 403: the person check refused it. 404: no such agent. 409: a control link while agents run as the server’s own user (a person who takes over can reach what the agent’s browser can on the machine, which then includes Clawboo’s own files), or the agent already has 20 links; revoke one first. Revoke every link to this agent ({ "ok": true, "revoked": 2 }), or one ({ "ok": true }, or 404 when it is not one of this agent’s links). Every live view open through a revoked link ends at once, and control held through it goes back to the agent. 403: the person check refused it.

POST /api/computer/tools/install

Installs TigerVNC’s Xvnc 1.16.2 (x86_64) and Cua Driver 0.38.0 (x86_64, arm64) into Clawboo’s runtimes folder, each checked against its pinned SHA-256 as it downloads and before it is unpacked, beside any install already there, which stays current unless everything worked. Where the system has its own Xvnc, TigerVNC is not downloaded. Linux only. A person’s act, on the sensitive tier. A request made while an install runs waits for that one and gets its answer. Behind a proxy it downloads with curl through HTTPS_PROXY. 200 OK: { "ok": true, "xvnc": true, "cuaDriver": true } (xvnc is false on arm64, where TigerVNC publishes no build, and where the system’s own Xvnc is used). 422 { "ok": false, "code": "UNSUPPORTED", "error": "..." }: not Linux on x86_64 or arm64. 502: a download failed or was not the pinned release (DOWNLOAD_FAILED, CHECKSUM), or it could not be unpacked or installed (UNPACK_FAILED, INSTALL_FAILED); nothing was switched to. 403: the person check refused it.

GET /api/computer-link/info

200 OK: { "ok": true, "kind": "view", "expiresAt": 1762898800000, "agent": { "name": "Research Boo" } }. 401: the link does not work any more. 403 (from 0.9.0): person_only under personCheck: verified without a verified person. 404: its agent is gone.

PATCH /api/agents/:agentId/model

Changes the model of a clawboo-native or hermes agent, and optionally its provider. It needs no Gateway.
  • Native agent: the stored agent config is rewritten, and the next run uses it. With a provider, the provider, model and the key variable it reads (envVar) change together, so a model picked from another provider’s list never runs against the old provider. Without a provider, only the model changes, which is also how you set a custom model id for the current provider. The server checks the provider name but not the model string, so custom ids work.
  • Hermes agent: the model is stored as { provider, model } in the agent’s execConfig, where provider is openrouter (an OpenRouter model id) or openai-codex (a ChatGPT subscription model). Without a provider, the agent keeps the provider it already has, so a model change never moves a ChatGPT-subscription agent onto OpenRouter. An agent with no provider stored stays unpinned: Hermes runs the model on the provider its keys or ChatGPT sign-in give it. Any other provider is a 400.
  • Other runtimes answer 404. An OpenClaw agent’s model is set through PATCH /api/system/openclaw-config (see System API).
  • Path params: agentId.
  • Request body: { model: string, provider?: string }. For a native agent, provider must be one of anthropic, openai, openrouter, ollama, google, xai, groq, mistral, together, cerebras, moonshot. With ollama, which needs no key, the stored envVar is OLLAMA_BASE_URL. For a Hermes agent, it must be openrouter or openai-codex.

Responses

200 OK: the model (and the provider, when sent) was saved. For a native agent, provider is echoed only when the request carried one. A Hermes agent’s reply always carries provider: the one it is pinned to, or null when it has none:
400 Bad Request: one of these messages: 404 Not Found: one of these messages: 500 Internal Server Error: any other failure:

Example


POST /api/agents/:agentId/chat

A message from a caller that does not pass the person check still gets its reply, and reads Local API call in the chat rather than You. It starts no work: a hand-off in that reply does not start, and the chat says why. It does not end the hold a Stop left, and it does not read results waiting for you. Starts one turn of the 1:1 chat of a clawboo-native, claude-code, codex or hermes agent, Boo Zero’s personal chat included. The route stores your message under the agent’s 1:1 session key, the sessionKey in its record: agent:<agentId>:native for a native agent and agent:<agentId>:<runtime> for the others. It starts the reply in the background and answers 202 at once. The reply streams over GET /api/agents/:agentId/chat/stream and is saved by the server, so closing the connection does not stop it. An OpenClaw agent answers 404; its 1:1 chat goes through the Gateway connection instead. Each turn resumes the session the agent’s previous 1:1 turn saved, so the conversation carries over. The pointer is one setting per agent, native-chat-session:<agentId>, whatever the runtime. /reset in the chat clears it, and so does a failed Claude Code, Codex or Hermes turn that tried to resume, so the next turn starts a fresh session. One agent’s turns run one at a time: a second message waits for the turn in front of it. On Clawboo Native, Codex and Hermes it also waits for that agent’s team-chat runs and routines, and a turn that cannot start within 10 minutes leaves the notice “This agent was busy with another run and did not pick the message up in time. Send it again.” Claude Code, Codex and Hermes get the agent’s SOUL.md as a persona block on every turn. Every turn starts in the agent’s team folder, <work folder>/teams/<teamId> (_no-team for an agent on no team), created 0700 before the run. If the folder cannot be created, the turn ends with a notice instead of starting anywhere else. A native agent gets its file tools there, and run_command when its shell switch is on. A turn that fails before it writes any reply leaves a notice with the reason, including a run ended after CLAWBOO_RUN_SILENT_TIMEOUT_MS (30 minutes by default) with no events. A turn that fails partway keeps the text it had written.
  • Path params: agentId.
  • Request body:

Responses

202 Accepted: the user turn was persisted and the reply run started:
400 Bad Request: missing agentId segment:
400 Bad Request: missing or blank message:
404 Not Found: the agent is unknown, or its runtime is openclaw:
500 Internal Server Error: any other failure:

Example


POST /api/agents/:agentId/chat/stop

A person’s route. A caller that does not pass the person check gets 403 { "ok": false, "error": "person_only" }, and nothing changes. A script you run yourself can pass it with the two Sec-Fetch- headers in the example. Stops the agent’s running 1:1 turn (the composer’s Stop button). An agent has at most one running 1:1 turn; with none running the call changes nothing and still answers 200.
  • Path params: agentId.
  • Request body: none.

Responses

200 OK: the run was aborted, or there was nothing to abort:
400 Bad Request: missing agentId segment:
500 Internal Server Error: a failure during abort:

Example


GET /api/agents/:agentId/chat/stream

A Server-Sent Events tail of the agent’s 1:1 chat (agent:<agentId>:native, or agent:<agentId>:<runtime> for a Claude Code, Codex or Hermes agent). It only reads; it never starts a turn. It sends two kinds of frame: stored chat_messages rows, polled every 750 ms past a row-id cursor (each with an id: line, so they replay on resume), and live frames for streaming text, run state and the cards of tasks handed off from this chat (no id: line, never replayed). Where it starts. With no Last-Event-ID header and no since, the stream starts at the newest stored message and sends only what follows. Load the history first with GET /api/chat-history (see Chat history API). A supplied cursor resumes after that row id; Last-Event-ID wins over since, and an invalid or negative value resumes from 0 (the whole chat).
  • Path params: agentId.
  • Query params:
  • Request body: none.
This is an SSE route: there is no JSON response body, and the catalog below describes the frames. A missing agentId ends the response with a bare 400 and no body. Each poll reads up to 500 rows past the cursor.

Connection

On open, the handler writes HTTP/1.1 200 with:
then sends a : connected comment, a cursor event with the row id it starts from, any stored rows already past the cursor, and the last status published for the chat, so a client that reconnects learns about a turn that ended while no stream was open.

Event catalog

The cursor event gives an EventSource a resume point before any row arrives, so a connection that drops first still reconnects from where it started instead of the newest row at that moment. A client needs no listener for it. delta, status, board and handOffs frames carry no id: line, so they never move the resume cursor. board frames are read from the task rows: every connection gets the chat’s cards again, up to its newest 200, so one missed while no stream was open is right after a reconnect. The stored rows are the record; the deltas only let a reply appear as it is written.

Example


GET /api/agents/:agentId/shell

Reports whether a clawboo-native agent may ask to run commands. The value is the tools.shell field of the agent’s stored config, and it decides whether the run_command tool is offered to the model at all. It does not let a command run on its own: run_command puts every command in front of a person, remembers nothing and has no allowlist, so a command allowed once asks again the next time. A missing field reads as off, and the native defaults leave it out, so a new native agent starts with the shell off. This switch is separate from /api/exec-settings (see Agent settings API), which writes the OpenClaw Gateway’s exec policy. Nothing reads that policy for a native agent, so this route refuses every other runtime by name.
  • Path params: agentId.
  • Request body: none.

Responses

200 OK:
400 Bad Request: the agent is not on the clawboo-native runtime. The response names the runtime it found:
404 Not Found: no agent with that id, or a native agent with no stored config:
500 Internal Server Error: any other failure, redacted:

Example


POST /api/agents/:agentId/shell

A person’s route. A caller that does not pass the person check gets 403 { "ok": false, "error": "person_only" }, and nothing changes. A script you run yourself can pass it with the two Sec-Fetch- headers in the example. Turns the switch on or off. Rate tier: sensitive. Changing what an agent may ask to run is a permissions change, so this route shares the 60-requests-a-minute sensitive budget (see rate limits). The route writes the whole tools record back with only shell changed, so the agent’s other tool flags (memory, tasks, teamchat and the reserved custom list) are kept. It then reads the config back and answers with what is stored, not with what you sent.
  • Path params: agentId.
  • Request body:
The confirmation the dashboard shows before switching this on exists only in the browser. This route accepts { "enabled": true } directly, and POST /api/agents with sourceId: 'clawboo-native' can set execConfig.tools.shell at creation. Native agents created from the dashboard start with the shell off.
Switching this on is necessary for run_command to exist, but not enough. The tool is also left out of any run without a working directory. Team chat, 1:1 chat, delegated turns and task runs all carry one: the team’s folder, or the task’s worktree. It is never offered on Windows.

Responses

200 OK: the stored value after the write:
400 Bad Request: enabled is missing or is not a boolean:
400 Bad Request: the agent is not on the clawboo-native runtime:
404 Not Found: no agent with that id, or a native agent with no stored config:
429 Too Many Requests: the sensitive ceiling:
500 Internal Server Error: any other failure, redacted:

Example


Error envelope

Most error bodies are { "error": "<message>" }. The exceptions:
  • The two 422 responses (create, and the file PUT) add findings, the injection findings that blocked the write: each has pattern, severity, intent, message, line, excerpt and fingerprint.
  • The two screenshot routes answer { "ok": false, "error": "..." }.
  • The two shell routes add runtime to their wrong-runtime 400, naming the runtime they found.
  • GET /api/agents/:agentId/chat/stream has no JSON error: its only failure before the stream opens is a bare 400 with no body.
A 503 { "error": "gateway_disconnected" } means the route needed the OpenClaw Gateway for an OpenClaw agent and the server’s connection is down. The list and single-agent reads never answer it: they serve SQLite.
  • Agent model: what an agent is, Boo Zero, and how agents relate to teams.
  • Agents: the agent files each runtime reads, and the dashboard screens behind these routes.
  • Agent settings API: personality, OpenClaw exec settings and skills.
  • Teams API: add an agent to a team, and team chat.
  • Runtimes API: run a board task on a runtime.
  • Agent sources: how OpenClaw agents are synced into SQLite.
Last modified on November 18, 2026