Clash Configuration File Reference

YAML structure, general settings, DNS, proxies, proxy groups, routing rules, and overrides.

For your first install, subscription import, and connection check, start with the Getting Started guide. This page is a field-by-field reference for what comes next: identify which section a field belongs to, what part of the traffic path it affects, and how to trace runtime behavior back to the configuration. Examples focus on fields supported by Mihomo; not every legacy Clash core or graphical client supports the same syntax. Ports, modes, and switches below are illustrative values. Check the active configuration on your device rather than treating examples as universal defaults.

YAML Structure: Inputs, Outputs, and References

Top-Level Keys and Nested Sections

mixed-port, mode, dns, proxies, proxy-groups, and rules are top-level keys with different roles. Port settings define how apps send requests to the core; proxies define available remote exits; groups organize those exits; rules route requests to a group, a specific proxy, or a built-in action. DNS settings control the domain lookup path. The order of top-level sections usually doesn't affect rule evaluation, but list order can be significant—never sort the rules list alphabetically.

When reading a file, check indentation first, then hyphens. The text before a colon is the key; the text after it is the value. In dns:, the indented enable is a child key. A path such as dns.enable is just a convenient way to refer to a field; you generally shouldn't copy it as a top-level key containing a dot. List items begin with a hyphen and a space. Proxies and groups are often mappings made up of multiple keys, while rules are usually one string per line. Similar-looking indentation doesn't mean the parsed types are the same: omit the hyphen before a rule and you may end up with a string instead of a list.

Start with a Baseline You Can Verify

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

proxy-groups:
  - name: Local
    type: select
    proxies:
      - DIRECT
      - REJECT

rules:
  - DOMAIN-SUFFIX,example.com,Local
  - MATCH,DIRECT

This file uses built-in actions only—no remote proxies or subscription required. Save it as a local test config and load it. In the group, select DIRECT, then REJECT. Each time, open a new connection to example.com through the same proxy entry point. The rule should always target Local, while the final action changes with your selection. Other addresses go direct through the final MATCH rule. This checks the links between the entry point, rules, and group; whether a public website is always online isn't a reliable test. Connection logs and match results are more useful than an old browser page.

When debugging your own subscription, map out a single reference chain: the app connects to a local entry point, the core matches a rule, the rule names a target, and that target may reference a proxy or another group. Don't confuse a proxy server's address with the system proxy address, or a group name with a protocol. For example, if you rename Local to Local-Test, update the third field of the rule too. Changing the config title shown in the UI won't automatically update references in the YAML.

A Successful Parse Doesn't Guarantee the Right Traffic Path

Use spaces for indentation, never tabs. Don't repeat the same key within a mapping; different loaders may report an error or keep only the later definition. Preserve arrays and mappings as their original types, use true or false for booleans, and write ports as integers. Quote values that should be strings if they look like numbers or booleans, or contain characters that YAML might interpret as syntax. In the right context, # starts a comment. Put notes on a separate line to avoid changing the value by mistake.

After saving, check three things: first, that the YAML parses; second, that the core loads it; and third, that requests take the expected path. A general YAML validator can catch indentation problems but may not know that a group name doesn't exist. A successful core load doesn't guarantee the client is using the file you just edited. If the first two checks pass but traffic hasn't changed, confirm that the config is selected and reloaded, and check whether the UI's mode setting overrides the file. Keep a working baseline and change one category at a time so you can identify which change caused a problem.

General Settings: mixed-port, Listening Address, and Mode

First, Check Which Entry Point the App Uses

mixed-port: 7890 provides HTTP and SOCKS proxy access on a single local port. port is a dedicated HTTP proxy port, and socks-port is a dedicated SOCKS proxy port. You don't need to fill in all three to enable a mixed port. If an app has separate server and port fields, use the loopback address and active port for local access—not the subscription server address. Choose HTTP or SOCKS to match the protocol the app actually uses; entering the right number won't fix a protocol mismatch.

mixed-port: 7890
allow-lan: false
mode: rule
log-level: info
FieldPurposeWhat to Check After Changing It
mixed-portA shared HTTP and SOCKS entry point.Whether the system proxy or app still points to the old value.
allow-lanWhether other devices can connect to the proxy.The actual listening address, access scope, and firewall rules.
modeSwitch between rule, global, and direct modes.The current value in the UI and the path taken by new connections.
log-levelAdjust the core's log verbosity.Whether logs show this reload or connection.

