config.yaml / Field Reference

Clash Configuration File Reference

For your first subscription import, mode selection, and connection check, start with the Getting Started Tutorial. It shows you how to get connected; this handbook explains how to read and edit the config afterward, and where to verify your changes.

Examples use Mihomo as a reference. Names shown in the client UI do not always match YAML keys, and older cores may not recognize the same options. Unless an example is marked as a standalone config, each snippet illustrates a specific field and should be added to the corresponding section of your existing config.

config.yaml / 01

YAML Structure and Config Entry Points

Top-Level Keys, Maps, and Lists

A config file's top level is a set of keys and values. Keys at the same level, such as mixed-port, mode, and rules, each serve a different purpose; their order usually doesn't affect how they work. But rules contains an ordered list, where the first and last rules can't be swapped arbitrarily. First identify whether you're looking at a map or a list, then decide where the lines you're copying belong. Simplifying a whole settings block to a single switch like dns: true may be valid YAML, but it isn't the structure the core expects.

Indent each nested level by two spaces; don't use tabs. This file can be loaded on its own: it opens a single mixed listener and sends all requests directly, with no upstream proxy required. Before loading it, check that no other instance is using the local port. It's useful for confirming that an app is connecting, but it can't test any remote proxy. To add DNS settings, add dns at the top level; don't indent it under the last rule.

mixed-port: 7890
allow-lan: false
mode: rule
log-level: info
rules:
  - MATCH,DIRECT

Each hyphenated item belongs to a list. A proxy entry can span several lines: the first line gives its name, with the type, server, and port aligned below it. A rule entry is usually a single string. One easy-to-miss detail is proxies under a proxy group: it lists candidate names, not another set of proxy definitions with server addresses. The same key can appear at different levels and refer to different data structures, so the two aren't interchangeable.

Scalar Types and Duplicate Keys

Write ports as integers, switches as booleans, and names and servers as strings. If a string is just a sequence of digits, quote it so YAML doesn't treat it as a number; references to it should also be strings. In ordinary strings, quote the whole value if it contains a colon followed by a space or a hash that could start a comment. Rule strings usually don't need quotes. If your editor misreads punctuation as YAML syntax, quote the entire rule rather than quoting each comma-separated field separately.

Don't define the same top-level key twice in one file. Pasting another rules block at the end of a file that already has rules doesn't append items to the existing list. Some parsers report duplicate keys; others may keep only one block. To troubleshoot, first check whether the key appears twice, then look a few lines above each occurrence to identify its actual level. If your editor flags indentation, the real issue could be a missing colon on the previous line or a list that wasn't closed properly much earlier.

From the Original Subscription to the Runtime Config

In a desktop client, the imported config, override, and runtime config are often separate files. A subscription refresh may rebuild the imported config; overrides store local changes; the runtime config is what the core reads. To check whether a field took effect, confirm which profile is selected, then see if the client can preview or export the runtime config. Opening only the file you originally downloaded tells you what the subscription provided, not what the client is using now.

With a standalone Mihomo instance, check candidate files in the core's working environment. Keep relative paths, external rule files, and the working directory as close as possible to the actual runtime setup. Configs that use remote providers may still need files or network access during validation. The command below won't switch profiles in a desktop client, verify that a port can be bound, or guarantee internet access. First rule out syntax errors with the minimal config above; then check references in the candidate file, and only then load it.

mihomo -t -f ./config.yaml

127.0.0.1 / 02

Listener Ports, Runtime Modes, and the Controller

Keep Local Listener Ports Separate from Upstream Ports

Your browser or terminal connects to a local listener, such as 127.0.0.1:7890. The core connects to the server address and port in a proxy definition. The two may happen to use the same port number, but they aren't linked. If you change the local listener, update the system proxy or app proxy too; changing a proxy's port usually doesn't require any changes to local apps. On a “connection refused” error, first check whether the address in the logs is local or belongs to a proxy server, then inspect the corresponding field.

