OpenClaw Debugger

Diagnose a broken OpenClaw agent (Orion, Echo, Radar, or any custom agent from awesome-openclaw-agents). Produces a structured diagnosis report identifying the most likely root cause.

Compatible with OpenClaw 2026.4.11 and later. For deeper reference see TROUBLESHOOTING.md in this repo.

When to use

• Agent returns empty output or times out
• openclaw agent --agent <name> --message "..." hangs
• Heartbeat dashboard shows the agent as stale
• Model provider errors (429, 401, connection refused)
• User says "openclaw is broken" / "agent is down" / "why is Orion not replying"

Instructions

Work through the checklist in order. Stop at the first failing step and report it, no need to run later steps until that's fixed.

1. Gateway health

openclaw agent --status

• If the gateway is down, tell the user to run openclaw gateway restart.
• If it reports "port 18789 in use by another process", find and kill the stale process (lsof -i :18789).

2. Tail recent logs

tail -n 200 ~/.openclaw/logs/gateway.log
tail -n 200 ~/.openclaw/agents/<name>/logs/agent.log

Grep for ERROR, PANIC, 401, 429, timeout. The first error in the tail is usually the real cause, everything after is fallout.

3. Heartbeat status

cat ~/.openclaw/agents/<name>/heartbeat.json

• Check last_seen timestamp. More than 5 minutes old = worker crashed.
• If status is starting for more than 60s, the agent is stuck in init (usually a bad SOUL.md or missing env var).

4. Session file integrity

ls -la ~/.openclaw/agents/<name>/sessions/sessions.json

• If the file is >5 MB, sessions may be corrupt. Back it up and delete:

  mv ~/.openclaw/agents/<name>/sessions/sessions.json{,.bak}
  

• If the JSON is invalid (python3 -m json.tool < sessions.json), same fix.

5. Model provider reachability