Before changing a port, check which process is using the old one. If the core log says the address is already in use, another client may still be running in the background, or the client may have started a second core instance. Don't point the system proxy at an arbitrary free port. Make sure the core is listening successfully, then update the system proxy and app settings to match. Conversely, if the core is listening but the browser connects directly, check whether the browser uses a proxy, has its own bypass list, or has been set to go direct. The system proxy only provides an entry point to apps that follow that setting; it doesn't capture traffic from every app.

Listening Scope and Traffic Capture Are Different Things

allow-lan: false is suitable when the config is for this device only. Enable LAN access only when devices on the same trusted network need to connect, and restrict the scope with supported listening addresses, authentication, and the host firewall. The client's control interface and proxy entry point are separate; opening the proxy doesn't require exposing the management interface to the LAN. Another device can't reach this host through its own loopback address. Check the target host's LAN address and make sure the network doesn't isolate devices. Close any temporary access when testing is done.

TUN captures traffic through a different path. It involves a virtual network interface, routes, and platform permissions—not the HTTP proxy settings in an app. Support depends on the platform, core, and frontend. If the system proxy works but TUN doesn't, first check whether the virtual interface was created successfully and whether its routes overlap with an existing VPN or network configuration. Then check DNS capture. Avoid changing ports, routes, and DNS all at once; even if that restores connectivity, you won't know which change fixed it.

mode Determines What Happens Inside the Core

rule routes traffic by matching rules; global uses the exit selected in the global group; direct sends connections that reach the core directly. Global mode doesn't create an entry point for apps that aren't connected to the core, and direct mode doesn't disable the system proxy. To use global mode as a comparison, confirm the global group is set to the exit you want to test, compare new connections to the same destination, then switch back to rule mode. For more on the differences, see Rule, Global, and Direct Modes Compared.

Some platform clients store their own port, log level, or mode settings and write them back to the runtime config at startup. If a manual YAML change reverts, check for a UI setting that may be taking precedence before reinstalling. If the current client doesn't provide a setting you need, check the platform options on the download page. Clash Plus is available on platforms with a listed installer; for Linux, use the downloads listed for that platform. Before switching clients, save a working config and avoid running two instances that try to manage the same entry point.

DNS Settings: Enhanced Modes, Upstreams, and Resolution Paths

dns.enable and enhanced-mode

dns.enable: true enables the DNS module in the config; enhanced-mode: fake-ip selects an enhanced mode. Enabling the module doesn't mean the system and every app will send queries to it. System proxy, TUN, an app's own encrypted DNS, and LAN forwarding can all use different paths. To investigate unexpected DNS resolution, first specify the device, app, and traffic capture method, then check which resolver handled the query. Seeing the name of a public resolver alone doesn't tell you whether the query came directly from your device or was resolved remotely.

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

Here, system is an example upstream using the system resolver in Mihomo versions that support this setting. It doesn't specify a separate public DNS server. If another component forwards queries to the system resolver, make sure it won't send them back to the core and create a loop. This example also doesn't configure a separate DNS listening address. If you want the core to act as an explicit DNS server, check its listening address and firewall scope separately; enable: true doesn't mean the service is exposed on any particular address.

In fake-ip mode, the core can return a virtual address mapped to a domain, then use that mapping to restore the destination when the connection reaches the core. Seeing an address from this range in a test doesn't mean the website's real address has changed. If an app keeps the virtual address but the subsequent connection bypasses the core—or the core restarts and loses the mapping—DNS can appear to succeed while the connection fails. For a comparison, create a new connection and account for cached results in the app and operating system. redir-host generally returns the real resolved address. Switching modes isn't a universal fix for DNS problems.

Separate Regular Queries, Exceptions, and Proxy Hostname Lookups

nameserver lists regular upstream resolvers; nameserver-policy can route specific domains to different resolvers. Cores that support proxy-server-nameserver can also use a separate resolver for proxy server hostnames. This matters when a proxy server is configured by hostname: if resolving that name requires connecting through the same proxy that hasn't started yet, you create a dependency loop. Before making changes, list which upstreams use hostnames, how their initial connections are established, and which resolver handles proxy server names. Don't send every kind of query down the same path by default.

fake-ip-filter controls when virtual addresses are returned; it isn't an access-control list or a proxy routing table. Adding a LAN service domain to the exceptions may help an app that needs the real address. Whether that address is reachable still depends on whether the upstream knows it, whether the device has a route to it, and which exit the rule selects. First confirm the service has a usable DNS record on the network, then keep the exception as narrow as possible. Broad exceptions for all domains change the behavior of enhanced mode across the board and make it harder to identify which apps actually need special handling.

How to Check for a DNS Leak

