Advanced 13-minute read

Clash YAML Configuration Explained: Every Section and Key

A field-by-field guide to Clash YAML configuration, from port, mode, and DNS to proxies, proxy-groups, and rules, including valid values and common errors.

Clash configuration files are usually written in YAML. They keep the listening port, operating mode, DNS, proxy nodes, proxy groups, and routing rules in one document. Key order generally does not affect how the core reads the file, but writing sections in the order “basic settings → DNS → nodes → proxy groups → rules” makes references and indentation errors easier to trace.

This guide uses the common Clash for Windows 0.20.39 configuration structure and the configuration semantics of the mihomo v1.19 series as references. Supported protocols, TUN options, and DNS extensions vary between cores. Before editing a subscription-generated configuration, save a local copy so the next subscription update does not overwrite your changes.

YAML Syntax and Top-Level Structure

Indentation, Lists, and Key-Value Pairs

YAML uses spaces to express nesting; Tabs cannot be used for indentation. Two spaces per level is a common convention. Leave one space after a colon, and begin list items with a hyphen. Nodes, proxy groups, and rules belong under different top-level keys, and a one-level indentation error can prevent the entire file from loading.

port: 7890
mode: rule

proxies:
  - name: "Example Node"
    type: ss
    server: 203.0.113.10
    port: 443

proxy-groups:
  - name: "Node Selection"
    type: select
    proxies:
      - "Example Node"
      - DIRECT

rules:
  - MATCH,Node Selection

port: 7890 is a key-value pair; proxies: is followed by a list; every item beginning with - name: is a node object. Names containing colons, hash signs, asterisks, or strings that could be interpreted as Boolean values should preferably be quoted. For example, writing the node name as "HK: 01" prevents the colon from being treated as a mapping separator.

Common Parsing Errors

Port, LAN Access, and Operating Mode

The file usually begins with inbound listeners and basic runtime settings. The example assigns separate ports to HTTP, SOCKS5, and mixed proxy access. You do not need all three enabled in practice; desktop clients most commonly use mixed-port.

port: 7890
socks-port: 7891
mixed-port: 7892
allow-lan: false
bind-address: "*"
mode: rule
log-level: info
ipv6: false
external-controller: 127.0.0.1:9090
secret: "change-this-controller-secret"

How the Three Proxy Ports Differ

The same IP address and port cannot be listened to by two programs at once. If the log shows address already in use or bind: Only one usage of each socket address, first check whether an old Clash process, another proxy tool, or a local development service is using the port. On Windows, run netstat -ano | findstr :7890 in a terminal to find the associated PID.

allow-lan and bind-address

allow-lan: false means the proxy is not exposed to devices on the local network. After changing it to true, a phone or another computer can use this computer’s LAN address as its proxy server, for example 192.168.1.20:7890. You must also allow the port through Windows Firewall.

bind-address determines the listening address. For local-only use, binding to 127.0.0.1 is more explicit; for LAN access, use * or a specific adapter address if supported by the core. Changing only allow-lan does not guarantee that other devices can connect; the firewall, guest-network isolation, and router AP isolation can also block access.

mode, log-level, and the Control Port

DNS: Listeners, Resolvers, and Enhanced Modes

The DNS section determines how domain names are resolved. It affects both rule matching and domain interception in TUN mode. A common basic structure looks like this:

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"
    - "+.msftconnecttest.com"
  default-nameserver:
    - 223.5.5.5
    - 1.1.1.1
  nameserver:
    - https://dns.alidns.com/dns-query
    - tls://1.1.1.1:853
  fallback:
    - https://dns.google/dns-query
  fallback-filter:
    geoip: true
    geoip-code: CN

enable, listen, and default-nameserver

enable controls the built-in DNS module. listen is the address where the DNS service listens; the example uses local UDP/TCP port 1053. If another local DNS service already occupies the port, the log will report a listening failure.

default-nameserver is mainly used to resolve the hostnames of upstream servers such as DoH and DoT endpoints; it is also called bootstrap DNS. To avoid circular dependencies, use directly reachable IP addresses here rather than another hostname that must itself be resolved first.

