Configuration 14 min read

How to Read a Clash YAML Configuration: From Port Settings to Proxy Groups

Follow the configuration from top to bottom, covering general settings, proxy nodes, proxy groups, rule providers, and DNS, with a clear look at how fields reference one another.

YAML Structure

Understand YAML hierarchy and data types first

Clash configuration files typically use YAML. When reading one, do not just search for a node name; first examine the parent-child relationships expressed by indentation. Top-level fields are usually major configuration sections, such as proxies, proxy-groups, rules, and dns; indented fields belong to the object above them. List items begin with a hyphen, and items at the same indentation level are siblings.

mode: rule
log-level: info

proxies:
  - name: "Example Node"
    type: ss
    server: example.com
    port: 443

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

This configuration contains two scalar fields, a node list, and a proxy-group list. name, type, and server all belong to the same node object in the list; proxies in the proxy group is a list of names, and “Example Node” must match a definition elsewhere.

YAML is indentation-sensitive, so use spaces consistently and avoid tabs. Names containing colons, hash signs, special characters, or values that could be interpreted as booleans can be enclosed in quotes. Comments begin with #; they provide context only and do not affect core operation. Field names must use syntax supported by the core. Changing a display name does not change its meaning, but it does affect name references.

General Settings

General settings, operating mode, and listening ports

The beginning of a file commonly contains ports, LAN access, operating mode, log level, and the controller interface. These fields determine how the program receives traffic and how the client connects to the core, but they do not decide which node a particular domain ultimately uses.

mixed-port: 7890
allow-lan: false
mode: rule
log-level: info
ipv6: false
external-controller: 127.0.0.1:9090
secret: "Set a dedicated controller secret"

How to tell the port fields apart

  • port usually specifies the HTTP proxy listening port.
  • socks-port specifies the SOCKS5 proxy listening port.
  • mixed-port accepts both HTTP and SOCKS traffic on one port, a common choice for desktop clients.
  • redir-port and tproxy-port are intended for specific transparent-proxy setups; whether they work depends on the operating system and network rules.

Multiple listening ports must not conflict with ports already occupied by other programs on the host. Desktop clients often manage ports in their own settings, so after editing subscription-generated YAML, check whether the client is overriding your changes.

mode: rule matches rules from top to bottom; global generally sends all traffic through the global policy; direct connects directly. The “Rule,” “Global,” and “Direct” switches in a client interface may change the mode at runtime without writing the change back to the original subscription file.

allow-lan controls whether LAN devices can access the listening port. When enabled, also restrict access with bind-address, the system firewall, and the actual network boundary. external-controller is the controller interface address, which graphical clients use to read connection, policy, and log status. If the interface must be reachable from outside the local machine, set secret and limit its reachable scope.

Proxy Sources

Proxy nodes and proxy providers

proxies stores static node definitions. Each node needs at least a unique name, protocol type, server address, port, and the authentication fields required by that protocol. Parameters cannot be mixed between protocols: Shadowsocks commonly uses cipher and password, Trojan commonly uses a password and TLS-related settings, while VMess and VLESS each have their own identity, transport, and encryption fields.

proxies:
  - name: "Tokyo-A"
    type: trojan
    server: edge.example.com
    port: 443
    password: "example-password"
    sni: edge.example.com
    udp: true

server is the connection target, while sni is the server name used during the TLS handshake. They may be identical, or the service configuration may specify them separately. Do not swap or remove TLS fields just because a connection fails. Use a valid configuration from the subscription provider and the current mihomo documentation as the reference.

When there are many nodes, configurations often use proxy-providers to import an external node collection. A provider reads nodes from a specified source and updates them on a schedule; a proxy group then references it through use. This separates where nodes come from from how they are selected.

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

primary is the provider key that proxy groups will reference. path specifies the local cache location, and interval sets the update interval. Health checks test connectivity or latency under specified conditions; they do not guarantee that real-world websites will work or automatically fix authentication parameters.

Policy Groups

How proxy groups connect nodes and rules

proxy-groups is the configuration’s dispatch layer. Rules usually hand traffic to a proxy group rather than naming a server address directly; the group then selects a node, built-in policy, or another proxy group. Understanding this layer explains why the client interface can show several levels of selection.

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

  - name: "Auto Select"
    type: url-test
    use:
      - primary
    url: "https://www.gstatic.com/generate_204"
    interval: 300

  - name: "Media Services"
    type: select
    proxies:
      - "Node Selection"
      - DIRECT

The first group uses select, letting the user choose a member in the interface. The second uses url-test to select from the nodes in provider primary based on test results. The third does not list servers directly; it references “Node Selection,” so it follows that reference to the final egress.

proxies lists static nodes, built-in policies, or other proxy groups; use references proxy-providers. Both can provide group members, but they refer to different object types. A common mistake is putting a provider name in proxies or a node name in use.

Common proxy-group types

select
Provides a manual selection point, suitable for the primary egress, application categories, and scenarios requiring a fixed policy.
url-test
Tests members at the specified URL and interval, usually selecting the node with the best test result.
fallback
Checks availability in member order and switches to the next member when the current one is unavailable.
load-balance
Distributes connections among members according to the configured strategy; suitability depends on the behavior of the application sessions.

DIRECT, REJECT, and similar entries are built-in policies and do not need to be defined in proxies. Custom names must match exactly, including capitalization, spaces, and symbols. Proxy groups can be nested, but they must not form circular references; otherwise the core cannot determine a clear egress.

Routing Rules

Rule matching order and rule-set references

