Apfree Wifidog

---
name: apfree-wifidog
description: Guide tool usage for managing ApFree WiFiDog routers, gateways, and captive portal devices.
user-invocable: false
---

# ApFree WiFiDog Tool Guidance

You have access to a suite of tools for managing and monitoring network routers, Wi-Fi access points, gateways, and captive portals.

When a user asks to manage, list, configure, or query routers (路由器), devices (设备), gateways (网关), Wi-Fi (无线网络), or network clients (终端/客户端), you must use the `apfree_wifidog_*` tools.

Prefer the specific `apfree_wifidog_*` tools over the low-level `apfree_wifidog` tool for router management.

## Recommended tool choices

- Use `apfree_wifidog_list_devices` to discover online routers.
- Use `apfree_wifidog_get_status` for router health, runtime, and service status.
- Use `apfree_wifidog_get_sys_info` for system resources, platform details, and runtime metrics.
- Use `apfree_wifidog_get_device_info` for configured device metadata.
- Use `apfree_wifidog_update_device_info` to update structured device metadata fields.
- Use `apfree_wifidog_get_clients` to inspect authenticated clients.
- Use `apfree_wifidog_get_client_info` for one client by MAC address.
- Use `apfree_wifidog_kickoff_client` to disconnect a client by MAC address.
- Use `apfree_wifidog_tmp_pass` to temporarily allow a client MAC.
- Use `apfree_wifidog_get_wifi_info` for Wi-Fi configuration.
- Use `apfree_wifidog_set_wifi_info` to update Wi-Fi settings including SSID (network name), password, encryption, or hidden status. Use this when the user asks to change or modify Wi-Fi or SSID settings.
- Use `apfree_wifidog_scan_wifi` to scan nearby Wi-Fi networks.
- Use `apfree_wifidog_set_wifi_relay` to configure upstream Wi-Fi relay or STA.
- Use `apfree_wifidog_get_trusted_domains` and `apfree_wifidog_sync_trusted_domains` for trusted domain allowlists.
- Use `apfree_wifidog_get_trusted_wildcard_domains` and `apfree_wifidog_sync_trusted_wildcard_domains` for wildcard domain allowlists.
- Use `apfree_wifidog_get_trusted_mac` and `apfree_wifidog_sync_trusted_mac` for trusted MAC allowlists.
- Use `apfree_wifidog_get_auth_serv` and `apfree_wifidog_set_auth_serv` for captive portal auth server settings.
- Use `apfree_wifidog_get_mqtt_serv` and `apfree_wifidog_set_mqtt_serv` for MQTT server connection settings.
- Use `apfree_wifidog_get_websocket_serv` and `apfree_wifidog_set_websocket_serv` for WebSocket server connection settings.
- Use `apfree_wifidog_generate_wireguard_keys` to generate a WireGuard key pair on the router (private key stays on device, only public key returned). **Always call this before `set_wireguard_vpn`** to avoid sending private keys over the network.
- Use `apfree_wifidog_get_wireguard_vpn`, `apfree_wifidog_set_wireguard_vpn`, and `apfree_wifidog_get_wireguard_vpn_status` for WireGuard VPN configuration and runtime status.
- Use `apfree_wifidog_get_vpn_routes` to view current VPN routing rules (which traffic goes through the WireGuard tunnel).
- Use `apfree_wifidog_set_vpn_routes` to steer traffic through the VPN tunnel: `selective` mode for specific CIDRs, `full_tunnel` mode for all traffic with `excludeIps` to prevent routing loop.
- Use `apfree_wifidog_delete_vpn_routes` to remove VPN routing rules: `flushAll` to clear everything, or `routes` array for individual CIDRs.
- Use `apfree_wifidog_get_firmware_info` for firmware and build details.
- Use `apfree_wifidog_get_network_interfaces` for interface inventory and IP details.
- Use `apfree_wifidog_bpf_add` to add an IPv4, IPv6, or MAC target to BPF traffic monitoring.
- Use `apfree_wifidog_bpf_json` to query BPF traffic monitoring statistics for `ipv4`, `ipv6`, `mac`, `sid`, or `l7` tables.
- Use `apfree_wifidog_get_l7_active_stats` to query active L7 protocol traffic speed and volume statistics (SID view).
- Use `apfree_wifidog_get_l7_protocol_catalog` to list the L7 protocol library currently supported by the device (including domain signatures when available).
- Use `apfree_wifidog_bpf_del` to remove an IPv4, IPv6, or MAC target from BPF traffic monitoring.
- Use `apfree_wifidog_bpf_flush` to clear all monitored entries in one BPF table.
- Use `apfree_wifidog_bpf_update` to update per-target downrate/uprate limits.
- Use `apfree_wifidog_bpf_update_all` to update downrate/uprate limits for all monitored entries in one BPF table.
- Use `apfree_wifidog_execute_shell` only when the user explicitly requests a shell command.
- Use `apfree_wifidog_reboot_device` only when the user explicitly requests a reboot.
  Only use the low-level `apfree_wifidog` tool when you need an apfree-wifidog operation that is not covered by a specific tool above.

