openclaw-agent-debugger

OpenClaw Agent Debugger

Diagnose OpenClaw problems systematically — from symptom to root cause to exact fix.

Diagnostic Philosophy

Every OpenClaw problem has a finite set of root causes. This skill works through them systematically rather than guessing. It always starts with the most likely cause for the reported symptom and works outward.

---

Stage 1: Symptom Triage

Classify the reported problem into one of these categories:

Symptom	Most Likely Root Cause	First Check
Agent not responding at all	Gateway down / channel disconnected	openclaw gateway status
Wrong agent responding	Binding order wrong / default agent incorrect	Check bindings in openclaw.json
Heartbeat stopped firing	every: "0m" / activeHours window / no heartbeat block on any agent	Check heartbeat config
Heartbeat fires but no message sent	target: "none" or target resolves to nothing	Check target + to fields
Cron job not running	cron.enabled: false / wrong timezone / job disabled	openclaw cron list
Cron job runs but no delivery	delivery.mode: "none" / wrong channel target	Check job delivery config
Gateway won't start	Config validation error / port conflict / auth missing	openclaw doctor
Model errors	Wrong model string format / missing API key / rate limit	Check model.primary format
Memory not persisting	Workspace path wrong / file permissions / session type	Check workspace config
Channel offline	Auth expired / bot token invalid / account not linked	openclaw channels status --probe
"Unauthorized" on connect	Auth token mismatch	Check OPENCLAW_GATEWAY_TOKEN
Multiple agents, routing broken	Binding specificity order wrong	Check binding priority order

---

Stage 2: Gather Diagnostics

Request or run these commands in order. Each is a gate — stop if you find the problem.

Gate 1: Gateway health

openclaw gateway status           # Is Gateway running?
openclaw gateway status --deep    # Detailed health
openclaw status                   # Quick overview

If Gateway is down → skip to Gateway Recovery section

Gate 2: Config validation

openclaw doctor                   # Config errors, drift, known issues
openclaw doctor --fix             # Auto-repair where possible

If doctor reports errors → fix config errors first, then retest

Gate 3: Channel health

openclaw channels status --probe  # Are channels connected?
openclaw logs --follow            # Live log stream (watch for errors)

Gate 4: Agent and binding state

openclaw agents list --bindings   # Which agent handles which channel/peer?
openclaw agents list              # All agents and their workspaces

Gate 5: Cron state (if cron issues)

openclaw cron list                # All jobs, enabled/disabled status
openclaw cron runs --id <jobId>   # Run history for specific job

Gate 6: Session state

openclaw sessions                 # Active sessions

---

Stage 3: Diagnosis by Symptom

HEARTBEAT NOT FIRING

Check 1: Is heartbeat configured?

// In openclaw.json — does agents.defaults.heartbeat exist?
// OR does any agents.list[] entry have a heartbeat block?
// CRITICAL: If ANY agents.list[] entry has a heartbeat block,
// ONLY those agents run heartbeats — not agents without the block.

Fix: Add heartbeat block to the correct agent in agents.list.

Check 2: Is every set to 0?

openclaw config get agents.defaults.heartbeat.every
# If "0m" → heartbeat disabled globally

Fix: openclaw config set agents.defaults.heartbeat.every "30m"

Check 3: activeHours window

// Is current time outside activeHours.start → activeHours.end?
// Check timezone — is it correct IANA timezone?
// "Africa/Johannesburg" not "SAST" not "UTC+2"

Fix: Correct timezone or adjust hours.

Check 4: Target is none

// heartbeat.target: "none" → runs but never delivers

Fix: Set target: "whatsapp" + to: "+27XXXXXXXXX" on the agent.

Check 5: Heartbeat runs but HEARTBEAT_OK is stripped

// If HEARTBEAT.md is empty (only headers/blank lines),
// OpenClaw skips the heartbeat turn to save API calls.

Fix: Add actual checklist items to HEARTBEAT.md.

---

CRON JOB NOT RUNNING

Check 1: Cron enabled?

openclaw config get cron.enabled
# Must be true

Check 2: Job state

openclaw cron list
# Check: enabled=true, schedule correct, agentId correct

Check 3: Timezone

# Is the job scheduled in the right timezone?
# "0 7 * * *" with --tz "UTC" fires at 07:00 UTC = 09:00 SAST
# Common mistake: forgetting Africa/Johannesburg is UTC+2

Check 4: Run history

openclaw cron runs --id <jobId>
# Look for error entries — auth failures, model errors, delivery failures

Check 5: Agent binding

# If --agent flag was used, does that agentId exist?
openclaw agents list | grep <agentId>

Fix for stuck job with backoff:

openclaw cron run <jobId>   # Force immediate run

---

WRONG AGENT RESPONDING

Root cause: Binding order. More-specific bindings must come BEFORE less-specific ones.

Priority order (highest to lowest):

1. peer (exact DM/group ID)
2. parentPeer (thread)
3. guildId + roles (Discord)
4. guildId (Discord)
5. teamId (Slack)
6. accountId
7. channel (no accountId)
8. fallback (default agent)

Diagnosis:

openclaw agents list --bindings
# Review binding order — is the more-specific rule ABOVE the less-specific?

