Clash DNS Configuration: How to Configure nameserver, fallback, and DNS Hijacking

Understand the Clash DNS request path first

Clash DNS configuration is not simply a matter of replacing the system DNS address. Once the built-in DNS module is enabled, the client receives domain queries and decides how to resolve them based on nameserver, fallback, rules, and the enhanced mode. When a connection is established, Clash also needs to associate the domain, resolution result, and proxy rules. DNS settings therefore directly affect rule matching, initial loading speed, and the availability of some applications.

A typical query can be divided into four steps: an application sends a query for example.com; the system or TUN passes the request on port 53 to Clash; Clash resolves it through the configured upstream servers; the connection then selects direct access or a proxy according to domain rules, IP rules, or the final rule. If any step bypasses Clash, domain rules may not match, stale results may be cached, or a webpage may open while an application fails to connect.

How to configure enable, listen, and the basic fields

enable: turn on built-in DNS

enable: true enables Clash's DNS module. After setting it to false, the other dns fields will not participate in resolution as expected. A successful configuration load does not prove that queries have entered this module; also check the system proxy, TUN, or the client's Network Extension implementation.

listen: provide a local DNS listening port

listen: 127.0.0.1:1053 provides DNS service on UDP/TCP port 1053 at the local loopback address only. Port 1053 is a common unprivileged test port and avoids conflicts with the system's port 53. If you use 0.0.0.0:1053, devices on the same local network may be able to access the port, so everyday mobile configurations generally prefer a loopback address or a listener managed automatically by the client.

listen only specifies “where to wait for queries”; it does not mean “capture the queries”. On desktop systems with TUN enabled, you usually also need tun.dns-hijack. On iOS, DNS interception is often handled by the client's Network Extension, and some clients ignore the YAML tun section in favor of their own app settings.

A configuration to use as a starting point

dns:
  enable: true
  listen: 127.0.0.1:1053
  ipv6: false
  enhanced-mode: fake-ip
  fake-ip-range: 198.18.0.1/16
  use-hosts: true

  default-nameserver:
    - 223.5.5.5
    - 1.1.1.1

  nameserver:
    - https://dns.alidns.com/dns-query
    - https://1.1.1.1/dns-query

  fallback:
    - https://8.8.8.8/dns-query
    - tls://1.0.0.1:853

  fallback-filter:
    geoip: true
    geoip-code: CN
    ipcidr:
      - 240.0.0.0/4
    domain:
      - +.google.com
      - +.github.com

This example can serve as a base template for clients that support Clash Meta or mihomo syntax. Individual clients may further process DoH, DoT, IPv6, or TUN fields, so check the configuration validation result after importing it. If the core is older, also confirm that it recognizes geoip-code, DoT addresses, and enhanced-mode fields.

The difference between nameserver, default-nameserver, and fallback

default-nameserver: bootstrap resolution for encrypted DNS addresses

When nameserver uses a DoH address with a hostname such as https://dns.alidns.com/dns-query, Clash must first determine the IP address for dns.alidns.com. default-nameserver mainly handles this bootstrap resolution. Prefer directly reachable IP addresses here to avoid a loop in which the DoH hostname must be resolved before DoH itself can be used.

If every upstream is specified by hostname and default-nameserver is unreachable, common symptoms include DNS request timeouts, no network access immediately after startup, or repeated failures to resolve upstream hostnames. During troubleshooting, keep one pure IP-based DNS server that the current network can reach, then verify the DoH address.

nameserver: the primary source for everyday queries

nameserver contains the primary upstream servers for ordinary queries. It can include traditional UDP DNS, TCP DNS, DoT, or DoH. A UDP address looks like 223.5.5.5; DoT can be written as tls://1.1.1.1:853; DoH can be written as https://1.1.1.1/dns-query. Mixing protocols can help identify network restrictions, but more upstreams are not necessarily better. Two stable servers with clear paths are usually easier to troubleshoot than six or seven stacked addresses.

