CONFIG.YAML / FIELD GUIDE

Clash Configuration File Field Reference

From YAML loading to rule matching: field types, references, and scope.

Getting Started covers importing a config and verifying your connection. This page is a field-by-field reference for syntax and troubleshooting. If you don't have a working config yet, start with the guide; for port, DNS, or routing issues, use the sections below. This reference uses mihomo as its baseline. Client UI options and override behavior depend on the product.

01 YAML / STRUCTURE

YAML Structure, Field Types & References

Start with the top level, then trace the traffic path

A Clash config is a top-level mapping, not a sequence of commands executed in file order. Think of its top-level keys as an index: ports and mode determine how requests enter the core; DNS settings control how its resolver answers queries; proxy entries describe outbound connections; proxy groups define available exits; and rules route connections to those exits. Moving the rules section to the top of the file won't make rules run before the core initializes. Moving a rule to the top of its list, however, can change routing. When comparing two files, distinguish the position of top-level keys from the order of items within a list.

mixed-port: 7890
allow-lan: false
mode: rule
log-level: info
proxies: []
proxy-groups:
  - name: Manual Exit
    type: select
    proxies:
      - DIRECT
rules:
  - DOMAIN-SUFFIX,example.org,Manual Exit
  - MATCH,DIRECT

This complete example has no remote proxies, making it useful for checking that the file loads and the local listener works. When a rule matches the target domain, it first tries to send the connection to the group named “Manual Exit”; that group contains only DIRECT, and the final rule sends other requests direct as well. If a webpage loads during this test, it only confirms that the direct route works—not that you're connected to a proxy server. To verify that a specific rule matched, check the client's new connection log instead of inferring the route from whether the page loaded. If another proxy app is using the example port, choose an unused port and point the test app to the same port.

Distinguish Fields with the Same Name at Different Levels

The same key can mean different things at different levels. Top-level proxies is a list of proxy objects, while proxies inside a proxy group is a list of member names. Each item in the first is a set of properties; each item in the second is a name. If you indent proxy objects under a group's members by mistake, the YAML may still be valid, but the core can reject it because the field has the wrong type. After renaming a group, also search for references to it in other groups and rules. Changing the definition without updating references can make a previously loadable config unusable.

FieldData ShapeWhat to Check When Editing
mixed-portIntegerDoes it match the actual client listener?
dnsMappingAre all keys indented under the same parent?
proxy-groupsList of objectsCan the name and all members be referenced?
rulesList of stringsDoes the list order match the intended precedence?

Check syntax, config validation, and runtime behavior separately

For syntax errors, check indentation, quotes, and list markers; for field errors, check types and references. Indent with spaces, not tabs. Align sibling fields under the same parent, and leave a space after each list-item hyphen. Quote string values that contain a hash that could be read as a comment, or a colon followed by a space. Keep ports and boolean switches in their proper types; quote only values that are meant to be strings. When copying formatted text, watch for full-width colons and curly quotes: they may look similar, but they aren't valid substitutes for YAML syntax characters.

The line number in a config error marks where the parser detected a problem, not necessarily where the mistake began. If a line reports a missing key, check the preceding item for an unclosed quote or a child item missing an indentation level. Once YAML parses, check for duplicate top-level keys, conflicting names, and unknown references. Two copies of a rules key in one mapping don't mean the core will combine their lists; depending on the parser, one may be rejected or overwritten. Keep each key in a given mapping in a single place.

Finally, verify at runtime that your changes were made to the config that's actually in use. A client may show a downloaded subscription copy while loading a different local config; it may also keep using the previous config if the new one fails validation. Note the active config name, when it was applied, and the match result for a new connection, then compare them with what you expected. Existing connections may keep using the exit they were established with, so start a new request after switching configs. For a first-time file or subscription import, follow the config import steps to confirm what's active before troubleshooting individual fields.

02 INBOUND / MODE

Common Fields: Ports, Listeners & Modes

First, identify the local listener the app connects to

