Skip to main content

​
Healthcheck

Keeps your AI running smoothly. Watches for problems, fixes what it can, and alerts you about the rest. Includes a daily backup system with verification. Zero npm dependencies. Runs via macOS LaunchAgent.

​
What It Does

Runs every 3 minutes and checks:
  1. Gateway process … is your AI’s gateway running?
  2. HTTP probe … does the gateway respond to requests?
  3. File descriptors … is the gateway approaching system limits?
  4. Token usage … are any sessions near context window capacity?
  5. Memory health (every 5th run) … NULL embedding vectors, API key errors, session export freshness, memory capture errors
When something fails:
  • Auto-restart: Restarts the gateway automatically (rate-limited so it doesn’t loop)
  • AI alert: Sends a message to your AI via the chat endpoint
  • iMessage fallback: Direct iMessage to you if the AI is unreachable

​
Install

git clone https://github.com/wipcomputer/wip-healthcheck.git
cd wip-healthcheck
cp config.example.json config.json
# Edit config.json with your values
bash install.sh
This installs a LaunchAgent that runs the healthcheck every 3 minutes.

​
Backup system (optional)

bash install-backup.sh
This installs:
  • A LaunchAgent that runs daily backups at midnight
  • A scheduled job that verifies the backup at 00:30

​
Configuration

Copy config.example.json to config.json and edit: 
{
  "gateway": {
    "host": "127.0.0.1",
    "port": 18789,
    "token": ""
  },
  "escalation": {
    "escalationContact": "you@icloud.com",
    "model": "",
    "viaAgent": true,
    "cooldownMinutes": 15
  },
  "paths": {
    "openclawHome": "",
    "sessionExports": "",
    "backupRoot": "",
    "backupExpectedFiles": ["crystal.db", "context-embeddings.sqlite"]
  },
  "backup": {
    "retentionDays": 7,
    "sources": []
  }
}

​
Key Fields

FieldWhatDefault
gateway.tokenGateway auth token. Auto-read from openclaw.json if empty.""
escalation.escalationContactiMessage address for direct fallback alerts.""
escalation.viaAgentTry alerting your AI before iMessage.true
paths.openclawHomeOpenClaw home folder.$OPENCLAW_HOME or ~/.openclaw
paths.backupRootWhere daily backups go. Empty skips backup verification.""
backup.retentionDaysDays of backups to keep.7

​
Backup Sources

Add custom backup sources to backup.sources: 
{
  "backup": {
    "sources": [
      { "type": "file", "src": "/path/to/file.db", "name": "file.db" },
      { "type": "tar",  "src": "/path/to/directory", "name": "archive.tar" },
      { "type": "dir",  "src": "/path/to/dir", "name": "dir-copy" }
    ]
  }
}
Types: file (copy), tar (archive directory), dir (recursive copy). If sources is empty, the backup script backs up core files automatically (crystal.db, context-embeddings.sqlite, main.sqlite, workspace, sessions, config).

​
Manual Run

node healthcheck.mjs       # run one check
bash backup.sh              # run one backup
bash verify-backup.sh       # verify today's backup

​
Uninstall

bash uninstall.sh           # removes healthcheck LaunchAgent

​
Files

healthcheck.mjs         Main watchdog script
backup.sh               Daily backup script (config-driven)
backup-wrapper.mjs      Node wrapper for backup LaunchAgent
verify-backup.sh        Backup verification (scheduled)
config.json             Your config (not committed)
config.example.json     Config template
install.sh              Install healthcheck LaunchAgent
install-backup.sh       Install backup LaunchAgent + verify job
uninstall.sh            Remove healthcheck LaunchAgent

​
Requirements

  • Node.js (18+)
  • macOS (uses LaunchAgent, iMessage, lsof)
  • OpenClaw gateway running

​
License

MIT