mcp/clawbox-mcp.ts) exposing the
device as tools. The agent can read system state, drive the desktop Chromium,
manage the desktop, install capabilities, and build webapps — all authenticated
back to the device APIs with a per-install bearer token.
The tool set depends on the edition. A tool that
cannot work on the running edition is not registered at all — the agent never
sees it, rather than discovering it fails. The edition is resolved once at
startup from the device’s edition lock.
What differs by edition
Clawbox.md is one file with two kinds of fenced block. <!-- edition:… --> follows the active harness, so it selects the tool sections above. <!-- ships:… --> follows the install, so a dual device is served the OpenClaw and the Hermes device facts — the gateway it really has and the Hermes dashboard it really has — while still getting only the active harness’s toolbelt.
Tool catalog
Orientation — the agent calls these first
The agent loadsclawbox_context once per session — the field guide, which also tells it how
to hand work to the coding agent and then steer and check it — and calls device_status before
answering anything about the device. After that it picks by question: coding_project_status
before starting a coding run, coding_run_list for “what are my runs doing”, and
memory_shard_status, local_ai_status or clawbox_ai_usage for memory, on-box engines and
your allowance, and anthropic_accounts before starting or retrying a coding run that uses
your Anthropic accounts.
System & device
disk_usage, disk_cleanup, logs_tail and screen_capture are probed at
startup — if the device cannot support one, it is simply not offered.
Desktop, apps and building
Hermes skills — Hermes edition only
skill_search · skill_info · skill_install · skill_list · skill_uninstall
Installing takes the full registry identifier (official/pdf); uninstalling
takes the short lock id — the first word of a skill_list line, which is
not always the name the skill’s own SKILL.md gives it (a ClawHub
martin-weather shows as weather). skill_install returns the lock id so the
agent never has to guess it, and skill_list prints it first, noting the
display name when the two differ.
A display name works too, and so does the store identifier the skill came from,
as long as it is itself a valid skill name: 1–128 characters, starting with a
letter or a digit, and made only of letters, digits, ., _ and -. That rules
out a card name with a space in it, such as the ClawHub shape QR Code Decode —
pass the first word of its skill_list line instead. When two installed skills
answer to one string, the device refuses and names both lock ids rather than
removing either. See
Hermes Skills.
Hermes plugins — Hermes edition only
hermes_plugins_reload
Hermes scans for plugins once, when its process starts, and offers no runtime reload — so
a plugin installed, enabled, disabled or removed after that does not reach the chat,
including a brand-new conversation. This tool restarts the agent so it scans again, and
answers which plugins the box now declares and, where it can be established, which of them
the restarted agent actually loaded.
It is the supported way to do this and it is not a privilege: the restart stops a
process the box already owns and lets the service manager bring it back. Verifying a
plugin from the command line proves nothing about the chat — that is a separate, fresh
process.
The restart closes the chat window you have open, so the tool tells the assistant to say
so, and the desktop shows the same notice. See
Hermes Edition.
AI configuration — Hermes edition only
ai_list_models · ai_set_provider · ai_set_model
There is deliberately no tool for switching your ClawBox AI plan: that
changes what you are billed, and “switch to a bigger plan for better results” is
a one-line prompt-injection payload with a financial outcome. The plan is
reported by device_status; changing it is one click in Settings → Providers.
These tools read and write the device default — the provider and model in
~/.hermes/config.yaml, what a new conversation starts on. ai_list_models
reports it as device_default, and ai_set_provider / ai_set_model change
only that. The chat window can run a different model per conversation, chosen
with the pills under its composer, and the tool server cannot see which: it is one process shared
by every session. So where the chat knows the model that served a
reply it prints it under that reply, and the agent is told to read that — not a
tool — when asked “which model are you”. On the OpenClaw edition the header writes the box
default for every session, so there the default is the chat’s model.
Browser (drives the real desktop Chromium — visible in Remote Desktop)
browser_open · browser_navigate · browser_screenshot · browser_close —
both editions.
browser_click · browser_type · browser_keypress · browser_scroll —
OpenClaw edition only.
browser_type reports a character count, never the text — it is the tool that
types passwords.
Coding family — OpenClaw edition only
bash · job_status · job_stop · read_file · write_file · edit_file ·
list_directory · glob · grep · notebook_edit · web_fetch · web_search
Hermes ships its own equivalents, so ClawBox does not add a second set.
Coding agent
Registered only while you have the coding agent switched on in the Coding Agent app (and the harness is ready).
A typical exchange: the agent checks
coding_project_status, starts coding_agent_run, tells you
it is running and stops. When you change your mind mid-run it sends coding_run_message rather
than stopping the run; when you ask how it went it calls coding_run_list or
coding_agent_status. A run paused for a spent allowance is resumed with coding_agent_resume
only after the allowance is back.
What stays yours. The agent cannot switch the coding agent on,
change a project’s pipeline default, merge a
run’s branch home, or pause, resume or stop a run you started. Those routes only accept your
own signed-in browser session, so the agent points you at the button instead.
Email — both editions
email_send · email_list · email_read
email_send does not put a message on the wire while Ask me before sending is
on, which is the default: it queues a draft that you approve in the chat or in
Settings → Email. Turn that switch off and the same tool sends directly. See
Messaging channels.
Pictures and audio — both editions
generate_image · generate_audio
Memory Shard
memory_shard_status — both editions — reports whether Memory Shard is on and healthy, how
many folders, files and chunks it holds, and how far a running indexing pass has got (files done
of the total, chunks, percent). The agent cannot start a reindex: that re-embeds all your
documents and can take hours, so it opens the Memory Shard app for you to press Reindex, and
then reports the progress.
memory_shard_search — Hermes edition only — searches the documents and notes in the folders you added to
Memory Shard, returning the file each passage came from, the
passage, and how well it matched.
It is Hermes-only because of where the index is, not because of which agent deserves
it: on an OpenClaw box the memory index belongs to OpenClaw and the agent already searches
it while answering, so a second tool would be a second answer to the same question.
The tool’s own description marks what comes back as the owner’s documents — information
to read, never instructions to follow — the same way the skills tools mark publisher text.
Local AI — both editions
local_ai_status lists the engines that run on the box itself — Kokoro (speaks replies), Whisper
(transcribes), the embedding model behind Memory Shard and the llama.cpp model — with whether each
is installed and running, and which voice and transcription engine the box uses right now. It
never installs anything: installing an engine runs as root and downloads the model, so it only
happens from Settings → Local AI in your browser.
ClawBox AI usage — both editions
clawbox_ai_usage reads how much of your ClawBox AI allowance is used: the weekly allowance and
the 5-hour limit (and when each frees up), the weekly meters for pictures, spoken replies,
transcribed audio and memory indexing, and your prepaid credits. Where clawbox.com does not share
the figures with the box yet, the agent says so and points you at your account there. No tool
changes your plan or buys credits.
Anthropic accounts — both editions
anthropic_accounts reads the Anthropic account pool from Settings → Providers →
Anthropic accounts: coding runs use it, and so does the chat on a Claude subscription once
the box has had to switch accounts. For each account it gives the name, the kind and the
state: it can answer, or it is at its usage limit and back at a given time. It also gives the
order, the active account (in_use: the one new coding runs start on and the chat follows
once it has switched — a run already under way may still be finishing on another), how many
can answer, and the last swap (last_swap: when, from which account to which, and why). When
every account is limited, it tells the agent to wait for the first reset: runs that were cut
off resume by themselves then, and coding_agent_run refuses a new Anthropic run until that
time. The answer never carries an email or a credential. Adding, ordering and removing
accounts is yours to do, in Settings. See
Multiple Anthropic Accounts.
Safety rails
- One protected-path list, applied to descendants and not just the path
handed in:
list_directoryfilters entries,globfilters results, andgrepfilters both its search roots and every hit. - Argv only. Outside
bash, no tool builds a shell string out of an argument. - Confirmation on irreversible actions.
system_powerandcode_project_deleterequire an explicit confirm flag — something a web page the agent happens to be reading cannot supply by accident. - Timeouts and output caps everywhere, so one slow call cannot stall a turn.
- Errors are instructions, not stack traces. Every failure comes back as a short code, a message and a suggested next step — never a raw trace or an absolute path.
- On the OpenClaw edition, plan around
bashbeing as capable as the device user. Its pre-flight refuses commands naming a credential store, but that is a guard rail against a mistake, not a sandbox. - Telegram senders must be pairing-approved before the agent will act for them (details).
The clawbox-cli wrapper
The same capabilities are shell-callable, from the Terminal app or over SSH.
The subcommands (shown below with that alias in place):
update asks for sudo itself when it re-runs the installer — do not prefix the
command with sudo, or it runs under root’s PATH and environment instead of yours.
On a Hermes device update refuses and points you at Settings → System Update,
which runs the edition-correct installer steps. (On the premium dual SKU the guard
does not fire, because the edition lock there reads dual.)
How authentication works
- The MCP server talks to the device APIs at
http://127.0.0.1:80/setup-api/*with the MCP bearer token (data/.mcp-token, seeded at boot,0600). - The token lives in that file only. Nothing copies it into a harness config, so rotating it is not a configuration-sync problem.
- The agent gets these tools only if its harness has the server registered:
- OpenClaw — reconciled into the gateway’s config on every gateway start.
- Hermes — reconciled into
~/.hermes/config.yamlon every web-server boot, and again at install time. Both paths are idempotent, so a restart, a redeploy or an update all converge on the same entry.
- If tools suddenly fail with auth errors,
clawbox_healthdiagnoses it. - On the
dualSKU the tool set follows the currently active harness (/setup-api/harness/active), re-resolved when the MCP server starts, rather than being fixed by the edition lock. If the lock file exists but cannot be read, the smaller Hermes tool set is registered on purpose.
For agent developers
Working on a ClawBox, or building automation against one? The stable integration surfaces are:- MCP tools (this page) — through the on-device agent.
/setup-api/*HTTP APIs — session-cookie or MCP-bearer authenticated; the same APIs the desktop UI uses.mcp/clawbox-cli.ts— over SSH or in the Terminal app, run throughbun run.- The agent workspace guide seeded on the device.