Clash DNS Configuration Explained: How to Set nameserver, fallback, and DNS Hijacking

Understanding the Clash DNS request flow

Clash DNS does more than forward system queries to a single public DNS server. Once enabled, it listens on a local port, reads the configured upstream servers, and chooses a result based on the domain, rules, and returned addresses. With TUN and DNS hijacking enabled, requests originally sent to a router or public DNS on port 53 can also enter this flow.

A typical lookup has four steps: an application requests an address for a domain; the system passes the request to Clash; Clash queries nameserver, the matched policy server, or fallback; and it returns a real address or Fake IP based on fallback-filter and the enhanced mode. Web access, domain-rule matching, and proxy-node resolution can all be affected by these steps.

A readable baseline configuration

dns:
  enable: true
  listen: 127.0.0.1:1053
  ipv6: false
  enhanced-mode: fake-ip
  fake-ip-range: 198.18.0.1/16
  default-nameserver:
    - 223.5.5.5
    - 1.1.1.1
  nameserver:
    - https://dns.alidns.com/dns-query
    - https://doh.pub/dns-query
  fallback:
    - https://1.1.1.1/dns-query
    - https://dns.google/dns-query
  fallback-filter:
    geoip: true
    geoip-code: CN
    ipcidr:
      - 240.0.0.0/4

Here, listen uses 127.0.0.1:1053, so Clash listens for UDP/TCP traffic on port 1053 at the local loopback address only. Port 1053 is a common unprivileged DNS port and avoids conflicts with an existing service on port 53. If the client manages the listening address automatically, do not add another conflicting configuration to the subscription file.

What nameserver, default-nameserver, and fallback each do

nameserver: the default resolver for regular domain lookups

nameserver is the primary upstream for most domain lookups. It can use standard UDP DNS or, with a compatible mihomo kernel, formats such as DoH and DoT. For low latency on a home network, choose servers that are nearby and responsive; for encrypted transport, use an HTTPS DNS endpoint.

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

Adding multiple servers to one list does not mean every query waits strictly on the first entry. Concurrency and result selection depend on the kernel implementation, so avoid piling four or five servers with very different latency and behavior into one list. In practice, keeping two or three reliable upstreams makes troubleshooting easier.

default-nameserver: resolving the DNS servers themselves first

When nameserver uses a hostname-based DoH endpoint such as https://dns.alidns.com/dns-query, the kernel must first resolve the IP address of dns.alidns.com before it can establish the HTTPS connection. default-nameserver handles this bootstrap lookup.

default-nameserver:
  - 223.5.5.5
  - 1.1.1.1

To avoid the circular dependency of needing a DNS server to resolve a DNS server, prefer directly reachable IP addresses here. If the logs repeatedly show lookup dns server failed or context deadline exceeded, first check whether these addresses are reachable on the current network instead of adding more DoH endpoints.

fallback: a parallel set of alternative answers

fallback is commonly used to provide a different DNS perspective from the primary upstream. Once enabled, Clash uses the filter conditions to decide whether to keep the nameserver result or use the fallback result. It does not wait until nameserver times out, so adding too many distant DoH services can increase connection and resource usage.

If the primary DNS on your network is already reliable and Fake IP mode is paired with a complete rule set, you may not need fallback at all. Get the simple setup working first, then add alternative paths for suspected DNS interference, incorrect regional results, or specific domain failures. This is usually more reliable than copying a large legacy template.

How fallback-filter selects the final answer

fallback-filter determines whether the primary result should be replaced. Common conditions include GeoIP country codes, specific CIDR ranges, and domain lists. Support for extended fields may vary across kernel versions; with mihomo, follow the documentation and startup logs for the version in use.

geoip and geoip-code

fallback-filter:
  geoip: true
  geoip-code: CN

These settings use GeoIP data to assess the geographic origin of returned addresses. A typical approach is to keep the primary result when it matches the expected region and consider the fallback result when it does not. Accuracy depends on how up to date the client's GeoIP data is, so a country code should not be treated as a definitive measure of route performance.

ipcidr: filtering clearly abnormal address ranges

fallback-filter:
  geoip: true
  geoip-code: CN
  ipcidr:
    - 0.0.0.0/32
    - 127.0.0.0/8
    - 240.0.0.0/4

ipcidr can mark address ranges that ordinary public domains should not return. For example, resolving a public website to 127.0.0.1 is usually suspicious. However, corporate networks, home servers, and lab environments may legitimately use private addresses, so do not indiscriminately block every address in 10.0.0.0/8, 172.16.0.0/12, or 192.168.0.0/16.

domain: prefer fallback for selected domains

