Diagnoses and auto-heals BlueBubbles ↔ OpenClaw iMessage connectivity. Use when: iMessages stop arriving after a gateway restart, webhook connection is broken, or user reports messages not coming through. Runs a 4-step diagnostic and auto-fixes webhook backoff, stale registrations, and gateway issues.
Use this skill when:
Diagnoses and auto-heals the webhook connection between BlueBubbles and OpenClaw. This is a common failure mode: after gateway restarts, BlueBubbles can lose its webhook or enter backoff state.
Diagnostic checks:
Auto-healing:
BB_URL="http://127.0.0.1:1234" \
BB_PASSWORD="your-password" \
~/.openclaw/workspace/skills/bluebubbles-healthcheck/scripts/diagnose.sh
Interpret the output:
BB_URL="http://127.0.0.1:1234" \
BB_PASSWORD="your-password" \
~/.openclaw/workspace/skills/bluebubbles-healthcheck/scripts/heal.sh
This will:
BB_URL="http://127.0.0.1:1234" \
BB_PASSWORD="your-password" \
~/.openclaw/workspace/skills/bluebubbles-healthcheck/scripts/heal.sh --dry-run
| Variable | Required | Default | Description |
|---|---|---|---|
BB_URL | Yes | http://127.0.0.1:1234 | BlueBubbles server URL |
BB_PASSWORD | Yes | — | BlueBubbles API password |
OPENCLAW_WEBHOOK_URL | No | http://127.0.0.1:18789/bluebubbles-webhook | OpenClaw webhook endpoint |
You can also pass these as args: --bb-url, --password, --webhook-url
User reports iMessage issue
↓
Run diagnose.sh
↓
┌────┴────┐
│ All ✅? │
└────┬────┘
Yes │ No
↓ │ ↓
Report │ Run heal.sh
healthy │ ↓
│ ┌───┴───┐
│ │Fixed? │
│ └───┬───┘
│ Yes │ No
│ ↓ │ ↓
│Report│ Escalate to user:
│fixed │ - BB app not running?
│ │ - Network issue?
└──────┴─ Manual intervention needed
Symptoms: Messages stop after openclaw gateway restart
Fix: heal.sh will reset webhook
Symptoms: Webhook exists but BB stopped trying to deliver
Fix: heal.sh deletes and re-registers webhook (clears backoff state)
Symptoms: Check 3 fails (port 18789 not listening)
Fix: heal.sh runs openclaw gateway restart
Symptoms: Check 1 fails (HTTP 000) Fix: Manual — user must start BlueBubbles.app on the Mac
skills/bluebubbles-healthcheck/
├── SKILL.md ← You are here
├── README.md ← GitHub docs
└── scripts/
├── diagnose.sh ← Read-only diagnostics (exit 0 = healthy)
├── heal.sh ← Auto-heal orchestrator
└── reset-webhook.sh ← Atomic webhook delete+re-register
reset-webhook.sh registers a webhook URL like: