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

What Clash DNS actually handles

When you visit a website, an application usually sends the domain to the system DNS and then uses the returned IP address to establish a connection. If the system resolves the domain first, Clash may see only the destination IP, causing domain rules, GeoSite rules, and domains recoverable only through sniffing to stop working. With Clash's built-in DNS enabled, the same proxy core can handle resolution requests, making the relationship between domains, rule matching, and outbound selection clearer.

DNS configuration is not simply a matter of entering a public server. A single query may involve the bootstrap resolver, regular resolvers, proxy-node resolvers, fallback resolvers, domain policies, and TUN hijacking. Each field handles a different stage. Repeating entries does not automatically improve reliability and may instead cause resolution loops or inconsistent results.

The main path of a DNS query

1. The browser or application requests a domain lookup, such as www.example.com.
2. The system DNS, TUN hijacking, or a manually specified local port passes the query to Clash.
3. The core first checks its cache, hosts, fake-ip-filter, and nameserver-policy.
4. If no specific policy matches, the query goes to nameserver; when fallback is enabled, fallback-filter is also used to evaluate the result.
5. The core returns the real IP address, or, in Fake-IP mode, a mapped address within 198.18.0.0/16.
6. The application opens the connection, and Clash selects the outbound based on domain rules, IP rules, and proxy groups.

nameserver, default-nameserver, and proxy-server-nameserver

nameserver: the standard domain-resolution entry point

dns.nameserver is the default resolver list. When no nameserver-policy matches and fallback does not take over, ordinary domains are sent to these servers. It can use traditional UDP DNS or encrypted protocols such as DoH and DoT. UDP DNS is usually written as an IP address and uses port 53 by default; DoH uses a complete HTTPS URL; DoT is typically written as tls://hostname:853.

dns:
  enable: true
  listen: 127.0.0.1:1053
  nameserver:
    - 223.5.5.5
    - https://dns.alidns.com/dns-query
    - https://doh.pub/dns-query

You can place multiple servers in the same list, but “multiple” does not mean strict failover in order. Depending on the core version, queries may run concurrently, with the first acceptable result being used. If mainland China domains and other domains must always use different resolvers, use nameserver-policy instead of relying on list order.

default-nameserver: resolving the resolver's own hostname

When nameserver contains https://dns.alidns.com/dns-query, the core must first learn the IP address of dns.alidns.com before it can establish the HTTPS connection. default-nameserver handles this bootstrap stage and is also commonly called bootstrap DNS. Prefer directly reachable resolvers specified by IP here to avoid the circular dependency of resolving the resolver's hostname first.

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

default-nameserver is not the mandatory resolver for every website. After startup, regular domain queries are still handled by nameserver, fallback, or nameserver-policy. It usually handles very few queries, but may be used again when networks switch, cached records expire, or a resolver connection is rebuilt.

proxy-server-nameserver: dedicated resolver for proxy-node hostnames

A proxy node address may be a hostname such as node.example.net rather than a fixed IP. If resolving the node hostname also depends on a proxy that has not connected yet, a loop forms: the node must be resolved before the proxy can connect, but resolving the node requires the proxy. mihomo provides proxy-server-nameserver to send proxy-server hostname lookups to a directly reachable DNS server.

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

When node hostname resolution fails, logs often contain messages such as lookup, no such host, or i/o timeout. Even if ordinary website domains resolve normally, all proxy nodes may still appear to time out. Check nameserver and proxy-server-nameserver separately; whether a browser can open a page is not enough to diagnose the issue.

How to configure fallback and fallback-filter

fallback is a group of backup resolvers, commonly used to filter DNS results from different network paths. It is not simply a list queried only after nameserver times out. Classic Clash configurations often query nameserver and fallback in parallel, then use fallback-filter to decide whether to accept the fallback result. mihomo retains this compatibility syntax, but nameserver-policy is usually a better choice for precise domain-based routing.

The four fallback-filter conditions

• geoip: Enable result evaluation based on an IP geolocation database.
• geoip-code: Specify the reference region code, such as CN. This logic depends on the local GeoIP data being kept up to date.
• ipcidr: When the primary result falls within a specified network range, select the fallback result according to the filter rules. This is often used to exclude clearly abnormal address ranges.
• domain: Send matching domains directly to the fallback result, with support for domain-suffix patterns.

dns:
  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
    domain:
      - +.google.com
      - +.githubusercontent.com

This type of configuration is better suited to networks that need to distinguish between local resolution and another resolver group. It is not appropriate for every region. If the device is outside mainland China, hard-coding geoip-code to CN may make the filtering logic inconsistent with the device's actual network location. For devices used across regions or while traveling, explicitly assigning resolvers by domain is usually easier to maintain.

nameserver-policy: assign resolvers precisely by domain

