Clash Configuration Guide

1. YAML Structure and Configuration Dependencies

A configuration file is first a YAML document, then a set of network settings that Clash can interpret. The parser must understand the hierarchy, lists, and data types before the core can validate the fields. Being able to open a file in an editor does not mean its structure is valid. Chinese comments are generally fine, but colons, quotation marks, and list hyphens must use standard ASCII characters. Save the file as UTF-8, and consider showing whitespace in your editor to catch tabs that can look like aligned spaces.

Root Fields, Mappings, and Lists

Keys at the same level should start in the same column. dns is a mapping, with its child fields indented beneath it. proxies, proxy-groups, and rules are usually lists, with each item starting with a hyphen. Use the configuration below as a starting point for validating the structure locally: it listens only on the loopback address, has a proxy group with only a direct option, and sends all traffic directly. It illustrates how references work and does not include a remote proxy you can connect to.

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

dns:
  enable: false

proxies: []

proxy-groups:
  - name: Proxy
    type: select
    proxies:
      - DIRECT

rules:
  - MATCH,Proxy

Here, Proxy is not a reserved keyword; it is the name of a proxy group. The final rule references it, so the names must match exactly, including capitalization, spaces, and punctuation. DIRECT is a built-in policy for connecting directly to the destination. When reviewing a configuration, trace references backward: which group does a rule point to, which proxies does the group list, and are those proxies actually defined? A missing link can cause a load error or send traffic somewhere unexpected.

Correct Indentation Is Not Enough—Check Data Types

Using two spaces per indentation level is a helpful convention, but YAML only requires consistent indentation at the same level. Ports should be integers, switches should be true or false, and names and passwords should be treated as strings. Quote passwords that contain colons, hash marks, or other special characters. Backslashes have escape meaning inside double quotes; single quotes preserve most ordinary characters, but a literal single quote must be doubled.

Comments start at a position where the hash mark is valid in YAML; make sure part of a password is not mistaken for a comment. Do not define dns or rules more than once in the same mapping. Even if a parser accepts duplicate keys, it may keep only the last value. An empty list, [], and an empty mapping, {}, are different: the former has no items, while the latter has no key-value pairs. Use the structure required by the field definition.

Distinguish the Source Configuration from the Runtime Configuration

Desktop clients often combine a subscription, global settings, and override snippets to generate a runtime configuration. That means mixed-port in the subscription file may not be the active listening port, and edits to a downloaded cache may not persist. Before making changes, identify three things: the original subscription, the client’s saved custom settings, and the file the core is currently using. Paths vary by client, so check the profile details, runtime information, or logs rather than guessing based on another client’s directory layout.

For easier maintenance, limit each change to one topic: adjust listening settings first, then DNS, and finally rules. Validate after each set of changes so errors can be narrowed down to a small diff. For a closer look at how to read the file section by section, see config.yaml, section by section. The chapters below explain the boundaries of each field; there is no need to enable every feature at once.

2. Ports, Modes, and Access Boundaries

Common fields determine where the client accepts connections, how it handles them, and which devices can access the proxy. When troubleshooting, separate the question of whether an application sends traffic to the core from the question of how the core selects an exit. Rule mode only affects requests that reach the core; it does not automatically route every application through the proxy. System proxy settings, per-app proxy settings, and TUN are different ways to capture traffic and cannot be substituted for one another using the mode field alone.

What Each Port Field Does

For typical desktop use, a single mixed-port is usually all you need; there is no benefit to enabling every listener for the sake of completeness. Different listeners cannot use the same port on the same address. If another process already has that port, the core may fail to start its listener. After changing a port, update the system proxy, browser extensions, terminal environment variables, and in-app settings as needed. Otherwise, applications may keep using the old address and make a working node appear unavailable.

mixed-port: 7890
allow-lan: false
bind-address: "127.0.0.1"
mode: rule
log-level: info
ipv6: false
external-controller: "127.0.0.1:9090"

The Three Modes Change How Exits Are Selected

rule selects a destination according to the rules from top to bottom; global uses the selected global policy for traffic that reaches the core; direct connects captured traffic directly. Global mode does not mean system-wide traffic capture, and direct mode does not mean applications bypass the local core. Clients may store the mode in their own settings, so check the final configuration or management interface to see what is active. For examples of when to use each mode, see Rule, Global, and Direct Modes Explained.