FieldPurposeWhat to Check
mixed-portAccept HTTP and SOCKS proxy connections on the same portThe system proxy and SOCKS-compatible apps can connect using their respective protocols
portSeparate HTTP proxy listener portThe app's HTTP proxy address
socks-portSeparate SOCKS proxy listener portThe app's SOCKS proxy address
allow-lanWhether devices on the local network can connect to the proxy listenerListener address, system firewall, and source of the connection
external-controllerThe core's external controllerA client dashboard or local admin tool, not an app proxy endpoint

For local use only, keep allow-lan: false. A loopback address always refers to the device making the connection; entering 127.0.0.1 on a phone won't connect it to your computer. Only check allow-lan, bind-address, and the firewall if you need to share access on a trusted local network. Allow access only from devices that need it, and don't expose the listener to the public internet. If you're only checking whether a browser on your computer connects, there's no need to enable LAN access.

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

The Mode Comes Before Individual Rules

In rule mode, the rules determine where traffic goes. global mode uses the current selection in the global proxy group; it doesn't necessarily mean a remote proxy is in use. direct mode sends traffic entering the core directly; it doesn't disable the listener or undo the system proxy. After switching modes, start a new connection to test the change—existing long-lived connections may not be recreated right away. For chat, sync, and download apps that keep background connections open, check connection details to tell old connections from new ones.

A desktop client can change the runtime mode through the controller. So a file containing mode: rule doesn't mean the global mode you selected in the UI a minute ago has been reset. To troubleshoot rules that don't match, first check the current mode and selected profile in the client, then inspect the rules. For a side-by-side look at the three modes, see Rule, Global, and Direct Modes Compared. Don't treat switching modes as a permanent fix.

Verify the Proxy Connection Before Checking the Controller

The operating system or client sets the system proxy, and only apps that read that setting will use it. A terminal may need a proxy specified for each command, while some browsers prioritize their own settings or extensions. Run the command below, then look for a request to the same destination at the same time in the connection log. A response confirms that this request used the specified proxy; it doesn't mean every terminal command will. If the command reports a local connection refusal, check the port and process first, then use separate troubleshooting steps for browsers and terminals to narrow it down.

curl -I --proxy http://127.0.0.1:7890 https://example.com/

The controller is a separate interface. If a desktop client already manages the core, don't change the controller address or authentication settings it maintains just to test a config. If you're running the core yourself and need external control, bind it to loopback where possible, and set authentication locally as required by your admin tool. If a port is in use, check the proxy and controller ports separately; after changing one, update the corresponding client too. Temporarily increasing the log level can help, but restore your usual level when you're done. Remove private addresses, subscription URLs, and credentials before sharing snippets.

proxies / 03

Proxy Fields and External Proxy Sources

Name, Protocol, Remote Address, and Port

proxies defines the outbound proxies the core can use. name is the name referenced by proxy groups and rules; type sets the protocol; server and port specify where that protocol's server is listening. The server field should contain only a hostname or address—no protocol prefix, path, or extra port component. Keep names short and unique, and avoid reserved target names such as DIRECT and REJECT.

This is a SOCKS5 outbound proxy definition. Use it to test traffic forwarding only if a separate SOCKS5 service is actually listening on 1080 on the same machine and allows unauthenticated local access. This isn't a public proxy, and you can't replace it with Clash's mixed port from the previous section; doing so could send outbound traffic back into the same core. After adding this snippet to the minimal config, make a test rule or proxy group reference the proxy. Defining it alone won't change where MATCH,DIRECT sends traffic.

proxies:
  - name: Local upstream
    type: socks5
    server: 127.0.0.1
    port: 1080
    udp: false

Changing protocols often means replacing a whole set of parameters, not just the type. For a proxy with TLS, the server address specifies where to connect, while the server name may be used for the handshake and certificate validation; they don't have to be the same. Any additional transport settings must also match the server. Don't add TLS or a transport option just because the port is 443. If you're unsure of a field name, check the protocol documentation for your core version and the parameters provided by the server. Don't copy authentication fields from another protocol.

