{
  "schemaVersion": "1.0",
  "item": {
    "slug": "pihole",
    "name": "Pi-hole Control",
    "source": "tencent",
    "type": "skill",
    "category": "开发工具",
    "sourceUrl": "https://clawhub.ai/baanish/pihole",
    "canonicalUrl": "https://clawhub.ai/baanish/pihole",
    "targetPlatform": "OpenClaw"
  },
  "install": {
    "downloadMode": "redirect",
    "downloadUrl": "/downloads/pihole",
    "sourceDownloadUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=pihole",
    "sourcePlatform": "tencent",
    "targetPlatform": "OpenClaw",
    "installMethod": "Manual import",
    "extraction": "Extract archive",
    "prerequisites": [
      "OpenClaw"
    ],
    "packageFormat": "ZIP package",
    "includedAssets": [
      "SECURITY_AUDIT.md",
      "SKILL.md",
      "pihole.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. 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. Summarize what changed and any follow-up checks I should run."
        }
      ]
    },
    "sourceHealth": {
      "source": "tencent",
      "status": "healthy",
      "reason": "direct_download_ok",
      "recommendedAction": "download",
      "checkedAt": "2026-04-30T16:55:25.780Z",
      "expiresAt": "2026-05-07T16:55:25.780Z",
      "httpStatus": 200,
      "finalUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=network",
      "contentType": "application/zip",
      "probeMethod": "head",
      "details": {
        "probeUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=network",
        "contentDisposition": "attachment; filename=\"network-1.0.0.zip\"",
        "redirectLocation": null,
        "bodySnippet": null
      },
      "scope": "source",
      "summary": "Source download looks usable.",
      "detail": "Yavira can redirect you to the upstream package for this source.",
      "primaryActionLabel": "Download for OpenClaw",
      "primaryActionHref": "/downloads/pihole"
    },
    "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/pihole",
    "agentPageUrl": "https://openagent3.xyz/skills/pihole/agent",
    "manifestUrl": "https://openagent3.xyz/skills/pihole/agent.json",
    "briefUrl": "https://openagent3.xyz/skills/pihole/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. 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. Summarize what changed and any follow-up checks I should run."
      }
    ]
  },
  "documentation": {
    "source": "clawhub",
    "primaryDoc": "SKILL.md",
    "sections": [
      {
        "title": "Pi-hole Skill",
        "body": "Control your Pi-hole DNS ad blocker via the Pi-hole v6 API."
      },
      {
        "title": "Setup",
        "body": "Set your Pi-hole API configuration in Clawdbot config:\n\nskills:\n  entries:\n    pihole:\n      apiUrl: \"https://pi-hole.local/api\"  # v6 API path\n      apiToken: \"your-app-password-here\"       # Get from Pi-hole Admin\n      insecure: false                          # Set to true for self-signed certs\n\nAlternatively, set environment variables:\n\nexport PIHOLE_API_URL=\"https://pi-hole.local/api\"\nexport PIHOLE_API_TOKEN=\"your-app-password-here\"\nexport PIHOLE_INSECURE=\"false\""
      },
      {
        "title": "Getting API Credentials",
        "body": "Open Pi-hole Admin at http://pi-hole.local/admin\nNavigate to Settings > API\nGenerate an app password\nUse that password as apiToken"
      },
      {
        "title": "Status",
        "body": "Get current Pi-hole status (enabled/disabled)\nView stats: queries blocked, queries today, domains being blocked, active clients\nSee recent query activity"
      },
      {
        "title": "Controls",
        "body": "Enable/Disable: Turn Pi-hole on or off\nDisable for 5 minutes: Temporarily disable ad blocking for a short period\nDisable for custom duration: Set specific disable time (in minutes)"
      },
      {
        "title": "Block Analysis",
        "body": "Check blocked domains: See what domains were blocked in a time window\nShow top blocked: Most frequently blocked domains"
      },
      {
        "title": "Usage Examples",
        "body": "# Check Pi-hole status\n\"pihole status\"\n\n# Turn off ad blocking\n\"pihole off\"\n\n# Turn on ad blocking\n\"pihole on\"\n\n# Disable for 5 minutes (for a site that needs ads)\n\"pihole disable 5m\"\n\n# Disable for 30 minutes\n\"pihole disable 30\"\n\n# See what was blocked in the last 30 minutes\n\"pihole blocked\"\n\n# See blocked domains in last 10 minutes (600 seconds)\n\"pihole blocked 600\"\n\n# Show statistics\n\"pihole stats\""
      },
      {
        "title": "Authentication",
        "body": "POST /api/auth\nContent-Type: application/json\n{\"password\":\"your-app-password\"}\n\nResponse:\n{\n  \"session\": {\n    \"sid\": \"session-token-here\",\n    \"validity\": 1800\n  }\n}"
      },
      {
        "title": "Status",
        "body": "GET /api/dns/blocking\nHeaders: sid: <session-token>\n\nResponse:\n{\n  \"blocking\": \"enabled\" | \"disabled\",\n  \"timer\": 30  // seconds until re-enable (if disabled with timer)\n}"
      },
      {
        "title": "Enable/Disable",
        "body": "POST /api/dns/blocking\nHeaders: sid: <session-token>\nContent-Type: application/json\n\nEnable:\n{\"blocking\":true}\n\nDisable:\n{\"blocking\":false}\n\nDisable with timer (seconds):\n{\"blocking\":false,\"timer\":300}"
      },
      {
        "title": "Stats",
        "body": "GET /api/stats/summary\nHeaders: sid: <session-token>\n\nResponse:\n{\n  \"queries\": {\n    \"total\": 233512,\n    \"blocked\": 23496,\n    \"percent_blocked\": 10.06\n  },\n  \"gravity\": {\n    \"domains_being_blocked\": 165606\n  },\n  \"clients\": {\n    \"active\": 45\n  }\n}"
      },
      {
        "title": "Queries",
        "body": "GET /api/queries?start=-<seconds>\nHeaders: sid: <session-token>\n\nResponse:\n{\n  \"queries\": [\n    {\n      \"domain\": \"example.com\",\n      \"status\": \"GRAVITY\",\n      \"time\": 1768363900,\n      \"type\": \"A\"\n    }\n  ]\n}"
      },
      {
        "title": "v5 vs v6 API Changes",
        "body": "Pi-hole v6 introduced significant API changes:\n\nFeaturev5 APIv6 APIBase URL/admin/api.php/apiAuthToken in URL/headersSession-basedStatus?status/api/dns/blockingStats?summaryRaw/api/stats/summaryQueries?recentBlocked/api/queriesWhitelistSupported via APINot available via API\n\nImportant: Domain whitelisting is no longer available via the v6 API. You must whitelist domains through the Pi-hole Admin UI."
      },
      {
        "title": "Production (Valid Cert)",
        "body": "{\n  \"apiUrl\": \"https://pi-hole.example.com/api\",\n  \"apiToken\": \"...\",\n  \"insecure\": false\n}"
      },
      {
        "title": "Self-Signed/Local Cert",
        "body": "{\n  \"apiUrl\": \"https://pi-hole.local/api\",\n  \"apiToken\": \"...\",\n  \"insecure\": true\n}\n\nThe insecure flag adds the -k option to curl to bypass certificate validation."
      },
      {
        "title": "Security Notes",
        "body": "Session tokens expire after 30 minutes (1800 seconds)\nAPI password is sent in JSON body, not URL\nAll requests have a 30-second timeout\nToken is not visible in process list (passed via environment)"
      },
      {
        "title": "\"Failed to authenticate\"",
        "body": "Check that apiToken matches your Pi-hole app password\nVerify apiUrl is correct (must end in /api)\nEnsure Pi-hole is accessible from your network"
      },
      {
        "title": "\"Could not determine status\"",
        "body": "Check API URL is reachable\nIf using HTTPS with self-signed cert, set insecure: true\nVerify API password is correct"
      },
      {
        "title": "Network Errors",
        "body": "Ensure clawdbot's machine can reach the Pi-hole\nCheck firewall rules allow API access\nVerify URL scheme (http vs https)"
      },
      {
        "title": "Requirements",
        "body": "Pi-hole v6 or later\nApp password generated in Pi-hole Admin\nNetwork access to Pi-hole API\ncurl, jq (installed on most Unix systems)"
      }
    ],
    "body": "Pi-hole Skill\n\nControl your Pi-hole DNS ad blocker via the Pi-hole v6 API.\n\nSetup\n\nSet your Pi-hole API configuration in Clawdbot config:\n\nskills:\n  entries:\n    pihole:\n      apiUrl: \"https://pi-hole.local/api\"  # v6 API path\n      apiToken: \"your-app-password-here\"       # Get from Pi-hole Admin\n      insecure: false                          # Set to true for self-signed certs\n\n\nAlternatively, set environment variables:\n\nexport PIHOLE_API_URL=\"https://pi-hole.local/api\"\nexport PIHOLE_API_TOKEN=\"your-app-password-here\"\nexport PIHOLE_INSECURE=\"false\"\n\nGetting API Credentials\nOpen Pi-hole Admin at http://pi-hole.local/admin\nNavigate to Settings > API\nGenerate an app password\nUse that password as apiToken\nCapabilities\nStatus\nGet current Pi-hole status (enabled/disabled)\nView stats: queries blocked, queries today, domains being blocked, active clients\nSee recent query activity\nControls\nEnable/Disable: Turn Pi-hole on or off\nDisable for 5 minutes: Temporarily disable ad blocking for a short period\nDisable for custom duration: Set specific disable time (in minutes)\nBlock Analysis\nCheck blocked domains: See what domains were blocked in a time window\nShow top blocked: Most frequently blocked domains\nUsage Examples\n# Check Pi-hole status\n\"pihole status\"\n\n# Turn off ad blocking\n\"pihole off\"\n\n# Turn on ad blocking\n\"pihole on\"\n\n# Disable for 5 minutes (for a site that needs ads)\n\"pihole disable 5m\"\n\n# Disable for 30 minutes\n\"pihole disable 30\"\n\n# See what was blocked in the last 30 minutes\n\"pihole blocked\"\n\n# See blocked domains in last 10 minutes (600 seconds)\n\"pihole blocked 600\"\n\n# Show statistics\n\"pihole stats\"\n\nAPI Endpoints (Pi-hole v6)\nAuthentication\nPOST /api/auth\nContent-Type: application/json\n{\"password\":\"your-app-password\"}\n\nResponse:\n{\n  \"session\": {\n    \"sid\": \"session-token-here\",\n    \"validity\": 1800\n  }\n}\n\nStatus\nGET /api/dns/blocking\nHeaders: sid: <session-token>\n\nResponse:\n{\n  \"blocking\": \"enabled\" | \"disabled\",\n  \"timer\": 30  // seconds until re-enable (if disabled with timer)\n}\n\nEnable/Disable\nPOST /api/dns/blocking\nHeaders: sid: <session-token>\nContent-Type: application/json\n\nEnable:\n{\"blocking\":true}\n\nDisable:\n{\"blocking\":false}\n\nDisable with timer (seconds):\n{\"blocking\":false,\"timer\":300}\n\nStats\nGET /api/stats/summary\nHeaders: sid: <session-token>\n\nResponse:\n{\n  \"queries\": {\n    \"total\": 233512,\n    \"blocked\": 23496,\n    \"percent_blocked\": 10.06\n  },\n  \"gravity\": {\n    \"domains_being_blocked\": 165606\n  },\n  \"clients\": {\n    \"active\": 45\n  }\n}\n\nQueries\nGET /api/queries?start=-<seconds>\nHeaders: sid: <session-token>\n\nResponse:\n{\n  \"queries\": [\n    {\n      \"domain\": \"example.com\",\n      \"status\": \"GRAVITY\",\n      \"time\": 1768363900,\n      \"type\": \"A\"\n    }\n  ]\n}\n\nv5 vs v6 API Changes\n\nPi-hole v6 introduced significant API changes:\n\nFeature\tv5 API\tv6 API\nBase URL\t/admin/api.php\t/api\nAuth\tToken in URL/headers\tSession-based\nStatus\t?status\t/api/dns/blocking\nStats\t?summaryRaw\t/api/stats/summary\nQueries\t?recentBlocked\t/api/queries\nWhitelist\tSupported via API\tNot available via API\n\nImportant: Domain whitelisting is no longer available via the v6 API. You must whitelist domains through the Pi-hole Admin UI.\n\nSSL Certificates\nProduction (Valid Cert)\n{\n  \"apiUrl\": \"https://pi-hole.example.com/api\",\n  \"apiToken\": \"...\",\n  \"insecure\": false\n}\n\nSelf-Signed/Local Cert\n{\n  \"apiUrl\": \"https://pi-hole.local/api\",\n  \"apiToken\": \"...\",\n  \"insecure\": true\n}\n\n\nThe insecure flag adds the -k option to curl to bypass certificate validation.\n\nSecurity Notes\nSession tokens expire after 30 minutes (1800 seconds)\nAPI password is sent in JSON body, not URL\nAll requests have a 30-second timeout\nToken is not visible in process list (passed via environment)\nTroubleshooting\n\"Failed to authenticate\"\nCheck that apiToken matches your Pi-hole app password\nVerify apiUrl is correct (must end in /api)\nEnsure Pi-hole is accessible from your network\n\"Could not determine status\"\nCheck API URL is reachable\nIf using HTTPS with self-signed cert, set insecure: true\nVerify API password is correct\nNetwork Errors\nEnsure clawdbot's machine can reach the Pi-hole\nCheck firewall rules allow API access\nVerify URL scheme (http vs https)\nRequirements\nPi-hole v6 or later\nApp password generated in Pi-hole Admin\nNetwork access to Pi-hole API\ncurl, jq (installed on most Unix systems)"
  },
  "trust": {
    "sourceLabel": "tencent",
    "provenanceUrl": "https://clawhub.ai/baanish/pihole",
    "publisherUrl": "https://clawhub.ai/baanish/pihole",
    "owner": "baanish",
    "version": "2.0.1",
    "license": null,
    "verificationStatus": "Indexed source record"
  },
  "links": {
    "detailUrl": "https://openagent3.xyz/skills/pihole",
    "downloadUrl": "https://openagent3.xyz/downloads/pihole",
    "agentUrl": "https://openagent3.xyz/skills/pihole/agent",
    "manifestUrl": "https://openagent3.xyz/skills/pihole/agent.json",
    "briefUrl": "https://openagent3.xyz/skills/pihole/agent.md"
  }
}