/openclaw-debugger

name: openclaw-debugger
description: Trigger when an OpenClaw agent is broken, silent, crashing, stuck, not responding, returning empty output, or the user says "my agent is down", "agent not working", "/openclaw-debugger". Walks through the standard OpenClaw 2026.4 diagnosis checklist and prints a report.

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

Read `~/.openclaw/agents/<name>/SOUL.md` frontmatter to find the configured `model` and `provider`. Then:

• **Anthropic (Opus 4.6, Sonnet 4.6):** `echo $ANTHROPIC_API_KEY | head -c 10` — confirm key exists.
• **GLM-5.1 / Minimax M2.7:** check `~/.openclaw/providers.json` for the base URL and hit `/v1/models` with curl.
• **Gemma 4 local:** confirm Ollama or the local runtime is up (`curl localhost:11434/api/tags`).

A 401 means bad key. A 429 means you're rate limited — retry with exponential backoff or switch model. Connection refused on localhost means the local runtime crashed.

6. SOUL.md validity

Read the agent's `SOUL.md` and check:

• YAML frontmatter parses (must have `name`, `model`, `system_prompt` fields)
• `model` string matches one in `~/.openclaw/providers.json`
• No lingering Turkish prompts if the agent is supposed to respond in English (per repo rules)

Output format

Print a diagnosis report like this:

OpenClaw Debugger — <agent-name>

[OK]     Gateway up (port 18789)
[OK]     Logs clean
[FAIL]   Heartbeat stale (last_seen 14 min ago)
[SKIP]   Session file
[SKIP]   Model provider
[SKIP]   SOUL.md

Root cause: worker process crashed ~14 min ago. Last log line:
  ERROR 2026-04-13T08:41:02 panic: model provider returned 401

Fix:
  1. Export a fresh ANTHROPIC_API_KEY
  2. openclaw gateway restart
  3. openclaw agent --agent <name> --message "ping"

Keep it terse. The user wants a fix, not an essay.

Example invocations

• `/openclaw-debugger orion`
• "My Echo agent is stuck — debug it"
• "Why is `openclaw agent --agent radar` timing out?"