A listener port handles the hop from the app to the core; it isn't the proxy server's port. port is for an HTTP proxy, socks-port is for a SOCKS proxy, and mixed-port accepts both inbound protocols on the same port. When troubleshooting, start with a single listener to make problems easier to isolate. If your browser or system proxy uses HTTP, its address and port must point to an HTTP or mixed listener; use a SOCKS listener only for apps that support SOCKS. If an app has both an automatic configuration URL and a separate manual proxy setting, first check which one it's actually using.

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

This example keeps the mixed listener available to the local machine. A client's system proxy feature usually just points the operating system to the core's address; it doesn't mean every program will use it. Some apps have their own network settings, some services read proxy addresses from environment variables, and others connect directly. To check whether an app is using the proxy, send a new request and look for its destination in the client's connection view. If there's no connection entry at all, check the app's proxy settings, system exclusions, and listener port before changing proxy groups.

Rule out listener conflicts before changing the bind address

Two listeners of the same kind can't freely share the same address and port. Assigning the same port to both an HTTP listener and a mixed listener, or having two clients claim the same port, can cause a bind failure. If startup logs say the address is already in use, first identify whether the failed listener is the mixed proxy, controller, or built-in DNS—not a proxy node. Once you find what's occupying it, disable the unused listener or choose a free port for this config, then update the proxy address saved in the OS and apps.

For local use, keep allow-lan: false. If you need to share access on your LAN, separately check the permitted range, bind address, and firewall rules, and verify the source of connections on a trusted network. Also distinguish external-controller from the proxy listener: the controller lets a dashboard or app manage the core, while the proxy listener receives requests. A dashboard connecting to the controller only confirms that the control channel is reachable; it doesn't prove the proxy port is listening. On public networks or anywhere the access scope is unclear, keeping both management and proxy listeners local makes access easier to control.

Mode controls rule processing, not which apps reach the core

Rule mode routes connections that enter the core according to the rule list. Global mode uses the exit selected in the global group instead of matching ordinary rules one by one. Direct mode sends regular proxied traffic that enters the core straight out. These modes change the core's internal routing; they don't automatically turn proxying on or off for apps. You can briefly switch modes to compare behavior: if a request works in Direct mode but fails through a selected exit, check that exit and its DNS dependencies. If only Rule mode picks the wrong exit, check the matching rule and group selection. Restore the original mode when testing is done so you don't assume rules are still active.

Choose a log level to answer a specific troubleshooting question. Keep it detailed enough to identify startup failures during normal use; raise verbosity temporarily when tracing a connection, and narrow the test scope. Open one target at a time and note when you tested it. Distinguish startup errors, inbound connections, DNS resolution, and outbound dialing. If the route looks normal but a page is still slow, separate the initial connection from later transfers over an established connection; a single log entry isn't enough to blame a port. Before sharing logs, remove subscription URLs, internal hostnames, and account-related fields. Keep only the error type and necessary port details.

03 DNS / RESOLUTION

DNS Configuration: Upstreams, Bootstrap Resolution & Fake IP

First, identify where the query originates

dns.enable enables the core's DNS module; it doesn't change DNS for the entire system. An app may query the OS first and pass the resulting address to the proxy listener, or it may send the target domain directly to the core. Some apps also use their own encrypted DNS, bypassing the system default. When troubleshooting, record separately which component made the query and which resolver answered it. A webpage loading doesn't prove every app used the same upstream; likewise, getting an IP address doesn't mean a connection to it succeeded.

dns:
  enable: true
  enhanced-mode: redir-host
  default-nameserver:
    - 1.1.1.1
  nameserver:
    - https://cloudflare-dns.com/dns-query
  proxy-server-nameserver:
    - 1.1.1.1

This example uses redir-host to return real addresses, sends regular queries to encrypted DNS, and explicitly separates the bootstrap upstream from the one used to resolve proxy nodes. It requires the local machine to reach the example resolvers; on a managed network, replace them with upstreams approved by your administrator and reachable over your current connection. default-nameserver primarily bootstraps resolution when the resolver itself is specified by hostname. If an encrypted DNS server is specified by hostname but relies on encrypted DNS that hasn't connected yet to resolve itself, you can create a loop. A numeric bootstrap address that's independently reachable breaks that dependency from the main resolution path.

