DNS Deep Dive About 8 min read

Clash DNS Configuration Guide: nameserver, fallback & DNS Hijack Fields Explained

A field-by-field breakdown of the DNS section in Clash config files, with ready-to-use examples for everyday home use and strict leak-proof setups.

Why Clash Ships With Its Own DNS Resolver

Open any Clash or Clash Meta (mihomo) config file and you'll find an entire block starting with dns. It's not just filler, and it's not something only power users need to touch.

In system proxy mode, browsers hand domain names straight to the proxy for remote resolution, so local DNS seems irrelevant. But if even one app skips the proxy and fires a UDP port 53 query straight at your ISP's DNS, poisoning and leaks are back on the table: you could get a spoofed IP, and the query log sits fully exposed on the local network side.

In TUN mode, all traffic from the whole machine goes through the virtual network adapter, so domain resolution has to be handled somewhere. That's exactly what Clash's built-in DNS module does: it takes over port 53 queries entirely, deciding per domain who to ask, how to ask, and whose answer to trust, all based on your config.

So whether the dns block is set up correctly decides three things directly: how fast pages load, whether you get handed a poisoned address, and whose hands your query logs end up in.

Going Through the dns Block Field by Field

The Three Switches: enable / listen / ipv6

  • enable: the master switch. Set it to false and the whole block does nothing — Clash won't take over any resolution, making every other field pointless.
  • listen: the address the built-in DNS server listens on, commonly written as 0.0.0.0:53. This is where TUN hijacking ends up and the entry point when LAN devices use Clash as their DNS server. If you're only using it locally with TUN hijacking, leave it at the default.
  • ipv6: set to false to drop AAAA query results. If your broadband doesn't support IPv6, it's best to turn this off — otherwise apps might grab a v6 address and end up on a route that's either nonexistent or slower.

enhanced-mode and fake-ip-filter

  • redir-host: the traditional mode — every domain gets a real resolution. Best compatibility, at the cost of one extra DNS round trip.
  • fake-ip: domains matching proxy rules get a fake address straight from the 198.18.0.x range, skipping real resolution entirely. Connections open faster, and it also sidesteps poisoning that can happen when an app does its own DNS lookup.
  • fake-ip-filter: the exceptions list — domains here always need a real IP. Typical entries include LAN domains like *.lan, time servers, STUN services, and login domains for certain vendors. If an app misbehaves under fake-ip, the first fix is always adding its domain to this list.

default-nameserver: the Bootstrap DNS

It has exactly one job: resolving DNS servers written as domain names in your config (e.g. dns.alidns.com) into IPs. It's also responsible for resolving proxy node domains when proxy-server-nameserver isn't set separately.

This field must be a plain-IP UDP DNS server, such as 223.5.5.5 or 119.29.29.29. Putting a DoH address here creates a chicken-and-egg loop — you'd need resolution to perform resolution — and the entire dns block collapses.

nameserver: the Primary Resolver List

The default set of resolvers, queried in parallel with the fastest response winning. Four formats are supported: a plain IP means UDP port 53; a tls:// prefix means DoT; an https:// prefix means DoH; and system means fall back to the OS's DNS.

For everyday home use, DoH providers based in mainland China work well: https://dns.alidns.com/dns-query and https://doh.pub/dns-query both offer low latency and results that align well with local CDN routing.

fallback and fallback-filter

fallback runs queries in parallel with nameserver, handling domains that might be poisoned or should be routed through the proxy anyway. It's typically set to a trusted DNS server outside mainland China, such as https://dns.cloudflare.com/dns-query or tls://8.8.4.4:853.

fallback-filter decides whose answer to trust, with four sub-fields each handling a different job:

  • geoip and geoip-code: if the IP returned by nameserver doesn't belong to the specified region (e.g. CN), it's treated as poisoned and the fallback answer is used instead.
  • geosite: when a domain matches categories like gfw, the fallback result is used directly.
  • ipcidr: if the returned IP falls within a reserved range like 240.0.0.0/4, it's treated as poisoned.
  • domain: domains on this list always go through fallback, no conditions attached.

Worth noting: newer mihomo releases lean toward using nameserver-policy combined with routing rules instead. fallback is still fully supported, so there's no rush to migrate an existing config.

nameserver-policy: Per-Domain Assignment (Advanced)

