Advanced Config

Clash config.yaml Explained: Ports, DNS, Proxies, Rules & More

A section-by-section guide to Clash config.yaml, from ports and DNS to proxies, proxy groups, rule providers, and rules—with tips for spotting common mistakes.

Ports and Modes: Start with the Traffic Entry Point

To check whether a configuration is working, first find out which entry point the app connects to, then see how the core routes traffic. The examples below use mihomo. Older Clash versions and mihomo support different fields, and the client version may differ from the core version. When running mihomo standalone, check the core version with mihomo -v. In a GUI client, refer to the core version shown in the app.

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

mixed-port accepts both HTTP and SOCKS proxy connections. For this example, set the app's proxy address to 127.0.0.1 and port to 7890, then choose a protocol supported by the app. If your config uses separate port and socks-port entries, they correspond to HTTP and SOCKS respectively. Don't enter the DNS listening port or controller port in the app's proxy settings. Here, 7890 is just an example—not a universal client port.

Whether the system proxy is enabled, and whether an app respects it, are separate from the config. TUN uses a virtual network interface to capture traffic that matches its routing conditions; its settings live in a separate top-level tun section. Changing mixed-port does not enable TUN. Even with TUN enabled, a browser loading a page doesn't tell you which route another app is using.

DNS: Listening Address, Upstreams, and Fake-IP

dns is a top-level mapping. enable turns on the core's DNS feature, listen sets the address where the core receives DNS queries, and nameserver lists the upstream resolvers. The example below uses port 1053 on the loopback address for local testing, rather than exposing the listener to your LAN.

dns:
  enable: true
  listen: 127.0.0.1:1053
  enhanced-mode: fake-ip
  fake-ip-range: 198.18.0.1/16
  nameserver:
    - 223.5.5.5
  fake-ip-filter:
    - localhost
    - '*.lan'

In the default filtering mode, domains matching fake-ip-filter won't be assigned a Fake-IP. That doesn't guarantee the upstream can resolve them or that their connections will go direct. Fake-IP maps addresses to domain names so the core can associate connections with their domains; routing through a proxy is still determined by the mode and rules. Quote the wildcard '*.lan' to prevent YAML from interpreting the leading asterisk as an alias.

Run nslookup -port=1053 example.com 127.0.0.1 to test the listening port directly. In this example, an unfiltered A-record query should return a Fake-IP from the configured address range. This only confirms that the query reached the core and got a response; it doesn't prove that the system DNS has changed or that the destination is reachable. If the manual query works but an app behaves differently, check the app's encrypted DNS, the system cache, and DNS hijacking settings when TUN is enabled.

proxies and proxy-groups: Separate Node Definitions from Policy Selection

Top-level proxies is the list of outbound nodes. Each entry usually includes name, type, server, and port; other parameters depend on the protocol. A node's port points to the remote service and has nothing to do with the local mixed-port. Don't put a subscription URL in a node's server. A client may convert a subscription into a complete config, while mihomo's proxy-providers loads a set of nodes through the configuration.

Top-level proxy-groups defines policy groups. The group's proxies field is a list of candidate names, not a list of node objects. To add candidates from a proxy provider, reference the provider by name with the group's use field. First, verify the references with a group containing only built-in outbounds—no node credentials needed:

proxy-groups:
  - name: Lab-Select
    type: select
    proxies:
      - DIRECT
      - REJECT

A select group uses its current selection. When a rule matches Lab-Select, traffic goes direct if the current selection is DIRECT, or is rejected if it's REJECT. Before testing, check the group's selected option in the client; it may restore a previously saved choice. When adding a node to a group, copy its full name and check capitalization, spaces, and punctuation. If you rename a policy group, update every rule that references it.

rule-providers: Defining a Rule Set Doesn't Enable Routing

rule-providers supplies matching conditions, not outbound nodes. Declaring a rule set here associates a name with its contents; you still need a RULE-SET entry in rules to specify the outbound for matches. Start with an inline rule set to verify this behavior and rule out download or cache issues.

rule-providers:
  lab-domains:
    type: inline
    behavior: domain
    payload:
      - '+.example.org'

For an HTTP provider, configure type: http, url, a local cache path, and an update interval. interval: 86400 means 24 hours; the unit is seconds. Make sure format matches the actual resource format. A link that returns a login page isn't a rule file, and changing a file extension won't turn text into MRS. A GUI client's core working directory may differ from the directory containing the original subscription file. To locate the cache, check the working directory first, then verify the relative path.

rules: Evaluated in List Order, Not by Specificity

Add the following list to the config above. rules, rule-providers, proxy-groups, and dns are all top-level keys and should be aligned, not nested inside one another. The core checks rules from top to bottom and uses the policy from the first match; it won't automatically move more specific domain conditions higher in the list.

rules:
  - DOMAIN,example.org,DIRECT
  - RULE-SET,lab-domains,Lab-Select
  - MATCH,DIRECT

When the core can match the connection's destination domain, example.org matches the first line, while www.example.org matches the rule set and goes to Lab-Select. Move the rule-set entry above the exact-domain rule, and the rule set will also catch the root domain. Put MATCH first, and no later rules will be checked. To test, select REJECT in Lab-Select and check the connection log to see whether the subdomain request matched the expected rule. Don't use whether the example site serves a page as your test.

Config Errors and Routing Issues: Check Parsing, Loading, and Connections

  1. Validate YAML syntax and references first. Indent with spaces and align keys at the same level. Use hyphens for list items and key-value pairs for mappings. Don't add a second top-level rules just to append a rule; add it to the existing list. When running standalone, test the config from its directory with mihomo -t -f config.yaml. If the client uses a separate working directory, test with the actual directory and config file. Focus on the first error: fix the structure before the names.
  2. Make sure you're testing the active config. A GUI client may merge subscriptions, overrides, and local preferences before passing the result to the core. Passing a test with the original file doesn't mean the running config contains the same rule. Check the active config and the merged result shown by the client, then reload and verify the mode, port, and policy group selection.
  3. Verify the entry point, then trace the outbound. Test the port used in this article with curl --proxy http://127.0.0.1:7890 https://example.org/. If the proxy port can't be reached, first check whether the listener is running or the port is already in use. If the connection appears in the log, check the destination domain, matched rule, and final outbound. If the rule matches but the request still fails, check the DNS upstream, selected outbound, or destination service.

Change one variable at a time. First, use DIRECT, REJECT, and two distinct domain conditions to verify the rules. Then gradually switch back to subscription nodes and remote rule sets. This makes it easier to pinpoint whether an issue comes from the local entry point, config merging, rule data, or a specific outbound.

Download Clash