Pi-hole 技能

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

设置

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

skills:
  entries:
    pihole:
      apiUrl: "https://pi-hole.local/api"  # v6 API path
      apiToken: "your-app-password-here"       # Get from Pi-hole Admin
      insecure: false                          # Set to true for self-signed certs

或者，设置环境变量：

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分钟：临时禁用广告拦截一小段时间
• 自定义时长禁用：设置特定的禁用时间（以分钟为单位）

拦截分析

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

使用示例

# Check Pi-hole status
"pihole status"

# Turn off ad blocking
"pihole off"

# Turn on ad blocking
"pihole on"

# Disable for 5 minutes (for a site that needs ads)
"pihole disable 5m"

# Disable for 30 minutes
"pihole disable 30"

# See what was blocked in the last 30 minutes
"pihole blocked"

# See blocked domains in last 10 minutes (600 seconds)
"pihole blocked 600"

# Show statistics
"pihole stats"

API端点（Pi-hole v6）

身份验证

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

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

状态

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

Response:
{
  "blocking": "enabled" | "disabled",
  "timer": 30  // seconds until re-enable (if disabled with timer)
}

启用/禁用

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

Enable:
{"blocking":true}

Disable:
{"blocking":false}

Disable with timer (seconds):
{"blocking":false,"timer":300}

统计

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

Response:
{
  "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>

Response:
{
  "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
}

该不安全标志添加了-kcurl命令中绕过证书验证的选项。

安全注意事项

• 会话令牌在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系统上已安装）