bluebubbles-healthcheck

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

```bash
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

```bash
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)

```bash
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 endp...

# BlueBubbles Healthcheck

**Diagnose and auto-heal BlueBubbles ↔ OpenClaw iMessage connectivity.**

If you've ever restarted your OpenClaw gateway and wondered why iMessages stopped coming through — this skill is for you.

## The Problem

BlueBubbles uses webhooks to push iMessage events to OpenClaw. When OpenClaw's gateway restarts, BlueBubbles doesn't know the endpoint is back. It may:

- Keep trying to deliver to a dead endpoint
- Enter exponential backoff (waiting longer between retries)
- Stop trying entirely after too many failures

The result: **messages silently stop flowing**, and there's no obvious error.

## The Solution

This skill provides scripts to:

1. **Diagnose** the connection (4 targeted health checks)
2. **Auto-heal** common issues (gateway restart, webhook reset)
3. **Verify** the fix worked

## Quick Start

### Prerequisites

- [OpenClaw](https://openclaw.ai) running on your Mac
- [BlueBubbles](https://bluebubbles.app) server configured
- BlueBubbles API password (from BB settings)

### Installation

The skill lives in your OpenClaw workspace:

```bash
# Clone or copy to your workspace
~/.openclaw/workspace/skills/bluebubbles-healthcheck/
```

### Usage

**Run a health check:**

```bash
export BB_URL="http://127.0.0.1:1234"
export BB_PASSWORD="your-bluebubbles-password"

~/.openclaw/workspace/skills/bluebubbles-healthcheck/scripts/diagnose.sh
```

**Auto-heal if issues are detected:**

```bash
~/.openclaw/workspace/skills/bluebubbles-healthcheck/scripts/heal.sh
```

## What It Checks

| Check | What It Tests | Common Failures |
|-------|--------------|-----------------|
| **1. BB Server Reachable** | `GET /api/v1/ping` returns 200 | BlueBubbles.app not running |
| **2. Webhook Registered** | A webhook exists pointing to port 18789 | Webhook deleted or misconfigured |
| **3. Gateway Endpoint Alive** | POST to webhook endpoint returns "ok" | OpenClaw gateway not running |
| **4. Webhook Delivery** | Recent webhook dispatches in BB logs | Backof...