Find your symptom below. Each section starts with the fastest checks and escalates to deeper fixes — run them in order. Commands marked over SSH are typed after connecting with ssh clawbox@YOUR_BOX_IP (your box password).
Fast triage: Is the box reachable at all? → Can’t reach the ClawBox. Reachable but login fails? → Browser rejects my password. Logged in but AI errors? → AI provider errors. Update problems? → Updates.

​
I can’t reach the ClawBox

Two very common mistakes:
  1. clawbox.local often fails on Windows and on routers that block mDNS between Wi-Fi and wired devices. Use the raw IP address instead.
  2. Don’t add :18789 to the address. That port is the internal AI gateway — its page loads but it does not accept your password. The ClawBox screen is served at http://YOUR_BOX_IP (port 80, nothing after the IP).
  • Router method (easiest): open your router’s connected-devices list and look for clawbox.
  • If SSH by name works (ssh [email protected] connects in a terminal even when the browser fails): run hostname -I over SSH — the first address is the box’s LAN IP.
Bookmark the IP once found. It can change after a reboot on dynamic leases — reserve it in your router settings for a permanent address.
Over SSH, restart the web services:
sudo systemctl restart clawbox-setup clawbox-gateway
Wait ~30 seconds and reload http://YOUR_BOX_IP. If SSH doesn’t work either, power-cycle the box and wait 2 minutes.
If a network change (new router, changed Wi-Fi password) left the box unable to join your network, it broadcasts its own ClawBox-Setup Wi-Fi network. Connect to it from a phone/laptop, open http://10.42.0.1, and re-run the network step of the wizard.

​
The browser rejects my password (but SSH accepts it)

There is no separate admin password — the browser login uses the same system password as SSH. When SSH accepts it but the browser says Incorrect password, work down this ladder:
1

Confirm you're on the right page

The login must be at http://YOUR_BOX_IP (port 80). The :18789 page is the gateway — it will never accept your system password.
2

Rule out browser autofill

Open a private/incognito window (Ctrl+Shift+N), type the URL and the password by hand — don’t let the browser autofill. A stale saved password is the most common cause. If this works, delete the saved password for the box’s IP in your browser settings.
3

Test the password exactly as the web app checks it (over SSH)

read -rsp 'Box password: ' PW; echo; printf '%s\0' "$PW" | /usr/sbin/unix_chkpwd clawbox nullok; echo "RESULT exit=$?"; unset PW
  • RESULT exit=0 → the password itself is fine; continue to the next step.
  • Any other number → the password check itself fails. If your password contains accented or non-ASCII characters, the browser may encode them differently than the terminal did when the password was set — reset to a simple ASCII password with sudo passwd clawbox and retry.
4

Test the login API directly (bypasses the browser)

read -rsp 'Box password: ' PW; echo; curl -sS -X POST http://localhost/login-api -H 'Content-Type: application/json' -d "{\"password\":\"$PW\",\"duration\":1200}"; echo; unset PW
  • {"success":true} → the server accepts it; the problem is browser-side (step 2).
  • {"error":"Incorrect password"} → continue to the next step.
  • A lockout message → too many attempts; wait 5 minutes and retry.
5

Check the password helper's permissions

ls -l /usr/sbin/unix_chkpwd /etc/shadow
Expected (note the s and the shadow group):
-rwxr-sr-x 1 root shadow ... /usr/sbin/unix_chkpwd
-rw-r----- 1 root shadow ... /etc/shadow
If unix_chkpwd shows -rwxr-xr-x (no s) or a different group:
sudo chgrp shadow /usr/sbin/unix_chkpwd
sudo chmod 2755 /usr/sbin/unix_chkpwd
sudo systemctl restart clawbox-setup
6

Set a fresh password (10 seconds, no data loss)

sudo passwd clawbox
Sets a brand-new password that both SSH and the browser use immediately. Use simple ASCII characters, then retest in a private window.
7

Rebuild the web app (a half-finished update can serve a stale build)

Run the safe reinstall — Recovery, option C (10–15 minutes; settings and keys are kept) — then retest in a private window after the reboot. If even a fresh password on a fresh build fails, contact support with the outputs of steps 3–5.