How Proxy Lists and Groups Depend on Each Other

When renaming a proxy, check the candidate lists in groups, any rules that target it directly, and any saved selections in the client. A new name won't inherit existing references—even if it differs by just one space. When proxies from different sources share a name, it's easy to misidentify the active one in the logs. To avoid confusion, distinguish the names at the source or use a provider renaming feature supported by your core, then check the final candidate list.

For many proxies or independent updates, use proxy-providers to name each source, then connect it to a group with use. The snippet below defines a file-based provider for a Mihomo working directory that can read the relative path. The file must already exist and can contain a complete proxies map like the one in the previous example. Maintain proxy definitions in that external file; don't redefine proxies with the same names in the main config. A provider name isn't a proxy name, so you can't use the source name directly as a rule target.

proxy-providers:
  office-socks:
    type: file
    path: ./providers/office-socks.yaml

proxy-groups:
  - name: Office egress
    type: select
    use:
      - office-socks
    proxies:
      - DIRECT

Troubleshoot Loading and Connectivity Separately

If the provider doesn't appear in a group, first check its reference name, file path, and load logs. If the file is there but won't load, its contents may not match the provider type—for example, a subscription webpage, a plain-text proxy share link, or an error response instead of a YAML file. If the proxy is listed and selectable, the issue is at the connection stage: check whether the server hostname resolves, whether the port is reachable, and then whether the handshake or authentication failed. Compare browser and test requests only after that.

A proxy that can load a webpage doesn't necessarily support every transport an app uses. udp: true can't add UDP support to the upstream; forwarding still depends on the protocol, server, and client connection method. If games or voice calls fail while ordinary webpages work, first confirm that the affected traffic enters the core and identify its transport, then check which outbound proxy the rules select. To compare with another client, see Clash Plus and other platform options on the client downloads page, and choose based on your OS and required features.

proxy-groups / 04

Proxy Groups, Candidates, and Health Checks

Proxy Groups Sit Between Rules and Outbound Proxies

A proxy group doesn't describe a server. A rule can send traffic to a group, which then selects a proxy, a direct connection, or another group. That way, rules don't need to track which server is currently in use. For example, send work-related domains to “Office egress” and switch to a direct connection temporarily by changing the group selection. That changes the route for all addresses using the group. If you want to change the route for just one domain, don't switch the whole group; check whether that domain needs a more specific rule.

select is a manual selection group. This snippet assumes the main config already defines “Local upstream” from the previous section. To check local routing, select DIRECT, record how a request is routed, then send the same request through the upstream. A proxy appearing in the candidates doesn't mean it's selected. If the client remembers an earlier choice, you also can't infer the current outbound proxy from the first item in the YAML list.

proxy-groups:
  - name: Office egress
    type: select
    proxies:
      - DIRECT
      - Local upstream

Latency Tests, Failover, and Load Balancing

url-test automatically selects an outbound proxy based on test results against a specified URL. fallback prioritizes available candidates in the order listed. If your preferred route is usually slower but should be used unless it goes offline, focus on failover rather than switching based on a single latency reading. load-balance distributes connections among candidates; it doesn't split one download across multiple routes. Don't use it for services that depend on a consistent outbound IP for login sessions unless you've tested the behavior.

This example uses a direct connection and a local upstream to demonstrate automatic health checks. In practice, don't add a direct connection to the candidate list just to make the test results look better if the service must use a particular type of outbound route. interval is the test interval in seconds. In this group, tolerance allows for some latency variation to avoid frequent switches over small differences. Choose a stable test URL that's reachable through all candidates and reflects your needs as closely as possible; reaching the example site doesn't guarantee that a business domain will work through the same route.

proxy-groups:
  - name: Connectivity test
    type: url-test
    proxies:
      - Local upstream
      - DIRECT
    url: https://example.com/
    interval: 300
    tolerance: 50

