什么是 Pi-hole 控制器 (pihole-ctl)？

pihole-ctl 技能允许 AI 智能体直接与本地 Pi-hole 实例交互，充当全面的网络卫士。它弥合了自然语言请求与 Pi-hole FTL 数据库之间的差距，使用户能够通过简单的对话界面查询网络统计数据、管理服务状态并更新阻止列表。通过在 Openclaw Skills 中使用此集成，开发人员和家庭实验室爱好者可以自动执行网络健康检查和广告拦截管理，而无需手动输入终端命令。

该技能专为高性能和安全性而设计，使用原生 Python 脚本安全地查询 SQLite 数据库。它提供有关已拦截广告、热门客户端和域名活动的实时反馈，对于希望维护清洁高效本地网络的 Openclaw Skills 用户来说，这是一个必不可少的补充。

下载入口:https://github.com/openclaw/skills/tree/main/skills/1999azzar/pihole-ctl

安装与下载

1. ClawHub CLI

从源直接安装技能的最快方式。

2. 手动安装

将技能文件夹复制到以下位置之一

优先级：工作区 > 本地 > 内置

3. 提示词安装

将此提示词复制到 OpenClaw 即可自动安装。

Pi-hole 控制器 (pihole-ctl) 应用场景

• 监控过去 24 小时内拦截的广告总数。
• 识别本地网络中最活跃或流量最大的客户端。
• 在特定维护窗口内开启或关闭广告拦截。
• 自动执行 Gravity 更新，确保阻止列表始终为最新。
• 审计热门被拦截域名，以验证网络安全策略。

1. 用户提供自然语言提示，例如“今天拦截了多少广告？”或“pihole 状态”。
2. Openclaw Skills 智能体解析请求并将其映射到相应的管理命令或数据库查询。
3. 对于统计请求，智能体执行 query_db.py 脚本以读取 FTL 数据库。
4. 对于管理任务，智能体触发 Pi-hole CLI 以修改服务状态（启用/禁用）。
5. 该技能处理 JSON 输出或 CLI 结果，并向用户返回结构化的摘要。

Pi-hole 控制器 (pihole-ctl) 配置指南

要开始使用此技能，请确保环境具有访问 Pi-hole 数据库和 CLI 工具的必要权限。

1. 将当前用户添加到 pihole 组以授予数据库读取权限：

sudo usermod -aG pihole $USER

2. 验证 Python 环境是否可以访问 FTL 数据库：

python3 scripts/query_db.py --summary --hours 24

3. 确保 pihole 命令在系统 PATH 中可用，以便执行管理功能。

Pi-hole 控制器 (pihole-ctl) 数据架构与分类体系

pihole-ctl 技能与位于 /etc/pihole/pihole-FTL.db 的 Pi-hole FTL 数据库进行交互。它根据以下查询参数组织输出：

name: pihole-ctl
description: Manage and monitor local Pi-hole instance. Query FTL database for statistics (blocked ads, top clients) and control service via CLI. Use when user asks "how many ads blocked", "pihole status", or "update gravity".

Pi-hole Controller

Usage

• Role: Network Guardian.
• Trigger: "Check Pi-hole", "Adblock status", "Who is querying top domains?".
• Output: JSON stats or CLI command results.

Capabilities

1. Statistics: Query FTL database for accurate logs (Last 24h, Top Domains).
2. Management: Enable/Disable blocking (pihole enable/disable).
3. Blocklists: Update Gravity (pihole -g).
4. Audit: Identify chatty clients or top blocked domains.

Scripts

• scripts/query_db.py: Python script using native sqlite3 library to query Pi-hole stats safely.
  • Requires read permission on /etc/pihole/pihole-FTL.db.
  • Usage: python3 scripts/query_db.py --summary --hours 24
  • Usage: python3 scripts/query_db.py --top 10

Permissions

• Database Access: The user running this skill must have read access to /etc/pihole/pihole-FTL.db.
  • Recommended: Add user to pihole group (usermod -aG pihole ubuntu).
• Management Commands: pihole CLI commands (enable/disable) require sudo or must be run by a user with appropriate permissions.

Reference Materials

• Database Schema