Why the YAML layout actually matters

Most newcomers paste a subscription into a GUI client and hope for the best. That works until something subtle breaks: a site loads from the wrong region, a game chat fails over UDP, or DNS queries leak outside the tunnel. At that point, the fix is almost always in the configuration file—usually a single .yaml profile that combines outbound nodes, grouped policies, ordered rules, and a DNS section that can run in Fake-IP mode.

Clash-family cores (including mihomo / Clash Meta) share the same mental model. Traffic is not “magically proxied”; it is classified by rules, mapped to a named proxy group or outbound, and only then sent through a concrete server. DNS is not an afterthought either: with Fake-IP enabled, domain names are resolved in a way that keeps routing information available to the proxy layer, which is why misconfigured DNS often looks like “rules not working.”

This article walks through those layers in the same order the core conceptually applies them. You will see why rule order is sacred, how nested proxy groups help you build sane fallbacks, and how to tune Fake-IP filters so local services and captive portals still behave. For field-by-field references beyond these patterns, our documentation hub is a good companion while you edit YAML by hand.

The four pillars of a typical profile

Think of a Clash profile as four cooperating sections. You do not need every advanced knob on day one, but you should know what each pillar is responsible for.

  • General—bind address, mixed port, logging, and the global mode hint (rule vs global vs direct). In modern setups you normally stay on rule and let the ruleset do the splitting.
  • Proxies—concrete upstreams: SS, VMess, VLESS, Trojan, Hysteria2, TUIC, and so on. Each entry is a single hop with its own server, port, and transport options.
  • Proxy groups—named policies that reference proxies or other groups. This is where you express user-facing choices (select), automatic latency picking (url-test), ordered failover (fallback), or multi-path balancing (load-balance).
  • Rules—an ordered list from top to bottom. The first match wins. Anything that falls through to the end typically hits MATCH and lands in your catch-all group.

DNS sits beside this pipeline. It can run in redir-host style behavior or fake-ip mode, and the choice changes how domains are handed to the routing engine. We will return to DNS after we have covered rules and groups, because Fake-IP only makes sense once you understand what the rules are trying to match.

Proxies: keep names stable and meaningful

Each node under proxies: should have a unique name because groups and rules refer to strings, not array positions. Good names pay off when you read logs: hk-relay-01 tells you more than server 3. If your subscription importer renames nodes on every refresh, consider fixing that in the client or post-processing—stable names make automation and debugging dramatically easier.

When you mix providers, be explicit about transports. A profile that silently relies on outdated cipher suites or wrong ALPN settings may connect only some of the time. If you hand-edit YAML, re-check the upstream documentation whenever you change the server side, because mihomo evolves faster than vintage Clash cores and exposes more transport options.

Proxy groups: the control panel your rules dial into

Proxy groups are the interface between human intent and raw nodes. Rules never point to a bare IP:port entry; they point to a group name (or special keywords like DIRECT and REJECT). That indirection is what lets GUIs show a dropdown while the same file still works headless on a router.

select

The simplest group type. It lists candidate proxies and preserves whichever option the user last chose. This is ideal for region buckets—HK, JP, US—and for pinning a low-latency node you trust for banking or video calls.

url-test and fallback

url-test periodically measures latency against a probe URL and picks a winner, subject to thresholds like interval and tolerance. It shines on unstable networks where the fastest node changes throughout the day. fallback walks the list in order and promotes the first healthy member—excellent when you want deterministic priority rather than continuous re-ranking.

When you nest groups, keep the graph easy to reason about: a select of several url-test region buckets is usually clearer than a deep chain of fallbacks that hides why a path was chosen.

relay and chaining

Chains stitch proxies together for specific threat models or topology requirements. They are powerful and easy to misconfigure: a weak hop at either end negates the benefit, and latency stacks quickly. Treat chains as a specialty tool, not the default.

Tip

If your GUI shows unexpected selections after imports, search the YAML for duplicate group names or shadowed definitions. The last duplicate key wins in many parsers—silent overrides are painful to spot without a diff.

Rules: top-down priority and the cost of a wrong order

Rules are evaluated sequentially. The first matching rule terminates the search. That single fact explains a surprising share of support issues: putting a broad GEOIP rule too high, or placing a catch-all domain rule above a finer exception, silently steers traffic the wrong way.

Practical guidance: put narrow, intentional exceptions first—LAN direct access, company VPN domains, local DNS names—then broader GEOIP or ASN logic, and finally your MATCH default. When you import community rulesets, resist the urge to prepend dozens of ad-hoc lines without reviewing how they interact; ordering bugs are the hardest because nothing throws an error.

Common match types you will actually use

  • DOMAIN-SUFFIX / DOMAIN / DOMAIN-KEYWORD—fast string matches for known services. Prefer suffix rules when you control an entire property; keyword rules are broader and risk collateral matches.
  • IP-CIDR and IP-CIDR6—match after resolution or for raw IP connects. Pair them with knowledge of Fake-IP behavior: Fake-IP changes when an IP is even available for matching.
  • GEOIP—handy for split routing (for example, sending domestic destinations direct). Keep databases updated; stale GEOIP data mislabels ranges.
  • RULE-SET—offloads large lists to providers so your main file stays readable. Verify behavior settings (domain, ipcidr, classical) against the file you fetch.
  • PROCESS-NAME / PROCESS-PATH—per-binary policies on desktops. Powerful for games and IDEs; fragile if binaries rename themselves on updates.