Regular domains and proxy-node domains may use different resolution paths

nameserver is the default DNS upstream; nameserver-policy lets you choose different upstreams for specific domains; and proxy-server-nameserver resolves proxy server hostnames. When a node is specified by hostname rather than IP address, the core must resolve it before it can establish a connection. If that lookup is routed through a node that isn't connected yet, the first connection can stall. To diagnose this, first verify that the node's hostname resolves through an independent path, then check whether the resulting address is reachable. Repeatedly changing the regular upstream can miss the separate node-resolution step.

For internal services, route specific domain scopes explicitly instead of sending company hostnames to public resolvers and hoping for the best. Internal and external DNS servers may return different views of the same name; a public resolver returning no record doesn't mean an internal record doesn't exist. After changing domain policies, test one internal and one external hostname and check that each resolves as expected. When switching networks, the internal DNS server you used before may no longer be reachable. If both internal and external names fail, first restore a minimal working config, then add routing policies one at a time rather than replacing every upstream at once.

Fake IPs are mapped addresses, not a service's real address

In fake-ip mode, queries return synthetic addresses. When the core receives a connection to one of these addresses, it uses the mapping to recover the original domain. For this to work, connections from the app that received the synthetic address must return to the core that owns the mapping. If a request leaves that interception scope, or the OS has cached an address from before the config changed, the app may get an address that can't be routed normally. For local device discovery or internal services that stop working, first check whether synthetic addresses are suitable for that use case. If needed, use fake-ip-filter to return real records for specific names rather than exempting every domain.

After switching enhanced mode, use the same app to make a fresh query and connection so cached results don't hide the difference. Check three things separately: whether the query gets an answer, whether the connection is associated with the right domain, and whether the rule selects the expected exit. If the first fails, check upstream reachability; if the second fails, check the app's DNS source and interception scope; only check rule order if the third fails. If the logs show a DNS timeout first, the later connection error in the browser is just a downstream symptom. If you're also troubleshooting nodes or the system proxy, see the layered troubleshooting order for proxy timeouts to narrow down each step.

04 PROXIES / OUTBOUND

Proxy Node Fields & Connection Boundaries

Separate a node's display name from its connection parameters

A proxy node is a set of parameters for an outbound connection. name is its reference name in the config, type selects the protocol, and server and port specify where to connect. Use a recognizable name, but make sure it matches references in proxy groups and doesn't conflict with another exit's name. Renaming a node won't change the remote server or fix a connection failure. Conversely, replacing the remote parameters while keeping the name usually leaves group references intact. Before editing, decide whether you're changing the display name or the actual connection details.

proxies:
  - name: Local Test Exit
    type: socks5
    server: 127.0.0.1
    port: 1081
    udp: false
proxy-groups:
  - name: Node Check
    type: select
    proxies:
      - Local Test Exit
      - DIRECT
rules:
  - DOMAIN-SUFFIX,example.org,Node Check
  - MATCH,DIRECT

This example depends on a separate SOCKS5 service already running on the local machine and accepting connections on the example port. It's not a built-in proxy node and won't start a service. If you don't have one, keep DIRECT for comparison or replace the node with a proxy you are authorized to use. Don't set the server port to this config's own mixed listener; that sends outbound traffic back to its inbound listener and isn't an independent test path. After applying the config, select the test exit in the group and visit the example domain. This avoids mistaking a saved DIRECT option in the group for a working proxy node.

Check protocol, transport, and authentication separately

Don't infer protocol-specific fields from their names. Some protocols use a username and password; others require protocol-specific identifiers. Some enable TLS at the transport layer, and others need transport options that match the server. Start with the field list provided for the node's protocol, then check the address, authentication method, and transport settings. Reaching the server only confirms that the address and port are accessible; it doesn't prove authentication succeeded. If the logs point to a handshake or authentication error, check the name, time, and server certificate configuration rather than hiding the error by disabling verification.