If an automatic group always selects the same route, check whether the others tested slower, timed out, or aren't included in the generated group at all. The test URL may also be rate-limited or return an unexpected page through one of the candidates. Don't immediately reduce the interval to a few seconds, especially on mobile devices: that increases test traffic without necessarily explaining the issue. Test one problematic candidate separately, then compare the connection log, current selection, and actual app request. Each shows something different.

Nested Groups and Saved Selections

A main group can contain an automatic group, letting you select a purpose first and then an automatic route. But references must not loop back to the same group. For example, if “Office egress” includes “Connectivity test” as a candidate, the test group shouldn't include “Office egress” in return. When reading logs, follow the chain from the rule target through each group to the actual proxy. If the groups are nested too deeply, simplifying the chain to explain the current selection is usually easier to maintain than adding another layer.

Mihomo's profile.store-selected can save proxy group selections. Exactly what gets restored also depends on the client's profile ID, cache directory, and group and proxy names. The snippet below belongs at the top level; note that the key is singular. If a subscription refresh removes or renames a proxy, saving the selection can't restore a candidate that no longer exists. After changing configs, check that the saved selection is still in the candidate list rather than switching repeatedly to guess whether it was remembered.

profile:
  store-selected: true

DIRECT / 05

Rule Syntax, Match Order, and the Default Target

Start with the First Matching Rule

In rule mode, rules are checked from top to bottom. Once a rule matches, traffic goes to its specified target; the core doesn't continue looking for a more specific rule. Put domain exceptions before suffix rules that would match them, and specific IP exceptions before CIDR rules that cover them. If it looks like a site always takes the wrong route, find the first rule matched by that request. Don't just search the file to see whether the domain appears somewhere.

This example assumes the “Office egress” proxy group is already defined. DOMAIN matches a complete domain name; DOMAIN-SUFFIX matches that domain and its subdomains. The first rule therefore excludes www.example.com from the suffix rule. IP-CIDR matches an IPv4 network; the example sends three common private ranges and the local loopback range directly. The final MATCH is the fallback and is used only if no earlier rule matches. The example uses a direct connection, but choose a fallback target that suits your setup.

rules:
  - DOMAIN,www.example.com,DIRECT
  - DOMAIN-SUFFIX,example.com,Office egress
  - IP-CIDR,127.0.0.0/8,DIRECT,no-resolve
  - IP-CIDR,10.0.0.0/8,DIRECT,no-resolve
  - IP-CIDR,172.16.0.0/12,DIRECT,no-resolve
  - IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
  - MATCH,DIRECT

no-resolve doesn't disable DNS for the whole client. It prevents this type of IP rule from triggering an extra domain lookup just to check the match; if the connection already has a destination IP, the rule can still match against it. So an internal domain that eventually resolves to a private IP won't necessarily match this rule. If you know which domains should connect directly, add exact-domain or suitable domain-suffix rules above it rather than relying on private-range rules to behave the same way for every connection method.

Addresses, Domains, and What You Actually See

The target a rule sees depends on what the app passes to the core. One app may pass a domain name to the proxy, while another resolves it first and sends only an IP address. Seeing a domain in the browser's address bar doesn't prove the rule received it. IPv4 CIDR rules don't match IPv6 destinations either. If your environment uses both address families, check the actual destination for each in the connection details and add the rules you need. Don't rely on disabling one address family as your only troubleshooting step.

A single webpage usually makes requests to multiple destinations. A direct connection for the main page doesn't mean its fonts, images, login, and API requests also connect directly. To verify a change, make one request to a known destination, compare it with the rule log, and clear old connections. If the client shows the matched rule and proxy chain, note the target, match, group, and actual outbound proxy. This helps distinguish a rule mismatch from a bad group selection or a correctly routed request that the destination server didn't answer.

Move Long Domain Lists into a Provider

If several domains should use the same outbound proxy, manage their list with rule-providers and keep only the list reference and target in the main rules. The local file below uses the domain behavior, so it should contain domain entries, not complete comma-separated rules. The main config matches the list once with RULE-SET; the list provides the conditions, while the main config sets the target. To move complete rules with their types and match conditions, use the classical format supported by your core. Don't paste full rules with their proxy targets into a domain list.

