Skip to main content
Clawboo spreads its configuration over a few places. Use this page to find where a setting lives, how to change it, and which files Clawboo reads or writes. ~/.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:
  1. 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.
  2. With no usable token, Clawboo falls back to OpenClaw’s openclaw.json (gateway.auth.token and gateway.port). It uses that token and, when settings.json has no URL, connects to ws://localhost:<port>.
  3. Otherwise the literal value is used.
The file is plain JSON, readable only by you (mode 0600). A folder Clawboo creates for it is owner-only (mode 0700); a folder that already exists keeps its mode. Saving a setting narrows an older file to 0600 first, and refuses to save when it cannot and the file is readable by others.
A studioAccessToken key in settings.json does nothing. The access gate reads only the STUDIO_ACCESS_TOKEN environment variable, so a token written here leaves the dashboard open. See Environment variables for the variable and its rules.

Settings stored in the database

Most settings you change in the dashboard are rows in the settings 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 writes api-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:
  1. On Linux, pidNamespace and initStart are your own process’s.
  2. A process with that pid exists.
  3. 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), CreationDate of Win32_Process on Windows. A process that started at another time holds a reused process id. The 15 seconds absorb start times that ps reports to the second and the moment between a process’s creation and Node’s start.
  4. bootAt is within 10 seconds of when the computer last started (now minus the system’s uptime).
The marker is stale, and its port not to be trusted, when no process has that 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 in secrets/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.
Keys you add in Settings > Providers, or in OpenClaw’s setup inside Clawboo, are also written in plain text to OpenClaw’s ~/.openclaw/.env and to each OpenClaw agent’s auth-profiles.json, because the OpenClaw Gateway reads them there. Disconnecting the provider removes both copies.Every OpenRouter, Anthropic or OpenAI key Hermes reads, from any of these places or from the server’s environment, is also written in plain text to each Hermes agent’s profile .env (runtimes/hermes/_gateway/profiles/<profile>/.env, mode 0600), and stays there between runs for the jobs Hermes runs on its own. A key you connect, replace or remove anywhere in Clawboo reaches every profile right away. Otherwise, a key you enter on a runtime’s own card in Settings > Runtimes stays only in the encrypted vault.

OpenClaw files Clawboo reads and writes

Clawboo finds OpenClaw’s folder from OPENCLAW_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 when settings.json has 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.
It writes:
  • When you connect or disconnect a provider in Settings > Providers or OpenClaw’s setup: the key line in .env and the <provider>:default profile in every agent’s auth-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 or OLLAMA_API_KEY=ollama-local for Ollama), and the Gateway URL and token in settings.json. With OLLAMA_BASE_URL set, the Ollama address goes into openclaw.json too.
  • 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.servers and adds OpenClaw’s sub-agent tools (sessions_spawn, sessions_yield) to tools.deny, alongside your own entries.
  • When the Gateway refuses to start and asks for a repair: it runs openclaw doctor --fix --non-interactive once, then tries again.
Clawboo writes .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 with codex 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.
  • settings.json is read by loadSettings() and written by saveSettings() in @clawboo/config; GET /api/settings returns gatewayUrl, hasToken and firstRunDismissedAt, and POST /api/settings accepts only gatewayUrl, gatewayToken and firstRunDismissedAt.
  • The server opens <CLAWBOO_HOME>/clawboo.db. The MCP stdio bins default to a different file, ~/.openclaw/clawboo/clawboo.db, unless CLAWBOO_DB_PATH is set; the stdio snippets from GET /api/mcp/config set it. This split is deliberate.
  • Source of truth: packages/config/src/index.ts (with the folder defaults in paths.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.
Last modified on November 18, 2026