The dial address and the server name used for certificate matching may differ. If the server requires a specific name, set it using the field supported by that protocol; the node's display name is not the handshake name. Likewise, a transport path isn't a subscription URL: a subscription URL retrieves the full config, while the path is part of the node's connection parameters. They affect different things. Check the actual config after a normal import, rather than pasting an encoded share-link string into a field that doesn't accept that format. When comparing configs, compare like-for-like fields within the same protocol.

Use a single exit to separate network failures from selection issues

Test UDP separately. A UDP-enabled field describes the core's outbound behavior; it doesn't guarantee that the proxy server, underlying transport, and target app all support the same traffic. A webpage working over TCP doesn't prove that voice or real-time apps will work. Conversely, treating one failed UDP test as proof the whole node is broken can lead you to disrupt working web traffic. First use a single manual group to confirm basic outbound connectivity. Then use an app that actually sends UDP and inspect its new connection entry, noting the protocol, destination, matched rule, and selected exit. A single browser speed test can't verify the entire path.

If a node fails to load, keep one minimal reproducible entry. If the group appears but a connection fails, check the parameters based on where the error occurs. A DNS failure may involve the node's hostname; a refused connection points more toward the port or service state; a handshake timeout may still involve the network path or transport settings. No single symptom proves the cause. Before removing a node, search for its name in all groups and rules. To check whether the client includes the required core, see the Download Center. For each platform, look first at Clash Plus, our top pick, then check which fields the product actually supports.

05 PROXY-GROUPS / SELECTION

Proxy Group Types, Members & Health Checks

Proxy groups select exits; rules determine which group handles a connection

A rule sends a connection to an exit or proxy group; the group selects the actual exit from its members. If a rule matches correctly but the connection takes the wrong path, check both the matched group name and its current selection. Start by testing a real node in a single manual group, then add automatic groups. Nesting several automatic groups from the start makes health status, test results, and user selection affect behavior at once, making it hard to explain which node handled a connection. Choose group names that describe their purpose, such as “Work Connections” or “Backup Exit,” rather than using node names that may change after an update.

proxy-groups:
  - name: Auto Exit
    type: url-test
    proxies:
      - Local Test Exit
    url: 'https://example.org/'
    interval: 300
    tolerance: 50
  - name: Manual Entry
    type: select
    proxies:
      - Auto Exit
      - DIRECT

Use this as a replacement for the entire top-level proxy group list; don't append a second top-level key with the same name to the existing file. The nodes come from the previous section. If you reuse its rules, also change “Node Check” in the rules to “Manual Entry.” Only one node is included to demonstrate the syntax, so there's no switching among candidates. The test URL is for illustration; in production, choose a lightweight, stable URL with a predictable response that's reachable through every candidate path. The automatic group's probe requests that URL. It doesn't measure one-way latency from your computer to the node server or indicate how other business sites will perform.

Choose a group type based on how you want to switch exits

TypeSelection BasisUse Case
selectUser selectionManually choose a route or pin an exit for troubleshooting
url-testProbe results and toleranceCompare probe responses across candidates
fallbackMember order and availabilityPrefer the primary exit and use a backup if it fails
load-balanceLoad distribution strategyDistribute connections across available members

When you need a fixed primary exit, use fallback to express priority; it isn't a fastest-node selector. To compare candidates by probe results, use the url-test tolerance to avoid switching exits over minor differences. Set tolerance in milliseconds and interval in seconds. Testing too often adds probe traffic; testing too infrequently can delay detection of changes. Observe real-world variation at different times before adjusting these fields. There's no need to rewrite the entire group based on a single probe.

load-balance distributes connections; it doesn't split a single download across multiple nodes. Apps that require session affinity can be sensitive to changes in exit, so route them through a fixed group rather than sharing a rotation policy with other connections. Before choosing between strategies, decide whether you need primary/backup priority, connection affinity, or even distribution, then see a comparison of automatic proxy group types and fields. Before and after changing groups, make new connections to the same destination and compare results over several attempts. Existing connections aren't a reliable way to verify a switch.