Modern cores also support advanced constructs (script hooks, sub-rules in mihomo) that let you segment policies without copy-pasting thousands of lines. If you are migrating from an older Premium-only setup, prefer supported primitives first—clarity beats cleverness when you troubleshoot at midnight.

DNS and Fake-IP: cooperation, not opposition

In redir-host-style flows, clients receive real resolved IPs, and rules that depend on IPs behave as you might expect from a traditional resolver. Fake-IP mode instead returns synthetic addresses from a reserved pool (commonly 198.18.0.0/15) while the core keeps a domain mapping internally. When the connection is actually established, the proxy can still see the original name—crucial for TLS SNI and for domain-based routing on the remote side.

Why people enable Fake-IP: it reduces accidental bypass where applications resolve DNS outside the tunnel, and it keeps domain information available for outbound policy. Why people struggle with Fake-IP: any rule that assumes a “real” public IP at match time may not fire the way you expect, and split-horizon names need explicit exceptions.

fake-ip-filter essentials

Some names should never be synthesized. LAN and multicast suffixes belong in the filter list so local discovery protocols keep working. Messaging apps that pin to captive portals or carrier endpoints sometimes need exceptions too—symptoms show up as endless redirects or broken Wi-Fi login pages.

Pair Fake-IP with a sane nameserver stack: fast domestic resolvers for everyday lookups, robust encrypted resolvers as fallback, and a fallback-filter that distinguishes poisoned or inconsistent answers. The exact providers depend on your region; the structure matters more than copying any single public list verbatim.

dns:
  enable: true
  listen: 0.0.0.0:53
  enhanced-mode: fake-ip
  fake-ip-range: 198.18.0.1/16
  fake-ip-filter:
    - '*.lan'
    - '*.local'
    - 'time.*.com'
  nameserver:
    - https://dns.example/dns-query
  fallback:
    - https://cloudflare-dns.com/dns-query
  fallback-filter:
    geoip: true
    geoip-code: CN
Important

Fake-IP is not a privacy toggle by itself. It changes how resolution interacts with routing. Real privacy gains come from consistent TUN capture, correct rules, encrypted DNS to resolvers you trust, and verifying leaks with external tests—not from any single YAML keyword.

Worked example: stitching groups, rules, and DNS together

Imagine you want three outcomes: domestic sites direct, a handful of services pinned to a low-latency proxy, and everything else through an auto-selected export node. You might define region buckets as select groups, create a url-test auto group for general traffic, and keep a concise list of domain rules ahead of GEOIP.

The skeleton below is illustrative—replace names and endpoints with your own. Notice how MATCH sends leftovers to the auto group, and how DNS is enabled alongside mode: rule in the general section.

mode: rule
log-level: info

proxies:
  - name: example-node-a
    type: ss
    server: 198.51.100.10
    port: 8388
    cipher: aes-256-gcm
    password: "replace-me"

proxy-groups:
  - name: AUTO
    type: url-test
    proxies:
      - example-node-a
    url: https://www.gstatic.com/generate_204
    interval: 300
    tolerance: 50

  - name: PINNED
    type: select
    proxies:
      - example-node-a

rules:
  - DOMAIN-SUFFIX,corp.internal,DIRECT
  - DOMAIN-SUFFIX,chat.example,PINNED
  - GEOIP,CN,DIRECT
  - MATCH,AUTO

When you enable Fake-IP, revisit the domain rules you rely on—especially for services that embed regional CDNs. If a domain fans out across many IPs, suffix rules are often more stable than IP rules that were generated from a one-off resolution.

Debugging checklist when “something feels off”

Start with logs. A high log level is noisy but decisive: you will see which rule matched, which group was selected, and whether DNS fell back. Then verify the three most common foot-guns: duplicate YAML keys, a rule section that never reaches MATCH, and a DNS path that resolves outside your intent.

Symptom What to inspect first
Domestic sites detour through export GEOIP order and outdated country databases; missing DIRECT exceptions
Apps work only with TUN off UDP handling on the node; PROCESS-NAME gaps; split tunneling in the OS
Captive portals fail on Fake-IP Expand fake-ip-filter; temporarily test redir-host to confirm
Rule-set updates break routing Provider URL reachability; behavior mismatch; parser errors in downloaded files

After YAML edits, restart or hot-reload according to your client. Some GUIs cache older profiles until you explicitly re-select them; if changes seem ignored, you are often looking at a different file than the one you edited.

Closing: clarity beats complexity

Readable YAML is operational YAML. Prefer small groups with obvious names, keep rules ordered like a story—exceptions first, geography next, default last—and treat DNS as part of routing, not a sidecar. Those habits matter more than chasing every new keyword in release notes.

When you are ready to put this into practice with a maintained desktop client, grab a build from our download page so you are not juggling raw binaries and mismatched cores by hand. A solid GUI does not replace understanding YAML, but it removes enough friction that you can iterate safely. → Download Clash for free and experience the difference.