Troubleshooting

OpenClaw not working? Start from these checks before random fixes

The official OpenClaw docs include a very useful triage ladder. If you follow it in order, you can quickly tell whether the problem is in the gateway, channels, model, dashboard, or system itself. This is the practical shortcut.

The first-60-seconds checklist

openclaw status
openclaw status --all
openclaw gateway probe
openclaw gateway status
openclaw doctor
openclaw channels status --probe
openclaw logs --follow

This sequence is recommended in the official docs for fast triage. If something fails here, there is no point changing plugins or models blindly.

If dashboard or Control UI do not connect

openclaw gateway status should show an active runtime and a healthy RPC probe.
If you see auth errors, the issue may be the token or authentication mode.
If you see connection errors, the cause is often a wrong URL or port.

Bring gateway and UI back into shape before changing anything else.

If the gateway does not start

port already in use
wrong gateway mode
bind without auth on non-local interfaces

The core commands stay the same: openclaw gateway status, openclaw doctor, and live logs.

If the issue looks model- or plugin-related

openclaw models status
openclaw models list
openclaw plugins list
openclaw plugins doctor

If a model is blocked, the issue may be an allowlist under agents.defaults.models.
If a plugin is installed but does not load, it may be missing a valid manifest or the right config.
Remember that native plugins run in-process inside the gateway, so a bad plugin can destabilize the whole system.