Advanced Configuration 13 min read

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

Understand DNS field order, use cases, and limits to diagnose resolution failures and rule-matching issues in Clash.

Separate DNS resolution, proxy rules, and connection exits

The DNS module in a Clash configuration resolves domain names to addresses and, in certain enhanced modes, preserves the relationship between domains and connections. Proxy rules decide whether a request uses DIRECT, REJECT, a proxy node, or a proxy group. The selected exit then establishes the connection. These three parts affect one another, but they are not the same thing.

For example, when a browser accesses a domain, the operating system may first send a query to the local DNS server. After Clash intercepts the query, it selects an upstream resolver based on the configuration and returns a real address or a Fake IP to the browser. The browser then starts a connection, and Clash determines the exit by combining the domain, target address, rule order, and current mode. Simply adding a DNS server to the configuration does not mean every connection will use the proxy. Likewise, assigning a domain rule to a proxy does not guarantee that the application will use Clash's DNS module.

When diagnosing resolution problems, answer three questions first: Did the DNS request actually reach Clash? Which upstream resolver did Clash choose? How did the result participate in subsequent rule matching? Looking only at the symptom that a page will not open can easily mix up resolution failures, incorrect rule matches, unavailable nodes, and an inactive system proxy.

Standard resolution versus enhanced modes

In common implementations, enhanced-mode can be set to fake-ip or redir-host. Fake IP mode returns a synthetic address from a reserved range to the application and stores a mapping between that address and the original domain in the core. When the application connects to the synthetic address, Clash can restore the domain and then apply domain rules and subsequent resolution. This usually helps preserve domain information and reduces rule mismatches caused by applications resolving names outside Clash.

Redir-host mode generally returns the real resolution result to the application. It is closer to traditional DNS behavior, but whether the full domain information remains available for the connection depends on the traffic entry point, sniffing capability, application protocol, and core implementation. Neither mode is universally better: LAN devices, games, printer services, applications that require real addresses, and some connection checks may need Fake IP exclusions. When stable domain-rule matching is the priority, Fake IP is often the first mode to test.

What nameserver and default-nameserver do

nameserver contains the primary upstream resolvers used by the Clash DNS module for regular domain queries. It can include traditional UDP/TCP DNS servers, as well as DoH or DoT endpoints when supported by the core. With multiple upstreams, the exact behavior for concurrency, caching, and result selection depends on the core version, so the list should not be understood as a strict top-to-bottom retry sequence.

default-nameserver is mainly used to resolve the hostnames of DNS servers themselves; this is bootstrap resolution. Suppose nameserver contains https://dns.example.net/dns-query. Clash must first obtain the address of dns.example.net before it can establish the DoH connection. If bootstrap resolution also depends on that DoH server, which is not connected yet, a dependency loop results. To avoid this, default resolvers are usually configured as directly reachable DNS addresses in IP form.

These two fields are not equivalent to a “preferred DNS” and a “backup DNS.” Regular queries mainly use nameserver, while default-nameserver handles basic bootstrap work. If the primary upstream uses a plain IP address such as 223.5.5.5, the bootstrap stage is less visible. Once a DoH or DoT endpoint includes a hostname, the default resolver becomes more important.

dns:
  enable: true
  listen: 0.0.0.0: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

The example disables AAAA result handling, but this does not disable IPv6 support in the operating system or stop every application from sending AAAA queries. It means that the Clash DNS module will not provide IPv6 resolution results to callers under this configuration. If the network has a stable IPv6 exit and both rules and proxy nodes fully support IPv6, enable it later and validate direct and proxied paths separately.

When to use nameserver-policy

Newer cores such as Mihomo also provide nameserver-policy, which allows resolvers to be assigned by domain, rule set, or Geosite category. It is useful when different domains need different resolution paths—for example, sending local domains to the LAN DNS server and specific service domains to a designated DoH endpoint. When a policy matches, its resolver overrides the regular nameserver selection.

This field depends on core support and rule data. When migrating a configuration, verify the core version actually used by the client. If a rule set has not loaded, a category is unsupported, or the syntax belongs to another branch, the policy may not work as expected. Before the basic configuration is verified, avoid stacking too many domain-based DNS policies at once.

Proxy node hostnames also require resolution

If the proxy server address is a hostname, the core must resolve it before it can establish a connection to the node. proxy-server-nameserver in Mihomo configurations can handle these queries separately, preventing node-hostname resolution from depending on the regular application-query path. If resolving the node hostname requires accessing a remote DNS service through that same node, a circular dependency can occur during startup.

