A section-by-section guide to Clash YAML

Configuration structure: follow references before changing fields

A Clash configuration file is more than a list of proxies. Ports determine how applications pass connections to the core; DNS controls hostname resolution; proxy definitions specify remote connection parameters; proxy groups organize outbound options; and rules route connections to the appropriate option. FlClash uses the Clash Meta core, also known as mihomo. This guide covers that core, and some fields may not be recognized by older cores.

The key relationship to remember is: rules reference proxy groups, and proxy groups reference proxy names or built-in outbound options. For example, a rule can send a request to “Manual Selection,” where the group lets you choose “Example Proxy” or DIRECT. Names must match exactly—even an extra space can make a target unavailable.

• proxies: a list of proxy definitions containing the protocol, server, port, and authentication details.
• proxy-groups: a list of proxy groups that defines available outbound options and how they are selected.
• rules: an ordered list of matching rules that determines which outbound option handles each connection.
• dns and tun: these handle name resolution and virtual network interface routing, respectively; neither is a proxy node.

General settings: ports, mode, and logging

Start with the top-level settings. This snippet defines a mixed port that accepts both HTTP proxy and SOCKS5 connections. The 7890 value is just an example; subscriptions and clients may use different ports.

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

The local proxy port is not the proxy node's port

Local applications connect to 127.0.0.1:7890, while a remote proxy node may use 443 or another port specified by its server. These ports do not need to match. port can provide an HTTP proxy listener, and socks-port can provide a SOCKS proxy listener. With a mixed port, there is no need to add every listener field just for completeness.

Once the configuration loads, run curl -I -x http://127.0.0.1:7890 https://example.com to check whether the proxy listener accepts connections. This tests only the HTTP request path; it does not confirm UDP, TUN, or all applications are being routed through the core. If the connection is refused, first check the active listener port and whether the core is running.

DNS settings: resolvers and Fake-IP

DNS settings control how the core resolves hostnames. This minimal example listens on local port 1053, uses Fake-IP mode, and specifies an encrypted upstream resolver. It is not a one-size-fits-all setup; the upstream address must be reachable on your network.

dns:
  enable: true
  listen: 127.0.0.1:1053
  ipv6: false
  enhanced-mode: fake-ip
  fake-ip-range: 198.18.0.1/16
  nameserver:
    - https://1.1.1.1/dns-query

Listening on port 1053 is separate from system DNS

listen makes the core provide a DNS service. Setting this field alone does not change the system's DNS server, and standard system DNS settings generally cannot specify a custom port. Whether system DNS is intercepted also depends on TUN DNS hijacking, network settings, and routing.

Fake-IP addresses are not real server addresses

198.18.0.1/16 is used here for the core's virtual address mapping. After an application receives a mapped address, the core uses its saved hostname mapping to match rules and establish the connection. Seeing an address in this range does not necessarily mean DNS failed; check instead that the request is routed back through the same core and that the mapping is still valid.

• dns.ipv6: false prevents AAAA records from being returned to clients here. Its scope differs from that of the top-level ipv6 setting.
• nameserver specifies the primary upstream resolver. If the upstream address is a hostname, consider how that hostname itself will be resolved.
• If a node's server is a hostname, it also needs to be resolvable. For more complex setups, use proxy-server-nameserver to specify an upstream resolver for proxy server hostnames.
• Avoid changing the upstream resolver, Fake-IP filters, and TUN DNS hijacking all at once. Change one setting at a time to identify the source of any problem.

proxies: match node settings to the server

proxies is a list, with each node starting with - name:. Required fields vary by protocol: Shadowsocks passwords and cipher methods cannot be applied to protocols that require UUIDs or TLS settings. This example shows only the field structure for a Shadowsocks node.

proxies:
  - name: "Example Proxy"
    type: ss
    server: 192.0.2.10
    port: 443
    cipher: chacha20-ietf-poly1305
    password: "yaml-demo-password"
    udp: true

name is the local name referenced by proxy groups and can be written in any language; server is the remote server address. udp: true enables UDP for this node configuration, but does not guarantee that the server, route, or application supports UDP forwarding.

If your provider supplies a complete Clash subscription, it usually already includes the node settings, so there is no need to rewrite them manually. Another common structure is proxy-providers, which lets a provider manage nodes. Proxy groups refer to provider names using use. Do not put a provider name in a group's proxies list as if it were an individual node name.

proxy-groups: organize nodes into outbound options

After defining nodes, create proxy groups. select lets users manually choose an outbound option in the group, making it useful for checking whether configuration references are correct. This “Manual Selection” group offers both an example proxy and a direct connection.

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

DIRECT is a built-in direct connection and does not need to appear under the top-level proxies. REJECT is also a built-in option, used to block connections. Avoid custom group names that conflict with these built-in names, and do not create a node and a proxy group with the same name.

Automatic latency checks are not download speed tests