Start by defining what you expect. For example, internal domains should use a specific internal resolver, or a particular app's public DNS queries shouldn't follow the default resolution path on the network you're connected to. Repeat the test in the same app and check whether the core received the domain, whether it used the expected upstream, and whether the app has Secure DNS enabled. A browser test page only describes queries from that browser; it says nothing about the rest of the system. Command-line tools may bypass the app's actual path if you specify a resolver directly. Record the proxy mode, TUN status, and query results so you don't mix results from different setups.

Proxy Fields: Protocol, Address, and Transport Settings

name Is a Reference; server Is the Connection Address

proxies is an inline list of proxy definitions. A proxy's name is referenced by groups and rules; type tells the core which protocol to use for the remaining fields; server and port specify where the proxy server is listening. A graphical client may show an icon, alias, or note for a proxy, but connections use the active config fields. The proxy server port and the local mixed-port serve different parts of the traffic path—even if the numbers match, they're not linked. Keep names unique within a config and avoid reusing group names or built-in action names.

proxies:
  - name: Local-SOCKS
    type: socks5
    server: 127.0.0.1
    port: 1080

proxy-groups:
  - name: Route
    type: select
    proxies:
      - Local-SOCKS
      - DIRECT

rules:
  - MATCH,Route

Add this snippet to the minimal baseline to reference a SOCKS5 service already running on the local device. It won't start that service. If nothing else is listening on loopback port 1080, a connection will fail when you select Local-SOCKS. Don't point it back to the same core's proxy entry point, or you'll create a self-reference. Select DIRECT to check whether the proxy upstream is the cause. An app using this example must still send requests to a separate local entry point configured in the core; don't confuse the upstream proxy address with that entry point.

Protocol-Specific Options Aren't Interchangeable

Different proxy types use different authentication fields and transport settings. HTTP and SOCKS5 may support user authentication; other types may require protocol-specific IDs, encryption settings, or handshake parameters. Use the original values from the server or subscription. Copying fields wholesale from a different proxy type—or changing only type—won't make the core and server use the same handshake. When converting a config with an import tool, check that integers, booleans, nested mappings, and strings retain their original types.

TLS-enabled proxies also depend on the connection address and certificate identity. The address tells the client which server to contact; settings such as the server name may be used in the TLS handshake. Some fronting services also route traffic based on a hostname or request path outside the transport layer. These values may sometimes match, but they're not interchangeable. For certificate errors, first check the system clock, the server name required by the proxy, and the certificate actually presented. Don't treat disabling certificate verification as a permanent fix. If the connection is established but the service rejects the request, check the path, authentication, and whether the server accepts the configured protocol.

Separate Import Problems from Connection Problems

If a proxy doesn't appear in the UI at all, first check whether the config loaded, the source updated successfully, the group references that source, and filters didn't exclude the proxy. If it's visible but unusable, check hostname resolution, destination port reachability, the protocol handshake, and the actual request separately. A UI test result reflects one specific request; it can't by itself explain an authentication failure, an unreachable address, or unsupported traffic. Reviewing logs around the time the proxy was loaded is more effective than cycling through many proxies.

Subscriptions may also provide proxies through proxy-providers. In that case, not every proxy will appear under the top-level proxies key; groups usually reference a source with use. The source name and proxy name are separate reference levels. If proxies disappear after an update, check whether the source failed to load, filters excluded them, or the upstream changed their names. Compare group members before and after, and don't post a full config containing credentials publicly. If every proxy fails, use the Proxy Timeout Troubleshooting Checklist to rule out shared causes such as the subscription, system time, entry point, and network.

Proxy Group Fields: select, url-test, and fallback

Choose the Group's Role Before Its Type

proxy-groups is a list of proxy groups. select lets the user choose and works well for manual comparisons or a fixed exit. url-test selects a member based on checks against a specified URL. fallback uses member order as priority, choosing the first available candidate. Automatic groups don't combine multiple connections into one faster connection. If you want one exit preferred, with another used only when it fails, fallback is more direct than trying to simulate priority by adjusting test latency.

proxy-groups:
  - name: Manual
    type: select
    proxies:
      - DIRECT
      - REJECT

  - name: Probe
    type: url-test
    proxies:
      - DIRECT
    url: 'https://example.com/'
    interval: 300
    tolerance: 50

  - name: Preferred
    type: fallback
    proxies:
      - Manual
      - DIRECT
    url: 'https://example.com/'
    interval: 300

rules:
  - DOMAIN-SUFFIX,example.com,Preferred
  - MATCH,Manual

