Start here
The triage ladder
Something broke and you need to figure out what. Do not panic. Run these commands in order. Most issues show up by step 3. Each command gives you more detail than the last, so by the time you reach the bottom you will know exactly what went wrong.
Most issues resolve themselves by step 3. If you get to `openclaw logs --follow` and still can't figure it out, copy the output of `openclaw status --all` and paste it in the Skool community. It redacts sensitive tokens automatically, so it's safe to share.
If the Gateway RPC is unreachable, fall back to the raw log file: /tmp/openclaw/openclaw-YYYY-MM-DD.log
Core process
Gateway won't start
The Gateway is the always-running process that powers your OpenClaw agent. If it won't start, nothing else works. Here are the three most common reasons it fails and how to fix each one.
EADDRINUSE / another gateway instance is already listeningWhy: Port 18789 is already in use by another process.
Fix: openclaw gateway stop, then start again. Or use --port to pick a different port.
Gateway start blocked: set gateway.mode=localWhy: Gateway mode is unset or set to remote.
Fix: Set gateway.mode: "local" in ~/.openclaw/openclaw.json.
Refusing to bind gateway without authWhy: Non-loopback bind attempted without token or password configured.
Fix: Add gateway.auth.mode and gateway.auth.token to your config.
Nine times out of ten, it's the port conflict. Run `lsof -i :18789` and you'll find the culprit. If you recently force-quit OpenClaw, the old process might still be hanging around.
Channel issues
No replies to messages
Your Gateway is running but your agent is not responding? This is usually a channel or permissions issue. Here is what to check.
Sender not paired / awaiting approvalWhy: DM policy is set to pairing and the sender has not been approved.
Fix: openclaw pairing list <channel> to see pending requests, then approve.
Mention gating blocks group messagesWhy: Bot requires @mention in groups but was messaged without one.
Fix: Mention the bot by name, or set mentionRequired: false for the group.
Channel shows disconnected / 401 / 403Why: Bot token expired or permissions changed on the channel platform.
Fix: openclaw channels status --probe, then re-authenticate the channel.
This is the most common support question in our community. Almost always it's either the sender not being approved (pairing mode) or the bot not being @mentioned in a group. Check those two things first before diving deeper.
API & credentials
Model and auth errors
These pop up when OpenClaw can't reach your AI model provider. Could be a missing API key, a rate limit, or a model that is not configured. Here is how to fix each one.
No credentials found for profile anthropic:defaultWhy: API key not configured for this agent.
Fix: Add ANTHROPIC_API_KEY=sk-ant-... to your ~/.openclaw/.env file, then restart the Gateway with openclaw gateway restart.
HTTP 429: rate_limit_errorWhy: Rate limit or quota exhausted for the current billing window.
Fix: Wait for reset, upgrade your plan, or configure a fallback model.
Model 'provider/model' is not allowedWhy: agents.defaults.models acts as an allowlist and this model is not on it.
Fix: Add the model to the allowlist, or remove the restriction.
If you just set up a new API key and it's not working, remember to restart the Gateway. OpenClaw reads env vars at startup, not on the fly. A quick `openclaw gateway restart` fixes most 'missing credentials' issues.
Browser interface
Dashboard / Control UI issues
The Control UI is your browser-based command center for OpenClaw. If it won't connect or keeps disconnecting, the issue is almost always an auth token mismatch.
Unauthorized / reconnect loop in Control UIWhy: Token in browser localStorage does not match gateway token.
Fix: openclaw dashboard prints the correct URL and token. Paste into UI settings.
Invalid handshake / code 1008Why: Gateway expected a WebSocket connect frame but got an HTTP request.
Fix: Use the WebSocket URL ws://<host>:18789, not the HTTP URL.
Device identity requiredWhy: Non-HTTPS context cannot complete device authentication.
Fix: Access via localhost (HTTPS not required) or set up HTTPS/Tailscale.
The token mismatch issue trips up almost everyone the first time. The fix is simple: run `openclaw dashboard`, copy the URL it prints (it includes the token), and paste it into your browser. Don't try to construct the URL manually.
Scheduled tasks
Cron / heartbeat / automation
Scheduled tasks depend on the Gateway running continuously. If your cron jobs or heartbeat aren't firing, start here.
Cron: scheduler disabled; jobs will not run automaticallyWhy: Cron is disabled in config or OPENCLAW_SKIP_CRON is set.
Fix: Set cron.enabled: true in config and unset OPENCLAW_SKIP_CRON.
Heartbeat skipped: reason=quiet-hoursWhy: Current time is outside the configured activeHours window.
Fix: Check activeHours.timezone. May differ from your actual timezone.
Jobs run at wrong wall-clock timeWhy: Timezone mismatch between cron schedule and gateway host.
Fix: Set explicit --tz on cron jobs. Verify host timezone with date.
The timezone issue is sneaky. Your VPS might be in UTC while your cron schedule assumes your local timezone. Always set an explicit `--tz` flag on cron jobs, especially if your server is in a different timezone than you.
Staying current
How to update OpenClaw
OpenClaw moves fast. New features, bug fixes, and security patches ship regularly. Updating takes about 60 seconds and your config, workspace, and session history are all preserved. Three paths depending on how you installed.
npm / pnpm (global install)
The doctor command migrates config if the schema changed between versions.
Docker (git clone + compose)
Volumes bind-mount ~/.openclaw, so config and data persist across image rebuilds.
One-click PaaS (Railway, Northflank, Render)
Persistent volumes at /data keep your config. The new image pulls the latest OpenClaw.
We update our client deployments every two weeks. The process takes about 60 seconds per server. Always run `openclaw doctor` after updating. It catches config schema changes that would otherwise cause confusing errors.
Deep debugging
Diagnostic tools
When the triage ladder does not pinpoint the issue, these tools let you look under the hood. Most users never need these, but when you do, they save hours of guessing.
Diagnostic flags
OPENCLAW_DIAGNOSTICS=telegram.http,gateway.* openclaw gateway restartEnable debug logs for specific subsystems without turning on verbose logging everywhere. Supports wildcards. Safe to leave enabled.
Raw stream logging
OPENCLAW_RAW_STREAM=1 openclaw gateway restartCaptures every LLM request and response as newline-delimited JSON at ~/.openclaw/logs/raw-stream.jsonl. Includes full prompts and tool output. Delete after debugging.
Gateway watch mode
pnpm gateway:watchAuto-restarts the Gateway on source file changes. Fast iteration for developers working from a git clone.
Dev profile isolation
OPENCLAW_PROFILE=dev openclaw gateway --devRuns a separate Gateway instance with isolated state at ~/.openclaw-dev on port 19001. Does not interfere with your production Gateway.
Deep health check
openclaw status --deepProbes every configured model provider for reachability. Shows which providers are up, which keys are valid, and which are rate-limited.
The diagnostic flags option is the most useful tool here. Instead of turning on verbose logging everywhere (which floods your log file), you can target exactly the subsystem that's misbehaving. We leave `gateway.*` diagnostics enabled on all production deployments.
Quick reference
Important file paths
When you are debugging, knowing where OpenClaw keeps its files saves time. Here are the paths you will reference most often.
| Path | Purpose |
|---|---|
| ~/.openclaw/openclaw.json | Main config file |
| ~/.openclaw/.env | Global env vars for Gateway service |
| ~/.openclaw/agents/<id>/agent/auth-profiles.json | Per-agent auth credentials |
| ~/.openclaw/agents/<id>/sessions/ | Conversation history |
| /tmp/openclaw/openclaw-YYYY-MM-DD.log | Structured file log (rotated daily) |
| ~/.openclaw/logs/raw-stream.jsonl | Raw LLM request/response stream |
Written by
Kevin Jeppesen
Founder, The Operator Vault
Kevin is an early OpenClaw adopter who has saved an estimated 400 to 500 hours through AI automation. He stress-tests new workflows daily, sharing what actually works through step-by-step guides and a security-conscious approach to operating AI with real tools.
Troubleshooting FAQ
Common questions
Still stuck?
Get help from 300+ operators.
The Operator Vault community has seen every OpenClaw error. Ask in Skool, get an answer from someone who fixed it.