nameserver, fallback, and Policy-Based Resolution

nameserver is the primary resolver and can be a regular DNS address or a DoH or DoT endpoint. fallback and fallback-filter are common in classic Clash configurations. mihomo also supports more granular keys such as nameserver-policy, proxy-server-nameserver, and direct-nameserver, allowing different upstreams for domain rules or proxy-node resolution.

Do not assume that writing multiple DNS servers means every request will use all of their answers at once. The core selects a resolution path based on field semantics, filters, and responses. When a domain resolves but the site will not open, check the DNS log, matched rule, and node connection together rather than relying only on the browser error.

fake-ip and redir-host

proxies: Individual Proxy Nodes

proxies stores manually defined nodes. Subscriptions usually generate this section automatically. Fields vary by protocol, but every node needs at least a unique name, protocol type, server address, and port.

proxies:
  - name: "SS-HK-01"
    type: ss
    server: hk.example.net
    port: 443
    cipher: aes-128-gcm
    password: "example-password"
    udp: true

  - name: "VMess-JP-01"
    type: vmess
    server: jp.example.net
    port: 443
    uuid: 11111111-2222-3333-4444-555555555555
    alterId: 0
    cipher: auto
    tls: true
    servername: jp.example.net
    network: ws
    ws-opts:
      path: /gateway
      headers:
        Host: jp.example.net

Common and Protocol-Specific Fields

A node appearing in the list only means that the YAML was parsed; it does not confirm that the connection parameters are correct. Incorrect credentials often appear as a handshake failure; an unresolvable server address produces a DNS error; a mismatched WebSocket path or Host header typically causes an immediate disconnect after the connection is established. During troubleshooting, open “Logs” in the client, temporarily set the level to debug, and run a latency test against one node.

proxy-providers and proxy-groups

Node Providers: proxy-providers

proxy-providers can load a group of nodes from a local file or remote URL. Compared with placing every node directly in proxies, providers make it easier to manage the node source separately from the proxy-group structure.

proxy-providers:
  provider-main:
    type: http
    url: "https://example.com/subscription"
    path: ./providers/provider-main.yaml
    interval: 3600
    health-check:
      enable: true
      interval: 600
      url: https://www.gstatic.com/generate_204

interval: 3600 checks for updates every 3,600 seconds; a health check with interval: 600 runs once every 10 minutes. If a provider download fails, check that the subscription URL is reachable, the system time is correct, the proxy startup sequence has no circular dependency, and the save path is writable.

Proxy-Group Types and References

proxy-groups:
  - name: "Node Selection"
    type: select
    proxies:
      - "Auto Select"
      - "Failover"
      - DIRECT
    use:
      - provider-main

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

  - name: "Failover"
    type: fallback
    use:
      - provider-main
    url: https://www.gstatic.com/generate_204
    interval: 300

tolerance: 80 means an auto-select group does not switch unnecessarily when the latency difference is within 80 ms. A value that is too small can cause repeated changes during minor network fluctuations; a value that is too large can keep a noticeably slower node. For home broadband, start by trying 50–100 ms.

rules and rule-providers: Rule-Matching Order

rules determines which proxy group handles a connection. Rules are matched from top to bottom, and matching stops at the first hit. More specific rules should therefore usually come first, with the catch-all rule at the end.

rules:
  - DOMAIN,api.example.com,Node Selection
  - DOMAIN-SUFFIX,example.net,Node Selection
  - DOMAIN-KEYWORD,stream,Auto Select
  - IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
  - IP-CIDR,10.0.0.0/8,DIRECT,no-resolve
  - GEOIP,CN,DIRECT
  - MATCH,Node Selection

Common Rule Types

no-resolve prevents some IP rules from triggering an extra domain lookup solely for matching. It is not a universal suffix required by every rule. If MATCH is placed on the first line, later rules can never match; if a rule references a nonexistent proxy group, loading may fail immediately or connection handling may report that the policy cannot be found.

