ClawDoc 🦞🩺

A self-hosted Telegram bot that keeps your OpenClaw running. It monitors, diagnoses, and fixes problems automatically.

clawdoc.org

---

What you get

• Automatic recovery — checks OpenClaw every 15 minutes. If something breaks, it figures out why, fixes it, and tells you what happened.
• Remote control — restart services, check system health, and view logs from anywhere. Everything is a button tap in Telegram.
• Config rollback — your config is backed up automatically. If an update breaks something, preview the diff and restore any previous version with one tap.
• Full diagnostics — one button runs a complete health check and tells you exactly what's wrong. If it can fix the problem, it gives you a button for that too.
• Network monitoring — watches your connection and notifies you when it drops or comes back, along with how long the outage lasted.

---

When something breaks

ClawDoc works through a fix chain automatically, stopping as soon as the problem is resolved:

1. Check if the config is valid — if it's broken, restore from the most recent backup
2. Restart the gateway and verify it comes back healthy
3. If that didn't work, run OpenClaw's built-in doctor to repair common issues
4. If still down and AI is enabled, diagnose the error logs and try a targeted fix
5. If nothing works, message you with exactly what went wrong

Most issues are resolved at step 1 or 2.

---

Why it works

OS (launchd / systemd)
  └── keeps ClawDoc running
        └── keeps OpenClaw running

ClawDoc runs as its own system service, independent of OpenClaw. When OpenClaw goes down, ClawDoc is still there to bring it back.

---

Get started

1. Run the installer

curl -fsSL https://raw.githubusercontent.com/rungmc357/clawdoc/main/install.sh | bash

You'll be prompted for a Telegram bot token. ClawDoc finds your OpenClaw install automatically.

2. Claim your bot in Telegram

Send the claim code, choose your preferences, and you're done.

Let your AI do it

If you use OpenClaw or any AI coding agent:

"Install ClawDoc on my machine. Read the AGENTS.md at https://github.com/rungmc357/clawdoc for setup instructions."

---

Add AI if you want

Everything works with buttons out of the box. If you have Ollama running locally, ClawDoc can also understand plain English and do smarter diagnostics.

• "why is openclaw down?"
• Error log analysis
• Custom skills — "whenever I say /deploy, run git pull && pm2 restart all"

Skip it during setup and add it anytime.

---

Configuration

Config lives at ~/.config/clawdoc/config.json. Most settings can be changed via the /settings button in Telegram.

{
  "bot_token": "YOUR_BOT_TOKEN",
  "allowed_chat_id": 123456789,
  "ollama_model": "qwen3.5:4b",
  "shell_security": "disabled",
  "shell_session_timeout_min": 10,
  "watchdog_interval_min": 15,
  "network_monitor": true,
  "log_level": "INFO",
  "watched_services": [
    {
      "name": "OpenClaw",
      "url": "http://localhost:18789/health",
      "restart_cmd": "openclaw gateway restart",
      "log_file": "~/.openclaw/logs/gateway.log",
      "config_files": ["~/.openclaw/openclaw.json"]
    }
  ]
}

New commands

• /history — show last 10 commands with one-tap re-run
• /lock — immediately re-lock the shell session (password mode only)
• /reload — re-read config from disk without restarting

Natural language shortcuts

Common intents are caught before AI, so they work even without Ollama:

• "fix openclaw" / "repair openclaw" — suggests doctor fix
• "restart openclaw" / "openclaw is down" — shows restart button
• "disable [plugin]" — suggests the config edit command
• "whats wrong" / "check openclaw" — runs diagnostics

Session unlock (password mode)

When shell_security is "password", entering your password once unlocks the session for shell_session_timeout_min minutes (default 10). During this window, /run commands only need tap-to-approve, no password. Use /lock to re-lock early. The unlock status and time remaining are shown in /status and /settings.

Password security

Passwords are hashed with PBKDF2-HMAC-SHA256 (100,000 iterations, random salt). Legacy SHA-256 hashes are automatically upgraded on next successful login.

Watchdog improvements

• Loop guard — if a service is auto-restarted 3+ times within 5 minutes, ClawDoc stops restarting and alerts you instead.
• Proactive notifications — every watchdog action (config restore, restart, doctor fix) sends a Telegram message explaining what was found and what was done.
• Network false alarm prevention — requires 2+ consecutive check failures before declaring the network down.
• Last check time — /status shows when the watchdog last ran.

Enriched diagnostics

/debug now shows OpenClaw version, process CPU/memory, enabled plugins, and recent log entries. Down services on startup get one-tap fix buttons.

Smart character handling

iOS smart punctuation (-- → em-dash, smart quotes) is automatically normalized, so commands typed on iPhone work correctly.

Log verbosity

Set "log_level": "DEBUG" in config to see verbose logs. Default is "INFO". Routine messages like backup checks are at DEBUG level.

Rollback diff preview

The /rollback command shows a "Diff" button alongside each restore option. Tap it to see exactly what will change before restoring.

---

Uninstall

# Mac
launchctl unload ~/Library/LaunchAgents/io.clawdoc.agent.plist
rm ~/Library/LaunchAgents/io.clawdoc.agent.plist
rm -rf ~/.local/share/clawdoc ~/.config/clawdoc

# Linux
systemctl --user disable --now clawdoc
rm -rf ~/.local/share/clawdoc ~/.config/clawdoc

---

License

MIT — Built by @thatguygeo