Everything load-bearing about a ClawBox on one page. Facts only — explanations live in the linked chapters.

​
Identity

FactValue
ProductClawBox — OpenClaw OS on NVIDIA Jetson (Ubuntu 22.04 aarch64)
Repogithub.com/ID-Robots/clawbox · releases = vX.Y.Z tags on main · integration branch beta
System userclawbox (uid 1000) · one password for SSH and browser login
Web UIhttp://<box-ip> (port 80) · http://clawbox.local when mDNS works
Setup hotspotSSID ClawBox-Setup → http://10.42.0.1 (fallback subnet 10.43.0.1)
StackNext.js 16 / React 19 / Node 22 runtime / Bun builds / OpenClaw gateway (npm-pinned)

​
Ports

PortServiceExposure
80Web OS (clawbox-setup) — UI, login, /setup-api/*, proxies to gatewayLAN
18789OpenClaw gatewayLAN, token-gated — never browse it directly
22SSHLAN
3006Terminal WS (proxied at /terminal-ws)LAN
5900/6080VNC (localhost) / noVNC (proxied at /novnc-ws)localhost / LAN
18800Chromium CDP (AI browser)localhost
11434Ollamalocalhost
8080 / 8880llama.cpp / Kokoro TTSlocalhost

​
Paths

PathContents
/home/clawbox/clawboxApp (git checkout)
…/clawbox/data/Device state: config.json, kv.json, .session-secret, .mcp-token, network.env — survives updates, wiped by factory reset (except network.env)
…/clawbox/.envApp env — survives everything
…/clawbox/.update-branchChannel pin (beta) — survives everything
…/clawbox/config/openclaw-target.txtPinned OpenClaw version
~/.openclaw/openclaw.jsonGateway config (auth metadata only)
~/.openclaw/agents/main/agent/auth-profiles.jsonReal provider credentials
~/.openclaw/agents/<agent>/agent/codex-home/auth.jsonChatGPT-subscription session (synced per-agent)
~/.openclaw/credentials/telegram-*.jsonTelegram pairing approvals
~/.clawkeep/Backup pairing/config/passphrase
~/.npm-global/bin/openclawGateway binary

​
Services (systemd)

clawbox-setup (web, port 80) · clawbox-gateway (OpenClaw, pre-start self-heal script) · clawbox-ap (+-watchdog.timer) · clawbox-vnc + clawbox-websockify · clawbox-browser (CDP, on demand) · clawbox-heartbeat.timer · clawbox-tunnel (optional) · clawbox-performance · clawbox-root-update@<step> (privileged installer steps) · ollama.

​
Commands (over SSH)

# Health / logs
systemctl status clawbox-setup clawbox-gateway --no-pager
journalctl -u clawbox-setup -n 50 --no-pager      # web/login
journalctl -u clawbox-gateway -n 50 --no-pager    # AI/providers/channels

# Restart services
sudo systemctl restart clawbox-setup clawbox-gateway

# Update (full, correct way)
sudo clawbox update            # == sudo bash /home/clawbox/clawbox/install.sh

# Targeted repairs
sudo bash install.sh --step gateway_setup     # fixes 'gateway token mismatch'
sudo bash install.sh --step openclaw_install  # fixes stale core / 'Unrecognized key' / plugin skew

# Password
sudo passwd clawbox            # new password, effective everywhere immediately

# Channel
echo beta > /home/clawbox/clawbox/.update-branch   # opt into beta (delete file to leave)

# Login check (exactly what the web app does)
read -rsp 'PW: ' PW; echo; printf '%s\0' "$PW" | /usr/sbin/unix_chkpwd clawbox nullok; echo "exit=$?"; unset PW

# Login API check (bypasses browser)
curl -sS -X POST http://localhost/login-api -H 'Content-Type: application/json' -d '{"password":"…","duration":1200}'

​
Key API endpoints (/setup-api/*, session-cookie or MCP-bearer auth)

EndpointPurpose
POST /login-api {password,duration}Login → clawbox_session cookie (durations 1200/21600/43200/86400 s)
GET /setup-api/system/info · system/statsDevice info / live metrics
POST /setup-api/system/credentialsChange password
POST /setup-api/system/powerRestart/shutdown
GET /setup-api/update/versions?force=1Version check (fresh)
POST /setup-api/update/run · GET update/statusRun update / poll progress
POST /setup-api/update/resetReset-to-channel & update (beta)
GET/POST /setup-api/system/update-branchRead/set channel
POST /setup-api/ai-models/configureWrite provider config
GET /setup-api/ai-models/status · catalog?provider=…Provider status / live model catalog
POST /setup-api/telegram/configure · pairingBot token / approve pairing codes
GET /setup-api/gateway/health · ws-configGateway health / WS URL + token
POST /setup-api/setup/resetFactory reset (destructive)
/setup-api/wifi/* · files/* · apps/* · clawkeep/* · code/* · preferencesWi-Fi, file manager, app store, backups, code projects, prefs (all under /setup-api/)

​
Gotchas (hard-won)

  1. :18789 never accepts your password — it’s the gateway; use plain http://<ip>.
  2. Browser login ≠ separate password — same Linux password as SSH; failures are usually autofill, unix_chkpwd perms (-rwxr-sr-x root shadow), a stale build, or password encoding. Ladder: Troubleshooting.
  3. git pull is not an update — always finish with sudo bash install.sh; otherwise service files + OpenClaw core go stale (token mismatch, Unrecognized key).
  4. Local commits silently block updates on stable ≤ current release (“up to date” forever); beta shows “Updates paused” + one-click reset. Manual fix = hard-sync (Recovery C).
  5. Two OpenAI lanes: API key = openai/… + sk-… key; ChatGPT subscription = codex/… + OAuth. Different catalogs (gpt-5 vs gpt-5.4/5.5), different credentials. Stale-key 401s after switching are self-healed on beta.
  6. Secrets live in auth-profiles.json, not openclaw.json (metadata only). The codex session is additionally per-agent in codex-home/auth.json.
  7. clawbox.local failing ≠ box down — mDNS/Windows/router multicast issue; the IP always works.
  8. The last update step reboots the box — 1–2 min offline is normal, not a hang.
  9. Factory reset password is clawbox — and the box comes back in AP mode (ClawBox-Setup → 10.42.0.1).
  10. Version label ≠ running code — package.json is read live; verify actual deployment via .next/BUILD_ID mtime.

​
Chapter index

Architecture · Networking · Filesystem · Auth & Security · AI Providers · Update System · Agent Interface · Troubleshooting · Recovery