Common mistake:

// WRONG — channel-wide rule catches everything before peer rule
bindings: [
  { agentId: "apex", match: { channel: "whatsapp" } },           // catches all WhatsApp
  { agentId: "sentinel", match: { channel: "whatsapp",
    peer: { kind: "direct", id: "+27XXXXXXXXX" } } },             // never reached
]

// CORRECT — peer rule first
bindings: [
  { agentId: "sentinel", match: { channel: "whatsapp",
    peer: { kind: "direct", id: "+27XXXXXXXXX" } } },             // specific → first
  { agentId: "apex", match: { channel: "whatsapp" } },            // catch-all → last
]

---

GATEWAY WON'T START

Step 1:

openclaw doctor
# Read every error — schema violations stop the Gateway cold

Common config errors:

Error	Fix
Unknown key in config	Remove the unrecognised field — strict schema validation
refusing to bind gateway ... without auth	Non-loopback bind needs gateway.auth.token
EADDRINUSE / port conflict	Another Gateway running: openclaw gateway stop then restart
Gateway start blocked: set gateway.mode=local	Config set to remote mode when running locally
Model string format wrong	Use provider/model format: anthropic/claude-sonnet-4-6
agentDir collision	Two agents sharing same agentDir — give each a unique path

Step 2: After fixing, validate:

openclaw doctor --fix     # auto-repair where possible
openclaw gateway status   # confirm running

---

CHANNEL DISCONNECTED

WhatsApp:

openclaw channels status --probe
# If offline: re-link the account
openclaw channels login --channel whatsapp --account personal

Telegram:

# If offline: verify bot token is still valid
# Check: channels.telegram.accounts.default.botToken
# Env var: TELEGRAM_BOT_TOKEN
openclaw logs --follow  # Watch for "bot token invalid" errors

Discord:

# Check bot token, guild invite, Message Content Intent enabled
openclaw logs --follow  # Watch for Discord-specific errors

---

MODEL ERRORS

Check 1: Model string format

// Must be: "provider/model"
// Common mistakes:
"claude-opus-4-6"                      // WRONG — missing provider prefix
"claude-opus-4-20250514"               // WRONG — old model string format
"anthropic/claude-opus-4-6"            // CORRECT
"anthropic/claude-sonnet-4-6"          // CORRECT
"anthropic/claude-haiku-4-5-20251001"  // CORRECT

Check 2: API key present

# Anthropic key should be in environment or ~/.openclaw/.env
echo $ANTHROPIC_API_KEY  # should not be empty
cat ~/.openclaw/.env     # check if key is there

Check 3: Rate limits

openclaw logs --follow  # Look for "429" or "overloaded" errors
# Cron jobs have exponential backoff for rate limits — wait and retry

---

MEMORY NOT WRITING

Check 1: Workspace is writable

ls -la ~/.openclaw/workspace-[agentid]/
# Check permissions — should not be 444 on .md files other than SOUL/IDENTITY

Check 2: Correct workspace path

openclaw config get agents.list  # check workspace path for the agent
ls ~/.openclaw/workspace-[agentid]/  # does this directory exist?

Check 3: Session type

// MEMORY.md only loads in main/private sessions, NOT group contexts
// If agent is running in a group chat, MEMORY.md is intentionally excluded

Check 4: Compaction memory flush disabled

// Is memoryFlush.enabled: true?
agents.defaults.compaction.memoryFlush.enabled = true

---

Stage 4: Fix Output Format

After diagnosis, produce the fix in this format:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
DIAGNOSIS: [Agent/Feature] — [Root Cause]
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

ROOT CAUSE:
[Clear explanation of what's wrong and why]

FIX:
[Exact commands or file changes — copy-paste ready]

VERIFY:
[Command to confirm the fix worked]

PREVENT:
[One sentence on how to avoid this happening again]
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

---

Gateway Recovery (Emergency)

If Gateway is completely unresponsive:

# 1. Check if it's running
openclaw gateway status

# 2. Force stop and restart
openclaw gateway stop
openclaw gateway restart

# 3. If that fails, kill the process directly
pkill -f openclaw
openclaw gateway --port 18789

# 4. Check logs for why it crashed
openclaw logs --follow

# 5. If config is corrupted, validate
openclaw doctor

# 6. Nuclear option — reset to minimal config
cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak
# Restore a git-backed version:
cd ~/.openclaw && git log --oneline  # find last good commit
git checkout <commit-hash> -- openclaw.json
openclaw gateway restart

---

Quick Reference: All Diagnostic Commands

openclaw gateway status           # Gateway health
openclaw gateway status --deep    # Detailed health
openclaw doctor                   # Config validation + known issues
openclaw doctor --fix             # Auto-repair
openclaw channels status --probe  # Channel connectivity
openclaw agents list --bindings   # Agent routing state
openclaw cron list                # All cron jobs
openclaw cron runs --id <id>      # Cron run history
openclaw logs --follow            # Live log stream
openclaw sessions                 # Active sessions
openclaw config get <key>         # Read specific config value
openclaw config set <key> <val>   # Set specific config value
openclaw system event --text "x"  # Manual heartbeat trigger
openclaw cron run <id>            # Force cron job run