adguard – OpenClaw Skill

---

name: adguard description: Control AdGuard Home DNS filtering via HTTP API. Use when managing blocklists/allowlists, checking domain filtering status, toggling protection, or clearing DNS cache. Supports blocking/allowing domains, viewing statistics, and protecting/disabling DNS filtering.

AdGuard Home Controller

Manage AdGuard Home DNS filtering from the command line via the REST API.

Requirements

• AdGuard Home running with web interface
• Admin username and password
• curl installed (usually default on macOS/Linux)

Quick Start

# Set password once
export ADGUARD_PASSWORD=your_admin_password

# Use commands
./adguard.sh status
./adguard.sh check example.com
./adguard.sh allow broken-site.com
./adguard.sh block malware.ru

Configuration

Set environment variables for your AdGuard instance:

export ADGUARD_URL="http://192.168.1.100:3000"      # Your AdGuard IP and port
export ADGUARD_USERNAME="admin"                     # Usually 'admin' (default)
export ADGUARD_PASSWORD="your_admin_password"       # REQUIRED

Add to ~/.bashrc or ~/.zshrc for persistence.

Config File Alternative

Create ~/.adguard/config.json (optional):

{
  "url": "http://192.168.1.100:3000",
  "username": "admin"
}

Then set ADGUARD_PASSWORD separately for security.

Commands

check <domain>

Check if a domain is currently blocked or allowed.

./adguard.sh check doubleclick.net
# ✗ doubleclick.net IS BLOCKED
#   Blocked by: Adblock Plus filter

./adguard.sh check example.com
# ✓ example.com is NOT blocked (allowed)

allow <domain> | whitelist <domain>

Add a domain to the allowlist (whitelist). Creates an exception rule that overrides blocklists.

./adguard.sh allow broken-site.com
# ✓ Added rule: @@||broken-site.com^
#   Domain: broken-site.com
#   Action: allow

block <domain> | blacklist <domain>

Add a domain to the blocklist. Creates a custom blocking rule.

./adguard.sh block spyware-domain.ru
# ✓ Added rule: ||spyware-domain.ru^
#   Domain: spyware-domain.ru
#   Action: block

status | stats

Display DNS filtering statistics and protection state.

./adguard.sh status
# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
# AdGuard Home Status
# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
# Protection: ✓ ENABLED
# 
# DNS Queries: 1,234
# Blocked by rules: 156
# Blocked by safe browsing: 23
# Safe search replacements: 5
# Block rate: 14%
# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

toggle | protection

Enable or disable DNS protection. Useful for temporarily disabling filtering.

./adguard.sh toggle
# Disabling protection...
# ✓ Protection is now false

cache-clear

Clear the DNS cache to apply rule changes immediately.

./adguard.sh cache-clear
# Clearing DNS cache...
# ✓ Cache cleared

Finding Your AdGuard Home Device

If you don't know your AdGuard URL:

1. Router admin panel — Look for a device named "AdGuard Home" or check for port 3000
2. Local network scan — Use nmap or check "Connected Devices"
3. If running on same machine — Default is http://localhost:3000
4. mDNS/Bonjour — Try http://adguard-home.local:3000 (depends on network)

Filtering Rules Syntax

AdGuard uses a DNS filtering rule syntax:

Rule	Effect
||example.com^	Block example.com and subdomains
@@||example.com^	Allow example.com (exception/whitelist)
example.com	Block exact domain only
||ad.example.com^	Block only ad.example.com

See API Reference for complete syntax.

Common Scenarios

Allow a site that's blocked by accident

adguard.sh allow my-bank.com

Block a known malware domain

adguard.sh block malicious-tracker.xyz

Check if a domain is being filtered

adguard.sh check ads.google.com

View today's statistics

adguard.sh status

Temporarily disable filtering (e.g., for troubleshooting)

adguard.sh toggle

Troubleshooting

