# Send Bluebubbles Healthcheck to your agent Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually. ## Fast path - Download the package from Yavira. - Extract it into a folder your agent can access. - Paste one of the prompts below and point your agent at the extracted folder. ## Suggested prompts ### New install ```text I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Then review README.md for any prerequisites, environment setup, or post-install checks. Tell me what you changed and call out any manual steps you could not complete. ``` ### Upgrade existing ```text I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Then review README.md for any prerequisites, environment setup, or post-install checks. Summarize what changed and any follow-up checks I should run. ``` ## Machine-readable fields ```json { "schemaVersion": "1.0", "item": { "slug": "bluebubbles-healthcheck", "name": "Bluebubbles Healthcheck", "source": "tencent", "type": "skill", "category": "通讯协作", "sourceUrl": "https://clawhub.ai/amzzzzzzz/bluebubbles-healthcheck", "canonicalUrl": "https://clawhub.ai/amzzzzzzz/bluebubbles-healthcheck", "targetPlatform": "OpenClaw" }, "install": { "downloadUrl": "/downloads/bluebubbles-healthcheck", "sourceDownloadUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=bluebubbles-healthcheck", "sourcePlatform": "tencent", "targetPlatform": "OpenClaw", "packageFormat": "ZIP package", "primaryDoc": "SKILL.md", "includedAssets": [ "README.md", "SKILL.md", "references/bluebubbles-api.md", "references/troubleshooting.md", "scripts/diagnose.sh", "scripts/heal.sh" ], "downloadMode": "redirect", "sourceHealth": { "source": "tencent", "slug": "bluebubbles-healthcheck", "status": "healthy", "reason": "direct_download_ok", "recommendedAction": "download", "checkedAt": "2026-04-29T07:47:48.304Z", "expiresAt": "2026-05-06T07:47:48.304Z", "httpStatus": 200, "finalUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=bluebubbles-healthcheck", "contentType": "application/zip", "probeMethod": "head", "details": { "probeUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=bluebubbles-healthcheck", "contentDisposition": "attachment; filename=\"bluebubbles-healthcheck-0.1.3.zip\"", "redirectLocation": null, "bodySnippet": null, "slug": "bluebubbles-healthcheck" }, "scope": "item", "summary": "Item download looks usable.", "detail": "Yavira can redirect you to the upstream package for this item.", "primaryActionLabel": "Download for OpenClaw", "primaryActionHref": "/downloads/bluebubbles-healthcheck" }, "validation": { "installChecklist": [ "Use the Yavira download entry.", "Review SKILL.md after the package is downloaded.", "Confirm the extracted package contains the expected setup assets." ], "postInstallChecks": [ "Confirm the extracted package includes the expected docs or setup files.", "Validate the skill or prompts are available in your target agent workspace.", "Capture any manual follow-up steps the agent could not complete." ] } }, "links": { "detailUrl": "https://openagent3.xyz/skills/bluebubbles-healthcheck", "downloadUrl": "https://openagent3.xyz/downloads/bluebubbles-healthcheck", "agentUrl": "https://openagent3.xyz/skills/bluebubbles-healthcheck/agent", "manifestUrl": "https://openagent3.xyz/skills/bluebubbles-healthcheck/agent.json", "briefUrl": "https://openagent3.xyz/skills/bluebubbles-healthcheck/agent.md" } } ``` ## Documentation ### 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: BlueBubbles server reachable Webhook registered pointing to OpenClaw OpenClaw gateway endpoint responding Recent webhook delivery activity Auto-healing: Restarts OpenClaw gateway if endpoint is down Deletes stale webhooks and re-registers fresh Verifies fix after healing ### 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: Run diagnostics Identify what's broken Attempt to fix it (gateway restart, webhook reset) 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 VariableRequiredDefaultDescriptionBB_URLYeshttp://127.0.0.1:1234BlueBubbles server URLBB_PASSWORDYes—BlueBubbles API passwordOPENCLAW_WEBHOOK_URLNohttp://127.0.0.1:18789/bluebubbles-webhookOpenClaw 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 ### 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 ### 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 BinaryUsed byNotescurlAll scriptsHTTP calls to BB APIpython3diagnose.sh, reset-webhook.shJSON parsingncdiagnose.sh, heal.shPort check on 18789openclawheal.shGateway 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. ## Trust - Source: tencent - Verification: Indexed source record - Publisher: amzzzzzzz - Version: 0.1.3 ## Source health - Status: healthy - Item download looks usable. - Yavira can redirect you to the upstream package for this item. - Health scope: item - Reason: direct_download_ok - Checked at: 2026-04-29T07:47:48.304Z - Expires at: 2026-05-06T07:47:48.304Z - Recommended action: Download for OpenClaw ## Links - [Detail page](https://openagent3.xyz/skills/bluebubbles-healthcheck) - [Send to Agent page](https://openagent3.xyz/skills/bluebubbles-healthcheck/agent) - [JSON manifest](https://openagent3.xyz/skills/bluebubbles-healthcheck/agent.json) - [Markdown brief](https://openagent3.xyz/skills/bluebubbles-healthcheck/agent.md) - [Download page](https://openagent3.xyz/downloads/bluebubbles-healthcheck)