1. Home
  2. Blog
  3. Clash DNS Configuration Explained
Advanced Config Estimated reading time: 9 minutes

Clash DNS Configuration Explained: nameserver, fallback, and DNS Hijacking Parameters

The dns block is the part of a Clash/Clash Meta config file that gets copy-pasted the most and understood the least. This article starts with the two modes of enhanced-mode, breaks down what nameserver and fallback are each responsible for, explains how fallback-filter decides whether a domain's resolution has been tampered with, and ends with a ready-to-use template with line-by-line notes.

What problem does the dns block solve

A proxy client itself doesn't resolve domain names — it forwards traffic. But before traffic ever reaches the proxy, the system or the app first needs to resolve a domain to an IP. If that step relies on the local ISP's DNS, two typical problems show up: the resolved result may be tampered with or hijacked and return the wrong IP; and the lookup itself reveals intent, since even if the resulting traffic later goes through the proxy, the DNS request itself is often sent in plaintext over UDP port 53, which can be logged or even blocked by devices along the path. Clash's dns configuration block exists to take over this resolution step, so that domain resolution and traffic forwarding both happen under the same rule system.

This module has two parts: enhanced-mode decides how domain-to-IP translation works, while the nameserver/fallback group of parameters decides which upstream servers actually handle the lookup and in what order. Only when both work together can rule matching stay accurate while also avoiding tampered results.

enhanced-mode: choosing between fake-ip and redir-host

enhanced-mode only has two possible values, and their behavior differs significantly:

  • fake-ip: after intercepting a DNS query, Clash doesn't immediately request the real IP. Instead it hands the app a fake IP from a dedicated address range (default 198.18.0.0/16). When the app connects using that fake IP, Clash resolves the real domain name at the moment the connection is established and picks a proxy group based on the rules. This approach gives the most accurate rule matching, since routing decisions are always based on the domain rather than a potentially variable IP. It's the default in mainstream clients (the mihomo kernel family) and the officially recommended setting.
  • redir-host: requests the real IP from the upstream server directly and returns it as-is. This is more compatible — some apps that rely on the real IP for geolocation (certain video or maps apps) will misbehave if handed a fake IP range, which is when switching to redir-host becomes necessary. The trade-off is that rule matching degrades to IP-range-based matching, which is less precise than domain-based routing.

Unless there's a specific compatibility issue, stick with fake-ip, and use fake-ip-filter to exclude LAN addresses, local network services, and domains that actively rely on real IPs (such as some banking apps or LAN device discovery protocols) from fake IP assignment, so those domains still go through real resolution.

How nameserver and fallback divide the work

Many people just fill both nameserver and fallback with a pile of DNS server addresses without understanding how Clash actually uses them. The real logic is:

  1. nameserver is queried first

    By default, every domain is first resolved using the servers in nameserver, which usually should be trustworthy public DNS servers (preferably DoH/DoT rather than plaintext UDP, to avoid having the query content visible at the transport layer and hijacked in the process).

  2. fallback-filter decides whether a re-check is needed

    Once a result comes back from nameserver, if fallback-filter's geoip check is enabled, Clash checks whether the IP belongs to the region specified by geoip-code (usually CN). If it does, the result is accepted as-is; if not, that likely means the domain actually points to a resource outside the region but was resolved to a wrong or anomalous IP, which triggers the next step.

  3. fallback re-resolves to confirm

    Once a re-check is triggered, Clash re-resolves the domain using the servers listed in fallback — usually DoH/DoT servers located outside the region or with stronger resistance to tampering — and takes that result as final.

In other words, nameserver is the default channel responsible for efficiency, fallback is the verification channel responsible for correction, and fallback-filter is the referee between the two. Missing any one of them weakens the whole block's resistance to tampering: with only nameserver and no fallback, there's no way to fix a bad result; with only fallback and no nameserver, every single request goes through servers outside the region, which noticeably increases resolution latency for local sites.

Note

The geoip check in fallback-filter relies on a built-in or downloaded GeoIP database. On first launch, or when that database is out of date, this feature can briefly fail, which shows up as abnormal resolution results for some domains outside the region. Confirming that the client's GeoIP database is in a valid state is the first step when troubleshooting DNS issues.

