claw-sos
Emergency recovery tool for OpenClaw. Diagnoses and fixes unresponsive bots via SSH.
Install
The script is bundled at scripts/sos.sh. Install locally:
cp scripts/sos.sh /usr/local/bin/sos
chmod +x /usr/local/bin/sos
To install on a remote machine:
scp scripts/sos.sh root@<IP>:/usr/local/bin/sos
ssh root@<IP> "chmod +x /usr/local/bin/sos"
Alternative — install from GitHub:
curl -fsSL https://raw.githubusercontent.com/clawsos/claw-sos/main/install.sh | bash
Usage
Interactive (human via SSH)
sos # whiptail arrow-key menu
Non-interactive (agent or cron)
sos auto # autofix: diagnose → doctor → restart → force → nuclear
sos net # network check only
sos tg # telegram test message
sos --version
sos --help
When the bot is down — decision tree
- Run
sos auto— handles 95% of cases automatically - If autofix fails → run
sos net— if network is broken, fix DNS/internet first - If network is fine but bot still down → run
sos tg— check Telegram delivery - If Telegram fails → check bot token validity
- Last resort →
sosmenu option 9 (Nuclear) — kills everything and starts fresh
Menu Options
| # | Name | What it does | Safe? |
|---|---|---|---|
| 1 | Check status | Gateway running, RAM, disk, version | ✅ Read-only |
| 2 | Restart | Graceful restart | ✅ Safe |
| 3 | Force kill | Kill process + restart | ⚠️ Drops active sessions |
| 4 | Rollback | Revert to previous version + config | ⚠️ Downgrade |
| 5 | View logs | Last 50 lines of gateway log | ✅ Read-only |
| 6 | Full diagnostic | RAM, disk, Telegram, sessions, process | ✅ Read-only |
| 7 | Backup config | Save config + version before changes | ✅ Safe |
| 8 | Self-test | Verify SOS script works | ✅ Read-only |
| 9 | Nuclear | Kill ALL openclaw processes, reload | 🔴 Last resort |
| 10 | Autofix | Escalating auto-repair | ⚠️ May restart |
| 11 | Network check | DNS, internet, Telegram API, Anthropic | ✅ Read-only |
| 12 | Telegram test | Send real test message | ✅ Safe |
Autofix Escalation Order
- Diagnose: process, RAM, disk
- Clean RAM/disk if critical
openclaw doctor --fix- Graceful restart → wait 15s → check
- Force kill + restart → wait 15s → check
- Nuclear (kill all + reload)
Stops as soon as gateway is healthy.
Log Location
All actions logged to ~/.openclaw/backups/sos.log. Read this to understand what happened during recovery:
cat ~/.openclaw/backups/sos.log
Platform Support
- Linux: Full support (systemd, journalctl, free, /proc)
- macOS: Full support (launchctl, log show, vm_stat, purge, dialog fallback)
- Docker: Partial — no systemd, manual fallback works
Credentials
This skill uses no API keys or tokens of its own. It reads existing OpenClaw config to:
- Check gateway status (local process, no network)
- Send Telegram test messages (uses the bot token already configured in
openclaw.json) - Check Anthropic API reachability (HTTPS ping only, no auth)
No credentials are stored, transmitted, or required to install or run SOS.