OpenClaw Troubleshooting — Fix Setup, Auth, Channels, and Gateway Issues Fast

Exact checks to go from “it’s not working” to “it’s reliable.”

I love building powerful software, but I hate fragile software. OpenClaw is designed to be hackable and composable, and that also means there are more moving parts than a single “chat app.” This page is your fastest path from failure to reliability.

Before you debug: understand the 4 parts that usually fail

Gateway

The running service that hosts the Control UI endpoint and executes work.

Auth

OAuth/API keys and gateway token that allow the agent to respond and the UI to connect.

Channels

WhatsApp/Telegram/Discord/etc integrations and their runtime requirements.

Policies & Pairing

DM safety and sandboxing defaults that prevent unknown users from triggering actions.

If you identify which layer is failing, you can usually fix the issue in under 10 minutes.

Quick triage (5 minutes)

Run these commands first and keep the output—this is the fastest way to locate the failure:

openclaw status
openclaw health
openclaw status --all
openclaw gateway status

If you installed the background service during onboarding, the gateway should already be running; otherwise start it manually in the foreground and enable verbose logs while you troubleshoot.

Problem: “I can’t open the dashboard” (or it’s blank)

The fastest chat surface is the Control UI in your browser, served locally by the gateway.

Try opening http://127.0.0.1:18789/ on the gateway host (the machine where OpenClaw is running).

If you’re not on that machine, you won’t be able to reach loopback—use remote access patterns (SSH tunnel/VPN) instead of exposing the gateway publicly.

If the page loads but asks for a token (or refuses to connect), that’s usually gateway auth doing its job: the onboarding wizard generates a gateway token by default and stores it in gateway.auth.token. In the Control UI, paste the token into settings as connect.params.auth.token so the UI can authenticate to the gateway.

Problem: “It says no auth configured” (agent won’t respond)

OpenClaw can run without a model, but it can’t respond intelligently without model authentication configured.

If openclaw health reports “no auth configured,” go back to onboarding and set OAuth or an API key (the CLI onboarding wizard openclaw onboard is the main path).

OpenClaw stores auth profiles under ~/.openclaw/agents/<agentId>/agent/auth-profiles.json, and legacy OAuth credentials may exist at ~/.openclaw/credentials/oauth.json—this matters when you move a gateway to a new host.

Problem: “WhatsApp/Telegram doesn’t work” (runtime + pairing)

For WhatsApp, you must link the device via QR login; use the CLI flow openclaw channels login to initiate it.

For Telegram/Discord and other providers, missing or incorrect bot tokens are common—re-run the wizard or re-check your provider config.

The docs explicitly warn that Bun has known issues with WhatsApp + Telegram; run the gateway with Node for those channels.

If you DM the bot and it doesn’t respond, it may be working correctly: OpenClaw’s default DM safety posture uses pairing approvals, where unknown DMs are not processed until approved.

List and approve pairings using: openclaw pairing list whatsapp and openclaw pairing approve whatsapp <code> (adjust the channel as needed). This is a feature, not a bug—especially if your gateway has access to files and shell commands.

Problem: “Token mismatch / unauthorized / 401”

A token mismatch usually means one of three things: the gateway token changed, the UI is pointing to a different gateway, or you copied a config to a new machine without moving credentials.

Confirm the gateway you’re connecting to (host + port), then confirm the token in gateway.auth.token, then re-enter it in the Control UI (connect.params.auth.token).

If you’re running multiple instances (local + VPS, or multiple gateways), label them clearly so you don’t debug the wrong box.

Problem: “It works in the UI, but behaves weird in group chats”

OpenClaw has sandboxing defaults so that group/channel sessions can be isolated from your “main” agent context.

Agents defaults like agents.defaults.sandbox.mode: "non-main" use session.mainKey (default "main") so group/channel sessions are sandboxed.

If you want your main agent to always run on the host, set a per-agent override in routing config (for your main agent, set sandbox.mode: "off").

Problem: “Search/web tools don’t work”

If web search fails, it’s often missing a search provider API key.

Use openclaw configure --section web to store tools.web.search.apiKey (Brave Search recommended).

Once configured, rerun openclaw health to confirm the tool is available and your workflow can fetch sources.

Problem: “I installed on Windows and things keep breaking”

OpenClaw’s docs strongly recommend WSL2 (Ubuntu recommended). Native Windows has poorer tool compatibility and is untested for some providers.