Configuration 12 min read

Clash Configuration File Explained: Ports, DNS, Rules, and More

A YAML walkthrough of common fields, showing how proxies, proxy groups, and rules reference one another.

Understand Clash’s configuration flow first

Clash, Clash Meta (now commonly called Mihomo), and its graphical clients typically use YAML files to describe runtime settings. Although a configuration may look like a collection of independent fields, it actually forms a continuous flow: application traffic enters through a local listening port or TUN interface, domain requests are handled by the DNS module, and connections are then matched against rules from top to bottom. The matched rule passes the connection to a proxy group, which selects a specific proxy node, a direct connection, or a reject action.

When reading a configuration, do not focus only on whether an individual node connects. A complete configuration should answer five questions: Where does traffic enter? How are domains resolved? Which exits are available? How are those exits organized into proxy groups? Which rule makes the final routing decision? A naming error at any stage can appear as a failed configuration load, an empty proxy group, DNS resolution failure, or traffic leaving through the wrong exit.

YAML is sensitive to indentation. Two spaces are typically used for each nesting level, and tabs must not be used in place of spaces. Keys at the same level must line up, while list items begin with a hyphen. Use true and false for Boolean values. Names containing colons, hash signs, asterisks, or other special characters should be quoted so the parser does not interpret them as YAML syntax.

Core fields and local listening ports

The top level of a configuration usually starts with ports, LAN access, the operating mode, and the log level. These fields determine how Clash accepts connections from the local machine or devices on the LAN, but they do not directly decide which proxy node a connection uses.

mixed-port: 7890
allow-lan: false
bind-address: "*"
mode: rule
log-level: info
ipv6: false

external-controller: 127.0.0.1:9090
secret: "change-this-controller-secret"

port, socks-port, and mixed-port

port provides an HTTP proxy listening port, socks-port provides a SOCKS5 proxy listening port, and mixed-port accepts both HTTP and SOCKS5 requests on the same port. Desktop clients often use a mixed port to simplify system proxy settings. If multiple ports are declared, check that none is already in use and confirm which port the system proxy actually targets.

redir-port and tproxy-port are mainly used for transparent proxying. They depend on the operating system’s network stack, routing rules, and permissions, and are not supported identically on every platform. Desktop users who route traffic through the system proxy or a client’s TUN switch usually do not need to add these fields manually.

LAN access and the control interface

allow-lan controls whether other devices can use the proxy through the local listening port. After enabling it, also check bind-address, the operating system firewall, and network connectivity between devices. Keep it disabled for local-only use. If phones or tablets on the same LAN need access, restrict the trusted network range and avoid exposing the listening port to the public internet.

external-controller is the control interface address. A graphical interface or external dashboard can use it to read connection, traffic, and proxy-group status. When it listens on 127.0.0.1, only the local machine can access it; if changed to a LAN address, also set a sufficiently strong secret and define network access boundaries. The control-interface port serves a different purpose from the proxy port, so the system proxy must not point to it.

Operating modes and logging

mode: rule routes traffic according to rules and is the most common mode for everyday configurations. global sends all connections to the global proxy group, while direct connects directly. Switching between “Rule,” “Global,” and “Direct” in a graphical client usually changes the current runtime mode, but may not rewrite the original YAML file.

log-level can be set to levels such as silent, error, warning, info, or debug; supported values depend on the core version in use. Temporarily increase log verbosity when investigating rule matches or DNS requests, then restore the normal level after confirming the issue to keep logs manageable.

The DNS section: resolution paths and Fake IP

The dns section determines whether Clash handles domain resolution, which upstream servers it queries, and whether it returns real addresses or Fake IPs. DNS settings are closely tied to proxy rules: a rule may need the original domain for matching, while a proxy node’s server address may need to be resolved first. An incorrect upstream setting can therefore make a node fail before the proxy connection is established.

dns:
  enable: true
  listen: 127.0.0.1:1053
  ipv6: false
  enhanced-mode: fake-ip
  fake-ip-range: 198.18.0.1/16
  fake-ip-filter:
    - "*.lan"
    - "localhost.ptlogin2.qq.com"
  default-nameserver:
    - 223.5.5.5
    - 1.1.1.1
  nameserver:
    - https://dns.alidns.com/dns-query
    - https://1.1.1.1/dns-query
  nameserver-policy:
    "geosite:cn":
      - https://dns.alidns.com/dns-query

enable, listen, and upstream servers

enable: true turns on the core DNS module. listen specifies the address on which the DNS service listens; whether it needs to be set depends on how the client takes over DNS queries, and some graphical clients generate or override it. Before listening on a non-local address, understand how this changes the scope of LAN DNS exposure.