Assigns a dedicated resolver by domain or category, taking priority over both nameserver and fallback. A typical setup: 'geosite:cn' pointing to a domestic DoH provider, and '+.internal.example.com' pointing to an internal company DNS server. This gives finer-grained control than fallback-filter, which suits setups with strict requirements on resolution paths.

What DNS Hijacking Actually Hijacks

"Hijacking" in the config refers to Clash actively taking over port 53 queries sent from the local machine, handing them to its built-in DNS to answer based on the rules above — it's not intercepting anyone else's traffic.

In TUN mode, once tun.enable and dns-hijack are configured, every DNS request entering the virtual network adapter gets captured. This is the most thorough coverage possible — no app can bypass it.

System proxy mode doesn't hijack DNS. Browsers handing domains off to the proxy for remote resolution works fine, but apps that connect directly still use the system's DNS. To close that gap, you either need to enable TUN or manually point the system DNS at the address set in listen.

Note

Keep listen reachable only from the local machine or LAN — never expose the built-in DNS server to the public internet. An open recursive DNS resolver will get found by scanners and abused for amplification attacks.

Two Ready-to-Use Configurations

Option 1: Everyday Home Setup

fake-ip for speed, with domains routed through Alibaba and Tencent DoH for faster domestic sites. Domains matching the gfw category or returning non-CN results automatically switch to fallback. Works well for most home broadband setups: pages load instantly and domestic CDN routing stays on track.

dns:
  enable: true
  listen: 0.0.0.0:53
  ipv6: false
  enhanced-mode: fake-ip
  fake-ip-range: 198.18.0.1/16
  fake-ip-filter:
    - "*.lan"
    - "*.local"
    - "*.msftconnecttest.com"
    - "time.*.com"
    - "localhost.ptlogin2.qq.com"
  default-nameserver:
    - 223.5.5.5
    - 119.29.29.29
  nameserver:
    - https://dns.alidns.com/dns-query
    - https://doh.pub/dns-query
  fallback:
    - https://dns.cloudflare.com/dns-query
    - tls://8.8.4.4:853
  fallback-filter:
    geoip: true
    geoip-code: CN
    geosite:
      - gfw
    ipcidr:
      - 240.0.0.0/4

Option 2: Strict Leak Protection

respect-rules: true routes queries sent to nameserver through the proxy per your routing rules, so query content never touches your local ISP. direct-nameserver handles direct-connect domains, while proxy-server-nameserver handles proxy node domains — each with a clearly separated role.

dns:
  enable: true
  listen: 0.0.0.0:53
  ipv6: false
  respect-rules: true
  enhanced-mode: fake-ip
  fake-ip-filter:
    - "*.lan"
    - "*.local"
  default-nameserver:
    - 223.5.5.5
    - 119.29.29.29
  proxy-server-nameserver:
    - https://dns.alidns.com/dns-query
  direct-nameserver:
    - https://dns.alidns.com/dns-query
    - https://doh.pub/dns-query
  nameserver:
    - https://dns.cloudflare.com/dns-query
    - https://dns.google/dns-query

Layer TUN on top to capture port 53 across the entire machine, leaving no side channel:

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

Worth being upfront about the trade-off: DoH servers outside mainland China get routed through the proxy, so the first lookup is a bit slower, and if the proxy goes down, resolution fails entirely — that's a dependency you have to accept.

Three Checks After Updating Your Config

  1. Check the logs: the [DNS] lines in your client's log show which server handled each domain and which rule matched — confirm the routing behaves as expected first.
  2. Run a leak test: visit a DNS leak test site in your browser. The resolver shown should be your configured DoH provider or proxy exit, not your local ISP.
  3. Spot-check from the command line: run nslookup example.com 127.0.0.1 to query the built-in DNS directly. Under fake-ip mode, getting back a 198.18.x.x address for proxied domains is expected behavior, not a bug.
Tip

Bad YAML indentation is the number one reason a dns block silently does nothing. Use two spaces consistently before each field, then reload the config or restart the core before testing again.

Three Common Issues

  • Domestic sites load slowly: fallback is set to a server outside mainland China with no geosite routing configured, so domestic domains get resolved by a foreign server and CDN routing goes sideways.
  • One app can't connect properly: it likely needs a real IP — add its domain to fake-ip-filter.
  • The config doesn't seem to be taking effect: confirm enable: true is set, check your indentation, and make sure your client isn't overriding the dns block through its GUI settings.

Download the Latest Clash

Clients for Windows, macOS, and Android — checked daily against official releases.

Go to Downloads View Setup Guide
Clash Update