fallback-filter:
  geoip: true
  geoip-code: CN
  domain:
    - '+.example.net'
    - '+.example.org'

A domain list is useful for a small number of reproducible problem sites. A pattern such as +.example.net matches the domain and its subdomains, but the exact syntax must be compatible with the kernel version in use. Do not let the list grow without limit; if hundreds of domains require manual entries, recheck the primary upstream, rule set, or network egress.

Choosing between fake-ip and redir-host

enhanced-mode determines which answer Clash returns to applications. The common values are fake-ip and redir-host. Both can work with proxy forwarding, but they differ in how domains are preserved, their compatibility, and how they are diagnosed.

fake-ip: return a reserved address and map the domain inside the kernel

enhanced-mode: fake-ip
fake-ip-range: 198.18.0.1/16

Fake IP mode returns a temporary address from a reserved pool, such as 198.18.0.23. The application then connects to that address, while Clash uses its internal mapping to recover the original domain before applying domain rules and proxy policies. This avoids waiting for a real DNS answer before starting the connection and makes traffic that exposes only a destination IP easier to associate with a domain.

198.18.0.0/15 is a reserved benchmark range commonly used by proxy kernels as a Fake IP pool. If a LAN, corporate VPN, or lab environment already uses the same range, switch to a kernel-supported range that does not conflict. Seeing ping return an address beginning with 198.18 does not by itself indicate a DNS error; the important question is whether Clash is handling the request.

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

fake-ip-filter:
  - '*.lan'
  - localhost.ptlogin2.qq.com
  - '+.stun.*.*'
  - '+.stun.*.*.*'

LAN device discovery, printers, some multiplayer games, STUN, time synchronization, and applications that need a real address may not work well with Fake IP. Add those domains to fake-ip-filter as needed. Add entries one at a time based on actual failures and clear the system DNS cache afterward; copying an oversized list makes many domains bypass Fake IP and weakens domain mapping.

redir-host: return real IPs for more transparent compatibility

enhanced-mode: redir-host

redir-host returns the real resolved address to the application. It can suit legacy software or unusual LAN environments that conflict with Fake IP and are difficult to filter individually. However, reliable domain-rule matching depends more on sniffing, connection metadata, and the interception method. For troubleshooting, temporarily switch from fake-ip to redir-host; if the problem disappears immediately, inspect Fake IP range conflicts and filter entries.

Why DNS hijacking is still needed in TUN mode

Setting the system DNS to 127.0.0.1:1053 does not guarantee that every program will use it. Some applications send UDP requests directly to 8.8.8.8:53, while some devices use the DNS server advertised by the router. TUN mode intercepts IP traffic; DNS hijacking additionally redirects matching port 53 requests to the Clash DNS module.

A common TUN section in a mihomo configuration looks like this. Field support varies by kernel and client wrapper. When a graphical client generates the TUN configuration automatically, use its interface controls first to avoid conflicts between the UI settings and subscription YAML.

tun:
  enable: true
  stack: mixed
  auto-route: true
  auto-detect-interface: true
  dns-hijack:
    - any:53

• enable enables TUN interception.
• stack: mixed uses the mixed network stack supported by the kernel.
• auto-route automatically adds the required routes.
• auto-detect-interface attempts to identify the current outbound network interface.
• any:53 matches ordinary DNS requests to port 53 in intercepted traffic.

DNS hijacking primarily covers traditional UDP/TCP traffic on port 53. In-app DoH uses HTTPS on port 443 and looks like ordinary HTTPS at the network layer, so dns-hijack alone cannot rewrite it universally. If the browser has Secure DNS enabled, temporarily disable it during troubleshooting to determine whether the browser or Clash is handling the lookup.

A practical mihomo DNS setup for everyday use

For everyday desktop and mobile use, start with this approach: let a local upstream handle common lookups, use encrypted alternatives for suspicious results, use Fake IP for domain mapping, and use TUN hijacking for traditional DNS. The example below illustrates the relationships between fields; no single set of servers fits every network.

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
    - 119.29.29.29
  nameserver:
    - https://dns.alidns.com/dns-query
    - https://doh.pub/dns-query
  fallback:
    - https://1.1.1.1/dns-query
    - https://dns.google/dns-query
  fallback-filter:
    geoip: true
    geoip-code: CN
    ipcidr:
      - 0.0.0.0/32
      - 127.0.0.0/8
      - 240.0.0.0/4
  fake-ip-filter:
    - '*.lan'
    - localhost
    - '+.stun.*.*'
    - '+.stun.*.*.*'

