openclaw-debugger - SKILL.md Agent Skill

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?"