{
  "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": {
    "downloadMode": "redirect",
    "downloadUrl": "/downloads/bluebubbles-healthcheck",
    "sourceDownloadUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=bluebubbles-healthcheck",
    "sourcePlatform": "tencent",
    "targetPlatform": "OpenClaw",
    "installMethod": "Manual import",
    "extraction": "Extract archive",
    "prerequisites": [
      "OpenClaw"
    ],
    "packageFormat": "ZIP package",
    "includedAssets": [
      "README.md",
      "SKILL.md",
      "references/bluebubbles-api.md",
      "references/troubleshooting.md",
      "scripts/diagnose.sh",
      "scripts/heal.sh"
    ],
    "primaryDoc": "SKILL.md",
    "quickSetup": [
      "Download the package from Yavira.",
      "Extract the archive and review SKILL.md first.",
      "Import or place the package into your OpenClaw setup."
    ],
    "agentAssist": {
      "summary": "Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.",
      "steps": [
        "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."
      ],
      "prompts": [
        {
          "label": "New install",
          "body": "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."
        },
        {
          "label": "Upgrade existing",
          "body": "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."
        }
      ]
    },
    "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."
      ]
    },
    "downloadPageUrl": "https://openagent3.xyz/downloads/bluebubbles-healthcheck",
    "agentPageUrl": "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"
  },
  "agentAssist": {
    "summary": "Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.",
    "steps": [
      "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."
    ],
    "prompts": [
      {
        "label": "New install",
        "body": "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."
      },
      {
        "label": "Upgrade existing",
        "body": "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."
      }
    ]
  },
  "documentation": {
    "source": "clawhub",
    "primaryDoc": "SKILL.md",
    "sections": [
      {
        "title": "When to Use This Skill",
        "body": "Use this skill when:\n\niMessages aren't being delivered to/from OpenClaw\nAfter restarting the OpenClaw gateway\nUser reports \"messages not coming through\"\nPeriodic healthcheck (can be added to HEARTBEAT.md)\nDebugging BlueBubbles ↔ OpenClaw connectivity"
      },
      {
        "title": "What It Does",
        "body": "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.\n\nDiagnostic checks:\n\nBlueBubbles server reachable\nWebhook registered pointing to OpenClaw\nOpenClaw gateway endpoint responding\nRecent webhook delivery activity\n\nAuto-healing:\n\nRestarts OpenClaw gateway if endpoint is down\nDeletes stale webhooks and re-registers fresh\nVerifies fix after healing"
      },
      {
        "title": "Quick Check (Read-Only)",
        "body": "BB_URL=\"http://127.0.0.1:1234\" \\\nBB_PASSWORD=\"your-password\" \\\n~/.openclaw/workspace/skills/bluebubbles-healthcheck/scripts/diagnose.sh\n\nInterpret the output:\n\nAll ✅ = healthy, no action needed\nAny ❌ = issue detected, consider running heal"
      },
      {
        "title": "Auto-Heal",
        "body": "BB_URL=\"http://127.0.0.1:1234\" \\\nBB_PASSWORD=\"your-password\" \\\n~/.openclaw/workspace/skills/bluebubbles-healthcheck/scripts/heal.sh\n\nThis will:\n\nRun diagnostics\nIdentify what's broken\nAttempt to fix it (gateway restart, webhook reset)\nRe-run diagnostics to verify"
      },
      {
        "title": "Dry Run (See What Would Happen)",
        "body": "BB_URL=\"http://127.0.0.1:1234\" \\\nBB_PASSWORD=\"your-password\" \\\n~/.openclaw/workspace/skills/bluebubbles-healthcheck/scripts/heal.sh --dry-run"
      },
      {
        "title": "Environment Variables",
        "body": "VariableRequiredDefaultDescriptionBB_URLYeshttp://127.0.0.1:1234BlueBubbles server URLBB_PASSWORDYes—BlueBubbles API passwordOPENCLAW_WEBHOOK_URLNohttp://127.0.0.1:18789/bluebubbles-webhookOpenClaw webhook endpoint\n\nYou can also pass these as args: --bb-url, --password, --webhook-url"
      },
      {
        "title": "Agent Decision Flow",
        "body": "User reports iMessage issue\n         ↓\n    Run diagnose.sh\n         ↓\n    ┌────┴────┐\n    │ All ✅? │\n    └────┬────┘\n    Yes  │  No\n    ↓    │  ↓\n Report  │  Run heal.sh\n healthy │      ↓\n         │  ┌───┴───┐\n         │  │Fixed? │\n         │  └───┬───┘\n         │  Yes │ No\n         │  ↓   │ ↓\n         │Report│ Escalate to user:\n         │fixed │ - BB app not running?\n         │      │ - Network issue?\n         └──────┴─ Manual intervention needed"
      },
      {
        "title": "Pattern 1: Gateway restart broke webhooks",
        "body": "Symptoms: Messages stop after openclaw gateway restart\nFix: heal.sh will reset webhook"
      },
      {
        "title": "Pattern 2: BlueBubbles in backoff",
        "body": "Symptoms: Webhook exists but BB stopped trying to deliver\nFix: heal.sh deletes and re-registers webhook (clears backoff state)"
      },
      {
        "title": "Pattern 3: Gateway not running",
        "body": "Symptoms: Check 3 fails (port 18789 not listening)\nFix: heal.sh runs openclaw gateway restart"
      },
      {
        "title": "Pattern 4: BlueBubbles.app not running",
        "body": "Symptoms: Check 1 fails (HTTP 000)\nFix: Manual — user must start BlueBubbles.app on the Mac"
      },
      {
        "title": "Files",
        "body": "skills/bluebubbles-healthcheck/\n├── SKILL.md           ← You are here\n├── README.md          ← GitHub docs\n└── scripts/\n    ├── diagnose.sh    ← Read-only diagnostics (exit 0 = healthy)\n    ├── heal.sh        ← Auto-heal orchestrator\n    └── reset-webhook.sh ← Atomic webhook delete+re-register"
      },
      {
        "title": "Why does the webhook URL contain the password?",
        "body": "reset-webhook.sh registers a webhook URL like:\n\nhttp://127.0.0.1:18789/bluebubbles-webhook?password=...\n\nThis 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.\n\nMitigations already in place:\n\nBoth services run on 127.0.0.1 (localhost only — never exposed externally)\nThe password is masked in all log output by the script\nThe URL is only stored inside BlueBubbles' local config (not transmitted off-device)\n\nWhat you should know before installing:\n\nBB_PASSWORD will be stored inside BlueBubbles' webhook config on disk\nOnly use on machines where both BB and OpenClaw run locally and are trusted\nDo not point BB_URL at a remote BlueBubbles instance"
      },
      {
        "title": "Required binaries",
        "body": "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)\n\nAll of these are standard on macOS except openclaw — this skill is part of the OpenClaw ecosystem and expects the openclaw CLI to be available."
      },
      {
        "title": "Adding to Heartbeat",
        "body": "To run periodic healthchecks, add to HEARTBEAT.md:\n\n## BlueBubbles Health\nEvery 4 hours, run the BlueBubbles healthcheck skill.\nIf any checks fail, run heal and report results."
      }
    ],
    "body": "BlueBubbles Healthcheck Skill\nWhen to Use This Skill\n\nUse this skill when:\n\niMessages aren't being delivered to/from OpenClaw\nAfter restarting the OpenClaw gateway\nUser reports \"messages not coming through\"\nPeriodic healthcheck (can be added to HEARTBEAT.md)\nDebugging BlueBubbles ↔ OpenClaw connectivity\nWhat It Does\n\nDiagnoses 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.\n\nDiagnostic checks:\n\nBlueBubbles server reachable\nWebhook registered pointing to OpenClaw\nOpenClaw gateway endpoint responding\nRecent webhook delivery activity\n\nAuto-healing:\n\nRestarts OpenClaw gateway if endpoint is down\nDeletes stale webhooks and re-registers fresh\nVerifies fix after healing\nHow to Use\nQuick Check (Read-Only)\nBB_URL=\"http://127.0.0.1:1234\" \\\nBB_PASSWORD=\"your-password\" \\\n~/.openclaw/workspace/skills/bluebubbles-healthcheck/scripts/diagnose.sh\n\n\nInterpret the output:\n\nAll ✅ = healthy, no action needed\nAny ❌ = issue detected, consider running heal\nAuto-Heal\nBB_URL=\"http://127.0.0.1:1234\" \\\nBB_PASSWORD=\"your-password\" \\\n~/.openclaw/workspace/skills/bluebubbles-healthcheck/scripts/heal.sh\n\n\nThis will:\n\nRun diagnostics\nIdentify what's broken\nAttempt to fix it (gateway restart, webhook reset)\nRe-run diagnostics to verify\nDry Run (See What Would Happen)\nBB_URL=\"http://127.0.0.1:1234\" \\\nBB_PASSWORD=\"your-password\" \\\n~/.openclaw/workspace/skills/bluebubbles-healthcheck/scripts/heal.sh --dry-run\n\nEnvironment Variables\nVariable\tRequired\tDefault\tDescription\nBB_URL\tYes\thttp://127.0.0.1:1234\tBlueBubbles server URL\nBB_PASSWORD\tYes\t—\tBlueBubbles API password\nOPENCLAW_WEBHOOK_URL\tNo\thttp://127.0.0.1:18789/bluebubbles-webhook\tOpenClaw webhook endpoint\n\nYou can also pass these as args: --bb-url, --password, --webhook-url\n\nAgent Decision Flow\nUser reports iMessage issue\n         ↓\n    Run diagnose.sh\n         ↓\n    ┌────┴────┐\n    │ All ✅? │\n    └────┬────┘\n    Yes  │  No\n    ↓    │  ↓\n Report  │  Run heal.sh\n healthy │      ↓\n         │  ┌───┴───┐\n         │  │Fixed? │\n         │  └───┬───┘\n         │  Yes │ No\n         │  ↓   │ ↓\n         │Report│ Escalate to user:\n         │fixed │ - BB app not running?\n         │      │ - Network issue?\n         └──────┴─ Manual intervention needed\n\nCommon Failure Patterns\nPattern 1: Gateway restart broke webhooks\n\nSymptoms: Messages stop after openclaw gateway restart Fix: heal.sh will reset webhook\n\nPattern 2: BlueBubbles in backoff\n\nSymptoms: Webhook exists but BB stopped trying to deliver Fix: heal.sh deletes and re-registers webhook (clears backoff state)\n\nPattern 3: Gateway not running\n\nSymptoms: Check 3 fails (port 18789 not listening) Fix: heal.sh runs openclaw gateway restart\n\nPattern 4: BlueBubbles.app not running\n\nSymptoms: Check 1 fails (HTTP 000) Fix: Manual — user must start BlueBubbles.app on the Mac\n\nFiles\nskills/bluebubbles-healthcheck/\n├── SKILL.md           ← You are here\n├── README.md          ← GitHub docs\n└── scripts/\n    ├── diagnose.sh    ← Read-only diagnostics (exit 0 = healthy)\n    ├── heal.sh        ← Auto-heal orchestrator\n    └── reset-webhook.sh ← Atomic webhook delete+re-register\n\nSecurity Notes\nWhy does the webhook URL contain the password?\n\nreset-webhook.sh registers a webhook URL like:\n\nhttp://127.0.0.1:18789/bluebubbles-webhook?password=...\n\n\nThis 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.\n\nMitigations already in place:\n\nBoth services run on 127.0.0.1 (localhost only — never exposed externally)\nThe password is masked in all log output by the script\nThe URL is only stored inside BlueBubbles' local config (not transmitted off-device)\n\nWhat you should know before installing:\n\nBB_PASSWORD will be stored inside BlueBubbles' webhook config on disk\nOnly use on machines where both BB and OpenClaw run locally and are trusted\nDo not point BB_URL at a remote BlueBubbles instance\nRequired binaries\nBinary\tUsed by\tNotes\ncurl\tAll scripts\tHTTP calls to BB API\npython3\tdiagnose.sh, reset-webhook.sh\tJSON parsing\nnc\tdiagnose.sh, heal.sh\tPort check on 18789\nopenclaw\theal.sh\tGateway restart (gracefully skipped if not found)\n\nAll of these are standard on macOS except openclaw — this skill is part of the OpenClaw ecosystem and expects the openclaw CLI to be available.\n\nAdding to Heartbeat\n\nTo run periodic healthchecks, add to HEARTBEAT.md:\n\n## BlueBubbles Health\nEvery 4 hours, run the BlueBubbles healthcheck skill.\nIf any checks fail, run heal and report results."
  },
  "trust": {
    "sourceLabel": "tencent",
    "provenanceUrl": "https://clawhub.ai/amzzzzzzz/bluebubbles-healthcheck",
    "publisherUrl": "https://clawhub.ai/amzzzzzzz/bluebubbles-healthcheck",
    "owner": "amzzzzzzz",
    "version": "0.1.3",
    "license": null,
    "verificationStatus": "Indexed source record"
  },
  "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"
  }
}