Rule Providers: rule-providers

rule-providers:
  private-network:
    type: http
    behavior: ipcidr
    format: yaml
    url: "https://example.com/rules/private-network.yaml"
    path: ./ruleset/private-network.yaml
    interval: 86400

rules:
  - RULE-SET,private-network,DIRECT
  - MATCH,Node Selection

behavior must match the contents of the rule set. Common values include domain, ipcidr, and classical. Declaring a domain rule set as ipcidr prevents it from being parsed correctly. mihomo rule sets also use format; specify the corresponding value when the remote file is YAML, text, or binary.

TUN and Transparent-Proxy Settings

TUN mode creates a virtual network interface to take over traffic from applications without their own proxy settings. It is a separate entry point from the system proxy. A common mihomo configuration looks like this:

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

After enabling TUN, if “the browser works but games lose network access” or “LAN devices cannot be reached,” check permissions, the routing table, DNS interception, direct rules for local subnets, and other VPNs in that order. Do not enable multiple network tools that create default routes. On Windows, run route print to inspect the default route and interface priority.

A Readable Minimal Configuration and Troubleshooting Flow

The structure below omits real credentials but preserves the complete reference chain from the entry point to the rules. When checking the configuration, trace backward from the proxy group on the last line: the rule references “Node Selection,” “Node Selection” references “Example Node,” and “Example Node” contains the server parameters.

mixed-port: 7890
allow-lan: false
mode: rule
log-level: info
ipv6: false

dns:
  enable: true
  listen: 127.0.0.1:1053
  enhanced-mode: fake-ip
  fake-ip-range: 198.18.0.1/16
  default-nameserver:
    - 223.5.5.5
  nameserver:
    - https://dns.alidns.com/dns-query

proxies:
  - name: "Example Node"
    type: ss
    server: 203.0.113.10
    port: 443
    cipher: aes-128-gcm
    password: "replace-with-valid-password"
    udp: true

proxy-groups:
  - name: "Node Selection"
    type: select
    proxies:
      - "Example Node"
      - DIRECT

rules:
  - IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
  - GEOIP,CN,DIRECT
  - MATCH,Node Selection

Check Each Layer by Error Type

  1. File will not load: Check Tabs, indentation, colons, quotes, and duplicate keys first. Do not test nodes yet, because the core has not successfully read the configuration.
  2. Configuration loads but the proxy group is empty: Check whether proxies contains nodes, whether the provider name in use is correct, and whether the provider file downloaded successfully.
  3. Node test fails: Check server, port, authentication fields, TLS name, and transport settings, then verify that the server hostname resolves.
  4. Only some websites will not open: Check the matched rule, destination domain, proxy group, and actual node in the connection log. Confirm that rule order has not sent the traffic prematurely to DIRECT or REJECT.
  5. System proxy works but other programs bypass it: Confirm whether the program follows the system proxy. If it does not, evaluate TUN rather than hiding the entry-point problem by repeatedly adding broad rules.
  6. Changes disappear after a subscription update: Move local DNS, TUN, or rule changes into an override or merged configuration supported by the client.

Compatibility and Maintenance

The Clash core configuration used by Clash for Windows 0.20.39 is not fully equivalent to the continuously updated mihomo configuration. Newer subscriptions may contain protocols, rule-set formats, or DNS fields that the older core does not recognize. For errors such as field not found or unsupported proxy type, first confirm which core and version the client actually invokes instead of relying only on the interface name.

For routine maintenance, divide the configuration into three areas: the subscription manages nodes, rule providers manage updateable rule sets, and local overrides manage ports, DNS, and TUN. This reduces manual merging and keeps problems in clearly defined areas. Change one topic at a time—for example, edit DNS and reload it first, then enable TUN after resolution works normally.

The core relationships in a configuration are straightforward: inbound ports receive traffic, DNS supplies domain information, rules choose a proxy group, the proxy group selects a node, and the node establishes the remote connection. Following this chain is more effective for finding a specific field than repeatedly switching nodes or replacing the entire YAML file at once.

View Client Downloads