rule-providers:
  office-domains:
    type: file
    behavior: domain
    format: yaml
    path: ./rules/office-domains.yaml

rules:
  - RULE-SET,office-domains,Office egress
  - MATCH,DIRECT
# ./rules/office-domains.yaml
payload:
  - 'example.com'
  - 'www.example.com'

Where a long list goes matters more than whether it's split into a separate file. An exception that should connect directly still needs to come before an overlapping RULE-SET; a rule set after the fallback will never match. Before using REJECT, test with an exact domain you're sure you don't need to access. A rejected connection can look like an ordinary network failure in the UI, so connection logs explain more than repeatedly switching proxy modes.

dns / 06

DNS Upstreams, Synthetic Addresses, and TUN

First Check Which Resolver Is Handling the Query

The core's dns settings control its own resolution behavior. Setting an upstream doesn't mean the operating system, browser, or every app sends queries to the core. A browser may use its own encrypted DNS; an app may resolve a domain before handing the connection to a proxy; the system may also have cached an earlier result. If “the upstream in the core config is set, but I'm getting a different result,” first identify how the test was made: through the system resolver, the core's DNS listener, or a proxy resolving the app's domain.

This example listens on a nonstandard port at a loopback address to make the query path easier to identify. Once enabled, you can explicitly query that port from an environment with dig installed. The example uses a public DNS service that must be reachable from your current network. Private internal domains usually still need the resolver provided by your organization. A response proves only that this query path got an answer; it doesn't prove the browser is using it or that the result works for every app.

dns:
  enable: true
  listen: 127.0.0.1:1053
  enhanced-mode: redir-host
  nameserver:
    - 223.5.5.5
dig @127.0.0.1 -p 1053 example.com A

Check App Domains and Proxy Server Domains Separately

nameserver lists upstreams for ordinary queries. To resolve a particular set of domains differently, Mihomo can use nameserver-policy to specify their upstream. First confirm that the upstream can answer queries for those domains, then add a suitably scoped match. If an organization's internal domain is sent to a public resolver, it's no surprise when no answer is returned. Check which resolver the system uses for direct connections instead of repeatedly adding similar public upstreams.

If an upstream is itself specified by a domain name, you also need a way to resolve the upstream server. default-nameserver resolves DNS server hostnames; proxy-server-nameserver resolves proxy server hostnames, helping separate the initial lookup needed to connect to a proxy from ordinary lookups. During troubleshooting, watch for circular dependencies: reaching a resolver may require connecting to a proxy, while finding the proxy's address depends on that resolver. Restore a working, independent DNS path first, then re-enable settings that route DNS queries by rule.

Synthetic Addresses Aren't the Server's Real Address

In fake-ip mode, the core can return a synthetic address for a domain and use its mapping to recover the original domain when the corresponding connection enters the core. An address in the 198.18.0.0/16 range in the logs doesn't mean a public website has moved there. This is a separate replacement settings block; don't append it after the earlier dns section and create a duplicate key. Use fake-ip-filter as needed for internal domains that must resolve to real addresses and have a verified compatibility issue.

dns:
  enable: true
  enhanced-mode: fake-ip
  fake-ip-range: 198.18.0.1/16
  fake-ip-filter:
    - '+.lan'
  nameserver:
    - 223.5.5.5

When switching DNS modes, an app with an old cached result may keep trying to connect to an outdated synthetic address. Have the affected app run a fresh lookup, then compare the DNS response with the connection log. If the same environment already uses this address range for testing or internal routing, check for conflicts. A failed lookup, a response that never reaches the core, and a connection that enters the core but takes the wrong route are different problems. You don't need to change upstreams, rules, and ports all at once.

TUN Handles Traffic Capture, Not Routing Rules