default-nameserver is mainly used to resolve the hostnames of encrypted DNS servers such as DoH and DoT, and may also participate in the initial resolution of proxy-node hostnames. It is therefore usually set to directly reachable, IP-based DNS servers. nameserver lists the main upstreams for regular queries and can use standard DNS addresses or encrypted DNS formats supported by the core. Support for extended parameters and protocol syntax may differ between Mihomo versions, so check the core documentation and startup logs when migrating a configuration.

nameserver-policy assigns DNS upstreams by domain or rule set, such as sending selected domains to a specific resolver. It answers “which DNS server should handle the query,” not “which exit should carry the connection” in a proxy rule. DNS query paths and subsequent connection paths must be configured separately.

fake-ip and redir-host

Fake IP mode first returns a temporary address from a reserved range to the application, then maps that address back to the original domain when the application connects. This helps the core preserve domain information more reliably for DOMAIN, DOMAIN-SUFFIX, and GeoSite rules. In TUN setups, Fake IP is also commonly used to take over DNS and connections consistently across different applications.

Some LAN services, game platforms, printers, and applications that depend on real DNS results may not work well with Fake IP. Add such domains to fake-ip-filter so they receive real resolution results. Do not expand the filter indiscriminately: excluding too many domains from Fake IP mapping reduces the visibility of domain-based rules. redir-host returns real IP addresses and is more straightforward for compatibility, but rule matching can still be affected by DNS caching, connection methods, and application behavior.

Proxy nodes and proxy providers

proxies is a static list of nodes. Each entry describes a proxy exit that proxy groups can reference. Common fields include the node name, protocol type, server address, server port, and protocol-specific authentication parameters. Different protocols require different fields; changing only type cannot convert one kind of node into another.

proxies:
  - name: "Example Node A"
    type: socks5
    server: 192.0.2.10
    port: 1080
    username: "example-user"
    password: "example-password"
    udp: true

name is the node’s reference identifier inside the configuration. Names used in proxy groups must match it exactly, including spaces, capitalization, and symbols. Duplicate node names may be rejected by some cores or clients, or make references difficult to resolve, so keep every name unique.

Subscriptions often contain many nodes, which becomes difficult to maintain when expanded directly under proxies. Mihomo supports proxy-providers, allowing a provider to read local files or remote content and pass the resulting node set to proxy groups. Providers commonly include type, url, path, an update interval, and health-check settings. A subscription URL is an access credential; do not put it in a public repository, screenshot, or public log.

proxy-providers:
  provider-main:
    type: http
    url: "Complete URL provided by the subscription service"
    path: ./providers/provider-main.yaml
    interval: 86400
    health-check:
      enable: true
      interval: 600
      url: https://www.gstatic.com/generate_204

A provider’s health check periodically tests node connectivity; it does not mean the proxy group automatically selects the lowest-latency node. Automatic selection depends on the proxy-group type. The health-check URL only reflects the response from that target, and latency can also be affected by the target server, DNS, network congestion, and the node’s egress location.

Proxy groups: organize nodes into reusable exits

proxy-groups sits between nodes and rules. Rules generally point to a stable proxy-group name instead of a frequently changing node. When nodes are updated or become unavailable, you can switch the group’s selection in the client without rewriting the entire rule set.

proxy-groups:
  - name: "Proxy Selection"
    type: select
    use:
      - provider-main
    proxies:
      - DIRECT

  - name: "Auto Test"
    type: url-test
    use:
      - provider-main
    url: https://www.gstatic.com/generate_204
    interval: 300
    tolerance: 80

  - name: "Default Exit"
    type: select
    proxies:
      - "Proxy Selection"
      - "Auto Test"
      - DIRECT

Common proxy-group types

  • select: Lets the user manually choose a node, another proxy group, or a built-in action from the group. Suitable for the main entry point and services that need a fixed exit.
  • url-test: Periodically measures latency against a specified test URL and automatically selects a qualifying low-latency node. It reflects probe results and does not mean every type of traffic will have the same speed.
  • fallback: Uses the first available node in the list and switches to the next one when the current node becomes unavailable. Suitable when a fixed priority order matters.
  • load-balance: Distributes connections across multiple nodes according to the strategy supported by the core. It does not simply combine bandwidth for a single TCP connection, and frequently changing egress addresses may affect services that depend on session or address consistency.

proxies lists static nodes, other proxy groups, and built-in actions such as DIRECT and REJECT; use references proxy-providers. Both can be combined in the same proxy group as needed. A proxy group can also reference another proxy group, but avoid circular references—for example, A referencing B while B references A—which causes configuration validation to fail.

Group names are strict references too. If a rule contains Default Exit, the configuration must contain a proxy group, node, or built-in policy with exactly that name. After renaming a proxy group, search for and update references in rules, other proxy groups, and override scripts.

The rules section: ordered matching determines the final exit