Common log-level values are debug, info, warning, error, and silent. For everyday use, keep the normal information level. Temporarily enable more detail when reproducing an issue, then switch it back afterward. Detailed logs may include visited domains and connection information. Remove subscription URLs, authentication details, and any destinations you do not want to share before posting logs or screenshots.

Plan LAN Access Separately

To let a phone or another computer use this machine’s proxy, changing allow-lan to true may not be enough. Check that the listening address includes the LAN interface, the system firewall allows inbound connections, and the client device is using the proxy host’s LAN address. Entering 127.0.0.1 on a phone points to the phone itself, not the computer. Be cautious about opening a listener on a public or shared network; where needed, add authentication and restrict which sources can connect.

Treat the management interface separately from the proxy endpoint. The controller can read status and change some runtime settings, so it should not be exposed directly to the public internet. If remote management is necessary, plan for authentication, access controls, and a protected transport channel. The example binds it to the loopback address for local tools only. Do not enter the controller port in browser proxy settings, and do not assume that a working management page means the proxy listener and remote connection are working.

Also distinguish the top-level ipv6 field from the identically named field under DNS. The former affects IPv6 use by the core; the latter controls AAAA responses from the built-in DNS. They are not the same switch. If your network depends on IPv6, disabling it is not a general-purpose optimization. First identify whether the failure occurs during resolution, connection, or routing, then decide what to change. For commands to diagnose port conflicts, see How to Find What’s Using Port 7890 and Change mixed-port.

3. DNS, Fake-IP, and Resolution Paths

DNS settings determine how domain names are resolved and how the core keeps domains associated with connections. They are separate from proxy rules and do not guarantee that applications send DNS requests to the core. Even with built-in DNS enabled, the operating system or an application may continue using its existing resolver. Requests may follow this path only if they are routed through system DNS, captured by TUN DNS hijacking, or passed as domain names through an application proxy protocol. Before troubleshooting, map out the actual path between the application, system resolver, core, and upstream resolver.

Basic Fields and Bootstrap Resolution

enable turns on the built-in resolver, listen sets its listening address, and nameserver specifies regular upstream resolvers. When using an encrypted DNS URL with a hostname, that hostname may itself need to be resolved first. default-nameserver is used for this bootstrap step; choose an address that is reachable on your current network and supported by the core. The example listens on a nonstandard local port for testing, but does not automatically change the operating system’s DNS settings.

dns:
  enable: true
  listen: "127.0.0.1:1053"
  ipv6: false
  enhanced-mode: fake-ip
  fake-ip-range: 198.18.0.1/16
  fake-ip-filter:
    - "*.lan"
    - "*.local"
  default-nameserver:
    - 223.5.5.5
  nameserver:
    - https://dns.alidns.com/dns-query

The upstream in the example is provided to illustrate the configuration format; test whether it works on your network. Encrypted DNS protects the relevant DNS traffic in transit, but does not guarantee that subsequent application connections use a proxy. Standard DNS queries usually use port 53, while the example uses port 1053. If your operating system accepts only a resolver address, do not copy a host-and-port value into it directly. Use the capture method provided by your client or a supported DNS forwarder instead.

Fake-IP vs. Redir-Host

fake-ip assigns a synthetic address to a domain being handled, then maps subsequent connections back to that domain. This can reduce reliance on having a real address in advance and preserve the domain information needed for rule matching. redir-host works from real DNS results and can suit cases that require real addresses. Actual rule matching still depends on the capture method, caches, and available domain-to-connection information, so neither mode can be described as universally faster.

fake-ip-filter lists domains that should not receive synthetic addresses, often LAN hostnames or domains used by applications that need real addresses. Add exceptions only for domains with a demonstrated compatibility issue; do not exclude every popular site by default. Filtering synthetic DNS behavior does not automatically add a direct-connection rule. A domain can resolve to a real address and still be routed to a proxy group. Check DNS exceptions and exit policies as separate layers.

After switching enhanced modes, the operating system, browser, and applications may retain old cache entries, while existing connections may continue using their previous path. For a clean test, close the relevant connections in the test application and, if needed, clear its DNS cache before sending a new request. A synthetic address alone does not indicate a DNS failure. However, if the client has exited while the system still caches synthetic addresses, access may temporarily fail; restore normal resolution and clear the cache.

Per-Domain Resolution and Proxy Endpoint Resolution