## BPF quick reference

Use `table` as one of: `mac`, `ipv4`, `ipv6`, `sid`, `l7`.

- `apfree_wifidog_bpf_add`
  - Required: `deviceId`, `address`
  - Optional: `table` (default `mac`)
  - Example: add one MAC to monitoring.
- `apfree_wifidog_bpf_del`
  - Required: `deviceId`, `address`
  - Optional: `table` (default `mac`)
  - Example: remove one IPv4 from monitoring.
- `apfree_wifidog_bpf_json`
  - Required: `deviceId`
  - Optional: `table` (default `mac`)
  - Example: read current stats for `ipv4` table, `sid` active L7 traffic stats, or `l7` protocol library.
- `apfree_wifidog_get_l7_active_stats`
  - Required: `deviceId`
  - Query target: `bpf_json` with `table=sid`.
- `apfree_wifidog_get_l7_protocol_catalog`
  - Required: `deviceId`
  - Query target: `bpf_json` with `table=l7`.
- `apfree_wifidog_bpf_flush`
  - Required: `deviceId`
  - Optional: `table` (default `mac`)
  - Example: clear all monitored entries in `mac` table.
- `apfree_wifidog_bpf_update`
  - Required: `deviceId`, `target`, `downrate`, `uprate`
  - Optional: `table` (default `mac`)
  - Rate units: bps, valid range `1..10000000000`.
- `apfree_wifidog_bpf_update_all`
  - Required: `deviceId`, `downrate`, `uprate`
  - Optional: `table` (default `mac`)
  - Rate units: bps, valid range `1..10000000000`.

## Additional operations via low-level `apfree_wifidog`

When a user explicitly asks for any of the following operations, call the low-level tool with `action=call` and `op` set to the exact operation name:

- `firmware_upgrade` or `ota` for firmware upgrades.
- `delete_wifi_relay` or `unset_wifi_relay` to clear Wi-Fi relay or STA configuration.
- `get_ipsec_vpn`, `set_ipsec_vpn`, `get_ipsec_vpn_status`.

## VPN route quick reference

- `apfree_wifidog_get_vpn_routes`
  - Required: `deviceId`
  - Returns: list of `proto static` routes on wg0, tunnel_up status.
- `apfree_wifidog_set_vpn_routes`
  - Required: `deviceId`, `mode` (`selective` or `full_tunnel`)
  - Selective mode: provide `routes` array of CIDRs (e.g. `["1.2.3.0/24", "4.5.6.0/24"]`).
  - Full tunnel mode: provide `excludeIps` array with VPS public IP to prevent routing loop. Routes `0.0.0.0/1` + `128.0.0.0/1` are added automatically.
  - Note: existing routes are flushed before new ones are applied.
- `apfree_wifidog_delete_vpn_routes`
  - Required: `deviceId`
  - Optional: `flushAll` (boolean, removes all VPN routes), `routes` (array of CIDRs to remove individually).

### WireGuard + VPN routing workflow

1. **Generate keys on router**: `apfree_wifidog_generate_wireguard_keys` — private key stays on device, returns public key for VPS `[Peer]` config.
2. Configure WireGuard tunnel: `apfree_wifidog_set_wireguard_vpn` with `routeAllowedIps: false` on the peer (omit `privateKey` — already set by step 1).
3. Check tunnel status: `apfree_wifidog_get_wireguard_vpn_status`.
4. Set VPN routes: `apfree_wifidog_set_vpn_routes` with `selective` or `full_tunnel` mode.
5. Verify routes: `apfree_wifidog_get_vpn_routes`.
6. Remove routes when no longer needed: `apfree_wifidog_delete_vpn_routes` with `flushAll: true`.

Do not use low-level `apfree_wifidog` for operations that already have dedicated tools unless the user explicitly asks for the exact low-level op.

The following are internal device-control operations and should not be used unless the user explicitly requests them with exact parameters:

- `gateway_heartbeat`
- `auth`

Note about device IDs: You can directly use a device alias (for example "Router-1", "Router-2") in the `device_id` parameter for any tool. The system will automatically map the alias to the correct long ID.

## Tool calling output

When you decide to use a tool, do not output any conversational text, preamble, or explanations. Output exactly the tool call directly and nothing else.