// 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.
| 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. |
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.
openclaw agent --agent <name> --message "..." hangsWork through the checklist in order. Stop at the first failing step and report it — no need to run later steps until that's fixed.
openclaw agent --status
openclaw gateway restart.lsof -i :18789).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.
cat ~/.openclaw/agents/<name>/heartbeat.json
last_seen timestamp. More than 5 minutes old = worker crashed.status is starting for more than 60s, the agent is stuck in init (usually a bad SOUL.md or missing env var).ls -la ~/.openclaw/agents/<name>/sessions/sessions.json
mv ~/.openclaw/agents/<name>/sessions/sessions.json{,.bak}
python3 -m json.tool < sessions.json), same fix.Read ~/.openclaw/agents/<name>/SOUL.md frontmatter to find the configured model and provider. Then:
echo $ANTHROPIC_API_KEY | head -c 10 — confirm key exists.~/.openclaw/providers.json for the base URL and hit /v1/models with curl.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.
Read the agent's SOUL.md and check:
name, model, system_prompt fields)model string matches one in ~/.openclaw/providers.jsonPrint 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.
/openclaw-debugger orionopenclaw agent --agent radar timing out?"Trigger when the user asks to audit Claude Code costs, reduce token spend, says "my Claude bill is too high", "optimize my CLAUDE.md", "why is this project burning tokens", or "/cost-optimizer". Scans a project for the common Claude Code cost leaks and returns a prioritized fix list.
Trigger when the user asks for an architecture diagram, says "draw the system", "update the architecture diagram", "give me an excalidraw of this codebase", or "/excalidraw-architecture". Generates or updates an Excalidraw JSON file at docs/architecture.excalidraw by reading the codebase's key entry points.
Trigger when the user asks to write a commit message, generate a commit from staged changes, review a diff before committing, or says "/commit". Reads git diff --staged and produces an opinionated, convention-matching commit message.
Trigger when the user asks which model to use, wants to compare model costs, says "what's cheapest for this task", "should I use Opus or Sonnet", "can a smaller model handle this", or "/model-cost-compare". Estimates token cost across Opus 4.6, Sonnet 4.6, GLM-5.1, Minimax M2.7, and local Gemma 4, then recommends the cheapest model capable of the task.
Describe the role and your background, get a concise, compelling cover letter paragraph.
Paste raw meeting notes and get a clean summary with key decisions and action items.