Troubleshooting
In a nutshell: check the lookup table on this page first β most issues can be resolved immediately. If you need to file an issue, include the Claw version, Claw logs, and relevant error screenshots.
Use cases
- Errors during installation, login, or connecting to Claw.
- Agent runs for a long time with no response, or is stuck waiting for input.
- Push notifications, downloads, or auto-updates fail intermittently.
Symptom lookup table
| Symptom | First step |
|---|---|
| Claw won't install | Run curl -fsSL .../install/claw.sh standalone and read the error |
| Claw shows offline | Check Claw management logs + Admin service reachability |
| Agent not responding | Check whether the LLM Connection is valid; look at the bottom-right error |
| Push not arriving | Check system notification permission + Admin FCM/APNs credentials |
| Download link 404 | Wait a few seconds and retry; the download source will auto-fall-back |
Installation errors
spawn node ENOENT
Usually a missing Node path in the runtime environment. The Claude Code Driver already auto-fills the Node path before startup. If the error persists, confirm the Claw process has loaded the latest code.
Failed to authenticate. API Error: 403 ... Request not allowed
API Key conflicts with an OAuth login state, or the key lacks permissions. The current local override prefers OAuth. If the error continues, confirm Claude Code has completed login first.
Not logged in Β· Please run /login
The local Claude Code OAuth session does not exist or has expired. Run /login and try again.
Connection issues
- Claw shows offline persistently: on the host, run
journalctl --user -u myclaws-claw -n 200(Linux) orlaunchctl list io.myclaws.claw(macOS) to confirm the service is running; then read the last few lines of Claw logs. - Changed direct-connect address but existing session did not switch: existing sessions require a manual reconnect; new sessions use the new address immediately.
LLM issues
- Streaming response never arrives: check the Base URL in the Connection. OpenRouter / Custom endpoints must have the correct routing URL.
token limit exceeded: adjust the context window size in the Connection, or compact manually with/compact.- Codex / Claude Code subagent fails: check whether the tool has a dedicated Connection selected. Prefer
reclaudeor a standalone OAuth connection.
Push issues
- iOS not responding: check ATS configuration + APNs credentials.
- Android FCM low delivery rate in mainland China: switch to the JPush channel.
- Background notification missing: system notification permission may be off. If the in-app message center shows the message correctly, the delivery chain is OK β only the notification layer is broken.
Download issues
/downloadredirects to 404: the server automatically falls back to the native OSS domainhttps://<bucket>.oss-<region>.aliyuncs.comor GitHub Release.- APK download requires enabling unknown sources: mobile browser security policy.
Log locations across surfaces
- Claw runtime logs:
~/.myclaws/claw/logs/and service logs (systemd / launchd). - Admin logs: depends on the deployment method (PM2 / Docker / Systemd).
- Client desktop logs: see the default Electron log path.
What to include when filing an issue
Always include environment info when filing an issue
Claw version, OS platform, error screenshot, and recent Claw logs (redacted) significantly reduce troubleshooting time.
If auto-update fails, run the install script manually again
This does not destroy data; the canonical path and service identity remain unchanged.
Cross-host migration is a high-risk operation
Back up ~/.myclaws/claw/data/ before proceeding. If something goes unrecoverably wrong, reinstall and restore from the backup.