Setup
Initial install or first-run confusion
When the local app, gateway, or browser UI is up but it is not clear how the parts fit together or what should be reachable first.
A practical guide for diagnosing common OpenClaw setup, pairing, access, and remote-connectivity issues without turning a small problem into a full rebuild.
Useful for owners and operators managing private AI assistant setups, especially when local vs remote behavior becomes confusing.
When the local app, gateway, or browser UI is up but it is not clear how the parts fit together or what should be reachable first.
Pairing required, unauthorized, invalid token, expired setup code, or similar first-time connection failures.
The most common pattern: local LAN or browser access works, but Tailscale, remote URLs, or companion access does not.
Check whether you are trying to reach the local UI, a gateway-exposed interface, or a remote companion path. Many “it is broken” reports are really routing or endpoint confusion between local, tailnet, and public-access methods.
That usually points to a stale or mismatched pairing flow. Regenerate the pairing/setup path cleanly and avoid mixing older setup codes, old public URLs, or expired bootstrap tokens.
That usually means the local service is healthy but remote routing is wrong. Check Tailscale connectivity first, then confirm the remote URL, gateway binding, and whether the expected port or public URL is actually being served.
When a previously working setup fails after an upgrade, compare versions, restart the relevant service cleanly, and confirm that config assumptions did not change. Broken-state troubleshooting should start with process order: service health, URL/access layer, then pairing state.
First confirm the local service actually starts, the expected interface is up, and the local URL responds before introducing pairing or remote access complexity.
If errors mention pairing required, unauthorized, invalid bootstrap token, or expired codes, focus on the device-pairing flow rather than generic network debugging.
If local works but remote does not, verify tailnet status, reachable hostnames, and whether the intended remote endpoint matches the actual bound service.
Separate gateway issues from app issues. A reachable gateway does not always mean the pairing, routing, or downstream app configuration is correct.
If local access fails, remote debugging is premature. Confirm the base service before touching Tailscale or public URLs.
Old pairing links and tokens create fake complexity fast. Use one fresh path when reattempting setup.
Application health, gateway routing, pairing state, and remote networking are not the same failure class.
When a setup changes after an update, verify state and configuration before assuming a total reinstall is needed.
If the problem involves private assistant architecture, remote deployment design, Tailscale exposure choices, repeated broken states after upgrades, or uncertainty about cloud vs private paths, it is often worth moving from ad hoc troubleshooting to a cleaner implementation review.
Sopraminds can help with private assistant deployment, OpenClaw troubleshooting, workflow integration, and choosing the right cloud or self-hosted setup path.