This example deliberately avoids remote subscriptions. Probe has just one member so you can check the probe settings; it won't compare real proxies. Preferred shows how a group references members and how their order matters. In a real config, replace built-in actions with proxies you know are available. Use a lightweight test URL that each candidate can reach and that permits periodic requests. In this example, interval: 300 sets the probe interval in seconds; tolerance: 50 sets a 50 ms threshold for automatic latency comparisons, reducing switches caused by minor fluctuations. After saving, check how the core handles the group. A single reading in the UI doesn't tell you when it will switch.

Evaluate Test Results in Context, Not Just by the Number

Probes only reach the test URL specified in the config. The DNS lookup, connection, handshake, and response may differ from those for real traffic. A proxy may respond quickly to a lightweight test but have limited throughput for a long download. Or it may be excluded from automatic selection because the test domain isn't reachable on that route. Compare the same test URL first, then use a real request to compare. For more on what latency tests can and can't tell you, see Latency Test Results vs. Real-World Speed.

Groups with their own probe URL and health checks run by a proxy provider may use different settings and schedules. A provider showing a healthy status doesn't mean a group referencing it will select members under the same conditions. Check whether the UI is showing a manual proxy test, a group probe, or a provider health check, and compare their URLs and intervals. Frequent probes create extra network traffic and can wake mobile devices more often. Use manual tests temporarily for troubleshooting; frequent long-term probing won't fix connectivity.

Check References and Selection Persistence

Inside a group, proxies lists member names; this isn't the same as the top-level key that defines proxies. Members can be built-in actions, proxy names, or references to other groups. use lists provider names. Avoid circular group references. If a group appears empty, check whether its source loaded, whether filters left any members, and whether the frontend is showing the active config. Nested groups can separate manual choices from automatic policies, but with too many levels the UI may show only the parent group. Trace the full chain to find the final exit.

If a reload keeps the last selected member, that doesn't necessarily mean YAML order was ignored; the frontend or core may persist selections. To check ordering or automatic switching, note the current manual selection and test with a new connection, not an existing one. Long-lived connections often stay on their original path after a group selection changes. If the group name, references, and availability all look right but traffic still takes the wrong route, check which rule matched. Changing group order won't help if an earlier rule sends the connection elsewhere.

Rule Syntax: First Match Wins, Then the Fallback

Rules Are Evaluated Top to Bottom, Not Reordered by Specificity

rules is a list of routing rules. A typical entry has a type, a matching value, and a target; some types also take additional parameters. DOMAIN matches an exact domain, DOMAIN-SUFFIX matches a domain and its subdomains, IP-CIDR matches an address range, and GEOIP relies on geographic data. MATCH takes no matching value and usually belongs last. The core uses the first rule that matches. If a broad rule comes before an exception, later, more specific rules never get a chance to run.

rules:
  - DOMAIN,blocked.example.com,REJECT
  - DOMAIN-SUFFIX,example.com,DIRECT
  - IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
  - MATCH,DIRECT

Replace the baseline rules with this snippet. A new request to blocked.example.com should match the first rule when the domain is visible to the core; other requests under the same suffix can match the second. The final direct fallback makes it easier to test without remote proxies; it doesn't mean a production config should default to direct. To use a custom policy, first define the relevant proxy or group in the same config. Note that the example address range covers only one common private range; it isn't a complete list of local or private networks.

TypeWhat It MatchesCommonly Overlooked Condition
DOMAINExact domain.The request may not expose its domain to the core.
DOMAIN-SUFFIXDomain suffix.Put narrower exceptions first.
IP-CIDRDestination address range.May involve DNS resolution; check the address family.
GEOIPGeographic data for the destination IP.Doesn't identify a region from the domain suffix.
MATCHRequests not matched by earlier rules.If placed too early, it overrides the rules below.

Domain Names and Destination Addresses Aren't Always Available Together

Rules only apply to traffic that reaches the core with the information they need. When an app connects directly to an IP address, the core may not know which domain it originally belonged to. Apps using the system proxy may pass the hostname to the proxy or resolve it first and pass only the address. Whether a domain can be recovered through sniffing also depends on the protocol and the data actually visible to the core. If a domain rule doesn't match, check the host or address in the connection log before adding an IP rule. Don't broaden the domain suffix just to see what happens.

no-resolve prevents an address rule from triggering an extra DNS lookup for that match. The rule can still use a destination address that's already available. It doesn't disable DNS globally or make a domain match an address range without an address to compare. If a domain hasn't been resolved and there's no destination address, the rule may be skipped and evaluation can continue with later rules. For GEOIP, also confirm the core has usable geographic data and that the destination falls into the expected category. A site may use multiple addresses or serve traffic over different networks; assumptions about its location can't replace checking the match log.

