# Openclaw Debugger

Trigger when an OpenClaw agent is broken, silent, crashing, stuck, not responding...

- Repository: https://github.com/mergisi/awesome-openclaw-agents (4042 stars)
- Category: AI and agents
- License: MIT
- Last updated: 2026-10-28
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add mergisi/awesome-openclaw-agents --skill openclaw-debugger -g -a claude-code -y`
Codex: `npx skills add mergisi/awesome-openclaw-agents --skill openclaw-debugger -g -a codex -y`
Cursor: `npx skills add mergisi/awesome-openclaw-agents --skill openclaw-debugger -g -a cursor -y`
Gemini CLI: `npx skills add mergisi/awesome-openclaw-agents --skill openclaw-debugger -g -a gemini-cli -y`

## 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.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# 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

```bash
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

```bash
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

```bash
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

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

- If the file is >5 MB, sessions may be corrupt. Back it up and delete:
  ```bash
  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

The rest: https://github.com/mergisi/awesome-openclaw-agents/blob/HEAD/skills/claude/openclaw-debugger/SKILL.md