pihole

核心用法

Pi-hole Skill 是一款面向 ClawdBot 生态的命令行工具，用于远程管理 Pi-hole v6 DNS 广告拦截服务。用户通过自然语言指令即可完成状态查询、广告过滤启停、临时禁用计时器设置以及阻断域名分析等操作。配置方式灵活，支持 YAML 配置文件与环境变量双模式，适配本地自签名证书与生产环境 HTTPS 场景。

显著优点

1. 会话安全机制：采用 Pi-hole v6 的 session-based 认证，令牌 30 分钟过期，API 密码以 JSON body 传输而非 URL 暴露，避免进程列表泄露。
2. 输入严格验证：内置 validate_number 与 validate_domain 函数，所有用户输入经转义处理，杜绝命令注入风险。
3. 网络传输安全：默认启用 SSL 证书验证，支持 insecure 标志适配内网自签名场景，curl 请求统一设置 30 秒超时防止阻塞。
4. 零文件系统写入：只读配置文件，不执行任何本地文件写入或系统权限提升操作，攻击面极小。
5. 运维友好设计：提供 5 分钟快速禁用、自定义时长禁用等实用功能，满足临时放行广告站点的需求。

潜在缺点与局限性

• 功能边界受限：Pi-hole v6 API 已移除域名白名单管理功能，用户必须登录 Web Admin 手动操作，无法通过本 Skill 完成。
• 无会话缓存机制：每次 API 调用均重新获取 session token，虽安全性高但增加一次往返请求。
• 令牌明文存储：API token 以明文形式存放于配置文件，依赖用户自行设置 600 权限控制访问。
• 外部强依赖：完全依赖 Pi-hole 服务可用性，若目标主机网络不可达或 API 变更，Skill 将失效。

适合的目标群体

• 家庭网络管理员：需快速开关广告过滤、查看阻断统计
• 中小企业 IT 运维：批量管理多台 Pi-hole 实例
• 技术爱好者：偏好命令行交互、集成至自动化工作流
• ClawdBot 用户：已在生态内，希望统一入口管理网络基础设施

使用风险

• 配置泄露风险：若 ~/.clawdbot/clawdbot.json 权限设置不当，其他用户可能读取 API 令牌
• 误操作风险：自然语言指令解析错误可能导致意外禁用广告过滤（如将 "30" 误解为 30 秒而非 30 分钟）
• 网络超时风险：高延迟网络环境下 30 秒超时可能导致操作失败
• 版本兼容性：仅支持 Pi-hole v6+，v5 用户需升级或寻找替代方案