Treat Rule Sets as Config Items with Dependencies

rule-providers supplies external rule sets; RULE-SET references them by name in the main rules list. The source format and behavior must be compatible with the core and the rule set's contents; a file extension alone isn't enough to tell. After importing, confirm the source loaded and check where its reference appears in the main list. The same rule set can produce different results depending on whether it comes before or after a precise exception. Refreshing a source may also change its coverage. When troubleshooting a domain, record the matched rule and source instead of comparing only the UI state on two different dates.

A webpage usually opens multiple connections. The main page, login, images, and APIs may use separate domains; matching the main domain to one policy doesn't automatically send them through the same exit. If part of a page fails to load, identify the specific failed request. In rule mode, check a new connection to the same domain and note the matched rule, group, and final exit. If the failing rule isn't in the config you see, check the merged config the client is actually using. Existing connections, caches, and mode changes can also make behavior appear inconsistent with the file.

Overrides and Merging: From Subscription Source to Active Config

Tell Apart the Subscription, Overrides, and Runtime Config

The subscription source is upstream input; overrides are locally maintained changes; the runtime config is the result after the client applies its settings and merges everything for the core. Many changes that seem to disappear were made to a cache or runtime copy that gets replaced on subscription refresh, not to a persistent override. Before editing, confirm which layer the UI editor changes and keep a working local copy. If the frontend can't export the merged result, at least record the active config, override location and scope, and load logs. Don't mistake a preview for the config currently in use.

Scalars, mappings, and lists don't all behave the same way. A scalar is usually replaced—for example, changing the mode string. A mapping may merge key by key or be replaced entirely. Whether adding a nested definition for dns.enable preserves existing upstreams depends on the merger. Lists may be replaced, prepended, or appended. All three can look like “adding an item,” but produce different results in a first-match rule system. Use override keys such as prepend-rules only when the current client explicitly supports them. They aren't universal top-level fields for every core.

Check the Merged Output to Confirm Order; Don't Guess How Merging Works

Suppose a subscription has two rules and you want to add an exact-match exception. The example shows the input and desired output without assuming that all clients use the same override syntax. If the editor supports prepending rules, add the exception and inspect the result. If it only supports replacing the full array, provide the complete target list and expect to maintain it as the subscription changes. Either way, keep the final fallback.

# Rules in the subscription source
rules:
  - DOMAIN-SUFFIX,example.com,DIRECT
  - MATCH,DIRECT
# Expected merged result
rules:
  - DOMAIN,blocked.example.com,REJECT
  - DOMAIN-SUFFIX,example.com,DIRECT
  - MATCH,DIRECT

If the editor appends the exception at the end, the fallback will match first. If it places the exception after the suffix rule but before the fallback, the suffix rule will still match first. If you also need to override group definitions, check whether the merger edits a group by name or replaces the entire group list. In the latter case, submitting one group with the same name may not update just that group; it could remove all the others while existing rules still reference them. Test a single-field change first, compare the before-and-after output, then decide how to maintain larger local changes.

Validate and Roll Back in Steps

Keep changes to rules, DNS, and entry points separate so you can identify which layer caused a problem. First confirm the config works without overrides. Then enable one change at a time, check that the core reloads, and compare one affected connection with one that should stay unchanged. Next, refresh the subscription and compare again. Watch for group names changed upstream, missing sources, DNS child keys replaced wholesale, and the frontend writing port settings back automatically. Some problems don't appear on the first save; they may surface only after a subscription update or client restart.

If startup fails, disable the most recent override and reload a known-working config. Keep the first clear error as a clue. If the core starts but connections fail, compare the current mode, app entry point, and matched rule, and make sure multiple components aren't changing network settings at once. Before quitting the client, restore any system proxy settings it applied and verify that apps can connect directly as expected on the current network. For detailed first-time import and setup steps, see the Getting Started guide. If you're unsure how the core differs from the frontend, check the Glossary.

Why Does the Panel Still Show the Old Value After an Override Change?

First check whether the panel shows the subscription source, the client's own setting, or the core's current runtime value. Then confirm the override is enabled for the active config, the merge completed without errors, and the client has reloaded.

How Can I Tell Whether an Override or the Subscription Is Causing the Problem?

Temporarily disable the override in the same client and on the same network, reload the original subscription, and create a new connection. If that fixes the issue, re-enable overrides one at a time and compare results. If the problem persists, check the subscription update, entry point, and core logs first.