Clash YAML Configuration File Structure: A Complete Guide from Basic Fields to Rules

Read the Structure First: YAML Order Is Not the Same as Configuration Dependencies

Clash, Clash Meta, and the mihomo core that followed them typically use YAML files to define runtime settings. A complete configuration may include listening ports, operating mode, DNS, proxies, proxy groups, rule providers, rules, and traffic sniffing. YAML mappings do not use their written order to express processing priority, so placing rules near the top of a file does not make rules take effect before port settings.

For troubleshooting, it is still best to read the configuration by dependency: verify the basic listener and operating mode first, then DNS, followed by proxy sources and proxy group references, and finally how rules send requests to proxy groups. This is not the YAML parser’s mandatory load order; it is simply a more effective troubleshooting path.

1. Basic fields determine how the client listens for local traffic and whether it uses rule, global, or direct mode.
2. DNS fields determine where domain queries enter, which upstream servers handle them, and how Fake-IP mappings work.
3. proxies and proxy-providers supply usable proxy nodes.
4. proxy-groups organizes nodes or other proxy groups into selectable exits.
5. rule-providers supplies remote rule collections, while rules determines the final matching order.

Basic Fields: Ports, LAN Access, and Operating Mode

The basic section is usually placed at the top of the file so you can quickly see which entry points the client exposes. Some clients override part of this configuration through their graphical interface, so file values may not match the final runtime values. When troubleshooting, check both the configuration file and the client’s current status page.

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

mixed-port accepts both HTTP and SOCKS proxy connections, making it suitable when applications need a single local proxy port. Some configurations instead use separate port and socks-port entries. There is no need to expose multiple conflicting ports for the same entry point; if a port is already in use, the core may fail to start listening.

allow-lan controls whether devices on the local network can connect to the proxy port on this machine. When set to true, also check the system firewall and listening address. bind-address determines which network interfaces accept connections, but the exact behavior depends on the core version. If the proxy is for local use only, keeping LAN access disabled makes the entry point easier to control.

Common mode values are rule, global, and direct. Rule mode evaluates rules one by one; global mode sends traffic to the global proxy selection; direct mode bypasses the proxy. Switching modes in a graphical client often changes the runtime setting directly and may not write the change back to the subscription file.

DNS: Query Entry Points, Upstreams, and Fake-IP Mapping

DNS configuration is more than a simple list of server addresses. With the built-in DNS service enabled, the core must determine its listening entry point, resolution mode, default resolver, and actual upstream servers. When TUN is used to take over traffic, DNS hijacking and routing settings also determine whether requests enter the core.

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

default-nameserver is mainly used to resolve the hostnames of encrypted DNS upstreams and is typically set to directly reachable IP addresses. nameserver handles regular domain queries. Some mihomo configurations also use proxy-server-nameserver specifically for resolving proxy server hostnames, or nameserver-policy to select different upstreams for specific domains.

enhanced-mode: fake-ip assigns a virtual address to a domain first, then restores the domain information when the connection is made and applies the rules. This can reduce mismatches caused by applications resolving domains on their own. LAN hostnames, certain device-discovery protocols, some games, and domains that depend on real-address responses may need to be added to fake-ip-filter. Add exclusions for observed issues rather than broadly excluding large groups of domains.

Proxies and Proxy Groups: Define Members First, Then Build the Exit

proxies stores nodes written directly into the file. Each node generally includes a name, protocol type, server address, port, and the authentication parameters required by that protocol. Fields vary considerably between protocols, so parameters from one protocol cannot be copied directly to another. Nodes generated by subscription conversion tools should still be checked against the fields supported by the core.

proxies:
  - name: "Node A"
    type: socks5
    server: proxy.example.com
    port: 1080
    username: account
    password: passphrase
    udp: true

proxy-groups:
  - name: "Node Selection"
    type: select
    proxies:
      - "Auto Test"
      - "Node A"
      - DIRECT

  - name: "Auto Test"
    type: url-test
    proxies:
      - "Node A"
    url: https://www.gstatic.com/generate_204
    interval: 300

The name is the reference key. Node A in a proxy group must exactly match the node name, including spaces, capitalization, and full-width punctuation. A proxy group can also reference another proxy group, so you can create “Auto Test” first and then use it as a member of “Node Selection.” Circular references leave the core without a valid exit and require restructuring.

select lets the user choose a member manually; url-test automatically selects an available node with lower latency based on test results; fallback focuses on choosing the first available member in order; load-balance distributes connections across members according to its strategy. The latency-test URL is used only to measure availability and response time; it does not represent the actual speed to every destination.

DIRECT, REJECT, and similar values are built-in actions and do not need to be declared again in proxies. DIRECT means connect directly, while REJECT blocks the connection. Rules can target these actions directly, but routing commonly used exits through proxy groups usually makes switching them in the client easier.

Rules: Match from Top to Bottom; the First Match Wins

Unlike a top-level YAML mapping, rules is an ordered list. The core typically checks entries from the first one and stops after a match. Put specific rules before broad rules, and keep catch-all rules at the end. Moving MATCH upward makes later domain and IP rules ineffective.

