Pi-hole 技能

通过 Pi-hole v6 API 控制您的 Pi-hole DNS 广告拦截器。

设置

在 Clawdbot 配置中设置您的 Pi-hole API 配置：

skills:
  entries:
    pihole:
      apiUrl: "https://pi-hole.local/api"  # v6 API 路径
      apiToken: "your-app-password-here"       # 从 Pi-hole 管理界面获取
      insecure: false                          # 对于自签名证书，设置为 true

或者，设置环境变量：

export PIHOLE_API_URL="https://pi-hole.local/api"
export PIHOLE_API_TOKEN="your-app-password-here"
export PIHOLE_INSECURE="false"

获取 API 凭证

1. 在浏览器中打开 Pi-hole 管理界面 http://pi-hole.local/admin
2. 导航至 设置 > API
3. 生成一个应用密码
4. 将该密码用作 apiToken

功能

状态

• 获取当前 Pi-hole 状态（启用/禁用）
• 查看统计信息：已拦截查询、今日查询、被拦截的域名、活跃客户端
• 查看近期查询活动

控制

• 启用/禁用：开启或关闭 Pi-hole
• 禁用 5 分钟：临时关闭广告拦截一小段时间
• 自定义时长禁用：设置特定的禁用时间（以分钟为单位）

拦截分析

• 检查被拦截域名：查看在特定时间窗口内哪些域名被拦截
• 显示最常被拦截域名：查看最频繁被拦截的域名

使用示例

# 检查 Pi-hole 状态
"pihole status"

# 关闭广告拦截
"pihole off"

# 开启广告拦截
"pihole on"

# 禁用 5 分钟（针对需要广告的网站）
"pihole disable 5m"

# 禁用 30 分钟
"pihole disable 30"

# 查看过去 30 分钟内被拦截的内容
"pihole blocked"

# 查看过去 10 分钟（600 秒）内被拦截的域名
"pihole blocked 600"

# 显示统计信息
"pihole stats"

API 端点 (Pi-hole v6)

认证

POST /api/auth
Content-Type: application/json
{"password":"your-app-password"}

响应:
{
  "session": {
    "sid": "session-token-here",
    "validity": 1800
  }
}

状态

GET /api/dns/blocking
Headers: sid: <session-token>

响应:
{
  "blocking": "enabled" | "disabled",
  "timer": 30  // 重新启用前的剩余秒数（如果设置了定时器禁用）
}

启用/禁用

POST /api/dns/blocking
Headers: sid: <session-token>
Content-Type: application/json

启用:
{"blocking":true}

禁用:
{"blocking":false}

定时禁用（秒）:
{"blocking":false,"timer":300}

统计

GET /api/stats/summary
Headers: sid: <session-token>

响应:
{
  "queries": {
    "total": 233512,
    "blocked": 23496,
    "percent_blocked": 10.06
  },
  "gravity": {
    "domains_being_blocked": 165606
  },
  "clients": {
    "active": 45
  }
}

查询

GET /api/queries?start=-<seconds>
Headers: sid: <session-token>

响应:
{
  "queries": [
    {
      "domain": "example.com",
      "status": "GRAVITY",
      "time": 1768363900,
      "type": "A"
    }
  ]
}

v5 与 v6 API 变更

Pi-hole v6 引入了重大的 API 变更：

重要提示： 域名白名单功能不再通过 v6 API 提供。您必须通过 Pi-hole 管理界面来添加域名到白名单。

SSL 证书

生产环境（有效证书）

{
  "apiUrl": "https://pi-hole.example.com/api",
  "apiToken": "...",
  "insecure": false
}

自签名/本地证书

{
  "apiUrl": "https://pi-hole.local/api",
  "apiToken": "...",
  "insecure": true
}

insecure 标志会为 curl 添加 -k 选项以绕过证书验证。

安全注意事项

• 会话令牌在 30 分钟（1800 秒）后过期
• API 密码通过 JSON 请求体发送，而非 URL
• 所有请求都有 30 秒的超时限制
• 令牌在进程列表中不可见（通过环境变量传递）

故障排除

"认证失败"

• 检查 apiToken 是否与您的 Pi-hole 应用密码匹配
• 验证 apiUrl 是否正确（必须以 /api 结尾）
• 确保 Pi-hole 可以从您的网络访问

"无法确定状态"

• 检查 API URL 是否可达
• 如果使用 HTTPS 且为自签名证书，请设置 insecure: true
• 验证 API 密码是否正确

网络错误

• 确保 Clawdbot 所在的机器可以访问 Pi-hole
• 检查防火墙规则是否允许 API 访问
• 验证 URL 方案（http 与 https）

要求

• Pi-hole v6 或更高版本
• 在 Pi-hole 管理界面生成的应用密码
• 网络可访问 Pi-hole API
• curl, jq（大多数 Unix 系统已预装）