Similarly, cores that support direct-nameserver can assign a resolver to direct traffic. Whether these extended fields are needed depends on the size of the configuration and the network environment. For most beginner configurations, it is easier to make default-nameserver and nameserver work first, then separate node and direct-traffic resolution step by step.

fallback is more than a simple backup

fallback is often misunderstood as a backup server that activates only after nameserver times out. In the classic Clash DNS design, primary and fallback resolvers can be queried in parallel, after which fallback-filter determines whether to use the fallback result. Fallback is therefore closer to a second set of candidate resolution paths than to the sequential backup DNS behavior found in traditional network equipment.

Common filtering criteria include GeoIP, specified networks, and domain lists. When geoip: true is enabled with geoip-code: CN, the core can decide whether to use fallback candidates based on the region associated with the primary result. domain specifies domains that should always be evaluated by the fallback logic, while ipcidr can treat particular address ranges as conditions for switching results.

dns:
  enable: true
  enhanced-mode: fake-ip

  default-nameserver:
    - 223.5.5.5

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

  fallback:
    - https://1.1.1.1/dns-query
    - tls://8.8.4.4:853

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

This example illustrates result-filtering logic; it does not mean every network should copy it. Whether a remote DoH or DoT endpoint can connect also depends on routing, the proxy exit, certificate validation, system time, and protocol support in the core. If the fallback server itself is unreachable, adding more filter rules will not create a usable result.

Limits of GeoIP filtering

GeoIP decisions depend on database contents, while large websites frequently use CDNs, Anycast, and regional routing. The same domain may return different addresses in different regions, and an address's geographic label cannot fully show whether it is suitable for the current network. GeoIP is therefore useful as a filtering signal, not as an absolutely accurate availability test.

When the business requirement is clear, assigning resolution policies by domain is usually easier to explain than relying on broad GeoIP switching. For example, LAN domains can go to the router DNS, internal company domains to the corporate DNS, and a specified public service to a particular DoH endpoint. In such cases, consider nameserver-policy first instead of sending every query to two resolver groups and relying on geographic result filtering.

The role of DNS hijacking in TUN mode

Here, “DNS hijacking” means that the local proxy core actively takes over DNS requests entering the TUN interface; it does not mean modifying public DNS records. With TUN enabled, application traffic enters a virtual network interface. The dns-hijack setting can forward traditional DNS requests sent to specified addresses and ports to Clash's built-in DNS module. Even if the system still sends DNS requests to the router or another address, the core can then apply Fake IP, caching, and upstream selection consistently.

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

any:53 generally means taking over DNS traffic sent to any address on port 53. Support for UDP, TCP, and specific syntax varies across operating systems, core versions, and TUN stacks, so use the valid configuration generated by the client and the startup logs as the reference. If TUN is enabled without directing DNS requests to the built-in resolver, the system may continue using its original DNS path, causing Fake IP and domain-rule behavior to differ from expectations.

DNS hijacking cannot take over every encrypted DNS request

A browser or application may have built-in DoH and connect directly to its own resolver over HTTPS on port 443. At the network layer, this traffic looks like ordinary HTTPS, so port 53 hijacking will not automatically convert it into a Clash DNS query. DoT generally uses port 853 and is also outside the usual port 53 interception range. If a browser returns different results from the system, check whether the application has enabled its own secure DNS feature.

Even if an application's DoH traffic can be forwarded by proxy rules, the application-selected DoH service still performs the resolution rather than the nameserver configured in Clash. This can produce two outcomes: the application receives a real IP before connecting, or rules can match only against the destination IP. To create a unified DNS path, inspect the application settings, system DNS, and TUN interception scope together.

Filter LAN and special-use domains

In Fake IP mode, some local domains, device-discovery domains, NTP services, gaming-platform connections, and applications that require real addresses may need to be added to fake-ip-filter. Filtered domains generally return real resolution results instead of receiving Fake IPs. Add entries one at a time based on actual failures rather than excluding large groups of top-level domains, which would weaken the value of preserving domain mappings in Fake IP mode.

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

.local is commonly associated with mDNS device discovery, and the actual query may not use ordinary unicast DNS. Adding it to the filter list only prevents Fake IP assignment; it cannot replace multicast forwarding, system firewall settings, or device-discovery services on the LAN. When LAN devices cannot be reached, also check TUN routing, bypassed networks, and local-interface selection.

How DNS results affect proxy rule matching

Clash generally matches rules from top to bottom. Domain rules in DOMAIN, DOMAIN-SUFFIX, and RULE-SET can use the requested domain directly, while IP-CIDR and GEOIP rules require a destination address. If the connection entry point provides only an IP, whether the core can restore the domain depends on Fake IP mappings, protocol sniffing, and the connection method. One purpose of DNS configuration is to keep domain information available for rule matching during the connection stage.

