bluebubbles-healthcheck
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.
Install via CLI (Recommended)
clawhub install openclaw/skills/skills/amzzzzzzz/bluebubbles-healthcheckWhat This Skill Does
The bluebubbles-healthcheck skill serves as a critical diagnostic and recovery utility for maintaining the link between the BlueBubbles server and your OpenClaw environment. The skill automates the detection and resolution of common connectivity failure modes, specifically those occurring after gateway restarts or network fluctuations. It performs a comprehensive 4-step diagnostic: verifying server reachability, validating the webhook configuration, checking OpenClaw gateway responsiveness, and inspecting recent event delivery logs. If a failure is detected, the skill can automatically restart the gateway, clear stale or malfunctioning webhook registrations, and re-bind fresh endpoints to ensure seamless message flow.
Installation
To integrate this utility, ensure you have the OpenClaw environment configured correctly. Install the skill by running the following command in your terminal:
clawhub install openclaw/skills/skills/amzzzzzzz/bluebubbles-healthcheck
Once installed, ensure your BB_URL and BB_PASSWORD environment variables are set to allow the scripts to communicate with your local BlueBubbles instance.
Use Cases
- Post-Restart Recovery: After updating or restarting the OpenClaw gateway, use this to quickly re-establish broken webhook handshakes.
- Connectivity Troubleshooting: Run as an immediate response when users complain that incoming iMessages are no longer hitting the OpenClaw dashboard.
- Automated Health Monitoring: Integrate with your HEARTBEAT.md routine to perform silent health checks that prevent downtime before a human user even notices an issue.
- Deployment Verification: Run a dry-run check during initial setup to confirm that the handshake between BlueBubbles and the OpenClaw agent is configured correctly.
Example Prompts
- "OpenClaw, I haven't received an iMessage in an hour, can you check the BlueBubbles connection?"
- "Run a health check on the BlueBubbles gateway and fix any webhook issues you find."
- "Verify the BlueBubbles sync status and perform a dry run to see if the webhook is currently in backoff mode."
Tips & Limitations
- Dry-Run Always: Before running a full heal, use the
--dry-runflag to see exactly which diagnostic steps would trigger a change. - Permissions: Ensure the user running the health check has the necessary filesystem permissions to trigger gateway restarts and manage system processes.
- Authentication: Keep your
BB_PASSWORDsecure; do not hardcode it in scripts if sharing your workspace, and prioritize environment variable injection over manual command-line passing for sensitive credentials.
Metadata
Not sure this is the right skill?
Describe what you want to build — we'll match you to the best skill from 16,000+ options.
Find the right skillPaste this into your clawhub.json to enable this plugin.
{
"plugins": {
"official-amzzzzzzz-bluebubbles-healthcheck": {
"enabled": true,
"auto_update": true
}
}
}Tags(AI)
Flags: network-access, file-read, code-execution