​
Updates say “up to date” but the version is old

The updater only offers a release when the device’s code history matches the official release line. A box whose code was modified locally (committed changes — e.g. by an on-box agent or manual edits) silently stops seeing updates on v3.1.4 and earlier. 
cd /home/clawbox/clawbox
git fetch origin
git status
git rev-list --left-right --count origin/main...HEAD
Output X Y = X commits behind, Y commits ahead. Y > 0 means local commits are blocking updates.
This discards local code changes (commits and edits under /home/clawbox/clawbox). Your settings, AI keys, chats, and Telegram pairing live outside the code and are kept.
Run the safe reinstall — Recovery, option C — which hard-syncs the code to the release line and rebuilds everything.
Devices on the beta channel (and the next stable release) detect this state and show “Updates paused” with a one-click reset — see Update System → Divergence.

​
Update finished but the box misbehaves

A ClawBox update is more than git pull — the installer also refreshes the systemd service files and the OpenClaw core, and manual or interrupted updates can leave those stale. The easiest fix is always the full installer — re-run the update from the System Update app, or sudo bash /home/clawbox/clawbox/install.sh over SSH — which runs every step. The targeted repairs below are the faster, surgical alternatives:
The gateway service file is stale (it passes an old token style). Over SSH:
sudo bash /home/clawbox/clawbox/install.sh --step gateway_setup
sudo systemctl restart clawbox-gateway
If you saw too many failed authentication attempts, wait ~5 minutes after the restart — the lockout expires on its own.
The OpenClaw core on the device is older than the config ClawBox writes. Refresh it to the pinned version:
sudo bash /home/clawbox/clawbox/install.sh --step openclaw_install
sudo systemctl restart clawbox-gateway
The version label reads from files on disk; the running app may still be the previous build if the rebuild step didn’t finish. Verify and fix:
ls -la /home/clawbox/clawbox/.next/BUILD_ID   # timestamp = when the running build was made
cd /home/clawbox/clawbox && sudo bash install.sh && sudo reboot

​
AI provider errors (401 “Incorrect API key”)

Cause: OpenAI has two separate lanes with different credentials, and after a switch an old dead API key can keep being used — recurring 401 on every reply, returning after each restart. (Full explanation: AI Providers.)Fix now, on any version: open Settings → AI, choose ChatGPT (sign in with ChatGPT), complete the sign-in again — then reboot once and confirm it still works after the restart. The beta channel (and the next stable release) self-heals this on boot; if the manual fix doesn’t stick, contact support.
Re-save the provider in Settings → AI (this rewrites the full provider config), then reboot. Check quota/billing on the provider’s dashboard — an exhausted key returns errors that look like auth failures.
Local models share the Jetson’s memory — only one local runtime is active at a time. Check status in Settings → AI. Over SSH: systemctl status ollama and retry after sudo systemctl restart ollama.

​
My assistant isn’t replying

A dead key or exhausted quota looks like silence. See AI provider errors above.
Over SSH:
systemctl status clawbox-gateway --no-pager | head -12
journalctl -u clawbox-gateway -n 40 --no-pager
Look for auth errors (see Update finished but the box misbehaves) or provider errors in the log tail. sudo systemctl restart clawbox-gateway clears transient wedges.
ping -c 3 8.8.8.8 over SSH. If offline, see Connect to a Network.

​
Telegram-specific issues

New Telegram users must be approved on the device (a pairing request appears on the ClawBox screen). Until approved, the bot stays silent for that user.
Changing the bot resets pairing — previously approved users must be re-approved under the new bot.

​
Reading logs (for bug reports)

When contacting support, include the relevant log tail — it usually pins the cause in one look: 
journalctl -u clawbox-setup -n 50 --no-pager     # web app / login / setup API
journalctl -u clawbox-gateway -n 50 --no-pager   # AI gateway / providers / channels
You can also message the assistant /diagnostics in chat (if it’s responding) to get a self-report.

​
Still stuck?

Recovery options

Password reset, safe reinstall, and full factory reset — ordered from least to most destructive.

Contact support

Tell us what you tried and where it’s blocked — include the log tails above and any on-screen error.