The no-resolve parameter in a rule means that an IP-based rule should not trigger an additional DNS lookup to obtain an address. It can reduce unnecessary queries and avoid certain loops, but if the current connection has no destination IP, the rule may not make the intended determination. Before using it, check whether a domain rule already appears earlier and whether the connection entry point supplies a real destination address.

The exit used by DNS servers also matters. A DoH server is an HTTPS destination and is matched by Clash rules itself. If the configuration requires a particular DoH service to use a proxy, make sure the proxy node is reachable and avoid making node-hostname resolution depend on that not-yet-established DoH path. If local DNS should connect directly, verify that broad proxy rules will not incorrectly send its address to a proxy group.

Caches can make changes appear ineffective

DNS results may be cached simultaneously by the browser, operating system, Clash core, and upstream resolver. If an old address appears immediately after changing nameserver, that does not necessarily mean the configuration failed to load. First confirm that the client completed the configuration reload, then close existing connections in the affected application, clear the system DNS cache if necessary, and allow the upstream record's TTL effects to expire.

HTTP/2, HTTP/3, and connection pools can also reuse established connections. Even when a new DNS query returns a different address, the browser may continue using the old connection. During diagnosis, use a private window, fully exit the application, and compare the Clash connection list with log timestamps to determine whether the issue affects a new query or an old session.

Diagnose resolution failures along the processing path

DNS failures are best checked layer by layer from the entry point to the exit. Changing only one variable at a time prevents multiple configuration problems from becoming intertwined. The sequence below applies to common cases such as “a domain will not open but its IP connects,” “the system proxy works but TUN does not,” and “some applications fail after enabling Fake IP.”

  1. Confirm that the core accepted the configuration.

    Start by checking Clash Verge's configuration validation result and startup logs. YAML indentation errors, misspelled fields, or an option unsupported by the current core can prevent the DNS module from starting as expected. Confirm that the listen address, enhanced mode, and upstream servers loaded successfully.

  2. Confirm that queries reach Clash.

    The system proxy only handles traffic from applications that support proxy settings; it does not automatically take over every operating-system DNS request. If you rely on DNS hijacking, confirm that TUN is enabled, automatic routing works, and requests enter the virtual interface. If an application continues querying the system DNS directly after only the Clash nameserver was changed, the two results will remain different.

  3. Verify that the upstream can establish a connection.

    For traditional DNS, check UDP or TCP reachability on port 53. For DoH, check the HTTPS connection, certificate, and system time. For DoT, check port 853 and the TLS handshake. An upstream specified by hostname also requires verification that default-nameserver can complete bootstrap resolution.

  4. Check the result type.

    In Fake IP mode, seeing reserved addresses in the 198.18.0.0/16 range is usually expected and should not immediately be treated as a resolution error. The important checks are whether the subsequent connection enters Clash and whether the core can restore the original domain from the Fake IP.

  5. Review the rules and DNS exit.

    Check whether the resolver's domain or IP ultimately matches DIRECT or a proxy group. If a remote DoH service is assigned to an unavailable node, queries will time out. If an internal DNS server is sent through a public proxy, LAN domains may also fail to resolve.

  6. Simplify the configuration and restore features one by one.

    Temporarily keep one working nameserver, disable complex fallback filters and domain policies, and verify basic resolution. Then restore fallback, nameserver-policy, dedicated proxy-node DNS, and Fake IP filters in sequence, checking logs and query results after each change.

A simplified approach to choosing a configuration

  • For unified standard resolution, start with reliable default-nameserver and nameserver settings.
  • When domain mappings must be preserved with TUN, test fake-ip and DNS hijacking, then add filters for special domains.
  • When two sets of candidate results need filtering, add fallback and fallback-filter.
  • When resolvers must be assigned by business domain, first evaluate the nameserver-policy support provided by the core.
  • When proxy node addresses are hostnames and startup resolution is complex, configure a separate resolution path for node hostnames.

A stable Clash DNS configuration is not necessarily the one with the most fields. Each resolution path should have a clear source, exit, and usage condition. Establish a working base path first, then extend it for LAN access, IPv6, TUN, and specific application needs. When something fails, this makes it easier to determine whether the issue lies with system DNS, the Clash core, the upstream resolver, or the proxy rules.

Continue with Clash Verge installation

Open the download page to choose your system and architecture, or read the complete installation steps first.

Go to Downloads View Installation Guide
Download Clash