clawboo. The server reads most of them once at startup, so run clawboo restart after a change.
Durations are in milliseconds, and an unset, empty or non-numeric duration means the default. Each variable’s section below says how it handles other values. Agent runtimes and OpenClaw read variables of their own, which this page does not cover.
HOSTNAME, OPENCLAW_CONFIG_PATH, CLAWBOO_API_URL and GATEWAY_AUTH_TOKEN (outside a ${...} template) are not read. TAVILY_API_KEY is no longer used: Clawboo has no built-in web search, so connect a search connector such as Exa Search instead. Variables Clawboo sets on the processes it starts are listed under Set by Clawboo.
Access and network
HOST
The network address the dashboard listens on.- Type: hostname or IP address
- Default:
127.0.0.1, so only this machine can connect - Example:
HOST=0.0.0.0
localhost, 127.x.x.x, ::1) exposes the dashboard to your network. The server then refuses to start, exiting with code 1, when the access gate is off (STUDIO_ACCESS_TOKEN set blank), unless CLAWBOO_ALLOW_INSECURE=1 is set. A default install has its per-install token, so it starts. Prefer 0.0.0.0 to a single LAN address: Clawboo’s own agents reach its MCP servers at 127.0.0.1, which a single-address bind does not answer. A wide bind without CLAWBOO_ALLOWED_ORIGINS also logs a warning that browsers on other machines will be blocked.
HOSTNAME is ignored. Docker, systemd and many CI runners set it automatically, so widening the bind always takes an explicit HOST. Self-host securely walks through reaching Clawboo from another machine.
STUDIO_ACCESS_TOKEN
The access token, in place of the per-install one.- Type: string of letters, digits,
.,_,~and- - Default: unset, so the server uses the per-install token in
~/.clawboo/access-token(underCLAWBOO_HOME), and makes it on the first start - Blank (
STUDIO_ACCESS_TOKEN=): no token, so the access gate is off and every/api/*route is open to anything that can reach the server.pnpm devsets it blank unless your shell sets it. - Example:
STUDIO_ACCESS_TOKEN=$(openssl rand -hex 32), saved somewhere you can reuse it
/api/* request and the Gateway WebSocket need the clawboo_access cookie, with this token or the per-install one. clawboo opens the browser with a one-time sign-in link that sets it, and clawboo open does the same for a running server. With a token you know, you can also open http://<host>:<port>/?access_token=<token> once: the right token sets an HttpOnly cookie (scoped to your CLAWBOO_BASE_PATH, SameSite=Lax, and Secure when the request arrives with X-Forwarded-Proto: https) and redirects to the same address without the token. A wrong token answers 401 Invalid Clawboo access token. and a missing cookie answers 401 Clawboo access token required. Run `clawboo open` on the computer running Clawboo, or open /?access_token=<token> once to set a cookie. The page shell and its static files load without the cookie. Security covers one-time links and the token file.
Clawboo’s own runtimes reach its MCP servers with a per-install attach token instead of the cookie, and only on direct connections from 127.0.0.1. The variable is read only from the environment; a studioAccessToken key in settings.json does nothing. It is removed from the environment of every runtime Clawboo starts. The clawboo CLI uses the same token as the server: this variable from its own shell, or the token file when it is unset; see Token-gated installs.
With the gate off, the first request that reaches the server through a reverse proxy logs a one-time SECURITY: warning, because such a proxy delivers every request from 127.0.0.1. Security explains what the gate does and does not protect.
CLAWBOO_ALLOW_INSECURE
Lets the server start on a wide bind with no access token.- Type: flag, exactly
1 - Default: unset
- Example:
CLAWBOO_ALLOW_INSECURE=1
HOST and no token starts the server with a loud SECURITY: warning instead of exiting. It has no effect on a loopback bind or when a token is set, and it does not skip the refusal of a token with an unsupported character. Use it only behind a proxy that authenticates every request.
CLAWBOO_ALLOWED_ORIGINS
Browser origins, beyond this machine’s, that may call the API.- Type: comma-separated origins, each
scheme://host[:port] - Default: none extra.
httpandhttpsonlocalhost,127.0.0.1and[::1]at the dashboard port, plus the bind address, are always allowed. - Example:
CLAWBOO_ALLOWED_ORIGINS=https://clawboo.example.com
/api/* or the Gateway WebSocket from any other origin gets 403 Cross-origin request blocked. The list only adds origins; it never turns the check off. Entries that are not valid origins are skipped.
CLAWBOO_ALLOWED_HOSTS
Host header values the server accepts, beyond this machine’s.
- Type: comma-separated hostnames
- Default: none extra.
localhost,127.x.x.x,::1and the bind address are always accepted. - Example:
CLAWBOO_ALLOWED_HOSTS=clawboo.example.com
CLAWBOO_ALLOWED_ORIGINS, or every /api/* call answers 403 Cross-origin request blocked.
CLAWBOO_BASE_PATH
A URL prefix to serve the whole app under, for sharing a hostname with other apps behind a proxy.- Type: URL path
- Default: unset, so the app is served at
/ - Example:
CLAWBOO_BASE_PATH=/clawboo
- The dashboard,
/api, the event streams and the Gateway WebSocket all move under the prefix. The built app needs no rebuild. clawboo,/clawbooand/clawboo/all mean/clawboo. Empty or/means the root.- These values stop the server at startup with
SECURITY/CONFIG: CLAWBOO_BASE_PATH is invalid (<reason>): whitespace, a backslash,?,#or%, an empty or./..segment, any character outsideA-Z a-z 0-9 . _ ~ -, or a first segment ofapi. - The unprefixed
/apistays available for the CLI and Clawboo’s own runtimes, with the same checks. /and the bare prefix redirect to<prefix>/. Any other unprefixed path answers 404Not found. This Clawboo is served under <prefix>/.- The access cookie is scoped to the prefix, so other apps on the same hostname never receive it. The CLI adds the prefix to the URLs it prints.
- What the dashboard keeps in the browser (theme, layout, board view, onboarding and tour progress, the browser alert choice) is stored under keys that start with the prefix, such as
/clawboo:clawboo.theme, so two instances under different prefixes on one hostname keep their own. A key saved before the prefix existed moves to the first instance that reads it; two instances whose pages load at the same moment can each keep a copy. At the root, keys keep their old names.
CLAWBOO_SECRETS_MASTER_KEY
The key that encrypts saved provider keys and connector secrets.- Type: a 32-byte key as base64, 64 hex characters, or exactly 32 characters
- Default: unset, so Clawboo generates
<CLAWBOO_HOME>/secrets/master.key - Example:
CLAWBOO_SECRETS_MASTER_KEY="$(cat ~/.config/clawboo/master.key)"
~/.clawboo, and give it the same value every time. An invalid value stops any use of the vault with an error that lists the accepted forms. A different key from the one that encrypted the vault makes saved keys read as missing, and System Health reports that the master key changed. It is removed from the environment of every runtime Clawboo starts.
CLAWBOO_APP_LINK_PUBLIC_KEY
Set by an app that starts Clawboo itself, such as the desktop app, so that the requests it signs carry a name. Leave it unset otherwise.- Type: an Ed25519 public key, as a PEM public key (
-----BEGIN PUBLIC KEY-----), a JWK or a JWKS - Default: unset (off)
- Example:
CLAWBOO_APP_LINK_PUBLIC_KEY='{"kty":"OKP","crv":"Ed25519","x":"…"}'
/api/ request may carry a token in the clawboo-app-identity header (a Gateway WebSocket upgrade that carries one is refused), signed with the app’s private key, that names one of the app’s own people. Such a person’s id starts with account:, and the request then counts as theirs, as a sign-in proxy’s person’s does, on the few routes the app signs for: sending work, answering an approval and checking its link. Anywhere else the token is refused. A request without the header works as before. A token that does not verify gets 401, and an allow_always answer to an approval from one of these people gets 403. An app that starts Clawboo has the token’s format.
Clawboo reads it from the environment only, never from the operator file, where an agent running as your user could swap in a key of its own. A key that is not an Ed25519 public key stops the server at startup.
Ports
CLAWBOO_API_PORT
The exact port for the dashboard.- Type: whole number, 1 to 65535
- Default: unset, so the server takes the first free port from 18790 upward
- Example:
CLAWBOO_API_PORT=18795 clawboo
CLAWBOO_API_PORT=N is already in use. The CLI then checks only this port when it looks for a running dashboard, and clawboo restart sets it on the new server to keep the old port.
CLAWBOO_API_PORT_START
The first port of the automatic scan.- Type: whole number, 1 to 65535
- Default:
18790 - Example:
CLAWBOO_API_PORT_START=19000
CLAWBOO_API_PORT and PORT are unset. The server tries 20 consecutive ports from here. The CLI does not scan from this value; it finds such a server through api-port.txt.
PORT
A port set by a hosting platform.- Type: whole number, 1 to 65535
- Default: unset
- Example:
PORT=8080
CLAWBOO_API_PORT is unset and the server is not running in development mode (--dev). Like CLAWBOO_API_PORT it has no fallback: a taken port stops the server with PORT=N is already in use (set by hosting platform).
CLAWBOO_HERMES_GATEWAY_PORT
The port the Hermes gateway’s API server listens on, on127.0.0.1 only.
- Type: whole number, 1 to 65535
- Default:
8642, Hermes’s own default - Example:
CLAWBOO_HERMES_GATEWAY_PORT=9642
CLAWBOO_HERMES_STOP_GRACE_MS
From 0.9.0: when Clawboo stops, how long the Hermes gateway gets to finish its planned stop after Clawboo sends it SIGINT, before Clawboo kills it and the processes it started.- Type: whole number of milliseconds, 0 to 8000
- Default:
5000 - Example:
CLAWBOO_HERMES_STOP_GRACE_MS=3000
Folders
CLAWBOO_HOME
The data folder, where Clawboo keeps its own state.- Type: path; a leading
~is expanded and a relative path is resolved - Default:
~/.clawboo - Example:
CLAWBOO_HOME=/srv/clawboo
settings.json, the vault, api-port.txt, the logs, agent browser profiles, per-agent runtime homes and the history of team folders. It also moves the default work folder, which becomes <CLAWBOO_HOME>-work (see CLAWBOO_WORK_DIR), and the default runtimes folder, which becomes <CLAWBOO_HOME>-runtimes (see CLAWBOO_RUNTIMES_DIR). With CLAWBOO_AGENT_USER set, the work folder, the runtime homes and the browser profiles are in the agent user’s home instead. The bundled server also runs with it as its working directory. Use the same value for every clawboo command, or stop and backup look in the wrong place. Configuration lists every file inside.
CLAWBOO_WORK_DIR
The work folder, where all agent work goes: team folders (teams/), task worktrees (worktrees/) and review checkouts (reviews/).
- Type: path; a leading
~is expanded and a relative path is resolved - Default:
<CLAWBOO_HOME>-workwhenCLAWBOO_HOMEis set, else~/clawboo-work(%USERPROFILE%\clawboo-workon Windows) - Example:
CLAWBOO_WORK_DIR=/srv/clawboo-work
0700). At startup it moves team folders and task checkouts that an older version made in CLAWBOO_HOME into this folder, leaving a link at each old path. Changing the value is a move too: the next start moves this install’s work from the previous folder to the new one.
The server refuses to start when this folder is the data folder, sits inside it or contains it, and when a value you set names a folder it cannot create. When the variable is unset and the default cannot be created, Clawboo logs a warning and keeps new work in CLAWBOO_HOME. In a container, set it to a second volume or folder. See The work folder.
With CLAWBOO_AGENT_USER set, the default is <agent home>/work, in the agent user’s home folder, and a folder you name must already exist and belong to the agent user. Clawboo does not fall back to CLAWBOO_HOME, and it does not move older work: it copies team folders in once and leaves the originals where they were (see With agents as their own user).
With CLAWBOO_AGENT_USERS set, this variable is required, and the folder must be yours, with mode 0711.
CLAWBOO_RUNTIMES_DIR
The runtimes folder, where Clawboo installs the runtimes it manages: OpenClaw, Claude Code’s Agent SDK, Codex and Hermes.- Type: path; a leading
~is expanded and a relative path is resolved - Default:
<CLAWBOO_HOME>-runtimeswhenCLAWBOO_HOMEis set, else~/clawboo-runtimes(%USERPROFILE%\clawboo-runtimeson Windows) - Example:
CLAWBOO_RUNTIMES_DIR=/srv/clawboo-runtimes
0755, and each finished install is readable by other users and writable only by you. Clawboo looks here for a runtime before your PATH.
Clawboo installs nothing into this folder, and runs nothing from it, when it is the data folder or the work folder, sits inside one or contains one, or when it, its bin/ or a launcher belongs to another user or others can write to it. It then uses a runtime on your PATH instead, and the server still starts. Changing the value moves nothing: install the runtimes again from Settings > Runtimes. See The runtimes folder.
OPENCLAW_STATE_DIR
OpenClaw’s folder.- Type: path; a leading
~is expanded - Default: the first of
~/.openclaw,~/.clawdbotand~/.moltbotthat exists, else~/.openclaw - Example:
OPENCLAW_STATE_DIR=/srv/openclaw
openclaw.json, .env and agent profiles here, and writes to them when you connect a provider key, set up OpenClaw or change its settings from the dashboard. MOLTBOT_STATE_DIR and CLAWDBOT_STATE_DIR are older names, checked in that order when this one is unset. Configuration lists every read and write.
CLAWBOO_DB_PATH
The database file the MCP stdio bins open.- Type: path (not
~-expanded; use$HOME) - Default:
~/.openclaw/clawboo/clawboo.db - Example:
CLAWBOO_DB_PATH="$HOME/.clawboo/clawboo.db" clawboo-mcp-tasks
clawboo-mcp-* bins read it; the dashboard server always uses <CLAWBOO_HOME>/clawboo.db. The bins’ default is a different file, so set this whenever you run a bin yourself and want it to see the dashboard’s board and memory. The stdio snippets from GET /api/mcp/config already include it.
CLAWBOO_UI_DIR
The folder of built dashboard files the server serves.- Type: path
- Default: the
uifolder next to the bundled server - Example:
CLAWBOO_UI_DIR=/opt/clawboo/ui
The Clawboo dashboard could not be read from disk. Check CLAWBOO_UI_DIR.
CLAWBOO_CATALOG_INDEX_URL
Where the marketplace catalog index comes from.- Type:
httporhttpsURL, with no user name, password or credential parameter in it - Default: the index at the running release’s tag,
https://raw.githubusercontent.com/clawboo/clawboo/refs/tags/clawboo%40<version>/catalog/dist/v1/index.json. A development build (version0.0.0-dev) reads themainbranch’s index instead. - Example:
CLAWBOO_CATALOG_INDEX_URL=https://mirror.example.com/catalog/v1/index.json
catalog/dist/v1/ folder above the server, as in a source checkout, takes precedence. Pack files are fetched relative to the index, and each is checked against the index’s digest before use. The index is cached for 6 hours. When it cannot be reached, the marketplace still shows the built-in pack. When the release’s tag has no index (GitHub answers 404), Clawboo reads the main branch’s index for that refresh. An override is used as it is, with no fallback.
The operator settings file key catalogIndexUrl sets the same thing; this variable wins over the file. A value Clawboo cannot use stops the server at startup (see CLAWBOO_OPERATOR_SETTINGS).
Agent isolation
These variables control agent isolation, which runs every agent as a separate operating system user that cannot read Clawboo’s database, vault, key, settings or access token. Run agents as their own user covers setup, the startup check, and what it does not protect. It is not available on Windows: withCLAWBOO_AGENT_USER set there, the server refuses to start. CLAWBOO_AGENT_USERS goes one step further and gives each agent a user of its own (Linux only for now).
CLAWBOO_AGENT_USER
The operating system user every agent runs as. Setting it turns agent isolation on.- Type: user name: letters, digits,
_,-and., starting with a letter or_, at most 32 characters - Default: unset, so agents run as the user Clawboo runs as
- Example:
CLAWBOO_AGENT_USER=clawboo-agent
SECURITY: refusing to start. with the step and the reason, and exits with code 1. It also refuses to start without an access token. A value that is not a user name stops it with CONFIG: refusing to start. Clawboo stops every process the agent user runs when it starts and when it stops, so give each install an agent user of its own. clawboo agent-user plan prints the setup commands, and clawboo agent-user check runs the check without starting the dashboard (see the CLI reference).
CLAWBOO_AGENT_USERS
A pool of operating system users, so each agent runs as a user of its own. Linux only for now, from 0.8.0.- Type: user names separated by commas, or a range of user ids
- Default: unset (off)
- Example:
CLAWBOO_AGENT_USERS=clawboo-a1,clawboo-a2orCLAWBOO_AGENT_USERS=uid:20001-20008
CLAWBOO_AGENT_USER, never with it. It needs CLAWBOO_WORK_DIR, a folder of yours with mode 0711. An agent gets a user from the pool when it is created, oldest agent first, and keeps it. A deleted agent’s user is wiped before another agent gets it. When no user is free, a new agent’s runs refuse with “has no agent user”; an agent never falls back to a shared user. clawboo agent-user plan --pool <n> prints the setup. See A user per agent, and what is not available yet with it.
CLAWBOO_AGENT_GROUPS
The groups for teams, withCLAWBOO_AGENT_USERS.
- Type: group names separated by commas, or a range of group ids
- Default: unset
- Example:
CLAWBOO_AGENT_GROUPS=clawboo-t1,clawboo-t2orCLAWBOO_AGENT_GROUPS=gid:21001-21004
CLAWBOO_AGENT_SWITCH
How the server starts the agent host asCLAWBOO_AGENT_USER on a computer or virtual machine.
- Type:
sudoordoas - Default:
sudo - Example:
CLAWBOO_AGENT_SWITCH=doas
CONFIG: refusing to start. It is not used when CLAWBOO_AGENT_HOST_SOCKET is set. The switch needs a rule that lets the user Clawboo runs as start processes as the agent user without a password; clawboo agent-user plan prints the sudoers rule.
CLAWBOO_AGENT_HOST_SOCKET
The socket of an agent host thatclawboo-launch started.
- Type: absolute path
- Default: unset, so the server starts the agent host itself through
CLAWBOO_AGENT_SWITCH - Set by:
clawboo-launch, on the server it starts, as<CLAWBOO_RUN_DIR>/agent.sock
CONFIG: refusing to start. See Set it up in a container.
CLAWBOO_AGENT_HOST_SCRIPT
The agent host script, the program that runs as the agent user.- Type: path
- Default:
agent-host.jsbeside the server bundle (dist/agent-host.jsin the package), or the build output when the server runs from source - Example:
CLAWBOO_AGENT_HOST_SCRIPT=/opt/clawboo/dist/agent-host.js
clawboo-launch reads it too. The agent user must be able to read the file. Normally you leave it unset.
CLAWBOO_SERVER_USER
The userclawboo-launch runs the server as. Only clawboo-launch reads it.
- Type: user name
- Default: none; the launcher exits with
set CLAWBOO_SERVER_USER to the user the server runs as - Example:
CLAWBOO_SERVER_USER=clawboo
HOME, USER, LOGNAME, CLAWBOO_AGENT_USER and CLAWBOO_AGENT_HOST_SOCKET.
CLAWBOO_RUN_DIR
The folder whereclawboo-launch makes the agent host’s socket, agent.sock. Only clawboo-launch reads it.
- Type: path
- Default:
/run/clawboo - Example:
CLAWBOO_RUN_DIR=/var/run/clawboo
0710, and gives the socket the server’s group, mode 0660.
CLAWBOO_NODE
The Node.js thatclawboo-launch runs the server and the agent host with. Only clawboo-launch reads it.
- Type: path
- Default:
nodeonPATH - Example:
CLAWBOO_NODE=/usr/local/bin/node
Started by an app
CLAWBOO_STOP_ON_DISCONNECT
Set by an app that starts the server as its own child process, with an IPC channel, so that the server stops with the app. Leave it unset otherwise.- Type: flag
- Default: unset, so the server keeps running when its channel closes
- Example:
CLAWBOO_STOP_ON_DISCONNECT=1
1, the server stops when the channel closes (the app quit, crashed or called disconnect()), as it does on SIGTERM: it stops the agent processes it started, closes the database and exits with code 0. Any other value leaves it off, and so does a server started without a channel. A { "type": "shutdown" } message on the channel stops the server the same way whether or not this is set. The server reads it once and removes it from its environment, so the runtimes, connectors and commands it starts do not inherit it. The clawboo launcher never passes it on: it starts the server with a channel, lets go of it and exits, and the server must keep running. See Start it from your own app.
Pinned by an administrator
An administrator who deploys Clawboo for a team can pin these settings for everyone, in one file or with these variables. Settings > System > Deployment shows a pinned setting as “Set by your administrator”, and it cannot be changed there. Run the Clawboo server walks through the file. Which value wins, highest first: what Clawboo itself refuses (an in-app update of an install this user cannot write stays off whatever is pinned), then the key’s variable, then the operator file, then a value saved in Settings > System > Deployment (one value for the whole install, not one per person), then the default. Every flag variable here takes1 or true to turn the setting on and 0 or false to pin it off, in any letter case. Empty or unset pins nothing. Any other value stops the server at startup, exiting with code 1 and logging CONFIG: refusing to start. with the variable and the reason.
CLAWBOO_OPERATOR_SETTINGS
Where the operator settings file is.- Type: path; a leading
~is expanded and a relative path is resolved - Default: unset, so Clawboo looks for
<CLAWBOO_HOME>/operator.jsonand runs without one when it is not there - Example:
CLAWBOO_OPERATOR_SETTINGS=/etc/clawboo/operator.json
CONFIG: refusing to start. and the reason, when:
- this variable names a file that does not exist, or a folder;
- the file is not valid JSON, is not an object, or is larger than 64 KB;
- any user on the machine can write it (on macOS and Linux);
- it has a key Clawboo does not know, or a key whose value has the wrong type;
- a key’s name looks like a credential (containing
token,secret,password,apiKey,credential,privateKeyorauth), or a URL carries a user name, a password or a credential parameter. Keep keys in the vault or in the environment.
Agents run as the same user as the server, so on a shared machine put the file where that user can read it but not write it, such as a root-owned
/etc/clawboo/operator.json, and point this variable at it.
CLAWBOO_DISABLE_SELF_UPDATE
Turns off updating Clawboo from the dashboard.- Type: flag
- Default: unset, so a global install the server’s user can write is offered the update
- Example:
CLAWBOO_DISABLE_SELF_UPDATE=1
GET /api/system/self-version answers as it does with ?local=1 (no call to npm’s registry, latest is null), and POST /api/system/self-update refuses with “In-app updates are turned off for this install by its administrator.” Use it on an install that something else manages, such as a container image, a distro package or a service manager. Operator file key: disableSelfUpdate.
Without it, the update is still refused on an install whose package folder, the folder holding it, or the folder npm links the clawboo command into (the prefix’s bin) the server’s user cannot write, such as a root-owned /usr/local. The chip there copies the update command instead.
CLAWBOO_DISABLE_BROWSER_AUTOSTART
Stops Clawboo starting the browser connectors on an install that has never had one.- Type: flag
- Default: unset, so Playwright and Chrome DevTools start when Clawboo starts, if neither has been connected or disconnected yet
- Example:
CLAWBOO_DISABLE_BROWSER_AUTOSTART=1
disableBrowserAutostart.
CLAWBOO_PROXY_IDENTITY
Checks the signed identity token a sign-in proxy in front of Clawboo sends with each request, and records the person it names on approvals, chat messages and task moves. Run Clawboo behind a sign-in proxy has the setup.- Type:
off,onorrequired - Default:
off - Example:
CLAWBOO_PROXY_IDENTITY=required
on, a request that carries a token must have a good one, and a request without one works as before, with no name recorded. With required, every /api/ request and the Gateway WebSocket must carry a good token, except a spawned runtime’s own MCP calls. A token that does not verify gets 401 in both. The access token is still needed beside it while it is on. Operator file key: proxyIdentity.
Turning it on needs a key (CLAWBOO_PROXY_IDENTITY_JWKS_URL or CLAWBOO_PROXY_IDENTITY_PUBLIC_KEY, not both), CLAWBOO_PROXY_IDENTITY_ISSUER and CLAWBOO_PROXY_IDENTITY_AUDIENCE. Without them, or with a value Clawboo cannot trust, the server logs CONFIG: refusing to start. and exits with code 1. Agents run as the same user as the server, so set these where that user cannot change them: in your service manager, or a root-owned operator file. The server logs a SECURITY: warning when they come from a file that user owns, can write, or can replace through a folder above it. On Windows, where it cannot check who can change a file, it logs the warning whenever they come from the operator file.
CLAWBOO_PROXY_IDENTITY_HEADER
- Type: header name, letters, digits and
- - Default:
clawboo-identity - Example:
CLAWBOO_PROXY_IDENTITY_HEADER=Cf-Access-Jwt-Assertion
Bearer prefix is allowed, so authorization works for a proxy that sends Authorization: Bearer <token>. Headers Clawboo or a browser already uses, such as cookie, host and the forwarding headers, are refused. So is clawboo-app-identity when the lane is on or required and CLAWBOO_APP_LINK_PUBLIC_KEY is set too; with the lane off, Clawboo reads no proxy header at all. Operator file key: proxyIdentityHeader.
CLAWBOO_PROXY_IDENTITY_JWKS_URL
- Type: URL,
https(plainhttponly tolocalhost,127.0.0.1or::1) - Default: unset
- Example:
CLAWBOO_PROXY_IDENTITY_JWKS_URL=https://team.cloudflareaccess.com/cdn-cgi/access/certs
proxyIdentityJwksUrl.
CLAWBOO_PROXY_IDENTITY_PUBLIC_KEY
- Type: a PEM public key (
-----BEGIN PUBLIC KEY-----), a JWK, or a JWKS of up to 16 keys - Default: unset
- Example:
CLAWBOO_PROXY_IDENTITY_PUBLIC_KEY='{"kty":"OKP","crv":"Ed25519","x":"…"}'
\n for each line break. A private key, a shared (oct) key or a certificate stops the server at startup. Operator file key: proxyIdentityPublicKey.
CLAWBOO_PROXY_IDENTITY_ISSUER
- Type: string
- Default: unset; required when the lane is on
- Example:
CLAWBOO_PROXY_IDENTITY_ISSUER=https://team.cloudflareaccess.com
iss every token must carry. Operator file key: proxyIdentityIssuer.
CLAWBOO_PROXY_IDENTITY_AUDIENCE
- Type: string
- Default: unset; required when the lane is on
- Example:
CLAWBOO_PROXY_IDENTITY_AUDIENCE=clawboo
aud every token must carry. Without it, a token your sign-in provider made for any other app would do. Operator file key: proxyIdentityAudience.
CLAWBOO_PROXY_IDENTITY_BINDING
- Type:
requestorsession - Default:
request - Example:
CLAWBOO_PROXY_IDENTITY_BINDING=session
request, every token names its request’s method and path (htm, htu), carries iat, exp and a jti, and is accepted once. With session, the proxy’s own sign-in token works on any path until it expires, which is what Cloudflare Access and oauth2-proxy send; htm and htu are still checked when present. Operator file key: proxyIdentityBinding.
CLAWBOO_PROXY_IDENTITY_MAX_LIFETIME
- Type: whole number of seconds, from 1 to 300
- Default:
60 - Example:
CLAWBOO_PROXY_IDENTITY_MAX_LIFETIME=30
iat to its exp. Ignored with session binding. Clocks may differ by 5 seconds either way. Operator file key: proxyIdentityMaxLifetime.
CLAWBOO_PROXY_IDENTITY_NAME_CLAIM
- Type: claim name, or a dotted path such as
profile.name - Default:
name - Example:
CLAWBOO_PROXY_IDENTITY_NAME_CLAIM=email
email, then preferred_username. Operator file key: proxyIdentityNameClaim.
CLAWBOO_PROXY_IDENTITY_ROLE_CLAIM
- Type: claim name, or a dotted path such as
realm_access.roles - Default:
role - Example:
CLAWBOO_PROXY_IDENTITY_ROLE_CLAIM=groups
CLAWBOO_PROXY_IDENTITY_ROLES is enforce. Operator file key: proxyIdentityRoleClaim.
CLAWBOO_PROXY_IDENTITY_ROLES
- Type:
offorenforce - Default:
off - Example:
CLAWBOO_PROXY_IDENTITY_ROLES=enforce
enforce, the role in each token decides what its person may do: owner, operator, member or guest, with the claims beside it described in Roles. It needs CLAWBOO_PROXY_IDENTITY=required; with any other mode the server refuses to start. Operator file key: proxyIdentityRoles.
CLAWBOO_PROXY_IDENTITY_CONTROL_CLAIM
- Type:
offorrequired - Default:
off - Example:
CLAWBOO_PROXY_IDENTITY_CONTROL_CLAIM=required
required, taking over an agent’s screen, and every batch of input after, needs a sign-in proxy token whose control claim names that agent; a batch without it hands the screen back to the agent. See Taking over a screen. It needs CLAWBOO_PROXY_IDENTITY on or required, and request binding; otherwise the server refuses to start. Operator file key: proxyIdentityControlClaim.
CLAWBOO_PROXY_IDENTITY_READER_PUBLIC_KEY
- Type: public key: a PEM public key (
BEGIN PUBLIC KEY), a JWK or a JWKS - Default: unset
- Example:
CLAWBOO_PROXY_IDENTITY_READER_PUBLIC_KEY='{"kty":"OKP","crv":"Ed25519","x":"…"}'
clawboo-reader-identity header, name a reader: program, never a person, and reach only a short fixed list of reads, each workspace-wide; anything else answers 403 with "reason": "reader". See A program beside Clawboo. It takes the same forms as CLAWBOO_PROXY_IDENTITY_PUBLIC_KEY and refuses a private key the same way. It needs CLAWBOO_PROXY_IDENTITY on or required; with it off, or with a key that CLAWBOO_PROXY_IDENTITY_PUBLIC_KEY or CLAWBOO_APP_LINK_PUBLIC_KEY holds too, the server refuses to start. Operator file key: proxyIdentityReaderPublicKey.
CLAWBOO_PERSON_CHECK
- Type:
pageorverified - Default:
page - Example:
CLAWBOO_PERSON_CHECK=verified
page: a person a verified token names, or the dashboard’s own page. verified: only a person a verified token names, and the same for the Gateway WebSocket and every route of an agent’s screen. See Only signed requests act as a person. It needs CLAWBOO_PROXY_IDENTITY on or required; with it off the server refuses to start. CLAWBOO_PROXY_IDENTITY=required always works as verified. Operator file key: personCheck.
Provider keys
Clawboo looks up a runtime’s key in this order: the server’s environment, the encrypted vault, then OpenClaw’s~/.openclaw/.env. A runtime you disconnected on its card uses only the vault until you connect it again. An exported key makes a runtime’s card read as connected, but Settings > Providers shows a provider as connected only when its key is in the vault or in OpenClaw’s .env. Providers and runtimes covers saving keys from the dashboard instead.
ANTHROPIC_API_KEY
- Type: string
- Default: unset
- Example:
ANTHROPIC_API_KEY=sk-ant-...
OPENAI_API_KEY
- Type: string
- Default: unset
- Example:
OPENAI_API_KEY=sk-...
text-embedding-3-small) when no local Ollama embedding model is available and you allow it. Clawboo connects Codex through codex login, not this key.
OPENROUTER_API_KEY
- Type: string
- Default: unset
- Example:
OPENROUTER_API_KEY=sk-or-...
OpenAI-compatible provider keys
Clawboo Native reaches seven more providers through their OpenAI-compatible endpoints. Each key, on its own, is enough to connect Clawboo Native. All default to unset.
Settings > Providers also saves
MINIMAX_API_KEY, NVIDIA_API_KEY, HF_TOKEN and VENICE_API_KEY into OpenClaw’s .env for the OpenClaw Gateway. Clawboo’s own runtimes do not use those four.
OLLAMA_BASE_URL
The address of an Ollama server, for keyless local models.- Type: URL including
/v1 - Default:
http://localhost:11434/v1 - Example:
OLLAMA_BASE_URL=http://192.168.1.20:11434/v1
/v1) into openclaw.json. Memory embeddings ignore it and always look for Ollama at http://localhost:11434; with a remote Ollama, memory search stays keyword-only unless a local Ollama or an allowed OpenAI key provides embeddings.
Provider base URLs
Where Clawboo Native sends a provider’s requests, for model traffic that goes through your own gateway or a company proxy, such as LiteLLM, an egress proxy or a regional endpoint. Leave them unset to reach each provider at its own address.- Type: URL,
httporhttps, with no user name, password, credential, query string or fragment in it - Default: unset (the provider’s own address)
- Example:
OPENROUTER_BASE_URL=https://llm-gateway.example.com/openrouter/v1
Write the address the way the provider’s own is written above: Anthropic’s without
/v1, every other one with its version path. Clawboo Native’s runs, the key check when you save a key, and the model lists all use it, so a key that only works through your gateway checks as good and its models show up:
- Through a gateway, OpenAI’s list keeps every chat model the gateway names, such as its own deployment names, not only OpenAI’s
gpt-families. - Through a gateway, OpenRouter’s list is asked with your OpenRouter key, and Clawboo Native’s default-model picker lists the gateway’s models. Without one, the picker keeps its own list of OpenRouter models.
- Memory embeddings take
OPENAI_BASE_URLtoo. Vectors made through a gateway count as their own source, apart from vectors made by OpenAI itself, so the two are never compared with each other.
- A base URL receives the provider’s API key with every request. The server logs a
SECURITY:warning for one that would send it over plainhttpto another machine, and for one that comes from an operator file its own user can change, since every agent it runs could then point a provider at a server of its own. On Windows it warns whenever one comes from the operator file. - A URL with a user name, a password, a credential parameter, a query string or a fragment in it stops the server at startup.
- Other runtimes keep their own settings. Claude Code, Codex, Hermes and OpenClaw decide for themselves where their requests go; a variable set for the server reaches the programs it starts, but a value from the operator file does not. Ollama has its own OLLAMA_BASE_URL.
COMPOSIO_BASE_URL
- Type: URL
- Default:
https://backend.composio.dev - Example:
COMPOSIO_BASE_URL=https://composio.example.com
Runs and verification
CLAWBOO_MAX_CONCURRENT_RUNS
- Type: whole number, 1 or more
- Default:
8 - Example:
CLAWBOO_MAX_CONCURRENT_RUNS=4
CLAWBOO_RUN_SILENT_TIMEOUT_MS
- Type: milliseconds
- Default:
1800000(30 minutes) - Example:
CLAWBOO_RUN_SILENT_TIMEOUT_MS=3600000
CLAWBOO_HOME_MUTEX_ACQUIRE_MS
- Type: milliseconds
- Default:
600000(10 minutes) - Example:
CLAWBOO_HOME_MUTEX_ACQUIRE_MS=900000
CLAWBOO_MAX_FIX_CYCLES
- Type: whole number, 0 or more
- Default:
1, which allows two attempts - Example:
CLAWBOO_MAX_FIX_CYCLES=0
0 allows a single attempt. When the attempts run out, the task moves to Needs you. Only runs that are verified count; How work is checked explains which runs those are.
CLAWBOO_REVIEWER_MODEL
- Type: model id
- Default: the model that did the work
- Example:
CLAWBOO_REVIEWER_MODEL=claude-sonnet-4-6
CLAWBOO_ROUTINE_OPENCLAW_TIMEOUT_MS
- Type: milliseconds
- Default:
600000(10 minutes) - Example:
CLAWBOO_ROUTINE_OPENCLAW_TIMEOUT_MS=1200000
Board timing
CLAWBOO_BOARD_STALE_TTL_MS
- Type: milliseconds, a whole number from 1 to 2147483647
- Default:
180000(3 minutes) - Example:
CLAWBOO_BOARD_STALE_TTL_MS=240000
CLAWBOO_BOARD_STALE_SWEEP_MS under 8 minutes, the fixed delegation watchdog, or that watchdog fails the task first.
CLAWBOO_BOARD_STALE_SWEEP_MS
- Type: milliseconds, a whole number from 1 to 2147483647
- Default:
60000(1 minute) - Example:
CLAWBOO_BOARD_STALE_SWEEP_MS=30000
CLAWBOO_DISPATCH_PUMP_MS
- Type: milliseconds, a whole number from 1 to 2147483647
- Default:
60000(1 minute) - Example:
CLAWBOO_DISPATCH_PUMP_MS=30000
CLAWBOO_DB_WRITE_BUDGET_MS
- Type: milliseconds
- Default:
1500 - Example:
CLAWBOO_DB_WRITE_BUDGET_MS=3000
Approvals and retention
CLAWBOO_APPROVAL_TTL_MS
- Type: milliseconds
- Default:
86400000(24 hours) - Example:
CLAWBOO_APPROVAL_TTL_MS=43200000
CLAWBOO_APPROVAL_REAPER_INTERVAL_MS
- Type: milliseconds
- Default:
3600000(1 hour) - Example:
CLAWBOO_APPROVAL_REAPER_INTERVAL_MS=600000
CLAWBOO_TOOL_RESULT_TTL_MS.
CLAWBOO_TOOL_RESULT_TTL_MS
- Type: milliseconds
- Default:
604800000(7 days) - Example:
CLAWBOO_TOOL_RESULT_TTL_MS=86400000
Memory, browsers and MCP
CLAWBOO_DISABLE_EMBEDDINGS
- Type: flag, exactly
1 - Default: unset
- Example:
CLAWBOO_DISABLE_EMBEDDINGS=1
CLAWBOO_MAX_AGENT_BROWSERS
- Type: whole number
- Default:
4 - Example:
CLAWBOO_MAX_AGENT_BROWSERS=2
CLAWBOO_AGENT_BROWSER_IDLE_MS
- Type: milliseconds
- Default:
600000(10 minutes) - Example:
CLAWBOO_AGENT_BROWSER_IDLE_MS=300000
CLAWBOO_AGENT_DISPLAYS
- Type: flag;
0,offorfalseturns it off - Default: on, on Linux with TigerVNC’s
Xvncfound - Example:
CLAWBOO_AGENT_DISPLAYS=0
Xvnc. Has no effect on macOS or Windows, where agents get no display.
CLAWBOO_AGENT_DISPLAY_SIZE
- Type:
WIDTHxHEIGHTin pixels, from 640x480 to 3840x2160 - Default:
1280x800 - Example:
CLAWBOO_AGENT_DISPLAY_SIZE=1440x900
CLAWBOO_OPENCLAW_CDP_PORT
- Type: port
- Default:
OPENCLAW_GATEWAY_PORTplus 11, so18800 - Example:
CLAWBOO_OPENCLAW_CDP_PORT=18850
OPENCLAW_GATEWAY_PORT
- Type: port
- Default:
18789 - Example:
OPENCLAW_GATEWAY_PORT=19789
settings.json holds that address.
CLAWBOO_MCP_PROBE_MS
- Type: milliseconds
- Default:
60000(1 minute) - Example:
CLAWBOO_MCP_PROBE_MS=120000
Logging and tracing
LOG_LEVEL
- Type: one of
trace,debug,info,warn,error,fatal,silent - Default:
info - Example:
LOG_LEVEL=debug
~/.clawboo/server.log. Credential-looking values are masked in every log line.
NODE_ENV
- Type: string
- Default: unset; the CLI sets
productionon the server it starts - Example:
NODE_ENV=production
production the server logs one JSON object per line. Anything else gives colored, readable lines.
OTEL_EXPORTER_OTLP_ENDPOINT
- Type: URL
- Default: unset
- Example:
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT set, Clawboo exports traces over OTLP/HTTP for agent Routines on Clawboo Native, Claude Code, Codex and Hermes, and for runs started with POST /api/runtimes/:id/run. Team chat runs produce no traces. Without either variable, the local event log is the only trace store.
The npm package does not include the OpenTelemetry SDK, so on an npm install these variables export nothing, and System Health reports that the exporter failed to initialize. Export works from a source checkout, where the SDK is installed.
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT
- Type: URL
- Default: unset
- Example:
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://localhost:4318/v1/traces
OTEL_EXPORTER_OTLP_ENDPOINT turns export on.
OTEL_SERVICE_NAME
- Type: string
- Default:
clawboo - Example:
OTEL_SERVICE_NAME=clawboo-office
Read from other tools
CODEX_HOME
- Type: path
- Default:
~/.codex - Example:
CODEX_HOME=/srv/codex
codex login saved (auth.json). Each Codex agent then runs with its own Codex home under ~/.clawboo/runtimes/, which Clawboo sets for that run.
HERMES_HOME
- Type: path
- Default:
~/.hermes - Example:
HERMES_HOME=/srv/hermes
auth.json). Each Hermes agent runs as a Hermes profile in the Hermes gateway’s own home, ~/.clawboo/runtimes/hermes/_gateway, which Clawboo sets as the gateway’s HERMES_HOME.
CLAUDE_CODE_USE_BEDROCK
- Type: flag; any value except empty,
0orfalseturns it on - Default: unset
- Example:
CLAUDE_CODE_USE_BEDROCK=1
AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY and AWS_SESSION_TOKEN from the environment of runtimes it starts. With this set, it keeps them, so Claude Code can use Amazon Bedrock.
Proxy variables
HTTP_PROXY, HTTPS_PROXY and ALL_PROXY (in either case), plus NO_PROXY and no_proxy. When any proxy variable is set, Clawboo adds 127.0.0.1,localhost,::1 to both NO_PROXY and no_proxy for the runtimes it starts, keeping any hosts already listed. Their calls to Clawboo’s own MCP servers then skip the proxy, which would otherwise see the attach token and break the connection.
GATEWAY_AUTH_TOKEN and other templates
Clawboo does not readGATEWAY_AUTH_TOKEN as its own setting. When settings.json or openclaw.json holds a template such as ${GATEWAY_AUTH_TOKEN} (any ${NAME} works), Clawboo resolves NAME from its own environment first, then from OpenClaw’s .env. It removes GATEWAY_AUTH_TOKEN from the environment of runtimes it starts.
Operating system variables
PATH and, on Windows, PATHEXT, ComSpec and APPDATA are read to find and start programs. Your home folder comes from the operating system (HOME or USERPROFILE).
Set by Clawboo
Clawboo sets these on processes it starts. Do not set them yourself.Testing and development
CLAWBOO_ENABLE_MOCK_RUNTIME
- Type: flag, exactly
1 - Default: unset
- Example:
CLAWBOO_ENABLE_MOCK_RUNTIME=1
clawboo-mock, a fault-injection runtime for reproducing failures such as silence, a crash or a slow start. It runs nothing real: every event comes from directives in the task text. Any other value leaves it hidden from the dashboard and from GET /api/runtimes.
CLAWBOO_SERVER_PATH
- Type: path
- Default: found by walking up from the CLI to a
package.jsonnamedclawboo - Example:
CLAWBOO_SERVER_PATH="$HOME/code/clawboo" clawboo
What runtimes inherit
Runtimes Clawboo starts (Claude Code, Codex, Hermes) and the verification command get the server’s environment, minus:- Clawboo’s own secrets:
STUDIO_ACCESS_TOKEN,CLAWBOO_SECRETS_MASTER_KEY,GATEWAY_AUTH_TOKEN, and any variable starting withBETTER_AUTH. - A fixed list of common third-party credentials: GitHub, GitLab and Bitbucket tokens, npm, PyPI and Cargo tokens, hosting and cloud tokens (DigitalOcean, Vercel, Netlify, Cloudflare, Heroku, Fly, Railway), Stripe, Twilio, SendGrid, Mailgun and Slack keys, database URLs and passwords, and Vault, 1Password, Doppler, Sentry, Codecov, Turbo, CircleCI and Docker tokens.
- AWS access keys, unless
CLAUDE_CODE_USE_BEDROCKis set.
OPENAI_API_KEY, reaches every agent those runtimes run. Start Clawboo from a shell that holds only what agents may see. What agents can do covers what else they can reach.
With CLAWBOO_AGENT_USER set, every process the agent host starts also loses the variables that describe your account and Clawboo’s folders: HOME, USER, LOGNAME, SHELL, TMPDIR, the XDG_* folders, SSH_AUTH_SOCK, GPG_AGENT_INFO, DBUS_SESSION_BUS_ADDRESS, CLAWBOO_HOME, CLAWBOO_WORK_DIR and the agent isolation variables, among others. The agent host fills in the agent user’s own HOME, USER, LOGNAME, SHELL and TMPDIR. From 0.9.0, your PYTHONPYCACHEPREFIX is one of them, since an agent user’s Python writing bytecode into your folder could plant code your own Python then runs; a process started as the agent user, such as a runtime, a connector or an approved command, gets PYTHONDONTWRITEBYTECODE=1 in its place, unless Clawboo gives it a folder of its own or a PYTHONDONTWRITEBYTECODE is already set.
What connectors and approved commands inherit
Local connectors and the shell commands you approve for a Clawboo Native agent start from an empty environment instead. They get back only:- What a process needs to start:
PATH,HOME,SHELL,USER,LOGNAME,TERM,TMPDIR,TZ,LANG,LC_ALLandLC_CTYPE, and on WindowsSystemRoot,APPDATA,LOCALAPPDATA,USERPROFILE,TEMPand the other system folders. - Proxy settings:
HTTP_PROXY,HTTPS_PROXYandNO_PROXY, in either case. - npm’s prefix, cache and update check:
npm_config_prefix,npm_config_cacheandnpm_config_update_notifier, in lower or upper case (NPM_CONFIG_PREFIXand so on). No other npm setting arrives, so npm credentials such asnpm_config__authTokenstay out. - From 0.9.0, Python’s bytecode settings:
PYTHONDONTWRITEBYTECODEandPYTHONPYCACHEPREFIX. No other Python setting arrives, soPYTHONPATHandPYTHONSTARTUPstay out. - For a connector, the keys you entered for that connector.
npm_config_update_notifier=false when neither spelling is set, so its npx start does not ask the registry for a newer npm. From 0.9.0, a connector started through npm (its command is npx, npm or node, wherever that program is, and on Windows also npx.cmd, npm.cmd or node.exe) also gets PYTHONDONTWRITEBYTECODE=1 when neither Python setting is set. Starting a connector through npx can build a native part of one of its packages, such as fsevents for the browser connector, and that build runs Python, which would otherwise write __pycache__ folders into the folder of the npm that runs it: nvm’s, Homebrew’s, or the npm of a Node.js bundled inside an app that runs Clawboo. A connector any other program starts, such as uvx, python or docker, gets no Python setting of Clawboo’s, so uv keeps the bytecode it caches between starts. Either setting you make passes through as it is, for every connector, with nothing added: to keep Python’s bytecode, set PYTHONPYCACHEPREFIX to a folder of your own before you start Clawboo, and Python writes it there. With agents as their own user, a process started as the agent user never gets that folder (see above). An approved command runs npm and Python as you configured them.
The npm that installs a runtime into the runtimes folder (OpenClaw, Claude Code’s Agent SDK, Codex, 1Password’s SDK) gets PYTHONDONTWRITEBYTECODE=1 on the same terms from 0.9.0, since a native part’s build runs Python there too.
Source of truth
Source of truth
Server start:
apps/web/server/index.ts, lib/resolveHost.ts, lib/portUtils.ts. Pinned settings: lib/operatorSettings.ts. Access: packages/gateway-proxy/src/access-gate.ts, origin-guard.ts. Paths and the base path: packages/config/src/index.ts, basePath.ts. Keys: apps/web/server/lib/secretsVault.ts, lib/runtimes/descriptor.ts. Runtime environments: lib/runtimes/childEnv.ts; connectors and approved commands: packages/mcp/src/connector/env.ts. Each timer’s variable is read next to its default; Limits and defaults gives the file and line.Related
- Configuration: the files these variables move, and what is stored where
- CLI reference: the variables the
clawboocommand reads and sets - Limits and defaults: every number, including the ones you cannot change
- Self-host securely:
HOST, the access token and the allowlists, step by step - Security: what the access gate, the origin check and the vault protect