rules determines which policy receives traffic. In rule mode, the core normally checks entries from top to bottom and stops after the first match. Put specific domains and explicit network ranges before broader rules, and place the fallback rule at the end.

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

DOMAIN matches a complete domain name, while DOMAIN-SUFFIX matches the specified domain and its subdomains. DOMAIN-KEYWORD matches keywords in the domain. IP-CIDR evaluates the destination against an IPv4 network range; IPv6 uses the corresponding IPv6 rule type. GEOIP relies on a geographic database to determine an IP address’s region. MATCH is the final fallback and should be placed at the end of the rules.

The final item in a rule is usually the target policy name, such as “Node Selection,” “Media Services,” DIRECT, or REJECT. If that name does not exist in proxy-groups, the configuration may fail during loading or behave unexpectedly even when the rule syntax looks complete.

Large rule collections can be placed in rule-providers. A rule provider defines the source, cache path, behavior type, and update interval; the main rules section invokes it with RULE-SET.

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

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

behavior describes the matching format of a rule set. Common values include domain, ipcidr, and classical. The actual rule file must match the declared behavior. classical can contain fuller classic rule expressions, while domain and ipcidr focus on collections of their respective data types.

DNS Pipeline

How the DNS section participates in name resolution

DNS configuration is more than entering two server addresses. It affects how names are resolved, how rules associate domains with IP addresses, and whether traffic can reliably enter the core in TUN mode. Common mihomo fields include enabled state, listening address, resolution mode, default resolver, primary resolver, fallback resolver, and nameserver policies for domain-based routing.

dns:
  enable: true
  listen: 127.0.0.1:1053
  ipv6: false
  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
  fake-ip-filter:
    - "*.lan"
    - "localhost.ptlogin2.qq.com"

default-nameserver is commonly used to resolve the hostnames of DoH or DoT servers, so it is usually set to resolvers reachable directly by IP address. nameserver is the primary query source; whether fallback participates and how its results are filtered depends on the current core version and related filtering settings.

enhanced-mode: fake-ip returns mapped addresses from a reserved range to applications. The core uses these mappings to retain domain information and complete subsequent forwarding. This helps with domain-based rules, but some LAN services, device discovery, gaming platforms, or applications that require real addresses may need to be added to fake-ip-filter. Another common mode is redir-host, which follows a different processing path; choose based on the operating system, client implementation, and application compatibility.

A DNS failure does not always appear as “unable to resolve.” Sometimes the browser receives a result, but an incorrect rule sends the connection to an unavailable policy. In other cases, system DNS, browser Secure DNS, and core DNS all operate at once, so the query does not follow the expected path. During troubleshooting, verify the application entry point, DNS listener status, resolution logs, and final rule match separately.

Traffic Capture

TUN mode and the system-proxy boundary

The system proxy affects only applications that follow the operating system’s proxy settings. Some command-line tools, games, standalone network stacks, and UDP traffic may bypass it. TUN mode receives more system traffic through a virtual network interface and passes it to DNS, rules, and proxy groups.

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

stack selects the TUN network-stack implementation; available values and recommended choices vary by platform and mihomo version. auto-route attempts to configure routes automatically, while auto-detect-interface identifies the default network interface. TUN mode usually requires appropriate system permissions, which a client may handle through a service mode or helper component.

TUN is only a traffic entry point; it does not replace rules or proxy groups. Once traffic enters the core, it still passes through DNS resolution, sniffing settings, rule matching, and policy selection. If LAN devices become unreachable after enabling TUN, check direct rules for private networks, route exclusions, and the scope of DNS hijacking instead of deleting all routing rules.

A client can manage the system proxy and TUN together. In practice, avoid running multiple tools that take over network traffic, and watch for changes to the default route after sleep and wake, network switches, or VPN-interface changes. If the network remains abnormal after disabling TUN, check whether the client restored the system-proxy and routing state.

Validation

Validation and troubleshooting after editing the configuration

A configuration file opening in a text editor does not mean the core can load it. Make one logical change at a time and keep a restorable version. If the client provides configuration validation, core logs, or an override preview, inspect the final merged YAML first rather than checking only an isolated fragment.

  1. Check YAML structure: Verify indentation, list hyphens, quotation marks, and colon placement, and make sure important top-level fields are not duplicated or overwritten.
  2. Check name references: Verify every rule target, proxy-group member, use provider name, and RULE-SET name.
  3. Check external resources: Confirm that proxy providers and rule providers can update, local cache paths are writable, and downloaded content matches the declared format.
  4. Check runtime logs: Load errors usually identify a field or object name; connection errors require checking DNS, the matched rule, and node handshake details together.
  5. Run minimal tests: Test DIRECT first, then a single static node, followed by the proxy group and rule set, narrowing the scope layer by layer.

Common high-frequency errors

  • A proxy group references a node that was renamed or removed by a subscription update.
  • A rule points to a nonexistent proxy group, or the name contains an extra space.
  • proxy-providers is defined, but the proxy group does not import it through use.
  • The RULE-SET name does not match a key in rule-providers.
  • A broad rule appears before a specific rule, so the later rule never gets a chance to match.
  • The DNS listening port conflicts with another service, or application requests never enter the core-managed resolution path.
  • The subscription cache was edited directly, so the custom content was replaced by the next subscription update.

A complete configuration can be understood as a chain of references: application traffic enters the core through the system proxy, a transparent proxy, or TUN; the DNS section resolves domains; rules and rule providers determine the target policy; proxy-groups select an egress from static nodes or proxy providers; finally, a node using a specific protocol establishes the connection. Following this chain makes configuration breakpoints easier to find than memorizing fields one by one.

Download Clash