mihomo's nameserver-policy assigns DNS servers based on domain matches. It is more direct than combining a primary resolver with geolocation filtering: matching domains go to the specified servers, while unmatched domains return to nameserver. You can enter full domain names and domain suffixes, or use geosite: matching with cores that support GeoSite data.

dns:
  enable: true
  nameserver:
    - https://1.1.1.1/dns-query
    - https://dns.google/dns-query
  nameserver-policy:
    "geosite:cn":
      - https://dns.alidns.com/dns-query
      - https://doh.pub/dns-query
    "+.example.cn":
      - https://dns.alidns.com/dns-query
    "intranet.example.net":
      - 192.168.1.1

The final example covers an internal-network scenario: if a company or home domain can be resolved only by a LAN DNS server, assign that domain specifically to 192.168.1.1 instead of putting the LAN DNS into the shared nameserver for every domain. This preserves internal-service resolution without routing every public domain through the router.

If the configuration references geosite:cn, make sure the GeoSite data exists and is compatible with the core. When startup logs report a failed ruleset load, missing database, or matcher error, update the core data files first. To reduce reliance on external data, you can also use simple domain-suffix rules such as +.example.com.

Domain policies and proxy rules are different

nameserver-policy determines “which DNS server to query,” while proxy rules determine “which outbound to use for the connection.” Resolving a domain through local DoH does not mean the connection must be DIRECT; resolving it through a remote DNS server does not mean the connection must use a proxy. Check the two rule systems separately so DNS selection is not mistaken for proxy-group selection.

Fake-IP, redir-host, and filter lists

Common values for enhanced-mode are fake-ip and redir-host. In Fake-IP mode, Clash does not immediately return the real address to the application; it returns a mapped address first. When the application connects to that address, Clash can accurately restore the original domain and then apply domain rules. The default mapped range is typically 198.18.0.1/16, a reserved benchmark range rather than ordinary public IP space.

dns:
  enable: true
  enhanced-mode: fake-ip
  fake-ip-range: 198.18.0.1/16
  fake-ip-filter:
    - "*.lan"
    - "+.local"
    - "localhost"
    - "time.*.com"
    - "ntp.*.com"

LAN device discovery, printers, screen casting, NTP time synchronization, and some applications that require real IP addresses may not work well with Fake-IP. Add the relevant domains to fake-ip-filter to make them return real DNS results. Do not expand the filter to cover every common top-level domain, or Fake-IP will lose much of its value for domain identification and routing.

redir-host returns the real IP directly to the application, providing a more straightforward compatibility path, but the core may retain only IP information after the connection arrives. Whether domain rules still work then depends on connection metadata, DNS mapping cache, and domain sniffing. On desktop systems using TUN with primarily domain-based rules, test Fake-IP first; if LAN services behave incorrectly, add filters one at a time instead of disabling the entire mode.

DNS hijacking in TUN mode

Enabling only dns.enable does not mean every program will actively use Clash DNS. A browser may enable its own secure DNS, the system may still send UDP 53 queries to the router, and some applications may bypass the system proxy. In TUN mode, dns-hijack intercepts DNS traffic on specified ports and passes it to the core.

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

any:53 covers ordinary UDP 53 queries, while tcp://any:53 covers queries using TCP 53. They do not automatically intercept DoH requests sent directly by an application, because DoH runs over HTTPS and normally uses port 443. If a browser specifies its own DoH, the query may never reach Clash DNS. For troubleshooting, temporarily set the browser's secure DNS to “Use system settings” and compare the logs.

TUN still requires system permissions. Windows typically needs permission for the core to create a virtual adapter and routes; macOS may request network-extension or VPN configuration permission; Linux needs access to the TUN device and permission to modify routes. If logs show permission denied, interface-creation failure, or a failed route addition, fix the permissions first instead of repeatedly changing nameserver.

Choosing a listen port

listen: 127.0.0.1:1053 is suitable for local testing and does not expose the service directly to other LAN devices. If other devices must use this computer as their DNS server, listen on a LAN interface and configure the system firewall and a stable address. Port 53 may already be occupied by the system resolver, virtualization software, or another DNS service. Higher ports such as 1053 and 5353 are more convenient for troubleshooting, although 5353 may also conflict with mDNS.

Recommended mihomo configuration example

Below is a starter mihomo configuration for desktop use. It uses Fake-IP, two DoH resolvers, a dedicated resolver for proxy-node hostnames, and TUN DNS hijacking. Adjust the DNS servers based on reachability from your network; there is no need to keep addresses that cannot connect reliably just for the sake of completeness.

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
    - 119.29.29.29

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

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

  nameserver-policy:
    "+.local":
      - 192.168.1.1
    "+.lan":
      - 192.168.1.1

  fake-ip-filter:
    - "*.lan"
    - "+.local"
    - "localhost"
    - "time.*.com"
    - "ntp.*.com"

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

