OpenClaw Field Guide

Section 21: Troubleshooting

Every OpenClaw user eventually hits problems. That's normal.

The difference between a frustrating setup and a reliable one is not "never having errors." It is having a repeatable troubleshooting pattern.

Use this approach:

  1. confirm current state,
  2. inspect logs,
  3. run diagnostics,
  4. apply the smallest safe fix,
  5. retest.

Start with these commands:

🖥️ Type this in your terminal:

openclaw status

🖥️ Type this in your terminal:

openclaw logs --limit 50

🖥️ Type this in your terminal:

openclaw doctor

Troubleshooting matrix (symptom → likely cause → recovery)

Symptom Likely Cause Recovery Steps
Channel disconnected (WhatsApp/Telegram) Session expired, pairing dropped, connector auth stale Re-run onboarding for channel, then restart gateway and retest.
invalid_grant / OAuth auth errors Token expired/revoked or callback auth invalid Re-authorize account via onboarding flow and verify in dashboard.
API key rejected / unauthorized Wrong key, expired key, or insufficient provider permissions Regenerate key at provider, update config safely, restart and retest.
Gateway fails to start Config syntax error, missing required field, corrupted state Inspect log tail, validate config, restore backup if needed, restart.
Assistant repeats same failing action Loop caused by ambiguous instructions or failing dependency Stop gateway, inspect loop trigger, simplify instructions, restart safely.
Responses stale, wrong, or out of context Outdated memory/state files or bad project context Review/update memory and STATE docs, clear obsolete instructions, retest.
Sudden high API cost Runaway retries, oversized prompts, repeated failure cycles Stop gateway immediately, inspect logs, add stop-on-fail guardrails.
Assistant silent/no replies Gateway down, provider outage, channel transport issue Check status + doctor + logs, restart gateway, verify provider/channel health.
Provider returns intermittent failures External provider outage/rate limits Switch/fail over model/provider if configured; retry later with reduced load.

::: beginner Most incidents are not catastrophic. They are usually one of five buckets: auth, config, channel session, loops, or provider instability. :::

Recovery playbooks by issue type

1) Auth/token problems (OAuth/API)

Typical signs:

  • invalid_grant
  • unauthorized responses
  • channel/account was working, then suddenly stopped

Steps:

  1. Check diagnosis and recent logs

🖥️ Type this in your terminal:

openclaw doctor

🖥️ Type this in your terminal:

openclaw logs --limit 50
  1. Re-run onboarding for fresh authorization

🖥️ Type this in your terminal:

openclaw onboard
  1. Restart and verify

🖥️ Type this in your terminal:

openclaw gateway restart

🖥️ Type this in your terminal:

openclaw status

2) Channel pairing failures

Typical signs:

  • WhatsApp/Telegram appears disconnected
  • dashboard shows channel unhealthy

Steps:

  1. Run onboarding to repair pairing

🖥️ Type this in your terminal:

openclaw onboard
  1. Restart gateway

🖥️ Type this in your terminal:

openclaw gateway restart
  1. Check dashboard and send a test message

🖥️ Type this in your terminal:

openclaw dashboard

3) Config errors (openclaw.json issues)

Typical signs:

  • gateway will not start
  • logs show parse/schema errors

Steps:

  1. View config file and confirm structure issues

🖥️ Type this in your terminal:

cat ~/.openclaw/openclaw.json
  1. Ensure backup exists (or create one before changes)

🖥️ Type this in your terminal:

cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak
  1. Restart and run diagnostics after correction

🖥️ Type this in your terminal:

openclaw gateway restart

🖥️ Type this in your terminal:

openclaw doctor

::: warning Never do frantic multi-edit fixes while the gateway is flapping. Make one deliberate correction, then retest. :::

4) Bad loops / runaway retries

Typical signs:

  • repetitive similar logs
  • repeated API calls with no progress
  • rising usage/cost

Emergency stop first:

🖥️ Type this in your terminal:

openclaw gateway stop

Then inspect what triggered repetition:

🖥️ Type this in your terminal:

openclaw logs

When fixed, resume safely:

🖥️ Type this in your terminal:

openclaw gateway start

Then verify:

🖥️ Type this in your terminal:

openclaw doctor

5) Provider outages or degraded service

Typical signs:

  • requests time out
  • provider-specific error spikes
  • issue appears across channels simultaneously

Steps:

  1. Confirm your gateway is healthy

🖥️ Type this in your terminal:

openclaw status
  1. Check diagnostics and logs

🖥️ Type this in your terminal:

openclaw doctor

🖥️ Type this in your terminal:

openclaw logs --limit 50
  1. If local setup is fine, treat as provider-side incident:
  • wait and retry later
  • switch provider/model if your setup supports fallback
  • reduce request volume until service stabilizes

A practical first-response checklist

When anything breaks, run this order exactly:

🖥️ Type this in your terminal:

openclaw status

🖥️ Type this in your terminal:

openclaw logs --limit 50

🖥️ Type this in your terminal:

openclaw doctor

If still unresolved:

🖥️ Type this in your terminal:

openclaw gateway restart

Then test one known-good action in your primary channel.

If channel-specific issue persists:

🖥️ Type this in your terminal:

openclaw onboard

When to escalate for help

Escalate when:

  • same issue remains after two careful attempts
  • logs show unclear internal errors you cannot interpret
  • outage appears external and prolonged

Where to get help:

  • docs.openclaw.ai
  • Community Discord: discord.gg/clawd
  • GitHub issues: github.com/openclaw/openclaw

When posting for help, include:

  • OpenClaw version
  • exact symptom
  • last relevant log lines (redacted)
  • what commands you already ran

This gets you useful help faster.

Realistic scenario: "Assistant started sending stale answers and then stopped replying."

A user notices replies are outdated, then no responses at all.

What likely happened:

  • context/state drift first
  • then a provider failure or gateway instability

Recovery sequence:

  1. Confirm runtime and diagnostics

🖥️ Type this in your terminal:

openclaw status

🖥️ Type this in your terminal:

openclaw doctor
  1. Inspect recent logs

🖥️ Type this in your terminal:

openclaw logs --limit 50
  1. Restart gateway

🖥️ Type this in your terminal:

openclaw gateway restart
  1. Verify dashboard/channel

🖥️ Type this in your terminal:

openclaw dashboard
  1. If auth-related errors appear, re-run onboarding

🖥️ Type this in your terminal:

openclaw onboard

Result: replies resume, stale-state issue identified, and no full reinstall required.

::: action Keep a "known-good recovery sequence" in your notes and follow it under pressure. Consistent troubleshooting beats improvised troubleshooting. :::

Self-check summary

  • Drafted all three required sections with exact headings: ## Section 19: Keeping Your Setup Updated, ## Section 20: Terminal Basics and Command Cheat Sheet, and ## Section 21: Troubleshooting.
  • Followed OUTLINE_v2 guidance: Section 19 includes update flow, cautions, and compatibility checks; Section 20 covers terminal basics across macOS/Linux/Windows plus navigation and command explanations; Section 21 includes a troubleshooting matrix with clear symptom→cause→fix paths.
  • Included every required command exactly in fenced code blocks where relevant: openclaw status, openclaw gateway start, openclaw gateway stop, openclaw gateway restart, openclaw dashboard, openclaw update, openclaw doctor, openclaw onboard, openclaw logs, openclaw logs --limit 50, cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak, cat ~/.openclaw/openclaw.json.
  • Maintained warm, practical, secular, non-patronizing tone for non-technical readers and used only allowed callouts: beginner, warning, tip, power-user, action.
  • Added one realistic scenario in each section and kept total length within the requested range (~2300-3000 words).