Keep group references one-way

Groups can include other groups, but they can't reference themselves, directly or indirectly. A straightforward structure is to have a rule-facing entry group reference a lower-level automatic group, which in turn references nodes. When a proxy provider supplies members, the group's use field references the provider name, not the name of a node within it. If a group starts with no selectable members, first check that local definitions and references exist, then confirm the provider loaded and filters haven't removed every member. Only then check for failed probes. A group with no defined members is a different problem from one whose members all exist but are unreachable.

When an automatic group behaves unexpectedly, first test the same candidate against the same target URL in a separate manual group. If the manual connection fails too, troubleshoot the node path first. If normal traffic works but the probe fails, check whether the target site restricts probes, whether it returns an unexpected response through that exit, and whether the probe has run. Some clients retain the last manual group selection; changing YAML doesn't necessarily make the UI switch back to the first item. Record the candidate order, actual selection, and probe time each time so you can distinguish config changes from runtime state retained by the client.

06 RULES / MATCH ORDER

Rule Syntax, Match Order & Fallbacks

Match specific scopes first, then broaden the scope

In Rule mode, rules are processed from top to bottom, and the first match determines the exit. Put exact-domain rules before suffix rules that cover them, and narrower IP ranges before broader ranges that include them. The goal isn't to add as many entries as possible, but to make scope and priority easy to understand. Before adding a rule, check whether an earlier, broader rule already covers the same target. If it does, put the new exception before it. An exception added after the final catch-all may load successfully but won't route traffic as intended.

mode: rule
proxy-groups:
  - name: Docs Exit
    type: select
    proxies:
      - DIRECT
rules:
  - DOMAIN,upload.example.org,DIRECT
  - DOMAIN-SUFFIX,example.org,Docs Exit
  - IP-CIDR,192.0.2.0/24,DIRECT,no-resolve
  - MATCH,DIRECT

The first rule in this example matches only upload subdomains. The second covers the example's main domain and its subdomains. The third demonstrates IP-range matching with a documentation-only address range. The final rule catches connections that didn't match earlier conditions. The example group contains only DIRECT, so check the rule or policy path in the connection log to tell the first two rules apart. MATCH takes no domain or IP range argument; it only needs an exit. In this syntax, a complete comma-separated rule is one YAML list item. Don't split its conditions and policy into separate items with multiple hyphens.

Target domain, connection address, and data source are three separate factors

Domain rules rely on the core seeing or recovering the target domain. If an app passes only an IP address and no usable domain information, a domain rule can't match it. IP-CIDR matches an address range; for a target specified only by domain, some IP-based rules may trigger a DNS lookup. Supported rule types can take no-resolve to avoid making an extra query just for that match. If the target address is already known, it can still be matched by IP. After adding this option, test both a domain and a numeric address; otherwise, it's easy to mistake “can't match without a lookup” for an incorrect network range.

GEOIP relies on a geolocation database; it doesn't infer location from a domain suffix. RULE-SET references a collection defined in rule-providers. Updating the database can change how an address is classified. Rule sets also have their own behavior type and data format; a successful download doesn't mean the core has loaded the rules. Before adding either type of condition to the live list, confirm the current config loads its data, then test one matching and one non-matching target. The Troubleshooting FAQ covers common issues with failed updates, proxy nodes, and unexpected routing.

Test order with positive, negative, and fallback cases

Test at least three types of target: one that should match an exact exception, one of the same kind that should match a broader condition, and one that should pass earlier rules and reach the fallback. Record the expected rule and exit for each target, then create new connections. If the exact target is caught by the broader rule, check the order. If both domains reach the fallback, verify the target values, whether the domain is visible, and whether Rule mode is active. If the rule is right but the exit isn't, check the group's members. A website may request multiple subdomains and third-party resources; inspect connections individually instead of treating the main address-bar domain as the page's only destination.

