BlueBubbles Health & Self-Healing

BlueBubbles Health & Self-Healing

Three scripts keep the BlueBubbles iMessage bridge healthy. They live in the agent workspace at openclaw-agents/lobster/scripts/ and are designed to run from cron, heartbeat, or manually.

Script	Mode	What It Does
bb-healthcheck.sh	Read-only	Diagnoses issues without changing anything
bb-selfheal.sh	Fix	Diagnoses and automatically fixes what it can
stuck-session-watchdog.sh	Read-only	Detects hung BlueBubbles agent runs

Why These Exist

On Feb 17, 2026, a stuck exec tool call in a BlueBubbles session hung indefinitely, blocking the session lane and preventing all inbound iMessage processing for ~70 minutes. The root cause: OpenClaw’s default agent timeout was 600 seconds, and the exec call never returned. These scripts detect and recover from that scenario and several others.

Health Check (bb-healthcheck.sh)

A read-only diagnostic that checks five things and reports healthy or unhealthy. Safe to run anytime — it changes nothing.

bash openclaw-agents/lobster/scripts/bb-healthcheck.sh

Optional argument: window in minutes for log scanning (default 90).

bash openclaw-agents/lobster/scripts/bb-healthcheck.sh 60  # Check last 60 minutes

What it checks:

1. BB server responding — Pings http://127.0.0.1:1234/api/v1/ping
2. Messages.app AppleScript bridge — Runs a 5-second timeout AppleScript call to verify Messages.app is responsive
3. Webhook rejections — Scans gateway logs for webhook rejected.*unauthorized in the time window
4. Webhook URL — Verifies the URL in BlueBubbles’ config.db includes the auth password
5. Stuck sessions — Calls stuck-session-watchdog.sh to check for hung agent runs

Exit codes: 0 = healthy, 1 = unhealthy (one or more checks failed).

Self-Heal (bb-selfheal.sh)

Runs the same checks as the health check, but automatically fixes issues it finds. If it can’t fix something, it reports failure.

bash openclaw-agents/lobster/scripts/bb-selfheal.sh

What it fixes:

Issue	Automated Fix
BB server down	Quits and relaunches BlueBubbles, waits up to 60s for it to come back
Messages.app AppleScript hung	Force-kills Messages.app and BlueBubbles, relaunches both
Webhook URL missing auth	Updates config.db directly via sqlite3, restarts BlueBubbles
Webhook rejections after fix	Restarts OpenClaw gateway
Stuck agent runs	Restarts OpenClaw gateway to clear the stuck lane

What it cannot fix (requires manual intervention):

• Private API disconnect — The script detects Private API is not enabled in logs but cannot fix it. Requires re-enabling in BlueBubbles settings (and SIP must be disabled on the host Mac).

Exit codes: 0 = healthy or healed, 1 = couldn’t fix one or more issues.

Output example:

=== BlueBubbles Self-Heal ===
Checking BB server... OK
Checking Messages.app AppleScript bridge... OK
Checking webhook URL... MISMATCH — fixing
  Was: http://127.0.0.1:18789/bluebubbles-webhook
  Now: http://127.0.0.1:18789/bluebubbles-webhook?password=xxxxx
Restarting BlueBubbles to apply new webhook URL...
Checking for webhook rejections... NONE

RESULT: HEALED — issues were found and fixed

Stuck Session Watchdog (stuck-session-watchdog.sh)

Detects BlueBubbles agent runs that started but never completed. This is the specific scenario that caused the 70-minute outage.

bash openclaw-agents/lobster/scripts/stuck-session-watchdog.sh [max_age_seconds]

Default max age: 180 seconds (matches the agents.defaults.timeoutSeconds config).

How it works:

1. Scans gateway logs for embedded run start.*bluebubbles entries (last 5)
2. For each, checks if a matching embedded run end/done/finish/error exists
3. If a run has been open longer than max_age_seconds (and less than 1 hour), it’s flagged as stuck

Exit codes: 0 = no stuck runs, 1 = stuck run(s) detected.

Output when stuck:

STUCK: runId=abc123 age=245s (max 180s)

STATUS: STUCK (1 stuck run(s) detected)
ACTION: Gateway restart recommended

Integration with Cron / Heartbeat

As a Cron Job

Run the self-heal script on a schedule to catch issues before users notice:

openclaw cron add --name "bb-selfheal" \
  --schedule "*/15 * * * *" \
  --command "bash ~/GitHub/lobster/openclaw-agents/lobster/scripts/bb-selfheal.sh"

From Heartbeat

The agent’s heartbeat checklist can call the health check and escalate if unhealthy:

## Heartbeat Checklist
- [ ] Run bb-healthcheck.sh — if unhealthy, run bb-selfheal.sh

From the Security Audit

The security-audit.sh script in the same directory calls secrets-audit.sh as part of its checks. You can extend it to include the health check as well.

Troubleshooting

Messages.app AppleScript Keeps Hanging

This happens when Messages.app gets into a bad state internally. The self-heal script force-kills and relaunches, but if it recurs frequently:

1. Check if Messages.app has pending iCloud sync (large attachment downloads can cause hangs)
2. Sign out and back into the agent’s Apple ID in Messages.app
3. Reboot the host Mac

Webhook URL Keeps Drifting

BlueBubbles can reset the webhook URL after updates or crashes. The self-heal script fixes this automatically, but if it’s happening on every run:

1. Check if BlueBubbles is auto-updating (disable auto-update in settings)
2. Verify the config.db path hasn’t changed after a BlueBubbles update

Stuck Sessions Keep Recurring

If agent runs keep getting stuck:

1. Verify agents.defaults.timeoutSeconds is set to 180 (not the old 600s default)
2. Check which exec command is hanging — look at the gateway logs around the stuck run’s start time
3. Consider adding the hanging command to the exec deny list