Error: Failed to authenticate → Check ADGUARD_PASSWORD is correct and set → Verify ADGUARD_URL points to the right IP and port

Error: API call failed (HTTP 401) → Authentication failed, check credentials

Rules don't take effect → Run adguard.sh cache-clear to flush DNS cache → Wait 5+ minutes for clients to refresh their cache → Restart your device's network connection

Can't connect to AdGuard → Verify device is on the same network → Check firewall isn't blocking port 3000 → Ping the device: ping <ip>

Advanced: Batch Operations

Block multiple domains:

for domain in tracker1.com tracker2.com tracker3.com; do
    adguard.sh block "$domain"
done

Check multiple domains:

for domain in example.com test.org my-site.net; do
    echo "Checking $domain..."
    adguard.sh check "$domain"
done

API Reference

See references/api.md for complete AdGuard Home API documentation.

AdGuard Home Controller Skill

Manage AdGuard Home DNS filtering from the command line. Check domains, add to allowlists/blocklists, toggle protection, and view statistics—all via the AdGuard REST API.

Installation

clawdhub install rowbotik/adguard

Quick Start

# Set your AdGuard admin password
export ADGUARD_PASSWORD=your_admin_password

# Check if a domain is blocked
./scripts/adguard.sh check doubleclick.net

# Add to allowlist
./scripts/adguard.sh allow broken-site.com

# View statistics
./scripts/adguard.sh status

Configuration

Create ~/.adguard/config.json or set environment variables:

export ADGUARD_URL="http://192.168.1.100:3000"
export ADGUARD_USERNAME="admin"
export ADGUARD_PASSWORD="your_password"

Commands

Command	Effect
check <domain>	Check if domain is blocked
allow <domain>	Add to allowlist (whitelist)
block <domain>	Add to blocklist
status	View statistics and protection status
toggle	Enable/disable DNS protection
cache-clear	Clear DNS cache

Examples

# Check a tracker domain
./scripts/adguard.sh check ads.google.com
# ✗ ads.google.com IS BLOCKED
#   Blocked by: Adblock Plus filter

# Whitelist a broken site
./scripts/adguard.sh allow bank.example.com
# ✓ Added rule: @@||bank.example.com^

# View stats
./scripts/adguard.sh status
# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
# Protection: ✓ ENABLED
# DNS Queries: 1,234
# Blocked by rules: 156
# Block rate: 12%

# Disable filtering temporarily
./scripts/adguard.sh toggle
# Disabling protection...
# ✓ Protection is now false

Features

• ✓ Check if domains are filtered
• ✓ Add/remove from allowlists and blocklists
• ✓ View DNS statistics
• ✓ Toggle protection on/off
• ✓ Clear DNS cache
• ✓ Proper error handling and validation
• ✓ Session-based authentication

Requirements

• AdGuard Home running with web interface
• Admin credentials
• curl installed (default on macOS/Linux)

Finding Your AdGuard Home

1. Router admin panel — Look for a device on port 3000
2. Same machine — http://localhost:3000
3. Network scan — Check connected devices for "AdGuard Home"
4. mDNS — Try http://adguard-home.local:3000

Filtering Rules

Rules follow AdGuard's DNS filtering syntax:

• ||example.com^ — Block example.com and subdomains
• @@||example.com^ — Allow example.com (exception)
• ||tracker.example.com^ — Block only tracker subdomain

See references/api.md for complete syntax and API docs.

Troubleshooting

Error: Failed to authenticate → Check ADGUARD_PASSWORD and ADGUARD_URL are correct

Rules don't take effect immediately → Run ./scripts/adguard.sh cache-clear → Wait 5+ minutes for clients to refresh

Can't connect → Verify AdGuard is running: curl http://<ip>:3000 → Check firewall allows port 3000

Documentation

• SKILL.md — Full command reference and examples
• references/api.md — Complete AdGuard REST API documentation
• scripts/adguard.sh — Main CLI tool

License

MIT