troubleshoot

name	troubleshoot
description	Step-by-step troubleshooting when something is broken. Triggers: "it's broken", "not working", "error", "help", "something wrong", "agent down".

Troubleshoot

MANDATORY: Gather evidence before suggesting fixes. Never guess without checking first.

Phase 1: Listen

Ask Trent:

1. What were you trying to do?
2. What happened instead? (What did you see?)
3. When did it start? Was it working before?
4. Did anything change recently? (Deploy, credential update, VPS restart, etc.)

If Trent can't answer all of these, that's fine. Gather what you can and move to Phase 2.

Phase 2: Gather Evidence

All of these are read-only (GREEN). Run them via SSH.

Dispatch the incident-responder agent with Trent's description. The agent will check:

1. Gateway health (openclaw gateway health)
2. Service status (systemctl is-active openclaw-gateway)
3. Recent logs (journalctl -u openclaw-gateway --since "1 hour ago" --no-pager | tail -50)
4. Unexpected processes (ss -tlnp | grep -v 'sshd\|openclaw\|systemd')
5. Disk space (df -h /)

Present the evidence to Trent in plain English before suggesting any fixes.

Phase 3: Diagnose

Based on evidence, match to common issues:

Symptom	Likely Cause	Quick Fix
Agent completely silent	Gateway service stopped	Restart: systemctl restart openclaw-gateway (YELLOW)
Agent gives garbled/error responses	API key expired or quota hit	Check provider dashboard, rotate key via /rotate-secrets
Agent stuck mid-response	Model failover broken	Check if fallback models are in allowed list (the config coupling bug)
Skills not working	Wrong invocation or not installed	Check: are they using /slash-command? Check: openclaw skills list
Cron jobs not firing	Gateway restart cleared cron	Re-run setup.sh to re-register crons
"Gateway closed (1008)" in logs	Missing paths in systemd config	Re-run deploy script
Slow responses	Provider latency	Check provider status page. Usually temporary.
Missing workspace files	Incomplete deploy	Re-run deploy script for affected agent
Can't SSH into VPS	VPS down or SSH key issue	Check Hostinger dashboard. Try from different network.

If the symptom doesn't match any of these, tell Trent: "This isn't a common issue. Let me dig deeper into the logs." Then search for specific error messages in the logs.

Phase 4: Fix

For each proposed fix:

1. Explain: What we're going to do, in plain English
2. Risk: GREEN / YELLOW / RED
3. Rollback: How to undo if it makes things worse
4. Confirm: Wait for Trent's "go ahead"
5. Execute: Run the single fix command
6. Verify: Check if it worked before moving on

NEVER apply multiple fixes at once. One change, verify, then decide on the next step.

Phase 5: Confirm Recovery

After applying the fix:

1. Run /health-check to verify system health
2. Ask Trent: "Can you try the thing that was broken? Is it working now?"
3. If still broken, go back to Phase 2 with the new evidence
4. If fixed: summarize what happened and what was done

If the fix didn't work after 2 attempts:

• Tell Trent: "We've tried the most likely fixes and it's still not working. I'd recommend reaching out to Sami with this summary:"
• Provide a copy-paste summary: symptom, evidence found, what was tried, current state

Rules

• NEVER skip Phase 2. No fixing without evidence.
• NEVER apply multiple fixes at once.
• Keep Trent informed at every step. "I'm checking the logs now..." is better than silence.
• If an unexpected network service is found during evidence gathering, immediately flag it as CRITICAL.
• If you suspect secrets may have been exposed, escalate immediately.
• After 2 failed fix attempts, escalate to Sami. Don't keep trying increasingly risky things.