More complex configurations can use nameserver-policy to select different upstream resolvers for specific domains, or proxy-server-nameserver to resolve proxy server hostnames separately. The latter can prevent a startup dependency loop where the proxy endpoint has not been resolved yet, but accessing the resolver requires that same proxy. Whether you need these fields depends on your network and core support. Get basic resolution working first, then add policies one at a time; that is easier to troubleshoot than copying a complete DNS recipe all at once.

With respect-rules enabled, DNS upstream connections follow the applicable routing rules. You must also account for separate resolution of proxy endpoints and startup order. Avoid configuring the upstream resolver, proxy group, and proxy hostname to depend on one another in a loop that requires each to be running before it can start. If DNS policies rely on rule sets, make sure those rule sets have loaded successfully. Resolver selection can fail before application traffic reaches the routing stage.

4. Proxy Fields and Protocol Requirements

proxies describes remote proxy endpoints, and each entry must include the fields required by its protocol. The node name is a local reference; the server address is the connection target, and the port is the remote service’s listening port. None of these replaces the local mixed-port. Before configuring a node manually, get the complete parameters from your provider. A server address and password alone do not tell you the cipher, transport, or certificate settings required.

Name, Type, Address, and Authentication

Keep name unique and easy to recognize; proxy groups refer to nodes by name. type determines how the remaining fields are interpreted, so do not put a password from one protocol into an example for another. server can be a hostname or an address, and port must be a valid integer. The example below shows a Shadowsocks node mapping with illustrative address and password values. Replace them with the actual parameters from your server before use.

proxies:
  - name: "Example SS"
    type: ss
    server: ss.example.com
    port: 8388
    cipher: aes-128-gcm
    password: "your-password"
    udp: true

cipher must match the server. Do not replace it just because another cipher name looks newer. Quote passwords containing spaces, hash marks, or colons so parsing does not change their value. udp: true allows the node to use UDP where supported; it does not guarantee that every application’s UDP traffic will be captured, or that a remote server that lacks UDP support will gain it. The result also depends on the capture method, protocol, and server configuration.

TLS Identity and Transport Fields

For nodes that use TLS, distinguish the actual connection address from the server name used for certificate validation. Some protocols use sni, while others use servername; these field names are not universal across protocols. The Trojan example below shows the distinction: server determines where to connect, while sni gives TLS the expected hostname. Whether they should match depends on the server deployment, not on the address shown in a browser.

proxies:
  - name: "Example Trojan"
    type: trojan
    server: gateway.example.com
    port: 443
    password: "your-password"
    sni: gateway.example.com
    skip-cert-verify: false
    udp: true

skip-cert-verify: false keeps certificate verification enabled. If a certificate error occurs, first check the system clock, expected hostname, server certificate chain, and whether the connection was redirected. Only then decide whether the configuration is wrong. Disabling verification can hide identity problems and should not be the default fix for TLS issues. For transports such as WebSocket or gRPC, also check the required path, service name, or request headers. A reachable port does not mean these higher-level parameters are correct.

Subscription Nodes and External Proxy Providers

A subscription may populate proxies directly or use proxy-providers to supply a collection of nodes. A provider is a named resource, usually referenced by a group’s use field; it is not the same as adding a node name to the proxies list. Provider URL, cache path, update interval, and health checks each have a different purpose. A successful download does not mean the nodes are connectable; it only confirms that the resource could be retrieved.

When using an external provider, first check that the resource uses a format accepted by the core, then confirm that the proxy group references the correct provider name. Some services return a complete client configuration, not a provider file containing only nodes. If your client converts subscriptions, check that the output retains the required protocols and fields, especially transport parameters, certificate names, and protocol-specific options. A similar node count does not mean the content is equivalent.

Renaming a node manually affects every proxy group that references it. Before deleting a node, search for its name throughout the configuration. When replacing names in bulk, remember that the same text may also appear in rules or comments. Subscription updates can change node names, so custom groups that reference specific nodes need periodic review. Before sharing a configuration or asking for help, redact server addresses, passwords, subscription URLs, and account details. The field structure and error type are usually enough for an initial diagnosis.

5. Proxy Group Types and References

Proxy groups separate exit selection from rule matching. Rules can point to a stable name, while node changes or selection behavior can be managed inside the group. Each proxy-groups entry has a name, type, and set of candidates. Candidates can be proxies, built-in policies, or other proxy groups. A name is a reference contract, not just a label in the interface. If you rename it, update the rules and parent groups that refer to it, or the chain will break.