A url-test proxy group compares the probe latency of candidate outbound options using the configured test URL and interval. For example, interval: 300 sets a 300-second interval, while tolerance: 50 sets a switching tolerance in milliseconds. Results depend on the target site and network route, so they do not directly indicate large-file download speeds.

For initial troubleshooting, keep one manual group. First confirm that the proxy works and rule references are correct, then add automatic selection or failover. Proxy groups can reference one another, but avoid circular dependencies—for example, group A referencing B while B references A.

rules: evaluated from top to bottom; the first match wins

With mode: rule, rules are generally checked from top to bottom, and a matching rule sends the connection to its specified outbound option. Put specific rules first and the catch-all rule last. The domains below illustrate matching behavior; they do not imply that any particular type of site must use a direct connection or a proxy.

rules:
  - DOMAIN,example.com,DIRECT
  - DOMAIN-SUFFIX,example.org,Manual Selection
  - IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
  - IP-CIDR,10.0.0.0/8,DIRECT,no-resolve
  - MATCH,Manual Selection

• DOMAIN,example.com: matches this exact hostname; it does not automatically include www.example.com.
• DOMAIN-SUFFIX,example.org: matches this domain and its subdomains, not any string that happens to contain it.
• IP-CIDR: matches a destination IP range. The example lists two private address ranges, not every address range used on local networks.
• no-resolve: avoids triggering a DNS lookup specifically for this IP rule. It does not mean the connection will never need DNS.
• MATCH: catches connections that did not match an earlier rule. Putting it first prevents later rules from being evaluated.

If rules are not taking effect, check the mode and use a new connection

If the client is in global mode, rule-mode behavior is not a valid expectation. Switch to rule mode, then check the connection log for the destination hostname, matched rule, and actual outbound option. A connection showing only an IP address, with no usable hostname, may not match the domain rule you expect.

After changing rules or switching proxy groups, test with a new connection. Browsers may reuse existing TCP or QUIC connections, which do not automatically reconnect under new rules just because the configuration changed. If needed, close the connection and try again instead of repeatedly refreshing the same reused session.

TUN: captures traffic, but does not replace rules or DNS

TUN mode passes traffic to the core through a virtual network interface, which is useful for applications that do not use system proxy settings. It is a different connection method from mixed-port, but captured connections still rely on proxy groups and rules to choose an outbound option. TUN is disabled in this example, which shows the structure of common mihomo fields.

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

auto-route configures routes automatically, while auto-detect-interface detects the outbound interface. Support and behavior depend on the operating system and core version. any:53 in dns-hijack handles ordinary DNS traffic that is captured; it does not mean that app-specific DoH or all encrypted DNS traffic is intercepted.

Enabling TUN usually requires system permissions. FlClash's interface settings may also contribute to the final configuration, so the enable value in a subscription file alone does not confirm whether TUN is active. Check the virtual interface, routes, client status, and connection logs together. If another VPN is running, note the current state first, then disable services one at a time for comparison. This avoids changing multiple traffic capture methods at once.

Check indentation and build a minimal loadable configuration

YAML uses indentation to represent structure. Use two spaces consistently and avoid tabs. Top-level dns, proxies, proxy-groups, and rules should align; fields such as type, server, and port within the same node should also be at the same indentation level.

1. Check the space after each colon. mode: rule is a key-value pair; mode:rule may be interpreted as a plain string.
2. Check list markers. Nodes, group options, and rules are all lists, but each belongs at a different level.
3. Check special characters. If a password or name contains #, a colon followed by a space, or similar characters, quote it appropriately. Backslashes in double-quoted strings also require escaping.
4. Check for duplicate keys. Do not append a second top-level rules key at the end of the file. Add rules to the existing list; duplicate keys may cause errors or overwrite earlier values.
5. Check name references. “Manual Selection” and “Manual Selection ” are different names. When renaming a node or proxy group, update every reference to it as well.

Test the direct-connection structure before adding real nodes

This standalone minimal configuration sends all connections directly. It does not provide a remote proxy, but it can help verify the basic structure of ports, proxy groups, and rules in a local copy. Do not use it to replace or overwrite a configuration you rely on.

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

proxies: []

proxy-groups:
  - name: "Manual Selection"
    type: select
    proxies:
      - DIRECT

rules:
  - MATCH,Manual Selection

If you use the standalone mihomo program, run mihomo -t -f ./config.yaml to check the specified file. Passing the check only means the core can accept the configuration; it does not confirm that node authentication is correct, upstream DNS is reachable, or routes are active. For configurations managed by FlClash, reload them in the client and check the actual error message.

As you continue configuring, refer to the Advanced Config guide to check how proxy groups, rules, and TUN work together. To start by importing a subscription, follow the configuration tutorial for import and mode selection. A configuration file describes the intended setup; confirm the effective result in the client status and connection logs.