rules is the decision table for routing connections. The core generally checks rules from the top, stops at the first match, and sends the connection to the policy specified at the end of that rule. Order therefore matters more than the number of rules: narrower, higher-priority rules should come first, followed by general and catch-all rules.

rules:
  - DOMAIN,example.org,DIRECT
  - DOMAIN-SUFFIX,example.com,Proxy Selection
  - DOMAIN-KEYWORD,service,Default Exit
  - IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
  - GEOIP,CN,DIRECT
  - MATCH,Default Exit

Common rule types

DOMAIN exactly matches a complete domain; DOMAIN-SUFFIX matches the specified domain and its subdomains; DOMAIN-KEYWORD matches keywords within a domain and has a broader scope, so watch for unintended matches. IP-CIDR and IP-CIDR6 match target IP ranges and are useful for LANs, fixed service addresses, and clearly defined network ranges.

GEOIP matches target addresses using an IP geolocation database. Mihomo can also process bulk domains through GeoSite or rule sets, depending on the core version and configuration method. Geographic rules rely on a local database; a missing database, incorrect path, or incompatible format will be reported during loading or in the runtime logs.

no-resolve is commonly used with IP rules to prevent an extra DNS lookup for a domain when evaluating the rule. This can reduce unnecessary resolution, but if the current connection has only a domain and no target IP available for matching, the IP rule may not match. Whether to add it depends on the DNS mode and the purpose of the rule.

MATCH is the final catch-all and should be placed at the end of the rule list. It handles connections that matched nothing earlier. Without a sensible fallback, different core versions or client-generated logic may produce unexpected results; in a hand-written configuration, explicitly adding MATCH makes the default exit clear.

Rule providers and large rule sets

When there are many rules, use rule-providers to split rule sets into separate files and reference them with RULE-SET. A rule provider usually declares its behavior type, source, storage path, update interval, and format. The reference name must match the provider key, and the rule-set content must conform to behavior.

rule-providers:
  private-network:
    type: http
    behavior: ipcidr
    format: yaml
    path: ./rules/private-network.yaml
    url: "Complete URL provided by the rule maintainer"
    interval: 86400

rules:
  - RULE-SET,private-network,DIRECT
  - MATCH,Default Exit

A successful rule-set update does not mean the order is correct. If a broader rule appears before RULE-SET, a connection may match it first and the later rule set will never take effect. When troubleshooting, inspect the rule type, matched content, and final policy in the connection details instead of checking only whether the rule file downloaded.

How TUN mode relates to the traffic entry point

The system proxy affects only applications that follow the operating system’s proxy settings. Terminal tools, games, virtual machines, and applications with their own network stack may ignore it. TUN mode uses a virtual network interface to take over a broader range of IP traffic, then sends connections through Clash’s DNS, rules, and proxy-group chain.

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

auto-route lets the core try to configure routes automatically, auto-detect-interface identifies the default outbound interface, and dns-hijack hands specified DNS traffic to the core. Available stack values and defaults vary by core and platform; common implementations include system, gVisor, and mixed. Graphical clients generally provide suitable defaults for the operating system, so avoid switching these options frequently unless investigating a compatibility issue.

When TUN startup fails, check client permissions, the virtual network interface, other VPN or network-filtering software, the routing table, and DNS interception conflicts in that order. If some applications still connect directly with TUN enabled, also check route exclusions, interface selection, and whether the application uses its own VPN. TUN sends traffic into the core; rules and proxy groups still decide whether the final route is direct or proxied.

Troubleshooting order for load failures and ineffective rules

  1. Check YAML syntax first. Verify indentation, spaces after colons, list hyphens, and closed quotes. The line reported by the parser is sometimes only where the error was detected; the actual problem may be several lines earlier.
  2. Next, check name references. Verify the policy name at the end of each rule, node names in proxy groups, the proxy provider referenced by use, and the rule provider referenced by RULE-SET.
  3. Confirm remote resource status. Check whether subscriptions, proxy providers, and rule providers updated successfully, whether their storage directories are writable, and whether the remote content uses a format supported by the core.
  4. Verify the traffic entry point. The system proxy port must match the active listening port. With TUN, confirm that the virtual interface and routes are established. For LAN devices, also check the listening address and firewall.
  5. Review DNS and rule logs. First determine whether the domain resolved successfully, then confirm which rule matched, which proxy group handled the connection, and which node was ultimately selected.
  6. Reduce the configuration scope. Temporarily keep one working node, one manual proxy group, and a small number of rules. Once the basic path is verified, restore DNS policies, rule sets, and automatic testing step by step.

A maintainable Clash configuration keeps its references clear: ports and TUN receive traffic, DNS resolves domains, nodes and proxy providers supply exits, proxy groups organize those exits, and rules select the policy. Validate each layer along this chain when making changes; it is easier to locate problems than when changing the core, subscription, DNS, and rule sets all at once.

Download Clash