When Control UI breaks, it rarely breaks in an interesting way.
It breaks in a way that feels random: you refresh, you re-login, it works once, then it fails again. People blame the dashboard. The real issue is almost always earlier in the chain: pairing, scopes, and where the gateway is actually running.
This report is a reading pack for operators who want Control UI to behave like infrastructure: reachable when you need it, understandable when it fails, recoverable when you upgrade.
Pairing Is Not a Login Screen
Pairing is a trust action. It answers questions like:
- Which runtime is allowed to act on behalf of which operator?
- Which scopes does the dashboard session have?
- Where does that authorization live (and how does it get out of sync)?
If you treat pairing like “a login,” you will keep redoing the same steps and never fix the underlying mismatch.
Start with /guides/openclaw-pairing-explained. It is the fastest way to get a stable mental model.
The Three Failure Patterns That Repeat
Most incidents fall into one of these:
- Straight unauthorized: you are not paired, you lost a token, or the session is invalid.
- Scope mismatch after changes: the gateway requires a scope you do not have yet (common after upgrades).
- Environment drift: the gateway service runs with different environment/state than your interactive shell (so the dashboard points at “a different reality” than you think).
The reading path is ordered to match those patterns.
Quick Fix Flow (If You’re Mid-Incident)
If you are currently locked out:
- Follow
/guides/control-ui-auth-and-pairingfor the concrete recovery steps (this covers the common “unauthorized” and 1008 cases). - If it mentions scope upgrades, jump to
/troubleshooting/solutions/gateway-pairing-required-scope-upgrade. - If the UI loads but behaves inconsistently across machines, read
/guides/openclaw-state-workspace-and-memoryto confirm you are not accidentally pointing at the wrong state directory.
Why Upgrades Make Control UI Feel Worse (Temporarily)
Upgrades often change one of:
- which scopes are required for a feature,
- where certain assets live (leading to missing/blank UI),
- the service installation behavior (so the running gateway differs from the one you just updated).
That is why “it worked yesterday” is not a strong debugging signal.
A Stable Operator Setup Checklist
If you want Control UI to be something you trust during an outage, aim for:
- one documented “source of truth” for the gateway endpoint you use,
- a clear pairing process you can repeat (and revoke) intentionally,
- a known recovery step for scope changes,
- backups and rollback before upgrades (
/guides/updating-and-migrationpairs well with this), - evidence: you can confirm what version and config the gateway is running, not just what you think you installed.
When Control UI Is “Working” But You Still Don’t Trust It
If the UI is reachable but feels like it turned your agent into a chatbot (it chats but won’t act), read /blog/openclaw-tools-profile-agent-to-chatbot after you stabilize pairing. It is a different class of problem, but it often shows up right after a Control UI incident because people start changing settings under stress.