Quick Reference

​

Identity

​

Ports

​

Paths

​

Services (systemd)

​

Commands (over SSH)

# Which edition is this?
cat /etc/clawbox/edition.env

# Health / logs — every edition
systemctl status clawbox-setup --no-pager
journalctl -u clawbox-setup -n 50 --no-pager      # web/login

# Health / logs — OpenClaw / dual
systemctl status clawbox-gateway --no-pager
journalctl -u clawbox-gateway -n 50 --no-pager    # AI/providers/channels
sudo systemctl restart clawbox-setup clawbox-gateway

# Health / logs — Hermes / dual (the gateway unit is masked; restarting it fails)
journalctl -u clawbox-hermes-dashboard -n 50 --no-pager
sudo systemctl restart clawbox-setup clawbox-hermes-dashboard clawbox-hermes-dashboard-proxy

# Update (full, correct way) — == sudo bash /home/clawbox/clawbox/install.sh
bun run /home/clawbox/clawbox/mcp/clawbox-cli.ts update   # asks for sudo itself; refused on Hermes
# Hermes: use Settings → System Update instead.

# Targeted repairs — OpenClaw / dual only; both print '[hermes edition] skipping …' and exit on Hermes
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)

​

Gotchas (hard-won)

1. :18789 never accepts your password — it’s the OpenClaw gateway (OpenClaw/dual); use plain http://<ip>. On Hermes it is closed entirely (connection refused) and the equivalent surface is the session-gated dashboard proxy on :8090.
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 + the agent core go stale (token mismatch, Unrecognized key). Hard-sync to the box’s own .update-branch, not a hardcoded main.
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 (OpenClaw/dual): both are openai/… since OpenClaw 2 — API key = profile openai:default + sk-…; ChatGPT subscription = OAuth profile openai:chatgpt plus agents.defaults.models."openai/<id>".agentRuntime.id = "codex". Different catalogs (the API lane carries the -pro tiers in addition to gpt-5.4/5.5/5.6; the subscription carries no -pro), different credentials. The codex/… namespace is retired (Unknown model); doctor --fix rewrites it. Stale-key 401s after switching are self-healed on beta. On Hermes there is no OpenAI API-key lane at all — OpenAI is sign-in (Codex) only, and the key providers are OpenRouter, Anthropic, Gemini, z.ai and Kimi.
6. Secrets live in auth-profiles.json (OpenClaw/dual), not openclaw.json (metadata only). The codex session is additionally per-agent in codex-home/auth.json. On Hermes, credentials are held by hermes auth add under ~/.hermes.
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). It keeps data/network.env, data/llamacpp/models and ~/.hermes/hermes-agent, and the portal device id is re-derived from /etc/machine-id. Never hand-roll it with rm -rf ~/.hermes or rm -rf data/* — see Recovery D.
10. Version label ≠ running code — package.json is read live; verify actual deployment via .next/BUILD_ID mtime.
11. Plan gates are internal names off by one — the internal flash tier is marketed Pro, internal pro is Max. Memory Shard and the Coding Agent need either paid tier; the cloud voice and the edition swap need Max; cloud transcription is on every connected box including Free.
12. ClawBox AI chat has no model picker — the chat is pinned to the flash alias (a saved pro-alias choice is migrated to it) and renders no model pill. Plan differences are allowance and device features.
13. Nothing heavy is installed by an update — only the llama.cpp runtime and Gemma 4. Kokoro, Whisper and the ~640 MB embedding model arrive through voice_kokoro_install, voice_whisper_install and embed_model, all owner-started and all off UI_ROOT_STEPS.
14. A provider or model change does not restart the gateway — it is hot-applied to the running agent, and open sessions are re-pointed. A change that does restart it (a subscription sign-in that migrates the auth store) waits for the gateway to answer again before sweeping sessions.

​

Chapter index