rules:
  - DOMAIN,example.com,DIRECT
  - DOMAIN-SUFFIX,example.org,Node Selection
  - DOMAIN-KEYWORD,media,Node Selection
  - IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
  - GEOIP,CN,DIRECT
  - MATCH,Node Selection

DOMAIN matches an exact domain; DOMAIN-SUFFIX matches the specified domain and its subdomains; DOMAIN-KEYWORD matches by keyword and usually covers a broader range. IP-CIDR applies to a destination IP range. Adding no-resolve avoids triggering an extra DNS lookup just to evaluate the rule, but it can be evaluated directly only when the connection context already contains a destination IP.

GEOIP categorizes IP addresses using a geographical database. mihomo also supports GeoSite, rule sets, and additional rule types, but availability depends on the core version, database files, and configuration method. A rule target must be an existing proxy group, node name, or built-in action. If the log says a policy cannot be found, first check the rule target and the names under proxy-groups.

Rule mode only selects an exit; it does not automatically send all device traffic through Clash. The browser or operating system must use the system proxy, or traffic must be taken over by a TUN virtual interface. When rules appear not to work, first confirm that the connection appears in the client log. If the connection is completely absent, investigate the traffic entry point instead of continuing to reorder rules.

Remote Providers: proxy-providers and rule-providers

When there are many nodes, proxy-providers can load a node collection from a remote URL or local file, after which proxy groups reference it with use. Rule collections are defined by rule-providers and invoked in rules with RULE-SET. Their names are similar, but they provide different data types and cannot be interchanged.

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

proxy-groups:
  - name: "Subscription Nodes"
    type: select
    use:
      - provider-main

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

rules:
  - RULE-SET,private-network,DIRECT
  - MATCH,Subscription Nodes

path is the local storage location for downloaded remote content. The runtime environment must allow the core to write to that directory. interval is usually measured in seconds and specifies the update interval; the health-check interval and subscription update interval are separate settings. A health check tests existing nodes only and does not replace subscription updates.

A rule provider’s behavior must match the structure of its content, such as a domain collection, IP-range collection, or classical rule format. Support for format, binary rule sets, and behavior types may vary between mihomo versions. When remote rules fail to load, check the download status, file format, and parse errors in the log—not just whether the URL opens in a browser.

Indentation, Quoting, and YAML Types: The Most Common Parsing Boundaries

YAML uses indentation to express hierarchy. Use spaces consistently and never mix in tabs. Keep the indentation level consistent for sibling fields, and use hyphens for list items. The following two sections may look similar, but in the second one enable is outside dns, which changes its meaning.

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

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

Text containing colons, hash signs, leading or trailing spaces, or values that may be interpreted as booleans should be quoted. Node and proxy group names may contain Chinese characters as long as they remain consistent. Ports should be numbers, and switches should be written as true or false; do not quote every value as a string. Some fields accept string forms, but compatibility should be determined from the core documentation and error logs.

YAML anchors and aliases can reduce duplicated configuration, but after a complex subscription passes through client overrides, format conversion, or re-exporting, anchor structures may be expanded. They can be useful when maintaining a file by hand, but when a subscription frequently passes through a conversion pipeline, writing critical fields explicitly is easier to troubleshoot.

Field Overrides and a Complete Verification Checklist

The runtime configuration may come from several layers: the original remote subscription, local client overrides, temporary selections made in the interface, and core startup parameters. The final effective value depends on how the client merges these sources. When the same field is defined more than once, do not infer the result from file position alone; inspect the final configuration generated by the client or its runtime status.

A proxy group’s current selection is usually stored by the client or in the core cache. After a subscription update, the previous selection may remain as long as the group name and member relationships are still valid. If a node is renamed or removed, the client may fall back to another member in the group. Updated rules do not prove that nodes are usable, and a successful node health check does not prove that rule targets are correct.

1. Validate YAML syntax: Check indentation, colons, list markers, and matching quotes to eliminate parse errors first.
2. Check the local entry point: Verify mixed-port, the system proxy, or TUN status, and watch whether the target connection appears in the log.
3. Check the DNS path: Confirm that queries are received by the core, the upstream is reachable, and the Fake-IP exclusions are appropriate.
4. Check the proxy source: Confirm that static nodes or proxy providers load successfully and that proxy server hostnames resolve.
5. Check name references: Trace each rule target to its proxy group, then trace the group to a node or provider.
6. Check rule order: Put specific rules first, broad rules later, and keep an explicit catch-all at the end.
7. Check runtime overrides: Confirm that the mode, port, and proxy selection in the client interface have not overridden the expected configuration.

A configuration is complete only when it can load, take over traffic, resolve DNS, and select a route. When troubleshooting, verify each stage in order—“entry point → DNS → proxy → proxy group → rule → exit”—instead of changing several fields at once. Adjust one layer at a time and use logs to verify the result, keeping syntax, network, and rule issues from interfering with one another.