fallback: choose alternative results according to filters

fallback is often understood as a backup DNS used only after nameserver times out. In practice, its behavior is usually closer to retrieving candidate results in parallel and then using fallback-filter to decide which result set to accept. Details such as concurrency, caching, and result selection vary between core versions, so it should not be treated as a traditional primary/backup switch.

For example, after enabling geoip: true and setting geoip-code: CN, the core may use results returned by fallback when the primary results do not meet the filter conditions. Domains explicitly listed under domain may also prefer fallback results. Rule-set versions, GeoIP data, and the CDN addresses returned by upstreams all affect this decision, so do not assume a configuration is wrong simply because an IP does not appear to be local.

How each fallback-filter condition works

geoip and geoip-code

geoip: true enables filtering based on IP geolocation data, while geoip-code: CN specifies the region code used for evaluation. This relies on GeoIP data bundled with or downloaded by the client, not on a real-time lookup service. Missing or outdated data files, or an incorrect path, can produce results that differ from expectations.

ipcidr

ipcidr uses CIDR ranges to mark addresses for which fallback candidates should be preferred. The common example 240.0.0.0/4 covers a reserved address range and helps exclude clearly abnormal results. Do not add large public network ranges without a specific reason, or normal websites may continually use fallback.

domain

domain specifies domains. The common mihomo syntax +.example.com matches the domain and its subdomains. If you need an independent upstream for only a few websites, newer mihomo configurations can also use nameserver-policy to map specific domains directly to designated DNS servers. This is usually clearer than broad fallback filtering.

dns:
  nameserver:
    - https://dns.alidns.com/dns-query

  nameserver-policy:
    "+.example.net":
      - https://1.1.1.1/dns-query
    "geosite:cn":
      - https://dns.alidns.com/dns-query

Whether nameserver-policy supports rule-set syntax depends on the core and the client packaging version. When using a mihomo v1.19 series configuration, follow the core version shown by the client and its configuration validation result. If the client still uses an older Clash core, use a standard domain list instead of copying unsupported rule-set syntax.

Choosing between fake-ip and redir-host

fake-ip: return a reserved address and associate the real domain

enhanced-mode: fake-ip returns a mapped address from the specified address pool, commonly 198.18.0.1/16. When the application later connects to that address, Clash restores the original domain through its internal mapping and applies the rules. This can reduce additional resolution delays in some situations and helps preserve domain information for rule matching.

In a test environment, run dig @127.0.0.1 -p 1053 example.com A. If the response is 198.18.x.x, the request has usually entered the fake-ip flow. This is not the website's real public IP and should not be compared item by item with results from a public DNS query.

fake-ip-filter: return real addresses for local and special domains

Printers, routers, local network discovery, and some services that depend on real IP addresses may not work well with fake-ip. Use fake-ip-filter to exclude local domains, starting with domains involved in an actual problem rather than copying a list of hundreds of entries from an unknown source.

dns:
  enhanced-mode: fake-ip
  fake-ip-range: 198.18.0.1/16
  fake-ip-filter:
    - "*.lan"
    - "*.local"
    - "localhost"
    - "router.asus.com"
    - "time.apple.com"

*.local is commonly associated with mDNS and local network discovery. If AirPlay, AirPrint, or home device discovery fails on iOS, first check whether these domains are being handled by fake-ip and confirm that the client is allowed to access the local network. In iOS 26, this permission is available under Settings → Privacy & Security → Local Network.

redir-host: return real resolution results directly

redir-host usually returns the real IP address to the application, offering a more straightforward compatibility path. However, the ability to associate domains with connections depends on the traffic interception method. When banking apps, local devices, or special protocols are incompatible with fake-ip, temporarily switch to redir-host for comparison. If the issue immediately disappears, improve fake-ip-filter first instead of changing nodes, rules, and DNS at the same time.

Configuring DNS hijacking and TUN mode