What DNS hijacking looks like, and what to do beyond fallback-filter

Some network environments intercept or poison plaintext DNS queries (UDP port 53) that pass through ISP equipment. A common symptom is that visiting a site outside the region resolves to an unrelated local IP, or returns a nonexistent address that causes the connection to time out. This kind of hijacking happens at the transport layer and has nothing to do with Clash's rule configuration — the only effective fix is to make the DNS query itself travel over an encrypted channel:

  • Use a DoH (DNS over HTTPS) address with an https:// prefix. The query goes over port 443 mixed in with ordinary HTTPS traffic, making it hard to identify and block separately.
  • Use a DoT (DNS over TLS) address with a tls:// prefix. The query goes over port 853 and is encrypted, which also avoids plaintext hijacking, though port 853 is sometimes individually throttled or blocked, making it slightly less compatible than DoH.
  • Avoid mixing in plaintext UDP addresses (like 8.8.8.8 with no protocol prefix) inside nameserver/fallback — a plaintext address offers essentially no protection on some networks.

Also pay attention to the default-nameserver field: it's used solely to resolve the domain names of the DoH/DoT servers listed under nameserver/fallback themselves (for example, figuring out which IP doh.pub points to). It must be filled with plain IP addresses, never a domain-based DoH address, otherwise a circular resolution loop occurs and the DNS module fails to start.

A ready-to-use dns config template

The template below is for the mihomo kernel (all Clash Meta family clients are based on it), with line-by-line comments on what each field does. It can be pasted directly to replace the dns block in your config file:

dns:
  enable: true                      # Turn on DNS takeover; if disabled, falls back to the system's default resolution
  ipv6: false                       # Recommended off if IPv6 isn't in use, to cut down on wasted queries
  enhanced-mode: fake-ip            # Most accurate rule matching; switch to redir-host if you hit compatibility issues
  fake-ip-range: 198.18.0.1/16      # Fake IP allocation range; just make sure it doesn't overlap your real local subnet
  fake-ip-filter:                   # Domains below use real resolution instead of a fake IP
    - "*.lan"
    - "+.local"
    - "time.*.com"
    - "*.market.xiaomi.com"
  default-nameserver:                # Used only to resolve the DoH/DoT server domains below; must be plain IPs
    - 223.5.5.5
    - 119.29.29.29
  nameserver:                        # Default resolution channel; prioritize local DoH here
    - https://doh.pub/dns-query
    - https://dns.alidns.com/dns-query
  fallback:                          # Verification/correction channel; kicks in when resolution outside the region looks off
    - https://1.1.1.1/dns-query
    - tls://8.8.8.8:853
  fallback-filter:
    geoip: true                      # Turn on the geo check
    geoip-code: CN                   # Trigger a fallback re-check if the result isn't from this region
    ipcidr:                          # Results within these ranges are treated as suspicious and trigger fallback directly
      - 240.0.0.0/4
    domain:                          # Domains below always go through fallback, skipping the nameserver check
      - "+.google.com"
      - "+.youtube.com"

Replace the example entries in fake-ip-filter and fallback-filter.domain with whatever domains actually need special handling in your case; the rest of the fields rarely need changing.

Common troubleshooting steps

Internet access completely broke after changing the dns config — what now?

First confirm that default-nameserver is set to a plain IP rather than a domain-based DoH address — this is the most common cause of a resolution loop. Next, check that your YAML indentation is correct; the dns block is strict about nesting, and a single misplaced space can cause the whole block to be ignored.

An app keeps failing to connect under fake-ip mode — is that a DNS issue?

It's likely that the app has its own server address validation or whitelists specific IP ranges. Adding its domain to fake-ip-filter so it uses real resolution usually fixes this; if the same kind of issue keeps recurring across multiple apps, it may be worth switching to redir-host altogether.

Sites outside the region are still slow — does that mean fallback isn't working?

First check whether the proxy rule itself is matching the correct proxy group — a correct DNS resolution routed through the wrong policy group also shows up as slowness. If rules aren't the issue, check the connectivity of your fallback servers and swap in a different working DoH/DoT address if needed.

Download Clash Client