Spaces:
Paused
Paused
File size: 2,628 Bytes
caea1dc | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 | ---
summary: "Troubleshooting hub: symptoms → checks → fixes"
read_when:
- You see an error and want the fix path
- The installer says “success” but the CLI doesn’t work
title: "Troubleshooting"
---
# Troubleshooting
## First 60 seconds
Run these in order:
```bash
openclaw status
openclaw status --all
openclaw gateway probe
openclaw logs --follow
openclaw doctor
```
If the gateway is reachable, deep probes:
```bash
openclaw status --deep
```
## Common “it broke” cases
### `openclaw: command not found`
Almost always a Node/npm PATH issue. Start here:
- [Install (Node/npm PATH sanity)](/install#nodejs--npm-path-sanity)
### Installer fails (or you need full logs)
Re-run the installer in verbose mode to see the full trace and npm output:
```bash
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --verbose
```
For beta installs:
```bash
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --beta --verbose
```
You can also set `OPENCLAW_VERBOSE=1` instead of the flag.
### Gateway “unauthorized”, can’t connect, or keeps reconnecting
- [Gateway troubleshooting](/gateway/troubleshooting)
- [Gateway authentication](/gateway/authentication)
### Control UI fails on HTTP (device identity required)
- [Gateway troubleshooting](/gateway/troubleshooting)
- [Control UI](/web/control-ui#insecure-http)
### `docs.openclaw.ai` shows an SSL error (Comcast/Xfinity)
Some Comcast/Xfinity connections block `docs.openclaw.ai` via Xfinity Advanced Security.
Disable Advanced Security or add `docs.openclaw.ai` to the allowlist, then retry.
- Xfinity Advanced Security help: https://www.xfinity.com/support/articles/using-xfinity-xfi-advanced-security
- Quick sanity checks: try a mobile hotspot or VPN to confirm it’s ISP-level filtering
### Service says running, but RPC probe fails
- [Gateway troubleshooting](/gateway/troubleshooting)
- [Background process / service](/gateway/background-process)
### Model/auth failures (rate limit, billing, “all models failed”)
- [Models](/cli/models)
- [OAuth / auth concepts](/concepts/oauth)
### `/model` says `model not allowed`
This usually means `agents.defaults.models` is configured as an allowlist. When it’s non-empty,
only those provider/model keys can be selected.
- Check the allowlist: `openclaw config get agents.defaults.models`
- Add the model you want (or clear the allowlist) and retry `/model`
- Use `/models` to browse the allowed providers/models
### When filing an issue
Paste a safe report:
```bash
openclaw status --all
```
If you can, include the relevant log tail from `openclaw logs --follow`.
|