Manual Selection and Automatic Testing

select lets the user choose a candidate in the client interface and is useful when you want direct control over the exit. url-test selects a candidate based on test results; fallback focuses on keeping an available exit in a preferred order; and load-balance distributes connections according to its strategy. These fields are not interchangeable. Decide whether you want a fixed manual choice, automatic comparison, a preferred backup, or distributed connections before choosing a type and its parameters.

proxy-groups:
  - name: Proxy
    type: select
    proxies:
      - Auto
      - DIRECT

  - name: Auto
    type: url-test
    proxies:
      - "Example SS"
      - "Example Trojan"
    url: https://www.gstatic.com/generate_204
    interval: 300
    tolerance: 50

This snippet references the two example nodes from the previous section and only works when those node definitions exist. Here, interval is the test interval in seconds, while tolerance helps avoid switching over small differences between candidates. Neither represents a real-time measurement shown in the interface. Choose a test URL that is reachable and responds consistently in your environment. A failed test may mean that URL is restricted, not that all application traffic is unavailable.

Test Results Do Not Reflect the Full User Experience

Health checks usually measure access to a specific URL; they are not the same as download speed, video quality, or reachability of every destination. An exit may pass a probe while a particular service still fails because of destination restrictions, protocol, region, or the remote network path. Test the actual service with a new connection and check its connection details. Repeatedly changing the test interval—or treating one successful probe as proof that every network layer works—will not resolve the issue.

Including DIRECT among the candidates means a user may select a direct connection, either manually or through the group’s behavior. If a service must always use a proxy, do not add direct access to its group as a convenience. For groups used by local services, be clear about whether remote proxies are allowed. Name groups by purpose or selection method, and avoid similar labels such as “Auto,” “Backup,” and “Direct” that could make it easy to choose the wrong one.

Provider References, Nested Groups, and Cycles

When using use to reference a provider, enter the key defined under proxy-providers, not the subscription’s display title. If you filter nodes, confirm that the result contains at least one valid candidate; changes to node names can leave the filter with no matches. After editing, check which options actually appear in the group before deciding whether the rules are correct. A rule may match the intended group even when that group has no usable nodes.

Groups can reference other groups, letting a service group choose between a manual and an automatic group. The chain must eventually lead to a node or built-in policy. If group A references group B, and B references A, the configuration has a cycle; renaming the groups will not fix it. For a complex setup, sketch a short chain: service rule, service group, exit group, node. The more layers there are, the more important it is to check the current selection at each step. The first choice shown in the interface is not necessarily the actual exit.

Clients can usually remember manual selections, but the saved choice may come from runtime data rather than YAML order. Whether a selection survives a reload depends on how the client and core save state. Moving a node to the top of a list may not change the saved selection. When troubleshooting, check the currently selected value, choose again manually if needed, and verify with a new connection rather than inferring runtime state from file order.

6. Rule Syntax, Order, and Fallbacks

rules is an ordered list of decisions, not a collection of unordered labels. The core checks each connection from top to bottom using the information available to it, then applies the policy for the first matching rule. It does not continue looking for a more specific match further down. Position determines priority. When troubleshooting routing, check both the rule and any broader domain, address, or fallback rules above it. Pay particular attention to where subscription-generated and custom rules are merged.

Common Rule Types and What They Match

Enter a hostname in a domain rule; do not include https://, a path, or query parameters. To route a website through a proxy, do not paste the full URL from the browser’s address bar into DOMAIN. A page may also request resources from several other domains, so matching only the main hostname will not cover its static assets, authentication, and APIs. Use connection logs to identify the hostnames that actually need handling, then choose an exact or suffix match.

rules:
  - DOMAIN,router.home.arpa,DIRECT
  - DOMAIN-SUFFIX,local,DIRECT
  - IP-CIDR,127.0.0.0/8,DIRECT,no-resolve
  - IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
  - DOMAIN-KEYWORD,github,Proxy
  - DOMAIN-SUFFIX,googleapis.com,Proxy
  - GEOIP,CN,DIRECT
  - MATCH,Proxy

Address Rules and no-resolve

For applicable address rules, no-resolve means the rule will not trigger an extra DNS lookup for evaluation; it does not disable DNS as a whole. If the connection target is already an address, the core can still match it. If the target is only a domain and no address is available for evaluation, the rule may not match. Add this option only if you want to prevent this rule from triggering resolution; it is not a performance switch to append to every rule.

