Clash Configuration Reference
Use this page to look up fields, check references, and understand the configuration actually loaded by the core. For a first install or subscription import, start with the quick-start guide; once your connection works, return here to adjust settings. Examples are based on mihomo, and any external service requirements are noted.
YAML Structure and Configuration Entry Points
Top-Level Fields, Mappings, and Lists
The core reads a YAML document with a mapping at its root. Ports and modes are top-level keys; DNS is a mapping, with resolver addresses listed beneath it. Nodes, proxy groups, and rules each have their own top-level keys. To determine where a field belongs, find its parent and check whether that parent expects key-value pairs or a list. Indenting a field so it looks visually close to other settings does not place it in the right section.
Keep fields at the same level aligned, using two spaces per level. Start list items with a hyphen followed by a space. Each node in a list is one record: its name, type, and address belong to that record and must not be split into separate list items. Rules work differently: each rule is usually a single string. Commas separate fields within a rule string; they do not make each field a separate YAML list item.
Write numeric ports as numbers and switches as true or false; don't quote everything. Names and long values can be quoted. In particular, keep quotes when a value contains characters that could be parsed as a comment or key-value separator. For example, if an unquoted name contains a space followed by a hash, the text after the hash may be treated as a comment. A proxy group referencing that name then won't find it. An empty list [] and an empty mapping {} are different values.
Minimal Baseline and Name References
This baseline exposes only a local mixed proxy port and sends all traffic entering through it to the built-in DIRECT outbound. It requires no subscription or extra resources, making it useful for first checking whether this machine can reach sites that are already accessible through the proxy entry point. It is not an encrypted proxy setup and does not affect traffic from apps that aren't routed through the core. If another client already uses this port, choose an available one and update the test client too.
mixed-port: 7890
allow-lan: false
mode: rule
log-level: info
rules:
- MATCH,DIRECT
When adding a proxy group to this baseline, trace the relationships as a chain: rules reference groups, groups reference nodes, other groups, or built-in outbounds, and nodes define how a connection is made. A rule can also point directly to a built-in outbound. References use names, not list positions. When renaming a node, check every group; when renaming a group, also check rules and any groups that reference it. Names that differ only by a space are still different objects.
Subscriptions, configuration files, and proxy provider resources are not always interchangeable. A client's subscription import may fetch and process a complete configuration, or generate the final configuration according to its own rules. Proxy providers load node collections for groups to choose from; a node list alone is not a complete configuration with top-level listeners and rules. Check the root keys before copying anything. If the root key is payload, confirm what kind of resource it is before treating it as a main config.
Distinguish the Source Config from the Active Config
With a GUI client, distinguish at least three things: the original subscription, local overrides, and the final config passed to the core. UI toggles may be used to generate the final file or may change core state through a runtime API. If your manual edits disappear after a subscription update, move custom settings to an override location supported by the client rather than repeatedly editing a cached file. Check the client for the exact location; if you're choosing a client for the first time, start with Clash Plus, the top pick on the downloads page.
Comments can explain why a change was made, but the core won't use them to resolve conflicting references. Don't repeat a key in the same mapping. Some parsers report an error; others may keep only one of the values. Duplicating a rules block won't append to it: combine the entries into one list and order them as needed for matching. After saving, check the actual structure and confirm the correct config is selected in the UI.
Editor syntax highlighting alone is not a reliable way to check whether a config is valid. It can flag some indentation and quoting issues, but it can't tell whether a group name is defined or whether the current core supports a field. When loading fails, start at the reported location and find the nearest parent key above it; check the list level and field type. Once the syntax passes, check references and behavior. This avoids changing spelling and routing logic at the same time, leaving you unsure which fix worked.
General Ports, Listening Addresses, and Modes
Choose an Entry Point and Check What's Listening
Port fields specify where the core accepts requests on this machine, not the service port on a remote node. A mixed port accepts both HTTP proxy and SOCKS requests, so two kinds of apps can share one address. If an app requires a dedicated entry point, configure separate HTTP and SOCKS ports. Each listener needs its own port; don't set all three fields to the same number.
| Field | What It Controls | What to Check |
|---|---|---|
mixed-port | Combined HTTP and SOCKS proxy entry point | The app still needs to use the proxy protocol it supports. |
port | HTTP proxy entry point | Accessing HTTPS sites through a proxy doesn't mean the local entry point should be configured as an HTTPS proxy. |
socks-port | SOCKS proxy entry point | Check whether the app sends the target hostname or an already-resolved address. |
allow-lan | Allow LAN devices to connect to the local proxy entry point | Set to false for local use only. |
bind-address | Address to bind when allowing LAN connections | If sharing access, choose an interface address explicitly and check the exposure range. |
external-controller | Core control API | This is not a proxy port and should not be exposed along with the proxy entry point. |
The example below assigns different ports to the two entry points. If the client manages these fields, set the values in its UI or check the final config after overrides. A port number in the config doesn't mean the process bound it successfully. A previous instance, another tool using the address, or OS restrictions can all prevent a port from being used. If there's a port conflict, identify the process using it before deciding whether to close the old instance or change the port.
port: 7890
socks-port: 7891
allow-lan: false
mode: rule
log-level: info
rules:
- MATCH,DIRECT
Local apps generally use the loopback address 127.0.0.1 and the port for the relevant protocol. To test, check the listener logs first, then send a request from an app where you can configure a proxy manually. If that app works but other apps show no connections, check whether they use the system proxy or have their own proxy settings. A lit proxy icon alone doesn't prove that every app uses the same entry point.
A client's system proxy toggle usually writes proxy settings at the OS level; whether apps use them is up to each app. TUN captures selected traffic at the network interface and routing layers and usually requires OS authorization. These are different ways to get traffic into the core; they don't determine which outbound is used afterward. Changing mode alone won't enable the system proxy or replace TUN interface settings. When troubleshooting, start with one traffic entry method at a time.
Rule, Global, and Direct Modes
In rule mode, rules are checked in order to select an outbound, making it suitable for configs with specific routing needs. global mode uses a global selection instead of checking rules one by one. Before using it, confirm which outbound the client has selected; don't assume traffic is going through a particular remote node. In direct mode, traffic that enters the core goes direct. This doesn't disable the local listener or restore the system proxy settings.
If a site behaves differently in rule and global modes, start by checking the actual outbound in the connection logs for each test. Success in global mode only shows that the selected route worked for that request; it doesn't prove the whole ruleset is wrong. The rule may have matched DIRECT, the referenced group may have a different selection, or the hostname may have resolved differently between tests. When testing in direct mode, check whether the site is accessible from the current network.
Keep the log level at info for normal use. Temporarily switch to debug to investigate an issue, reproduce it once, then switch back. Logs may reveal target addresses and config names that identify your environment, so share only relevant lines. Distinguish three stages: the request reaches the entry point, a rule selects an outbound, and the remote connection succeeds. If only the first stage is confirmed, don't assume the target site is at fault.
Keep Local and LAN Access Separate
Enable LAN access only if other devices need to connect. Remote devices must use the LAN address of the host running the core, not their own loopback address. Before opening access, identify the interface and firewall scope; turn it off when it's no longer needed. Consider the control API separately: the ability to reach the internet through a proxy doesn't mean a device needs to control the core. Don't expose both proxy and control ports on every interface just to troubleshoot a local connection.
After intentionally changing a port, check that the system proxy, browser-specific settings, and terminal environment variables aren't still using the old value. If it works before a restart but not afterward, note the listening address and config name before and after the restart, and confirm the same instance is running. For platform-specific system settings and permissions, see the quick start, then return here to check the core fields.
DNS Fields and fake-ip Behavior
Check Whether DNS Queries Go Through the Core
Enabling DNS in the config activates the core's own resolver; that switch alone does not route every OS DNS query through it. Browsers may use their own encrypted DNS, and apps may send resolved addresses to the proxy. Whether DNS requests reach the core also depends on the traffic entry method, which differs between system proxy and TUN. Before troubleshooting, identify the app making the query and which resolver actually receives it.
In the DNS config, nameserver is the resolver list for general domains; nameserver-policy can choose a resolver for specific domains. default-nameserver is for bootstrap lookups, such as resolving the hostname of a DNS server at startup. It isn't a fallback list tried for every request. When using encrypted DNS endpoints with hostnames, make sure the bootstrap resolver is reachable on the current network. Otherwise, the config may load successfully while the first query still times out.
proxy-server-nameserver resolves the hostnames of proxy servers. It addresses the question, "How do I get the node's IP before connecting to it?"—not general website resolution. If the node is specified by hostname and the upstream resolver needed to resolve it is reachable only through that same node, you'll have a dependency loop. In that case, first provide a resolution path that works before connecting to the node, then decide how general website queries should be resolved.
Address Mapping, Filters, and Local DNS Examples
In fake-ip mode, the core can assign a virtual address to a queried domain and store the mapping between the domain and address. If the connection returns to the same core using that address, the core may be able to recover the domain and apply domain-based rules. This virtual address is not the target server's public IP and can't be used independently of the core's mapping. If the query goes through the core but the connection is then handed directly to the system router, the app may try to connect to an unreachable virtual address.
mixed-port: 7890
allow-lan: false
mode: rule
dns:
enable: true
listen: 127.0.0.1:1053
enhanced-mode: fake-ip
fake-ip-range: 198.18.0.1/16
fake-ip-filter:
- 'localhost'
- '+.lan'
nameserver:
- system
rules:
- MATCH,DIRECT
This example exposes a separate DNS port on the loopback address and forwards ordinary queries to the system resolver. It's useful for manually sending test queries to that port, but it won't change the system DNS settings for you. Make sure the system resolver doesn't forward queries back to this same listener. If another tool uses the port, choose an available one. Also check that the virtual IP range doesn't overlap with existing local routes or another proxy instance's virtual network.
With the example's default filtering behavior, fake-ip-filter excludes listed names from virtual address assignment. Adding a local domain to the list means "use a real DNS answer"; it doesn't create a DNS record for that domain. If an internal suffix must be resolved by your organization's DNS server, make sure the system resolver can return it or configure a reachable resolver for that suffix, then verify that routing allows access to that DNS server.
Another enhanced mode is redir-host, which generally returns real addresses to apps. Whether domain rules can still match depends on whether the domain is carried with the proxied request or the core can obtain it from the traffic entry path. Switching modes won't fix every domain-matching issue. Check both the DNS response and connection logs for the same target; a change in the former alone doesn't mean the latter matched the expected rule.
Distinguish Resolution Failures, Caching, and Connection Failures
If you have a query tool that lets you specify a server and port, run the two queries below. The first explicitly uses the example listener; the second uses the tool's default system resolver path. Compare the response status and address type, not whether the address values are identical. Different results can be expected in fake-IP mode. If the listener receives no request, check the address and port first rather than changing the upstream resolver.
dig @127.0.0.1 -p 1053 example.com A
dig example.com A
If you get a response but the connection still fails, check whether the connection reaches the same instance that holds the mapping, then inspect domain rules, proxy groups, and outbound logs. After switching configs, the browser and OS may keep cached addresses, and existing connections may be reused. Test with a new connection and, if needed, clear only the relevant state for the test app. Change one thing at a time; don't switch DNS, enable traffic capture, and change nodes all at once.
In dual-stack environments, check IPv4 and IPv6 separately. DNS's ipv6 option controls how the core handles IPv6 queries; it doesn't disable the OS IPv6 stack or replace checking the IPv6 traffic path. During diagnosis, note the query type and actual target address. A successful connection over one address family doesn't mean the other uses the same rules or route.
Proxy Node Fields and Providers
Build an Outbound Record by Protocol
proxies is a list of node records. A typical record includes a name, protocol type, server, and port; protocol-specific fields depend on the service. The name is used for display and references, while the address and port define the connection target. Use a hostname or address, not a subscription URL with a scheme and path. A subscription URL fetches or generates config; a node address establishes an outbound connection. They serve different roles in the loading process.
This example adds a node for an existing local SOCKS service. It requires a separate SOCKS service listening on 1080 on this machine and accessible to the client; you don't need to change that service. The core's inbound port is 7890. Don't change the node's service port to the core's own mixed port: requests could loop from the outbound back into the inbound, causing repeated processing or connection failures.
mixed-port: 7890
allow-lan: false
mode: rule
proxies:
- name: Local-SOCKS
type: socks5
server: 127.0.0.1
port: 1080
udp: false
rules:
- DOMAIN-SUFFIX,example.com,Local-SOCKS
- MATCH,DIRECT
This example routes only connections matching the example domain through the node; everything else remains direct. If you don't already have a SOCKS service, use the minimal baseline to test the entry point first. Don't mistake a failing node example for a YAML load failure. Seeing a node in the client list only means the record was loaded. To verify that it works, check that the address is reachable, the protocol handshake completes, and the target request returns through that outbound. Failure at any step may simply appear as a timeout in the UI.
When switching protocols, don't just change type and keep all the old fields. For example, Shadowsocks needs a password and cipher that match the server. Other TLS-based protocols may also require a service name, certificate verification settings, and a transport mode. Similar config structures don't mean compatible handshakes. If you see a certificate error, check the service name, system clock, and server certificate first; disabling verification is not a routine fix.
udp indicates whether some nodes enable UDP forwarding; it can't give that capability to a service that doesn't support it. Accessing a website through a node only verifies that particular web connection, not voice calls or other UDP apps. Check whether the inbound carries this kind of traffic, the policy selects a compatible outbound, and the server can actually forward it. Don't use a website loading as a substitute for checking the protocol.
Provider Paths and Loading Order
For a separately maintained set of nodes, use proxy-providers. The main config declares the resource source, and a proxy group references the provider by name with use. The example below uses a local file, which must already exist in the core's working directory. It reuses the separate SOCKS service from earlier, so make sure that service is running before use. If the file can't be found, check the relative path and the working directory selected at startup.
mixed-port: 7890
allow-lan: false
mode: rule
proxy-providers:
local-source:
type: file
path: ./local-proxies.yaml
proxy-groups:
- name: PROXY
type: select
proxies:
- DIRECT
use:
- local-source
rules:
- DOMAIN-SUFFIX,example.com,PROXY
- MATCH,DIRECT
proxies:
- name: Local-SOCKS
type: socks5
server: 127.0.0.1
port: 1080
udp: false
Open the proxy group and confirm that the provider's members appear, then select one manually. Don't rely on connection logs showing the group name: if the group's current member is still DIRECT, you haven't tested the node. For an HTTP provider, make sure it returns node resources the core can parse, not a login page or another complete config. Manage the provider's working path and update interval separately to avoid multiple resources sharing the same cache file.
When checking resource updates, track "downloaded," "parsed," and "members available" separately. An update may remove members or replace a same-named record with different server parameters. If a manually selected member disappears after an update, check the provider's new member list and the group's current selection rather than relying on an old screenshot. When sharing config snippets, remove subscription URLs, credentials, and internal hostnames; keep only the fields needed to show the structure.
Proxy Group Types, Members, and Health Checks
Proxy Groups Select an Outbound
proxy-groups defines outbound selection policies, not new proxy protocols. A group name is a destination that rules can reference; its members can be individual nodes, built-in outbounds, other groups, or provider nodes. Groups keep rules stable: you can replace or adjust members without rewriting the rules that reference the group. Give each group a clear purpose before choosing its members. Avoid creating multiple groups with names that differ by only one character.
| Type | Selection Method | What to Watch |
|---|---|---|
select | User-selected member | Check whether the client restores the last manual selection. |
url-test | Selects a member based on test results | The test URL, interval, and tolerance affect selection. |
fallback | Selects the first available member in list order | Primary/backup order follows the member list, not latency. |
load-balance | Distributes connections according to the configured policy | Connections may use different outbounds; check whether the application requires a fixed egress. |
Static members go under proxies as names that have already been declared, not as full node records embedded in the group. Provider references go under use as provider names, not resource URLs. Putting a node name under use or a provider name under proxies is a reference-level mistake. When migrating a config, first validate references with a small static group, then add provider members gradually.
The example reuses the Local-SOCKS node from the previous section. Replace the original rules list with the rules shown here and add the group definition at the top level. DIRECT remains as a manual comparison option. The catch-all rule goes last so only the specified domain uses the manual group. For testing, select each of the two options and start a new connection; compare the logs to see whether the final member changes with your selection.
proxy-groups:
- name: PROXY
type: select
proxies:
- Local-SOCKS
- DIRECT
rules:
- DOMAIN-SUFFIX,example.com,PROXY
- MATCH,DIRECT
Nested groups are useful for putting automatic selection behind a manual entry point—for example, a manual group can include both an automatic group and a fixed node. Keep references traceable: group A must not reference group B if B references A, and a group must not reference itself. To troubleshoot a circular reference, map the outer-to-inner group links and trace each rule target through to a node or built-in outbound. If you encounter a group you've already visited, revise the structure.
Test Real-World Traffic, Not Just Probe Results
To change the manual group above into a primary/backup group, use the definition below and keep the same group name in the rules. interval is measured in seconds. The example uses a public documentation domain to show the probe fields. In practice, choose a probe URL you're allowed to access that returns consistently, and confirm it's reachable through every candidate outbound. The probe tests a request to one address, not the availability of the whole internet.
proxy-groups:
- name: PROXY
type: fallback
proxies:
- Local-SOCKS
- DIRECT
url: https://example.com/
interval: 300
DIRECT is included here as a fallback for comparison only. If an app requires a fixed egress, don't add DIRECT as an automatic fallback; handle cases where all candidates are unavailable according to the app's requirements. Don't mix outbounds that aren't equivalent just to see more available options. Group availability depends both on whether a member can connect and whether that member meets the access requirements for the target.
Setting a switch tolerance for a url-test group can reduce frequent switches caused by small changes in probe time. A very short interval adds requests and makes it easier to mistake temporary fluctuations for persistent differences. If one member is slow in a test, first check whether the result is consistent, then see whether the issue can be reproduced with the actual app. If the probe succeeds but the app fails, compare their domains, protocols, and selected outbounds instead of shortening the probe interval first.
Providers can also run their own health checks. When troubleshooting, distinguish three things: which members the resource contains, their probe status, and the member currently selected by the proxy group. Policy changes generally affect new connections; apps that keep existing sessions may not show an immediate change. If the client remembers selections, reloading the config may restore the previous member. If needed, start a new session and use that connection's logs.
Rule Syntax, Match Order, and Rule Sets
Start with the First Matching Rule
In rule mode, the core checks rules in list order and uses the result of the first match. The common syntax is "type, condition, target," though some types take additional options. MATCH needs no condition and takes only a target. A broad rule placed first can prevent more specific rules below it from ever matching. Put exceptions before general rules, and make sure the final catch-all matches your intent.
This example requires no remote node; it uses DIRECT and REJECT to illustrate several branches. An exact hostname goes direct, while other names in the same suffix scope are rejected. Connections to loopback addresses match the IP rule and go direct; other requests fall through to the catch-all. The example affects only requests that enter this core. Traffic sent directly through the OS routing table isn't blocked just because the config contains a reject rule.
mode: rule
rules:
- DOMAIN,example.com,DIRECT
- DOMAIN-SUFFIX,example.com,REJECT
- IP-CIDR,127.0.0.0/8,DIRECT,no-resolve
- MATCH,DIRECT
DOMAIN checks an exact hostname; DOMAIN-SUFFIX matches that domain and its subdomains, not any string that happens to end the same way. If you want to affect only one hostname, don't broaden the rule to the whole suffix, which could also change other services under the same domain. DOMAIN-KEYWORD matches a keyword and has wider scope. Check what other hostnames contain that keyword before using it.
IP-CIDR is for IPv4 ranges; use IP-CIDR6 for IPv6. Rules that need a destination IP may require the core to resolve a hostname first. no-resolve prevents that rule from triggering an extra lookup; it doesn't remove an address already present in the request. It isn't a command to disable DNS globally. If a match depends on resolution, first check whether the rule allows it, then confirm the result falls within the specified range.
GEOIP and GEOSITE depend on geographic IP and domain classification data available to the core. They refer to categories in that data, not a live measurement of a connection's location or ownership. Different data files can produce different matches even with identical rule text. When investigating a discrepancy, note the data source and the config enabled in the client; don't infer the behavior of an entire dataset from one site.
Separate Match Data from the Action
Use rule-providers when a set of match conditions needs to be maintained separately. The main config uses RULE-SET to specify a rule set and its action; the resource itself defines only the conditions. The local example below uses a domain list to send a specified domain and its subdomains direct. Create the file before loading the config. Check relative paths against the core's working directory rather than assuming they're relative to the directory open in your editor.
mode: rule
rule-providers:
reference-domains:
type: file
behavior: domain
format: yaml
path: ./reference-domains.yaml
rules:
- RULE-SET,reference-domains,DIRECT
- MATCH,REJECT
payload:
- '+.example.com'
The last rule in this example rejects targets not listed in the set. Use this only when deliberately testing an allowlist, not as a drop-in replacement for everyday rules. behavior: domain accepts domain-style conditions; ipcidr is for address ranges; classical can contain conditions made up of rule types and parameters. Don't put an entire line like DOMAIN-SUFFIX,example.com,DIRECT in a domain list, or include an outbound name in conditions whose action is set by the main config.
Use Connection Logs to Verify What Matched
If a target falls through to the catch-all, first check whether the client logged it as a hostname or a numeric address. If an app resolves the name itself and sends only the address, domain rules may have nothing to match. Changing rule order alone won't fix that. Next, check for a broad rule earlier in the list, then confirm the rule-set file loaded successfully. If the connection log shows the expected rule, move on to group members and outbounds rather than continuing to adjust match conditions.
A webpage can connect to its main document, static files, and other services separately; each connection is matched on its own. The main document loading doesn't mean every page resource used the same outbound, and a failed resource doesn't necessarily require changing rules for the whole domain. Start with one failed connection and note its target, matched rule, and final member before adding an exception. For field terminology, see the routing-rule categories in the glossary.
Overrides, Merging, and Update Differences
First, Find Out Who Performs the Merge
An override is a client-side process for generating the final config; the core doesn't automatically merge two keys just because they have the same name. Clients may handle mappings, lists, and empty values differently, and may offer both UI-based overrides and script processing. Before editing, identify the exact entry point and whether it applies to one config or all configs. A key intended for a third-party override feature can't be moved into the main YAML and treated as a core field.
Classify changes as scalars, mappings, or order-dependent lists. Ports and modes usually require changing a single value. DNS is a mapping, and replacing the whole section may discard existing resolvers or filters. Rules are ordered lists, so appending, prepending, and replacing the entire list produce different results. Even if a client says it "deep-merges mappings," that doesn't mean it appends lists. Check the actual output, not how many lines the override file contains.
| Data Type | Example Change | Verify the Result |
|---|---|---|
| Scalar | Change mixed-port to another available port | The final config, actual listener, and app settings all agree. |
| Mapping | Change dns.enhanced-mode | Required resolvers and policy mappings are still present. |
| Ordered list | Add an exception to rules | The exception appears before any older rule that would cover it. |
| Object list | Add a group to proxy-groups | The original groups remain, names are unique, and all member references resolve. |
The examples below show the complete file before and after the change. The goal is to change the mixed port and make the example domain match REJECT before the catch-all. This is a manually merged result, not a patch syntax that depends on a particular client. Even if the client can generate the same output, verify that there is only one rules list, the exception comes first, and the original mode and listening scope are unchanged.
mixed-port: 7890
allow-lan: false
mode: rule
rules:
- MATCH,DIRECT
mixed-port: 7892
allow-lan: false
mode: rule
rules:
- DOMAIN-SUFFIX,example.com,REJECT
- MATCH,DIRECT
If the client only appends new rules to the existing list, the added rule in the example will end up after MATCH and won't match. Use a feature that explicitly supports prepending, or replace the full rules list after organizing it. Replacing the whole list also means taking responsibility for maintenance: important rules added to the subscription won't automatically appear in your custom list. After an update, compare the upstream rules again rather than checking only whether the config still starts.
Renaming, Empty Values, and YAML Merge Keys
Before adding a proxy group, check that its name isn't already used. If the override tool merges objects by name, a group with the same name may replace the old one; if it only appends objects, duplicate names may make the config fail to load. Before deleting a node, group, or provider, search for every reference to it. If rules target the old group name, you don't need to update every rule as long as a group with that name remains and has valid members. Deleting the group itself means migrating its references.
Empty values need careful interpretation too. A blank value after a key is often parsed as null; it doesn't mean "keep the original value." An empty list doesn't automatically mean "don't change anything" either. An override tool may treat these as clearing, replacing, or invalid input, or reject them outright. If you want to leave a subscription field unchanged, usually omit it from the override file and check the final config. Don't use an empty value to express an unconfirmed merge intention.
YAML anchors and aliases work only within the parsing scope of a single YAML document; a separate override file can't share anchors from the original subscription. Some parsers support the << merge key, which is mainly for merging mappings, not concatenating rule lists. A client may also expand or change this syntax when reading and re-serializing the config. For cross-client portability, prefer simple structures and verify the final exported plain YAML.
Treat a Subscription Update as a Regeneration
Before updating a subscription, keep separate copies of the last working final config and local overrides. After the update, compare top-level ports and the DNS mapping, then check references between nodes, groups, and rules, and finally retest the same target. If an update causes a problem, temporarily disable overrides and test the original config, then enable one local change at a time. This helps distinguish changes in source data, client-side merging, and runtime selection.
When moving to another client, migrate only core fields whose meaning you can confirm. The same mihomo core doesn't guarantee that two UIs apply overrides in the same order or use the same config directory and provider paths. To migrate an old config to mihomo, compare the field differences between the mihomo core and original Clash, then check which core and configuration entry point the target client actually uses.
Config Validation, Connection Tests, and Common Issues
Validate the File Before Testing at Runtime
At the start of troubleshooting, keep a known-good config and give the test file a different name. In a GUI client, confirm which config is selected and which overridden config is used at startup. With a standalone core, specify the file path and working directory. If the system has multiple installations, also check that the binary called from the terminal is the same core used by the UI. One passing test and one load failure aren't contradictory if they're using different binaries.
The command below is for environments where mihomo runs from a terminal. It assumes config.yaml is in the current directory; the working directory must also provide access to the data and local resources required by the config. Passing this test only means the core completed this config check. It doesn't prove that all listener ports can bind, resolvers are reachable, or nodes complete their protocol handshakes.
mihomo -t -d . -f ./config.yaml
If you get an error, narrow it down by stage. For syntax errors, check the reported line and the previous item for a missing colon, broken indentation, or unclosed quote. For reference errors, check group, node, and provider names. For resource errors, verify the working directory, paths, and file format. Don't change filenames, rules, and subscription URLs all at once. Repeat the same check after each fix until the reported stage advances, then move on to the next layer.
Retest Each Layer: Entry Point, Match, and Outbound
After startup, confirm the local listener, then send a simple request through the specified proxy entry point. The command below assumes the mixed port is listening on 127.0.0.1:7890 and the current policy allows the target. If you used the earlier port override example, update the port in the command too. If you're testing a REJECT rule, treat a blocked request as the expected result, not proof that the entry point is broken.
curl --noproxy "" --proxy http://127.0.0.1:7890 \
--max-time 15 --head https://example.com/
The line continuations above are for common Unix-like command-line environments. In a terminal that doesn't recognize them, put the command on one line and use the actual curl executable. --noproxy "" clears the proxy bypass list for this command, making it easier to check the entry point. A response from the target server doesn't mean every app reads system proxy settings; this test covers only the explicitly specified route and doesn't depend on the UI icon.
If there's no new connection log, check the proxy protocol, address, and port, and whether the app bypasses the proxy. If a connection is logged but the wrong rule matched, check the mode at the time, the form of the target sent to the core, and rule order. If the match and selection are correct, inspect the outbound handshake, node hostname resolution, and target service response. Record the target, mode, matched rule, and final member each time; these four details are more useful than simply noting that it "can't connect."
All nodes timing out and a single node timing out are different problems. If all nodes time out, check shared factors such as the subscription, entry point, resolution, and local network. If only one node fails, keep the entry point and target the same and compare another member. Avoid changing several settings at once before you've finished checking. For symptom-based troubleshooting, see what to check when a node times out; to set up system traffic routing again, return to the quick-start guide.
Common Configuration Issues
Why Does the Client Still Use the Old Port After the Config Loads?
First check whether the new port shown in the UI made it into the final config, then confirm the config was reloaded and the port is actually bound. If the core is listening on the new port but the app still sends requests to the old one, update the system proxy, app-specific proxy settings, or terminal environment variables. If the old port still responds, check for another running instance so you don't mistake its logs for the current test.
Why Do Results Differ Even Though the Rule Matches the Expected Group?
The group name tells you only which selection policy was entered. A manual group may restore an old selection, a primary/backup group may use its backup, and an automatic group may select a different member after a probe change. Check the final member used by that connection, then confirm the group contains members suited to the task. Start a new connection after changing the selection; an app reusing an existing connection may not show the change right away.
Why Doesn't Restoring the YAML Restore the System Network Settings?
System proxy settings, virtual interfaces, routes, and OS DNS settings are managed by their respective system features or the client. Replacing a config file alone won't undo them. In the client UI, turn off any traffic-entry features you originally enabled, check which settings remain active in the OS, then test with a new request. If the issue occurs both before and after restoring the old config, distinguish OS-level state from core configuration issues.