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