If the local network has no IPv6 connectivity, setting ipv6 to false prevents applications from receiving AAAA records and attempting an unreachable path. Enable it when native IPv6 is stable and the proxy nodes and rules handle IPv6 correctly. Do not check only whether the ISP assigned an IPv6 address; also test the default route, DNS responses, and proxy egress.

mihomo also provides extended fields such as nameserver-policy, proxy-server-nameserver, and direct-nameserver to assign resolvers for specific domains, proxy-node hostnames, and direct connections. These are useful once the resolution paths are clearly separated. Adding every advanced field before the basic setup works can create circular lookups or send node hostnames through the wrong egress.

Extra considerations when proxy nodes use hostnames

A subscription may specify a server as node.example.com; the kernel must resolve it before the proxy connection can be established. If resolving that hostname requires a proxy that has not been established yet, the result is a loop: the proxy is needed to resolve the node, but the node is needed to establish the proxy. mihomo can use proxy-server-nameserver to assign a directly reachable resolver specifically for node hostnames.

proxy-server-nameserver:
  - 223.5.5.5
  - https://dns.alidns.com/dns-query

A step-by-step method for troubleshooting DNS issues

Step 1: Confirm that the kernel loaded the configuration

1. After saving the YAML, use the client's “Reload configuration” action instead of merely closing the editor.
2. Open the kernel log and search for DNS, listen, timeout, and parse.
3. If a YAML indentation error appears, check that dns: uses consistent space indentation and that list items retain their hyphens.
4. Make sure the selected subscription did not overwrite your local changes during an automatic update.

YAML is indentation-sensitive. In the example below, indenting fallback inside the nameserver list does not express the intended structure. Use two spaces per level and never use tabs.

Step 2: Query Clash's listening port directly

On Windows, use nslookup in PowerShell or Command Prompt; on macOS and Linux, use dig. Point the query at the listening address to distinguish “Clash DNS itself is failing” from “the system is not sending requests to Clash.”

nslookup example.com 127.0.0.1

dig @127.0.0.1 -p 1053 example.com A
dig @127.0.0.1 -p 1053 example.com AAAA

nslookup usually queries port 53 by default. If Clash listens only on 1053, use a tool that supports a custom port or have the client forward system requests from port 53 to 1053. Getting 198.18.x.x in Fake IP mode is expected; repeated timeouts point to port conflicts, firewall rules, or unreachable upstreams.

Step 3: Measure upstream responses, not just resolution success

One successful response does not prove that the path is stable. Run 20 consecutive queries and watch for intermittent timeouts. Ordinary DNS on a LAN often responds in about 5–30 ms; cross-region DoH may take 80–250 ms. Actual values depend on the access network, so focus on timeout rate and variance rather than chasing the lowest single result.

• Only DoH times out: check the system clock, the TLS connection, and bootstrap resolution for the DoH hostname.
• Both ordinary UDP DNS and DoH time out: check the current network, default route, and firewall.
• The query succeeds but the page does not open: continue by checking proxy rules, the node connection, and TUN routes.
• Recovery after switching to redir-host: check for Fake IP range conflicts and filter entries.
• Only LAN domains fail: assign a dedicated resolution policy for internal domains or add the necessary Fake IP exclusions.

Step 4: Clear old caches before testing again

After changing the upstream or enhanced mode, the system, browser, and Clash may all retain old answers. On Windows, run ipconfig /flushdns; on Linux with systemd-resolved, run resolvectl flush-caches. Browsers may also maintain their own host cache. After clearing the caches, reload the configuration and test the same domain again so an old record is not mistaken for the new result.

Final checklist for these fields

• enable is on, and the listening port does not conflict with another local DNS service.
• default-nameserver is directly reachable before the proxy is established.
• Keep two or three stable upstreams in nameserver instead of stacking many redundant services.
• Use fallback for a different DNS perspective, not as a mechanical timeout backup.
• The GeoIP, CIDR, and domain conditions in fallback-filter match the current network environment.
• fake-ip-range does not conflict with a corporate VPN, home LAN, or lab network.
• Add only domains that genuinely need real addresses to fake-ip-filter.
• When TUN mode is enabled, confirm that dns-hijack does not conflict with the client's automatic configuration.
• When proxy nodes use hostnames, make sure their bootstrap resolution does not depend on a proxy that has not been established.
• Change one group of fields at a time, and record query results and logs before and after each change.

The key to configuring Clash DNS is not finding one fixed template for every network. It is building a verifiable chain from the resolution entry point and alternative results through filtering, enhanced mode, and traffic interception. Start with the fewest fields needed to confirm reachability, then add Fake IP, fallback, and TUN hijacking step by step so any failure can be traced to a specific link.