BlueBubbles Healthcheck Skill

When to Use This Skill

Use this skill when:

• - iMessages aren't being delivered to/from OpenClaw
• After restarting the OpenClaw gateway
• User reports "messages not coming through"
• Periodic healthcheck (can be added to HEARTBEAT.md)
• Debugging BlueBubbles ↔ OpenClaw connectivity

What It Does

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:

1. 1. BlueBubbles server reachable
2. Webhook registered pointing to OpenClaw
3. OpenClaw gateway endpoint responding
4. Recent webhook delivery activity

Auto-healing:

• - Restarts OpenClaw gateway if endpoint is down
• Deletes stale webhooks and re-registers fresh
• Verifies fix after healing

How to Use

Quick Check (Read-Only)

CODEBLOCK0

Interpret the output:

• - All ✅ = healthy, no action needed
• Any ❌ = issue detected, consider running heal

Auto-Heal

CODEBLOCK1

This will:

1. 1. Run diagnostics
2. Identify what's broken
3. Attempt to fix it (gateway restart, webhook reset)
4. Re-run diagnostics to verify

Dry Run (See What Would Happen)

CODEBLOCK2

Environment Variables

Variable	Required	Default	Description
INLINECODE0	Yes	INLINECODE1	BlueBubbles server URL
INLINECODE2

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, INLINECODE7

Agent Decision Flow

CODEBLOCK3

Common Failure Patterns

Pattern 1: Gateway restart broke webhooks

Symptoms: Messages stop after openclaw gateway restart Fix: heal.sh will reset webhook

Pattern 2: BlueBubbles in backoff

Symptoms: Webhook exists but BB stopped trying to deliver Fix: heal.sh deletes and re-registers webhook (clears backoff state)

Pattern 3: Gateway not running

Symptoms: Check 3 fails (port 18789 not listening) Fix: heal.sh runs INLINECODE12

Pattern 4: BlueBubbles.app not running

Symptoms: Check 1 fails (HTTP 000) Fix: Manual — user must start BlueBubbles.app on the Mac

Files

CODEBLOCK4

Security Notes

Why does the webhook URL contain the password?

INLINECODE13 registers a webhook URL like:
CODEBLOCK5

This is a BlueBubbles → OpenClaw authentication constraint, not arbitrary exposure. When BlueBubbles fires webhook events, it calls this URL. OpenClaw's BB plugin uses ?password= to verify the incoming callback is from a trusted source. There is no other mechanism in the current BB↔OpenClaw integration for authenticating inbound webhook calls.

Mitigations already in place:

• - Both services run on 127.0.0.1 (localhost only — never exposed externally)
• The password is masked in all log output by the script
• The URL is only stored inside BlueBubbles' local config (not transmitted off-device)

What you should know before installing:

• - BB_PASSWORD will be stored inside BlueBubbles' webhook config on disk
• Only use on machines where both BB and OpenClaw run locally and are trusted
• Do not point BB_URL at a remote BlueBubbles instance

Required binaries

Binary	Used by	Notes
INLINECODE18	All scripts	HTTP calls to BB API
INLINECODE19

diagnose.sh, reset-webhook.sh | JSON parsing | | nc | diagnose.sh, heal.sh | Port check on 18789 | | openclaw | heal.sh | Gateway restart (gracefully skipped if not found) |

All of these are standard on macOS except openclaw — this skill is part of the OpenClaw ecosystem and expects the openclaw CLI to be available.

Adding to Heartbeat

To run periodic healthchecks, add to HEARTBEAT.md:

CODEBLOCK6