GEOIP matching relies on an IP address database, not the company’s location or the user’s region. A domain hosted by an overseas provider or a local service using a public network can produce results that differ from intuition. Database updates can also change the outcome. For services that must always be handled a certain way, add explicit domain exceptions before broad geographic rules. Check the core logs to confirm that the required data files are available.

Rule Sets, Process Matching, and Their Limits

RULE-SET lets you manage a collection of rules as a resource under rule-providers, making it easier to update and reuse. The provider’s behavior type must match the file contents: domain lists, address lists, and traditional rule collections are not interchangeable. Declaring a remote rule set does not mean it has downloaded successfully. On first launch, restricted networks, or with an invalid cache path, check the load logs before assuming rules that reference it can run.

Process rules depend on whether the operating system and traffic capture method can provide process information. A router receiving connections from other devices usually cannot identify the applications running on those remote devices. Process-name matching is not a capability you can count on across every platform. Before using these rules, check what your client supports. For routing ordinary websites, explicit domain rules are often easier to reproduce and share across devices.

A final MATCH,Proxy sends the remaining traffic to a proxy group; MATCH,DIRECT sends it directly. These represent different default policies, so choose based on your needs rather than copying the example blindly. If a catch-all rule appears at the top, the rules below it will never run. After changing rules, close existing connections in the test application or send a new, separate request. Established connections usually do not switch exits automatically when rules are reloaded.

A rule match confirms only that the destination policy was selected; it does not prove the exit connection succeeded. If the logs show a match for Proxy followed by a handshake error, check the group’s current selection and node parameters rather than adding the same rule repeatedly. If there are no request logs at all, return to the traffic capture layer and check the system proxy or TUN. Editing rules cannot affect traffic that never reaches the core.

7. Subscription Overrides and Configuration Merging

Subscription files handle remote updates, while custom configuration stores local preferences. Mixing them directly can cause conflicts the next time the subscription updates. Overrides let you save ports, DNS, service-specific rules, and custom groups in a stable place, then have the client generate the final configuration. First confirm whether your client performs a full replacement, field merge, rule insertion, or script processing. Features with similar names can use different merge behavior, so do not assume another client’s steps will apply.

Scalars, Mappings, and Lists Are Handled Differently

Scalars such as ports and modes usually have one final value, so a later override may replace an earlier one. DNS is a nested mapping: some tools merge it recursively, while others replace the whole section. Rules and proxy groups are lists, which may be replaced, prepended, or appended. YAML describes the data but does not define these client-specific behaviors. The snippet below shows fields you might want to add; it is not guaranteed to work the same way in every client.

mixed-port: 7890
mode: rule

dns:
  enable: true
  enhanced-mode: fake-ip

rules:
  - DOMAIN,router.home.arpa,DIRECT

If a tool treats rules as a full replacement, the example above will remove every rule from the original subscription. If it appends rules after an existing MATCH, the new rules may never match. Use the rule-prepending feature explicitly supported by your client, or reorder the list in a script you control, then inspect the generated result. A “saved successfully” message in the override editor does not prove the rules are in the right place or active.

Keep References Intact After Merging

When adding a service group, make sure the nodes or providers it references still exist after subscription updates. When adding a rule, make sure the target policy name has not been removed or renamed during merging. If the subscription already has a group named Proxy, a custom group with the same name may conflict or be overwritten. Use names that distinguish your local purpose, then check for duplicates after every generation instead of relying on the merger to deduplicate automatically.

DNS overrides need particular care with nested fields. Replacing the entire dns section just to change enhanced-mode may also remove the existing upstreams, per-domain policies, and proxy endpoint resolution settings. Conversely, a recursive merge may preserve old fields you no longer need. Inspect the complete merged DNS section and confirm that the old and new settings form a consistent resolution path. Do not rely on searching only for the line you changed.

The same risks apply to proxy and rule providers. Conflicting cache paths can cause resources to overwrite each other, renamed resources can leave broken references, and changes to file contents may make the original behavior type invalid. Keep a working copy before subscription updates, then check the load logs and group contents afterward. If something breaks, first roll back to a known-good state and compare the actual differences. Avoid layering more patches onto a failed result.

Local Maintenance and Safe Sharing