Before changing the fallback, decide how unmatched traffic should be handled. Using DIRECT as a fallback makes it easier to isolate known rules while testing. For production, choose an explicit fallback exit based on your network and business requirements, then check how common apps behave on that route. When saving changes, note which earlier rule now takes precedence. That way, if you later remove a temporary exception, you'll know which route it replaced instead of relying on memory. For frequently updated external rule sets, keep one or two repeatable test targets and check them again in the same order after updates.

07 OVERRIDES / EFFECTIVE CONFIG

Config Overrides, Merging & Rollback

Keep the original subscription, local changes, and effective config separate

When troubleshooting changes that don't take effect, compare against the config actually loaded by the core, not just the subscription copy in your editor. A client may fetch a base subscription, merge local overrides, and then add runtime parameters based on UI settings. Override files aren't a universal core syntax shared by all clients. First check whether the product supports a full replacement, key-based merge, list append, script processing, or another method. If it doesn't support overrides, adding a merge directive to YAML won't make the core execute it.

Keep an unchanged copy of the subscription source, and save a separate local config for testing. If you only need to change a listener, use the YAML below as a change checklist, or apply it according to the rules of a client that supports mapping-based overrides. Don't use this snippet by itself as a replacement for the original config, or the original nodes, groups, and rules won't be loaded with it. Apply these two changes first and confirm the active listeners match your expectations before changing DNS or rules. Applying changes in batches makes it easier to identify which change altered behavior.

mixed-port: 7891
allow-lan: false

Check the value's shape before merging

A port is a scalar, so replacing it usually means updating only the apps that use it. DNS is a nested mapping: some tools merge individual keys, while others replace the whole section. Changing only the enhanced mode could therefore discard existing upstreams or internal-domain policies. Check the generated config to make sure the old fields are still there, then retest an internal target that previously resolved. Don't use empty values to test deletion behavior: a missing field, an empty list, and a YAML null value are different states, and clients and cores may handle them differently.

Check whether lists are replaced, prepended, or appended. This matters especially for rules: having every item present after a merge doesn't guarantee the order is correct. Here's a minimal example of the result when you want to keep the existing rules: the first item is a new exception, while the second item and fallback come from the base config. If the tool only supports replacing the entire section, include every old item you need to keep in the final list. If it supports prepending, submit only the new item to avoid duplicating old rules. The exception must also reference an existing exit. Two YAML files loading successfully doesn't guarantee the merged result will load.

rules:
  - DOMAIN,status.example.org,DIRECT
  - DOMAIN-SUFFIX,example.org,Docs Exit
  - MATCH,DIRECT

Validate the structure with a load test and the procedure with a rollback

If you use mihomo directly and already have the executable on your machine, test mode can check the complete config before loading. In a client, use its built-in validation feature where available. If you run a separate command-line test, match the working directory and required rule resources to the actual deployment; otherwise, errors involving external resources may only reflect differences in the test environment. After a successful test, reload the config and check the listener, DNS resolution, and exit for a new connection. Static validation can't guarantee that remote proxy nodes or resolvers are reachable, and it doesn't replace testing the OS proxy setup.

mihomo -t -f ./config.yaml

Check for changes to names and order before and after subscription updates. An update may remove a node, rename it, or replace a proxy group's members. If a local override references nodes by name, it may no longer find them after an update. If a group gets its candidates from a provider and applies filters, recheck the filtered results. To reuse a config across devices, share the nodes, groups, and rules, but keep environment-specific settings such as listener ports local to each device. See a comparison of config sync options for multiple devices for more.

Keep backups of the pre-update base file, local overrides, and effective config for rollback. Add a short note for each change with its purpose, scope, and test result, such as “Changed the listener port; verified a browser connection on the new port.” If the effective config contains account information, restrict access and don't attach the original file to a public issue. That way, even if a subscription update and local changes happen on the same day, you can restore a known working route first, then use your change notes to find what caused the difference.

Clash Downloads