TUN captures traffic through a virtual interface; it isn't the same as entering a proxy port in an app. Before enabling it, confirm that the client has permission to create the interface and set routes. For a baseline, disable other connection tools that capture the same traffic. The example enables automatic routing and sends matching traditional DNS queries to the core; it doesn't automatically turn an app's own encrypted DNS requests into regular queries. If the client already manages TUN settings, check its generated runtime config instead of adding a second set of settings alongside them.

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

If the option is enabled but you can't see the target connection, check whether the interface was created, whether system routes point to it, and whether the platform excludes the app's traffic. If the connection is already in the logs, troubleshoot the rules or DNS instead of repeatedly toggling the virtual interface. If printing, file sharing, or an office connection stops working, disable TUN to restore access, then use a single target to determine whether routing or name resolution changed.

config.yaml / 07

Subscription Overrides, Field Merging, and Rollbacks

Separate Updatable Sources from Local Changes

Subscriptions provide proxies and rules that may change over time; local overrides are for settings such as ports, common exceptions, or DNS options suited to your setup. Avoid repeatedly editing the original file if every refresh will overwrite your changes. If the client supports overrides, first confirm whether they apply to all profiles or just one, then add only the fields you need to preserve. If it doesn't support overrides, you can copy the config to a local profile to experiment. Your changes will persist there, but the copy won't automatically receive future subscription updates.

Don't assume all clients use the same override syntax. Some editors accept full Mihomo YAML, some use client-specific merge instructions, and others allow changes to only a few settings in the UI. Even if a feature is called “merge,” check whether it replaces or preserves scalar values, merges maps by key, and replaces lists in full. If the core reports an unrecognized extension key, first check whether you selected an override file directly as the core config before concluding that a proxy is unavailable.

Compare Scalars, Maps, and Ordered Lists Separately

A port is a scalar, so the final config contains one value. dns is a map; some tools replace just one key, while others replace the entire block. For example, if the original config has nameserver and the upstream disappears from the runtime file after you override only enable, that merge didn't preserve the original map by key. For profiles with complex existing maps, export the effective values first, then decide whether to provide the whole map based on how the tool actually works.

Rules and proxy groups are both lists, but what matters when comparing them is different. Rule order determines priority; proxy groups also rely on names and candidate references. Suppose the original profile defines “Office egress” and uses the first rule block below. The second block shows the expected result if you want only www.example.com to connect directly. Both are valid core YAML for checking a merge result, not universal override instructions for every client. If the second block is appended after MATCH, the file may load, but the exception still won't take effect.

rules:
  - DOMAIN-SUFFIX,example.com,Office egress
  - MATCH,DIRECT
rules:
  - DOMAIN,www.example.com,DIRECT
  - DOMAIN-SUFFIX,example.com,Office egress
  - MATCH,DIRECT

If you see two proxy groups with the same name after an update, don't just keep the first one and stop there. Check whether a list append was used by mistake, then find out where each group's original candidates came from. You may need to replace one group by name, or just change one group's candidates. Similarly, if a proxy provider's path moves from the override directory to the runtime directory, its relative path may resolve differently. Check relative paths against the working directory the core actually uses.

Validate in Order: Resolution, Traffic Capture, and Matching

Before making changes, save a known-working snapshot and note the selected profile and mode. Afterward, check that the generated config contains the intended fields, then load it and look for parsing errors or port conflicts. Once it starts, test two destinations with the same connection method: one that should connect directly and one that should use a proxy group. Check the matched rule and outbound proxy for both. If the results are as expected, manually refresh the subscription and repeat the config check to make sure the change survives an update.

If the client crashes on launch or cuts off your network as soon as the new config loads, first undo the last override and restore a known-working profile. Then check that the system proxy or TUN isn't still pointing to a core that has exited. Once access is restored, retry with one minimal change and keep the first useful error message. Instead of replacing ports, DNS, and the entire rules list at once, identify which layer is failing. For log-based troubleshooting, see How to Fix a Client That Crashes on Launch and Common Troubleshooting Steps.