Bluebubbles Healthcheck

Diagnoses and auto-heals BlueBubbles ↔ OpenClaw iMessage connectivity. Use when: iMessages stop arriving after a gateway restart, webhook connection is broke...

Security Scan

The skill's scripts largely match its stated purpose (diagnose and heal local BlueBubbles ↔ OpenClaw issues), but there are incoherences and modest risks you should understand before installing.

Purpose & Capability

The name/description align with the scripts' behavior: they query the BlueBubbles API, reset webhooks, and restart the OpenClaw gateway. However, the registry metadata provided with the skill (top-level metadata) does not declare the BB_PASSWORD credential even though SKILL.md and every script require it; that's an inconsistency that could confuse users and permission systems.

Instruction Scope

Runtime instructions and scripts are focused on local diagnostics and healing (HTTP calls to BB on BB_URL, listing/deleting/creating webhooks, POST to local OpenClaw webhook, optional openclaw gateway restart). This stays within the stated purpose. Caveat: the scripts accept arbitrary BB_URL and OPENCLAW_WEBHOOK_URL values supplied by the user — if pointed at remote hosts, the scripts will transmit BB_PASSWORD and register webhooks remotely, which is outside the intended local-only usage described in docs.

Install Mechanism

Instruction-only skill with bundled shell scripts; there is no package download or archive extraction. It relies on standard CLI tools (curl, python3, nc) and the openclaw CLI when available. Low install mechanism risk.

Credentials

The scripts require a sensitive secret (BB_PASSWORD) and do include that secret in webhook registration URLs so BlueBubbles can authenticate callbacks. That is functionally necessary for this integration and is documented, but the top-level registry metadata does not declare this required credential. Also, because the password is embedded in URLs, a misconfigured BB_URL or OPENCLAW_WEBHOOK_URL (pointing to remote services) could cause unintended disclosure/exfiltration of the password.

Persistence & Privilege

The skill does not request always: true and does not attempt to modify other skills or system-wide agent configs. It runs as-on-demand and its actions are limited to local service management and API calls.

What to consider before installing

What to know before installing: - The scripts legitimately need the BlueBubbles API password (BB_PASSWORD). The top-level registry metadata omitted this, so make sure you provide BB_PASSWORD only when you intend to run the scripts. Treat BB_PASSWORD as sensitive. - Intended use is local-only: defaults are 127.0.0.1 (BB_URL) and localhost webhook. Do not point BB_URL or OPENCLAW_WEBHOOK_URL at remote systems unless you explicitly understand and accept that the password and webhook registration will be sent to that remote host. - The reset script registers the webhook URL containing ?password=... so the password will be stored in BlueBubbles' webhook config on disk (documented by the skill). That is required by this integration but is a persistent secret on the machine. - Use --dry-run first to see planned actions. Inspect the scripts (they are small and included) and test on a non-production/local machine if possible. - If you manage multiple agents or remote BlueBubbles instances, avoid enabling this skill to run automatically against unknown endpoints. If you want to harden: keep BB_URL and OPENCLAW_WEBHOOK_URL to 127.0.0.1, prefer Authorization header for API calls where possible, and ensure logs/backups do not leak the stored webhook config. - Because the registry metadata and SKILL.md disagree about required credentials, ask the publisher (or update the skill) so the required env variables are declared clearly before granting secrets to the agent.

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. 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)

BB_URL="http://127.0.0.1:1234" \
BB_PASSWORD="your-password" \
~/.openclaw/workspace/skills/bluebubbles-healthcheck/scripts/diagnose.sh

Interpret the output:

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

Auto-Heal

BB_URL="http://127.0.0.1:1234" \
BB_PASSWORD="your-password" \
~/.openclaw/workspace/skills/bluebubbles-healthcheck/scripts/heal.sh

This will:

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)

BB_URL="http://127.0.0.1:1234" \
BB_PASSWORD="your-password" \
~/.openclaw/workspace/skills/bluebubbles-healthcheck/scripts/heal.sh --dry-run

Environment Variables

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

Agent Decision Flow

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

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 openclaw gateway restart

Pattern 4: BlueBubbles.app not running

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

Files

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

Security Notes

Why does the webhook URL contain the password?

reset-webhook.sh registers a webhook URL like:

http://127.0.0.1:18789/bluebubbles-webhook?password=...

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
curl	All scripts	HTTP calls to BB API
python3	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:

## BlueBubbles Health
Every 4 hours, run the BlueBubbles healthcheck skill.
If any checks fail, run heal and report results.