Keep three things available: the remote subscription source, local custom snippets, and the final runtime configuration. The first two show where the configuration comes from; the third shows what is actually running. When comparing them, start with top-level keys and list lengths, then check important rule positions, group names, and DNS paths. Do not copy every remote node into a custom file. That would prevent subscription updates from reflecting server address changes and node additions or removals, while shifting the maintenance burden to manual edits.

If an override script can run code, treat it as a program with permission to process your configuration. Use only logic you understand, and do not accept an unknown script just to insert one rule. Before sharing examples, remove real subscription URLs, authentication fields, and personal paths. Even a screenshot may expose account details in a full query string. Keep illustrative values in place to show the field structure without revealing account information.

8. Configuration Validation and Layered Troubleshooting

Validate in this order: syntax, references, listeners, DNS, rules, and remote connections. This sequence helps avoid unnecessary changes. There is no point changing node selection before the file loads successfully, or adjusting routing rules before a request reaches the core. Before you begin, note the client name, core, traffic capture method, and fields you just changed; there is no need to share the actual subscription. Keep the first error message, as many later connection failures may be consequences of the same underlying issue.

Run Static Checks, Then Review Startup Logs

When running mihomo independently, use its test option to check the configuration. The command below assumes the binary is in the current directory and the configuration is in the specified directory. Testing may also access external resources referenced by the configuration, so an error is not necessarily caused by indentation. In a GUI client, use its built-in validation and reload features where possible to avoid starting a second instance that competes for ports. Whichever method you use, confirm that you are validating the exact file you plan to enable.

./mihomo -t -d ./config-dir -f ./config-dir/config.yaml

A parse error may point to a line or nearby field, but the real cause can be on the previous line—for example, an unclosed quote, changed list indentation, or duplicate root field. For a reference error, trace the names: does the rule target exist, do the group’s candidates exist, and does the provider name match? If a field is unsupported, check whether the current core implements it. Clients with the same name may use different core capabilities across platforms and installation sources.

Check the Port and Confirm Traffic Reaches the Core

After the configuration loads, confirm that the listeners started successfully. Desktop systems with multiple proxy clients may have a background service occupying the port even if only one client interface is open. Identify the process first, then decide whether to stop the old instance or change the new configuration. Do not terminate an unfamiliar system process. Next, send a request with an explicitly specified proxy to test the HTTP path and temporarily rule out incorrect system proxy settings.

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

The command uses the local mixed port and a sample site to test connectivity. If you receive an HTTP response, that request passed through the specified listener, but this does not mean every application is using it. If the connection is refused, first check the listener and port. If the proxy accepts the request but it times out, check the rules, group selection, and remote error. A destination’s access restriction is different from an unreachable local listener; not every non-success response means the proxy is broken.

Use Logs to Trace DNS and Exit Problems

When DNS resolution fails, identify which hostname failed: the destination, the proxy server, or the DNS upstream itself. If the proxy endpoint cannot resolve, check bootstrap resolution and circular dependencies. If only LAN hostnames fail, check the local resolver, Fake-IP filters, and capture method. Once an application request resolves and matches a rule, check the selected policy and final node to make sure nested group selections are not sending traffic through a different exit.

For TLS errors, check the system clock, hostname, and certificate chain first. For authentication errors, verify the password and protocol fields. For timeouts, continue with the address, port, transport parameters, and network path. Do not disable certificate verification, replace DNS, and switch modes all at once; new variables can hide the original issue. Change one category of fields at a time and retest with a new connection to the same destination. Reused connections, caches, and background retries can all affect the result.

Rollbacks, Notes, and Ongoing Maintenance

Once a fix is confirmed, keep a short record of the fields changed, the error resolved, and whether the fix depends on a particular network. After client or subscription updates, check these fields first because they are easy to override. Restore any increased log level, temporarily opened listening address, and extra test listener to your normal settings. The more complex the configuration, the more useful it is to keep a known-good baseline for distinguishing environmental changes from issues introduced by new features.

Command-line deployments and GUI clients manage services differently. In particular, avoid running a system service and desktop application against the same core at the same time. For Linux, see Deploying mihomo on Linux Desktop and with systemd. Find quick links for common issues in Troubleshooting, or visit the download page to choose a client by platform. A successful validation means the configuration loads correctly, test requests follow an explainable path, and everyday application behavior matches expectations—not just that the interface says the client is running.