What makes ClawBox an AI-operated OS rather than a chat box: the on-device agent is wired to a ClawBox MCP server (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

​
Tool catalog

​
Orientation — the agent calls these first

​
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; uninstalling takes the short name. skill_install returns the name so the agent never has to guess it. See Hermes Skills.

​
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 → AI.

​
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.

​
Safety rails

  • One protected-path list, applied to descendants and not just the path handed in: list_directory filters entries, glob filters results, and grep filters 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_power and code_project_delete require 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 bash being 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

The same capabilities are shell-callable, from the Terminal app or over SSH:
clawbox update refuses to run on a Hermes device, because it would re-run the OpenClaw installer. Update a Hermes box from Settings → System Update.

​
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.yaml on 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_health diagnoses it.

​
For agent developers

Working on a ClawBox, or building automation against one? The stable integration surfaces are:
  1. MCP tools (this page) — through the on-device agent.
  2. /setup-api/* HTTP APIs — session-cookie or MCP-bearer authenticated; the same APIs the desktop UI uses.
  3. clawbox CLI — over SSH or in the Terminal app.
  4. The agent workspace guide seeded on the device.
See the Quick Reference for the one-page fact sheet (ports, paths, services, commands).