Troubleshooting OpenClaw — fixes that actually work.

Before any deeper debugging, run the built-in auditor. It catches most of the common issues — wrong file permissions, port conflicts, stale config keys, dead daemon — and applies fixes inline.

openclaw doctor --fix

Output looks like this:

✓ Gateway binary found at /usr/local/bin/openclaw
✓ Config valid: ~/.openclaw/openclaw.json
✗ Daemon not running
  → Starting... done
✓ Port 18789 available
✗ State directory permissions: 755 (should be 700)
  → Fixing... done
✓ All checks passed

If doctor --fix doesn't resolve your issue, the diagnostic below maps every known recurring symptom to its specific fix.

Type your error message or symptom. The tool finds the closest match in our index of recurring OpenClaw issues — built from GitHub Issues, Discord help threads, and our own support inbox.

The error message is generic but the cause almost always isn't. Three patterns produce 90% of these reports:

• OpenRouter base URL bug. The fresh setup writes https://openrouter.ai/v1 but the correct endpoint is https://openrouter.ai/api/v1. Add the /api.
• Empty turn from Anthropic. Opus 4.6/4.7 sometimes returns a zero-content "successful" response. Switch to Sonnet temporarily; the bug is being tracked.
• Wrong API key. openclaw models list returns nothing if the provider rejects the key. Test the key directly against the provider.

# The OpenRouter fix
sed -i 's|openrouter.ai/v1|openrouter.ai/api/v1|g' \
  ~/.openclaw/agents/main/agent/models.json
openclaw gateway restart

After openclaw update, you sometimes see:

Daemon restart failed: SyntaxError: The requested module
'../daemon-cli-B8367s61.js' does not provide an export named
'runDaemonInstall'

The update succeeded — just the auto-restart hit a hashed filename mismatch. Manually restart:

openclaw gateway stop
pkill -f openclaw-gateway      # belt and suspenders
openclaw gateway start
openclaw gateway status

If you also have a stale clawdbot-gateway service from a pre-rename install, that's the second cause of port conflicts:

sudo systemctl stop clawdbot-gateway 2>/dev/null
sudo systemctl disable clawdbot-gateway 2>/dev/null
openclaw service install

The agent says "I'd love to read that file but I don't have the read tool" — even though you added it. Cause: two layers of allow-listing.

Both must list the tool. Edit ~/.openclaw/openclaw.json:

{
  "agents": [{
    "id": "main",
    "tools": { "allow": ["read", "write", "exec", "browser"] }
  }],
  "tools": {
    "sandbox": {
      "tools": ["read", "write", "exec", "browser"]
    }
  }
}

Worth its own section because the fresh-install path produces this error so reliably. The signs:

• Set up via onboarding with OpenRouter selected
• First message returns "Couldn't generate a response"
• Logs show "incomplete turn detected: payloads=0"
• Direct test of your OpenRouter key works fine outside OpenClaw

The fix is one line:

sed -i 's|openrouter.ai/v1|openrouter.ai/api/v1|g' \
  ~/.openclaw/agents/main/agent/models.json
openclaw gateway restart

Or edit ~/.openclaw/agents/main/agent/models.json by hand and replace both openrouter.ai/v1 instances with openrouter.ai/api/v1.

After the agent runs long enough to trigger compaction, you sometimes see:

Error: tool_result block references unknown tool_use id

The compaction process can leave dangling references between tool_use and tool_result blocks. The session is unrecoverable once this happens — but durable facts in MEMORY.md are already saved (the memory flush ran before compaction).

openclaw sessions reset --agent main

Tracked in issues #9672, #8967, and #5497. The OpenClaw team is working on it; for now resetting is the workaround.

Three log destinations depending on how you're running:

The five most diagnostic log lines:

• incomplete turn detected: payloads=0 — model returned nothing. Wrong base URL, dead provider, or empty response.
• tool_result orphaned — session corruption from compaction. Reset.
• heartbeat skipped — rate-limited or model timeout. Check provider status page.
• sandbox denied tool — sandbox.tools needs that tool added.
• memory_search returned 0 results — index out of date. openclaw memory reindex.