This example sets ipv6 to false, which suits networks with unstable local IPv6 routing or proxy nodes without IPv6 support. If your broadband connection, LAN, and nodes all handle IPv6 correctly, change it to true and check that your rules include IPv6 ranges. Enabling IPv6 responses in DNS without a usable IPv6 outbound often causes applications to try AAAA addresses first and then wait for a timeout.

Before importing, make a copy of the currently working configuration. In many desktop clients, open the current subscription or local configuration editor from “Profiles.” Subscription updates may overwrite manual changes, so the safer approach is to use the client's override, supplementary configuration, or Mixin feature. After saving, review the core startup log for YAML indentation errors, unknown fields, or port conflicts.

Verify that DNS works as expected

Step 1: Check the core log

After saving the configuration and restarting the core, watch the log for 30 seconds. Search for DNS, lookup, timeout, connection refused, address already in use, and failed to parse. If 127.0.0.1:1053 is already in use, close the process occupying it or change listen to an available port.

Step 2: Query the local listening port directly

On systems with dig installed, bypass the browser cache and test Clash DNS directly. The following command explicitly targets the local address and port 1053:

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

In Fake-IP mode, an A record may return an address within 198.18.0.0/16; this is expected. Domains added to fake-ip-filter should return real addresses. If both types of domains return identical results, check whether enhanced-mode is active, whether the subscription overwrote the configuration, and whether the running configuration is the one you just edited.

Step 3: Compare rules with connection logs

Open a domain for testing and confirm that the connection record shows the domain rather than only the destination IP. Then check the matched rule and proxy group. If DNS succeeds but the connection fails, the problem is usually at the node, routing, or rule stage. If DNS logs time out directly, continue checking resolver reachability, proxy-node hostnames, and the firewall.

Step 4: Test on different networks

Test separately on home broadband, a mobile hotspot, or another available network. After each switch, wait 10 to 30 seconds for interfaces, routes, and DNS caches to update. If the failure occurs on only one network, that network may be blocking a specific DNS protocol, have faulty IPv6 routing, or be unable to reach the DoH server. Temporarily keep one UDP DNS server and one DoH server for comparison instead of replacing every parameter at once.

Common errors and troubleshooting order

Error 1: All nodes time out, but website domains resolve

Check proxy-server-nameserver first. If node addresses use hostnames, working regular nameserver does not prove that node hostnames are using a reachable path. Also confirm that nameserver-policy is not directing node hostnames to a DNS server reachable only after the proxy is established.

Error 2: LAN devices stop opening after TUN is enabled

Add the domains used by the router, NAS, printers, and screen-casting services to fake-ip-filter, and set nameserver-policy for internal domains. Common LAN suffixes include .lan and .local, but use the names defined by the router's DHCP or internal DNS configuration. Do not add only the device's current IP, because it may change after a DHCP lease renewal.

Error 3: The browser works, but command-line programs fail

The browser may use its own DoH while command-line tools rely on system DNS; it may also use the system proxy while the command-line program uses only TUN. First disable the browser's independent secure DNS for comparison, then query Clash's listening port with dig. If the local query succeeds, continue checking the system proxy, TUN routes, and whether the command-line program is hard-coded to use a particular resolver.

Error 4: Rules occasionally match the IP instead of the domain

Confirm that DNS queries are actually passing through Clash and check enhanced-mode. If using redir-host, enable the domain-sniffing feature supported by the core, but remember that sniffing cannot recover domains from every protocol. In desktop environments that depend heavily on domain rules, Fake-IP with a sensible filter list is usually more stable.

Error 5: Manual changes disappear after a configuration update

Subscription updates usually rewrite the configuration file. Put custom DNS settings in the client's override, supplementary script, or Mixin, or maintain a separate local configuration. Before editing, note the actual core shown under “Settings” → “Core,” then confirm the loaded file path in “Logs” so you do not edit a copy that the current configuration is not using.

Configuration trade-offs at a glance

• Put regular domain resolution in nameserver and the bootstrap resolution required for DoH in default-nameserver.
• When proxy nodes use hostnames, configure a directly reachable proxy-server-nameserver to avoid circular dependencies.
• For fixed domain-based routing, prefer nameserver-policy; fallback-filter is better suited to the traditional dual-resolver filtering approach.
• In TUN environments, use dns-hijack to intercept UDP 53 and TCP 53, but it will not automatically intercept DoH sent directly by applications.
• Fake-IP helps preserve domain information; when LAN services, time synchronization, or device discovery misbehave, add entries to fake-ip-filter one at a time.
• Change only one parameter group at a time, restart the core, review the log, and verify with a local-port query. Avoid changing DNS, rules, and nodes simultaneously.

A maintainable Clash DNS configuration does not need a long list of servers. First decide which resolver handles regular domains, proxy-node hostnames, and internal domains, then determine whether fallback, Fake-IP, and TUN hijacking are needed. Once the path is clear, resolution failures, incorrect rule matches, and LAN conflicts can each be traced back to the relevant field.