Clash YAML Config Guide: Understanding port, dns, proxies, and rules

Identify the file first: config, subscription, or client settings

A Clash config is usually a YAML text file, commonly named config.yaml. It defines local listening ports, DNS, proxy nodes, proxy groups, and routing rules. The client reads the file, then the selected core interprets these fields. A subscription link is one way to get a config: the client requests the link, saves the response, and refreshes it on a schedule. The subscription URL itself is not a proxies node and cannot be added to rules as a rule.

Check which Profile is currently selected in the client before deciding whether to edit it. A client can store multiple configs, but usually runs only the selected one. Manual changes to a subscription-generated file may be overwritten at the next update. For lasting changes, use the client’s override feature or maintain an editable local config. Override options vary by client, so before saving, confirm whether the changes apply to the original file or a subscription copy.

Make a copy of the original config before editing. Afterward, first check that the client can load the YAML, then verify that proxy groups and rules behave as expected. “Imported successfully” and “traffic uses the right route” are two different things.

Core settings: port, mixed-port, and operating mode

Top-level fields start at the beginning of a line. port sets the local HTTP proxy listening port, while socks-port sets the local SOCKS5 proxy listening port. mixed-port accepts both HTTP and SOCKS5 proxy connections on the same port. This example uses 7890 as the mixed port, so apps with manual proxy settings can use 127.0.0.1:7890. This is a local entry point, not the port of a remote proxy node.

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

allow-lan: false means other devices on the local network cannot use this device’s proxy entry point. If you need to share it, also check the client’s listening address, system permissions, and network; changing a single switch may not be enough. mode: rule uses rules to choose the route. global generally sends requests through the selected policy, while direct handles them as direct connections. Switching modes can help with troubleshooting, but it is no substitute for correct rules and proxy settings.

On iPhone, distinguish the local proxy port from system-wide traffic routing. When the client creates a VPN configuration or enables TUN, some traffic can reach the core through a system network extension, without requiring every app to enter 7890 manually. Which requests are routed depends on the client, system permissions, and network settings. Not every iOS client supports the config’s tun field; don’t paste a desktop TUN example directly into a phone config.

DNS settings: how resolution feeds into rule matching

dns is a nested object. enable controls the core’s DNS feature, and nameserver lists upstream DNS servers. With fake-ip, the core returns reserved addresses for eligible domains and keeps a mapping between each domain and its address. When a later connection matches that mapping, the core can still identify the original domain for domain-based rules. This does not permanently replace a website’s real address with a reserved one.

dns:
  enable: true
  enhanced-mode: fake-ip
  fake-ip-range: 198.18.0.1/16
  nameserver:
    - 223.5.5.5
    - 119.29.29.29
  fake-ip-filter:
    - "*.lan"

198.18.0.1/16 is the example Fake-IP range, not an address you can use to visit a website. fake-ip-filter excludes specific domains from Fake-IP mapping. If local device names or services that rely on real DNS answers stop working, test the affected domains individually before adding them to the filter. The broader the filter list, the harder it is to tell which setting changed the outcome. Choose upstream DNS servers for your actual network: if an upstream server is unreachable, a page may stall during DNS resolution before the proxy connection even starts.

If a domain rule doesn’t work, first check whether the request still includes domain information that can be matched and whether the client is using DNS from this config. Some apps connect directly to IP addresses or use their own DNS resolution; changing nameserver alone won’t ensure they match DOMAIN-SUFFIX. For more on when to use Fake-IP or redir-host, check the supported fields for your client in the technical reference.

proxies and proxy-groups: define nodes separately from selectors

proxies is a list of individual proxy nodes. Each entry needs at least a name, type, server address, and port that match its protocol; authentication, encryption, and transport fields vary by protocol. The example below uses the documentation domain proxy.example.net to show the structure—it is not a working proxy address. Use the settings provided by your service, and don’t guess the protocol based on a node’s name.

proxies:
  - name: "Custom SOCKS5"
    type: socks5
    server: proxy.example.net
    port: 1080

proxy-groups:
  - name: "Node selection"
    type: select
    proxies:
      - "Custom SOCKS5"
      - DIRECT

proxies appears twice here, but at different levels. The top-level proxies defines nodes; the indented proxies under a proxy-groups entry lists the routes that group can select. select is a manual selection group, usually shown as a list of options in the client’s policy view. DIRECT is a built-in direct route; you don’t need to create a proxy node with that name. Group and node names are references and must match exactly in your rules.

Subscription configs may also use proxy-providers to fetch nodes centrally, then reference a provider in a proxy group. This is a different organization method from listing each node directly under the top-level proxies. If the node list is empty, check whether the subscription updated, whether the provider is referenced by a proxy group, and whether the selected Profile is the one you just updated. Don’t assume an empty group option list means there’s a DNS problem.

rules: match from top to bottom, and make sure the route exists

rules is an ordered list. The core typically checks entries from top to bottom and uses the route specified by the first match. Put narrow domain rules before broader geographic rules, and leave the catch-all rule until last. In this example, Node selection must exactly match the proxy group’s name above.

rules:
  - DOMAIN-SUFFIX,example.org,Node selection
  - GEOIP,CN,DIRECT
  - MATCH,Node selection

DOMAIN-SUFFIX matches a domain and its subdomains. GEOIP,CN,DIRECT makes a decision based on the destination IP’s geolocation data; it is not the same as checking whether an app is from mainland China. MATCH catches requests that didn’t match earlier rules. Put MATCH on the first line and later rules usually won’t get a chance to match; move a broad rule too high and it may mask more specific domain rules.

A page that still won’t load after a rule matches doesn’t necessarily mean the rule syntax is wrong. Check the client’s connection log to see which rule matched and which proxy group handled the request, then confirm whether the group currently selects a node or DIRECT. If the destination connects directly by IP, there may be no domain to match. If the route is REJECT, the request is blocked rather than sent through a proxy. See the glossary for definitions of these terms.

Indentation, order, and saving: change one thing at a time

YAML uses indentation to show structure. Top-level dns:, proxies:, proxy-groups:, and rules: start at the beginning of a line. Nested fields need further indentation, and list items use a hyphen followed by a space. Use spaces consistently; don’t mix in tabs. Quote names containing colons, hash signs, or leading or trailing spaces to prevent them from being parsed as YAML syntax. Case matters too: DIRECT and a custom name like Direct are different references.

Symptom	Check first	What to do
Config won’t load	Indentation, colons, and list hyphens near the reported line	Undo the latest change, then add changes back one section at a time
Rule references a missing target	The name at the end of the rule and the proxy group name	Make the names match, including capitalization
No selectable nodes in the proxy group	Node names or provider references in the group	Confirm nodes loaded, then check the group’s options
Changes keep reverting	The selected Profile’s source and subscription update history	Use a persistent override or a local config

A safer workflow: back up the original file, change just one field or rule, save and reload the config in the client, check for parsing errors, then use a specific domain to inspect the connection log. For example, when changing DOMAIN-SUFFIX,example.org,Node selection, test a domain covered by that rule and confirm the log shows the expected proxy group. Continue with the next change only after testing; if something breaks, you’ll know where to look.

A config that parses as YAML may still contain fields the current core doesn’t recognize. Clash, Clash Meta (mihomo), and individual clients don’t support exactly the same options. Before copying a config from another device, check which core your client uses and which fields it supports. On iPhone, check system network extension permissions, Profile selection, config syntax, and actual routing results separately. Troubleshooting these four layers one at a time makes it easier to find the issue than replacing the entire file at once.