DNS hijacking here means that the client forwards port 53 requests sent to other DNS addresses to Clash's built-in DNS. It addresses applications that bypass the system DNS and access a fixed DNS server directly. Configuring only listen does not change the destination of these packets.

tun:
  enable: true
  stack: mixed
  auto-route: true
  strict-route: true
  dns-hijack:
    - any:53
    - tcp://any:53

any:53 takes over common DNS requests, while tcp://any:53 covers TCP DNS. DoH uses HTTPS port 443 and DoT commonly uses port 853, so ordinary port 53 hijacking cannot fully identify or intercept them. When an application has built-in DoH, handle it through domain rules, connection policies, or the application's own settings.

On iPhone and iPad, clients usually establish a VPN configuration through the iOS Network Extension. Whether the YAML tun fields take effect depends on the client implementation. If the system and app show inconsistent states, go to Settings → General → VPN & Device Management → VPN to confirm the active connection, then return to the client and check its logs for DNS timeout, no such host, or upstream connection failures.

Verification steps after configuration

1. Validate the syntax first. YAML uses space indentation and must not contain tabs. dns and tun must be at the correct level, with hyphens retained before list items.
2. Check the listening status. On desktop, confirm that the core is listening on port 1053. If another program already uses the port, change it to 1054 and update the test command accordingly.
3. Query an uncached domain. On a device with command-line access, run dig @127.0.0.1 -p 1053 example.com A. In fake-ip mode, expect an address in the 198.18.0.0/16 range; redir-host mode should return a public address.
4. Compare the first and subsequent queries. In the same test environment, a first query taking 1800 ms followed by one taking 20 ms usually indicates that caching works but the upstream connection is slow to establish. If every query exceeds 2000 ms and times out, check the DoH path and default-nameserver.
5. Check rule matching. Open a website with a clear domain rule and confirm in the client's connection records that the domain rule is shown, rather than an unexpected IP-CIDR or MATCH result.
6. Clear old caches and test again. After changing the enhanced mode, restart the core or use the client's DNS cache refresh function. Refreshing only the webpage may still use an old result saved by the app, system, or browser.

Common mistakes and a recommended adjustment order

Assuming more upstreams mean greater stability

The more upstream servers you add, the more path differences, concurrent results, and log noise you introduce. During troubleshooting, start with one UDP DNS and one DoH server, verify that each is reachable, and then decide whether to keep more. Mobile networks, company Wi-Fi, and home broadband may restrict ports 53, 853, and 443 differently, so judge stability through testing on the current network.

Enabling fallback, policy, and extensive filtering at once

fallback-filter, nameserver-policy, and proxy rules can all affect a single request. Adding many conditions at once makes it difficult to determine which setting controls the final result. The recommended order is: make nameserver work first, choose fake-ip or redir-host, add a small number of policies, and only then introduce fallback filtering.

Treating a DNS issue as a node issue

DNS queries occur before or in parallel with the connection to a proxy node. If changing the node temporarily fixes the problem, the cache may simply have been refreshed or an upstream connection re-established. Check the logs: if the resolution stage shows context deadline exceeded or no such host, address DNS first. If the target IP has already been resolved but the proxy handshake times out, then investigate the node and route.

Ignoring inconsistent IPv6 settings

ipv6: false generally means that the DNS module will not return AAAA results, but the system, TUN, and proxy node may each have their own IPv6 settings. If the network has an unstable IPv6 route, disable DNS IPv6 temporarily for comparison. If you must access IPv6-only services, confirm that the local network, node, and rules all support IPv6; changing only this field to true is not enough.

The key to a stable configuration is a clear request path: use default-nameserver for bootstrap resolution, a small number of nameserver entries for primary queries, add fallback only when regional filtering is needed, preserve the domain-to-connection relationship with fake-ip or redir-host, and let TUN or the iOS Network Extension take over the actual traffic. Adjusting the configuration in this order usually makes DNS timeouts, missed rules, and local network failures much easier to isolate.