Quick Reference

​

Identity

​

Ports

​

Paths

​

Services (systemd)

​

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)

​

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