~/.clawboo is the default for CLAWBOO_HOME and ~/.openclaw the default for OPENCLAW_STATE_DIR; every path under them on this page moves with them. The work folder and the runtimes folder move with CLAWBOO_HOME too, to <CLAWBOO_HOME>-work and <CLAWBOO_HOME>-runtimes, unless CLAWBOO_WORK_DIR or CLAWBOO_RUNTIMES_DIR names them. The ~/.codex, ~/.hermes and ~/.claude paths below do not.
On a machine several teams share, one tuning variable is worth knowing: CLAWBOO_MAX_CONCURRENT_RUNS, how many agent runs execute at once across the whole server (8 by default). Runs beyond it wait their turn rather than fail. Environment variables describes it with the rest.
settings.json
<CLAWBOO_HOME>/settings.json holds the connection to your OpenClaw Gateway. Clawboo creates it the first time it saves a setting; a missing or unreadable file means the defaults apply.
How the token is resolved:
- A value written as a template, such as
${GATEWAY_AUTH_TOKEN}, is read from the server’s environment first, then from OpenClaw’s~/.openclaw/.env. - With no usable token, Clawboo falls back to OpenClaw’s
openclaw.json(gateway.auth.tokenandgateway.port). It uses that token and, whensettings.jsonhas no URL, connects tows://localhost:<port>. - Otherwise the literal value is used.
Settings stored in the database
Most settings you change in the dashboard are rows in thesettings table of clawboo.db, so they travel with a database backup.
The table has no schema of its own beyond key and value; Database schema describes it.
Preferences stored in your browser
The theme, sidebar width and collapsed state, panel layout, Board view, Org chart layout and a few one-time flags live in your browser’s local storage. They apply to one browser only, a database backup does not include them, and clearing the site’s data resets them.Files under ~/.clawboo
Clawboo owns everything in this folder. The bundled server also runs with it as its working directory. Data and state explains what to back up, what is safe to delete, and how to reset.
The database files,
settings.json and secrets are owner-only (mode 0600) in an owner-only folder (0700).
Start marker
From 0.9.0, the server writesapi-port.json next to api-port.txt, right after it, once it is listening. api-port.txt still holds only the port number, so older readers keep working. The marker also names the process that wrote the port. A server that crashed or was killed leaves both files behind, and any program may take its port afterwards; the marker lets a reader tell that record from a running server’s.
Every field is always there. A later release may add fields but never renames or retypes these, so a reader should ignore fields it does not know. The server writes the marker to a temporary file of its own and renames it into place, so a reader never sees half of one. On Windows, when another program holds the file open and the rename is refused, it is written in place instead; a reader that cannot parse it should treat it as missing. At a clean shutdown the server removes the marker only when it is still the one the server wrote (the same
pid, startedAt, bootAt, pidNamespace and initStart), so a second server’s marker stays, even one with the same pid in another container.
Checking it. Never trust the port because the file exists. Trust it only when all of these hold:
- On Linux,
pidNamespaceandinitStartare your own process’s. - A process with that
pidexists. - That process started within 15 seconds of
startedAt:TZ=UTC0 LC_ALL=C ps -o lstart= -p <pid>on macOS and Linux (in UTC, since local time reads the same for the two passes of the hour a DST change repeats),CreationDateofWin32_Processon Windows. A process that started at another time holds a reused process id. The 15 seconds absorb start times thatpsreports to the second and the moment between a process’s creation and Node’s start. bootAtis within 10 seconds of when the computer last started (now minus the system’s uptime).
pid, when the marker is from an earlier run of the PID namespace, or when the process holding the pid started at another time (on this boot, or after a reboot).
The marker tells a running server from the record of one that is gone. It is not proof of who answers on the port: a process that was given the server’s pid within 15 seconds of the server’s start (so the server stopped within that time) and took its port passes every check above. Before you send a secret to the port, treat a marker that checks out as narrowing that risk, not ruling it out.
When bootAt is more than 10 seconds off but the process still started at startedAt, or started exactly that much later, you cannot tell: a wall clock stepped since the server started moves the boot reading (and, on Linux, the start time ps reports) by the step, so it looks like a reboot. The same goes when start times cannot be read, or the marker names a PID namespace you are not in (or yours cannot be read). Then go by api-port.txt alone, as before the marker. Do the same with no marker (a server from 0.8.0 or earlier), and when api-port.txt is newer than the marker. Then the marker describes an earlier server, and the one that wrote api-port.txt since left no marker of its own: a server from 0.8.0 or earlier, or one whose marker write failed or that stopped before it, so there is nothing to check it by. Going by api-port.txt alone then keeps a running server reachable, and, as with no marker, cannot tell it from a program that took the port after that server crashed. When the two files name different ports and the marker checks out, go by the marker: two servers that started together can leave the files naming different ports, and the marker’s server is the one shown to be running.
The clawboo command follows these rules before it trusts the recorded port, and checks a server it found running again, start time included, on each request: a server that crashes while the command runs can have its pid handed to another process. A stale marker’s port gets no access token and does not count as a busy server holding the port, and clawboo stop removes a stale marker with api-port.txt (see CLI).
Files in the work folder
Your agents’ work lives in the work folder:CLAWBOO_WORK_DIR, else <CLAWBOO_HOME>-work when CLAWBOO_HOME is set, else ~/clawboo-work. It must be outside ~/.clawboo, or the server refuses to start. The work folder covers how older work moves there.
Everything Clawboo creates in the work folder is owner-only (0700). With
CLAWBOO_AGENT_USER set, the work folder defaults to <agent home>/work and belongs to the agent user, and so do each agent’s runtime home and browser profile, under <agent home>/runtimes/ and <agent home>/browser-profiles/ instead of ~/.clawboo. See With agents as their own user.
With CLAWBOO_AGENT_USERS (a user per agent, Linux only for now), the work folder is the one CLAWBOO_WORK_DIR names and is yours (0711), no agent outside a team can reach that team’s folder, and an agent with no team works in teams/_agent-<agent id> instead of _no-team.
Files in the runtimes folder
The runtimes Clawboo installs for you go in the runtimes folder:CLAWBOO_RUNTIMES_DIR, else <CLAWBOO_HOME>-runtimes when CLAWBOO_HOME is set, else ~/clawboo-runtimes. It must be apart from ~/.clawboo and the work folder, or Clawboo installs nothing there and runs nothing from it. The runtimes folder covers how an install works and which copy Clawboo runs.
Folders Clawboo creates here are
0755, and each finished install is readable by others and writable only by the server’s user.
Saved keys
Provider keys, connector secrets and sign-in tokens are encrypted with AES-256-GCM insecrets/runtime-keys.json, under the key in secrets/master.key. This protects a copied or synced vault file; a program running as your user can still read both files. To keep the key apart from the vault, set CLAWBOO_SECRETS_MASTER_KEY. If the key changes, saved keys read as missing and System Health reports that the master key changed.
A runtime looks for its key in this order: the server’s environment, the vault, then OpenClaw’s ~/.openclaw/.env. After you disconnect a runtime on its card in Settings > Runtimes, that runtime uses only the vault until you connect it again. That disconnect deletes the vault keys only that runtime reads and keeps any key another runtime also reads; Providers and runtimes covers connecting and disconnecting.
OpenClaw files Clawboo reads and writes
Clawboo finds OpenClaw’s folder fromOPENCLAW_STATE_DIR (or the older MOLTBOT_STATE_DIR and CLAWDBOT_STATE_DIR), else the first of ~/.openclaw, ~/.clawdbot and ~/.moltbot that exists, else ~/.openclaw.
It reads:
openclaw.json: the Gateway’s port and token whensettings.jsonhas none, and the settings the System panel shows..env: a fallback for provider keys and for${NAME}token templates.agents/<id>/agent/auth-profiles.json: which providers each OpenClaw agent has keys for.
- When you connect or disconnect a provider in Settings > Providers or OpenClaw’s setup: the key line in
.envand the<provider>:defaultprofile in every agent’sauth-profiles.json. - When you set up OpenClaw from the dashboard:
openclaw.json(including OpenClaw’s tool sandbox off,agents.defaults.sandbox.mode: off, when you set none) and.env(the Gateway token, plus the provider key orOLLAMA_API_KEY=ollama-localfor Ollama), and the Gateway URL and token insettings.json. WithOLLAMA_BASE_URLset, the Ollama address goes intoopenclaw.jsontoo. - When you change OpenClaw settings from the dashboard:
openclaw.json, and any keys you enter. That covers the System panel, OpenClaw’s default model, an OpenClaw agent’s model, and drawing a routing link on the Org chart, which turns on agent-to-agent messaging. - Each time it connects to the Gateway: through the Gateway, it registers Clawboo’s Memory, Tasks and Tools servers under
mcp.serversand adds OpenClaw’s sub-agent tools (sessions_spawn,sessions_yield) totools.deny, alongside your own entries. - When the Gateway refuses to start and asks for a repair: it runs
openclaw doctor --fix --non-interactiveonce, then tries again.
.env and each auth-profiles.json owner-only (mode 0600), narrowing an existing file first, and creates OpenClaw’s folder owner-only (0700) when it does not exist.
Resetting ~/.clawboo leaves all of these in place, so provider keys saved this way keep working for OpenClaw. OPENCLAW_CONFIG_PATH is not read; the config is always openclaw.json inside that folder.
Other folders Clawboo reads
~/.codex/auth.json(or$CODEX_HOME/auth.json): to see whether you signed in withcodex login. Each Codex agent then runs with its own home under~/.clawboo/runtimes/.~/.hermes/auth.json(or$HERMES_HOME/auth.json): to see whether you signed in to Hermes.~/.claude: Claude Code agents run with your real home folder and save their session files under~/.claude/projects. Clawboo starts them without your own settings, MCP servers and memory files from there.
Under the hood
Under the hood
settings.jsonis read byloadSettings()and written bysaveSettings()in@clawboo/config;GET /api/settingsreturnsgatewayUrl,hasTokenandfirstRunDismissedAt, andPOST /api/settingsaccepts onlygatewayUrl,gatewayTokenandfirstRunDismissedAt.- The server opens
<CLAWBOO_HOME>/clawboo.db. The MCP stdio bins default to a different file,~/.openclaw/clawboo/clawboo.db, unlessCLAWBOO_DB_PATHis set; the stdio snippets fromGET /api/mcp/configset it. This split is deliberate. - Source of truth:
packages/config/src/index.ts(with the folder defaults inpaths.ts),apps/web/server/lib/runtimeFolder.ts,apps/web/server/lib/secretsVault.ts,apps/web/server/lib/openclawEnv.ts,apps/web/server/lib/providerKeys.ts,apps/web/server/api/system.ts,apps/web/server/lib/agentSource/openClawAgentSource.ts.
Related
- Environment variables: every variable, including the ones that move these folders
- Data and state: back up, restore and reset
- Security: the access gate, the vault and what each protects
- Providers and runtimes: connect keys and runtimes from the dashboard
- Settings API:
GETandPOST /api/settings