Skip to main content
Use this page when you want to work with one agent (a Boo) directly: chat with it, edit its config files, tune its personality, or create and remove it. Every Boo is a real agent record backed by an AgentSource; its config lives in seven Markdown files that the runtime reads on each turn. The whole surface is the agent detail view (AgentDetailView), backed by /api/agents/:agentId/files/:name for file I/O and /api/personality for the sliders. This page documents what each panel does, how the four core files map to behavior, and where edits persist.

​
Prerequisites

Agent file reads and writes go through the connected runtime. The editor and personality sliders are no-ops while the connection is down (saving never fires; the file PUT returns 503 gateway_disconnected).
  • A connected runtime (OpenClaw Gateway, or a non-OpenClaw runtime, see Connecting runtimes).
  • At least one Boo. If you have none, create one (see Create a Boo).

​
Open the agent detail view

Three entry points open the detail view (they all call openAgent(agentId)):
  • The agent list: click a Boo in the left column (AgentListColumn).
  • The Ghost Graph: right-click a Boo node → Chat, Edit personality, or Edit files. See Ghost Graph.
  • The fleet sidebar: click a Boo’s edit affordance.
The view is a 3-panel resizable layout under one shared 44 px header (the agent’s avatar, name, connection dot, and the GitHub Star pill):
The panel split sizes persist to localStorage (the Group has an id), so your layout survives a reload. Drag a ResizeHandle to resize. The MiniGraph header fuses the agent’s runtime icon with a model selector for changing this agent’s model. A native (clawboo-native) agent picks from the native model catalog and the change is saved to its AgentConfig via PATCH /api/agents/:agentId/model (no Gateway needed); an OpenClaw agent picks from the OpenClaw catalog and the change is written as a per-agent override in openclaw.json; a Hermes agent picks from the live OpenRouter catalog (stored in execConfig, routed through OpenRouter). Codex and Claude Code run their account/SDK default, so they show a “runtime-managed model” note instead of a picker. The agent detail view: chat on the left, mini-graph and the tabbed inline editor on the right.

​
Edit the agent files

The inline editor’s file tabs are a single CodeMirror 6 instance (Markdown highlighting, line wrapping). The four core tabs always show; the three extra OpenClaw files appear as tabs only when they already have content.

​
Steps

  1. Pick a file tab. The active tab gets an accent underline; the CodeMirror document swaps to that file’s content. All seven files are loaded in parallel when the view opens.
  2. Edit. A modified tab shows an amber dot. The whole editor footer reads Unsaved while any file is dirty.
  3. Save. Click Save, or press Cmd/Ctrl+S. The write goes through a per-agent mutation queue (serialized so concurrent writes never race) to PUT /api/agents/:agentId/files/:name, and a toast confirms Saved <file>.
  4. Saving TOOLS.md or AGENTS.md also triggers a Ghost Graph refresh, so new skill nodes or routing edges appear without a manual reload.
You don’t have to save before switching agents or leaving the view; the editor saves all dirty files automatically on unmount (best-effort). Saving explicitly is still safer when the connection is flaky.

​
Tune the personality

The Personality tab has five sliders, each 0–100. Moving a slider does not save; the save fires on pointer-up (the commit). Each slider shows a one-line description that updates live as you drag.

​
Where values persist

A commit writes to two places:
  1. SQLite (POST /api/personality): the source of truth for the slider values. The handler stores a { values, customText } JSON wrapper in the agent’s personality_config column (upserting the agent row if it doesn’t exist yet).
  2. SOUL.md (best-effort): the sliders are rendered into Markdown sections and merged into SOUL.md below a --- separator and a “marker. The merge reads the currentSOUL.md, strips any old personality block, preserves the role description above the separator, and writes the result back.
Because SQLite is authoritative, the slider positions survive even if the SOUL.md write fails. When the detail view loads SOUL.md, it strips the stale personality block and re-merges the SQLite values, so the editor’s SOUL tab always reflects the current sliders.
Writes through the Gateway’s agent-file API are best-effort and may not persist, so the slider values live in SQLite as the source of truth. Treat the SOUL.md block as a generated projection of the SQLite source, not the other way around.

​
Custom instructions instead of sliders

Click Use Custom Instructions to switch to a free-text override. The textarea content saves on blur or Cmd/Ctrl+S (POST /api/personality with customText), and is merged into SOUL.md under a “ marker; it overrides the slider-generated block. Switch to Sliders clears the custom text and restores the slider personality. The footer’s Preview SOUL.md toggle shows the merged result (role description plus the active personality block) so you can see exactly what the runtime will read.

​
The other editor tabs

​
Create a Boo

Click Create Boo in the agent list (or the fleet sidebar) to open CreateBooModal.
  1. Enter a Name (required) and an optional Role (free text that becomes the base SOUL.md).
  2. Click Create Boo (or press Enter). The modal:
    • merges the default personality (all five sliders at 50) into the role text and creates the agent via POST /api/agents; the server resolves the workspace and writes SOUL.md, IDENTITY.md, and TOOLS.md;
    • persists the default personality to SQLite (POST /api/personality);
    • assigns the new Boo to the currently selected team (best-effort) via POST /api/teams/:id/agents.
Create requires a connected runtime. With no connection the modal shows Not connected to Gateway and does nothing. A name collision with an existing agent surfaces as a create error.

​
Delete a Boo

Hover a Boo in the agent list and click the trash icon. deleteAgentOperation:
  1. archives the agent via DELETE /api/agents/:agentId; the server deletes it upstream (the Gateway) and removes the SQLite row plus its FK-referenced cost/approval rows. If the connection is down, the server falls back to a SQLite-only cleanup and returns { ok: true, upstreamDeleted: false };
  2. removes it from the in-memory fleet store;
  3. re-identifies Boo Zero from the remaining agents (in case the deleted Boo was the leader);
  4. clears its transcript and deletes its chat history.
Deletion is not reversible. The agent’s files and config are removed from both the runtime and SQLite. There is no undo.

​
Verify it worked

  • File save: re-open the file tab (or reload the view) and confirm the saved content is loaded back from GET /api/agents/:agentId/files/:name. The footer reads Saved.
  • Personality: reload the detail view; the sliders should restore their saved positions (read from GET /api/personality?agentId=...), and Preview SOUL.md should show the matching personality block.
  • Create / delete: the agent appears in (or disappears from) the agent list. After a create, GET /api/agents includes the new record.

​
Troubleshooting

Edits don’t save. The editor and sliders write through the connected runtime. If the connection dot in the header is amber, file writes return 503 and slider commits silently fail. Reconnect the runtime, then retry the save.
Personality slider moved back after I switched agents. A slider commit fires on pointer-up; a drag with no release doesn’t save. Release the thumb (or use a keyboard arrow + release) to commit, and watch for the Saved ✓ indicator.
An invalid file name returns 400. The file routes validate :name against the seven known agent files (AGENTS.md, SOUL.md, IDENTITY.md, USER.md, TOOLS.md, HEARTBEAT.md, MEMORY.md). Any other name is rejected with { error: "invalid file name" }.

​
See also

  • Ghost Graph, the per-agent mini-graph and the team-wide canvas
  • Group chat, work with a whole team at once
  • Boo Zero, the universal team leader’s Brief and rules
  • /api/agents reference, full request/response shapes for the registry, files, and sessions
  • Glossary, Boo, Boo Zero, AgentSource, registry of record
Last modified on August 6, 2026