Clash Configuration Guide

1. YAML Overview: From File Structure to Active Configuration

A Clash configuration is not just a list of node addresses; it is a set of interdependent objects. General fields define entry points and operating modes, DNS fields determine how the core resolves domains, proxies define available exits, policy groups organize those exits, and rules send connections to their targets. When reading an unfamiliar configuration, start with the top-level keys and then trace name references. Reading hundreds of rules from the top down can obscure the entry settings and final policy that actually control the connection path.

Indentation, Mappings, and Lists

YAML expresses hierarchy through indentation. A colon followed by one space separates a key from its value, while a leading hyphen usually marks a list item. Two spaces are recommended consistently; do not mix tabs with spaces, and keep each level aligned. Top-level dns and rules should align, while enable belongs under DNS. Chinese names are allowed, but spaces, punctuation, and capitalization in a name are part of the reference and must not be changed elsewhere.

Use integers for ports and unquoted true or false for switches. Quote domain patterns, passwords, and strings containing colons or hash marks to prevent them from being interpreted as mappings, comments, or other types. A hash mark starts a comment only outside a quoted string. Avoid duplicate top-level keys as well: parsers may reject them or keep only one copy, and repeating a rules list is not a reliable way to append entries.

# Complete direct-connection example for teaching; no remote proxy nodes included
mixed-port: 7890
allow-lan: false
mode: rule
log-level: info

dns:
  enable: false

proxies: []
proxy-groups: []

rules:
  - MATCH,DIRECT

This configuration can run a basic startup test on cores that support these fields. If the port is available, it creates a local mixed proxy entry, but every matched connection still goes direct. An application must explicitly use that entry for the configuration to handle requests. It provides no remote exit and does not enable core DNS. Save it as a separate test file; do not overwrite an active subscription with it, or its existing nodes and rules will be removed.

Identify which layer the input file belongs to

A subscription URL is an address for retrieving content; it does not guarantee that the response is complete YAML. Some URLs return a full configuration, others return only a node list, encoded text, or a single-node share link. Put a complete configuration into the configuration import entry; a node collection may require client-side conversion or a proxy-providers reference. Choosing the wrong entry can produce missing fields, parse errors, or nonexistent rule targets even when the URL downloads successfully.

A client may process the configuration a second time. The subscription source preserves what the provider supplied, local settings store preferences such as ports and takeover methods, override files insert or replace selected fields, and only the generated final file is passed to the core. After editing any layer, find the client's runtime configuration preview or export function and verify that the change reached the final file. A value shown in the interface does not necessarily have final priority over a field with the same name in the subscription.

Trace references, not just syntax

A policy name in a rule must match a node, policy group, or built-in target; node names inside a policy group must also exist. Correct spelling is not enough: groups must not form circular references. Read in this order: nodes, policy groups, then rules. First identify the available exits, then how they are selected, and finally which connections are sent there. When rule providers or proxy providers are involved, also check their paths, formats, and load results rather than treating a top-level declaration as proof that loading succeeded.

Before making changes, record the current client name, core type, and configuration source, then export a restorable copy. Keep the working configuration whenever possible, change one topic at a time, and verify the difference. If you do not have a client yet, start with Clash Plus on the client download page, then compare other options by platform and required features. For a finer distinction between import formats, see Subscription Links and YAML Import.

2. General Fields: Ports, Modes, and Access Boundaries

General fields determine how local applications enter the proxy and which processing mode the core uses after receiving a connection. The most common confusion is between a local listening port and a remote node port: the former is provided by the core on the device, while the latter belongs to the server connection parameters. Putting a node's server port into system proxy settings does not establish a connection; system proxy settings usually need the local listening address and its HTTP proxy port, while the node port stays inside the node definition.

Choose a listening entry and verify actual usage

For a typical desktop setup, start with one mixed port to make troubleshooting easier. Configure separate HTTP or SOCKS ports only when an application truly requires one. Do not assign the same port to multiple listening fields, and do not start a second core on the same port while a graphical client is already running. If listening fails, identify the process using the port first; changing the port without updating system proxy settings merely moves the error from startup to connection.

# General field snippet; listening ports are for teaching only
mixed-port: 7890
allow-lan: false
bind-address: "127.0.0.1"
mode: rule
log-level: info
ipv6: false

This example restricts listening to the local device. The exact effect of bind-address on each entry must be confirmed against the core and the client's generated configuration; external accessibility cannot be inferred from the file alone. Applications should connect to 127.0.0.1:7890, not treat it as a remote node. Desktop proxy settings, browser-specific proxy settings, and terminal environment variables can differ, so programs on the same device may follow different paths.

Mode selection and traffic takeover are separate

rule selects a target for connections that have entered the core, following rule order; global processes those connections through the global policy; direct connects directly. Global mode is not full operating-system takeover and cannot guarantee that every application enters the proxy. Conversely, enabling TUN does not mean every request uses a remote node: once traffic enters the core, rules can still choose direct, reject, or proxy.

System proxy settings mainly affect applications that follow them. TUN takes over traffic through a virtual network interface and corresponding routes, and may require administrator privileges, a service component, or VPN authorization on mobile platforms. Do not change system proxy settings, TUN, DNS, and mode all at once just to test one webpage. First confirm that one application can reach a clear local port, then decide whether broader takeover is needed. For installation and authorization steps, return to the Modes and Traffic Takeover guide.

LAN access, logging, and IPv6

Enable LAN access only when other trusted devices need to use this device's proxy. Then check the listening interface, inbound firewall rules, and proxy authentication, and make sure the router does not expose the entry to the public internet. A proxy entry and a control interface are different services; the latter may switch policies, read connections, and modify configuration. Without a remote-management requirement, keep the control interface local-only rather than expanding management access to solve a connection problem.

log-level: info is suitable for everyday observation. Temporarily increase log detail while troubleshooting to see more context, but remember that logs may contain domains, node addresses, and connection metadata; redact them before sharing. Restore the normal level when finished to avoid continuously writing large volumes of records. Whether logs are persisted, how long they are retained, and where they are stored is usually controlled by the client as well, not just the core's level field.

The top-level ipv6 field and the field with the same name in the DNS section operate at different layers, and the operating system may continue using IPv6. Disabling it in an example only simplifies testing; it is not a general network optimization recommendation. For dual-stack access, check resolution results, routes, takeover scope, and whether the node can reach the target. Changing one switch cannot prove that no connection bypasses the proxy. Validate every general-field change against the final listening state and the actual request path.

3. DNS Handling: Resolution Entry Points, Upstreams, and Fake-IP

A DNS configuration must first answer who sends the query, who receives it, and how it reaches the upstream. Enabling the core's DNS service does not mean that the system and every application will use it automatically; browser-encrypted DNS, application-specific resolvers, and other VPNs can create separate paths. During troubleshooting, map the sequence between the application, system resolver, core DNS, and upstream server. Confirm that requests actually enter the intended entry point before judging whether the returned address is correct.

Core fields and resolution dependencies

# DNS snippet; 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
  default-nameserver:
    - 223.5.5.5
  nameserver:
    - https://dns.alidns.com/dns-query
  fake-ip-filter:
    - "*.lan"
    - "*.local"

listen declares the address where core DNS listens. This example uses a non-standard local port, which is suitable for explicit query tests, but most system network settings cannot accept a port like this directly. For ordinary applications to use it, the client must provide DNS takeover, forwarding, or TUN interception; do not set the system DNS to an address that listens on a non-standard port unless the client supports it. The upstream in the example is only a replaceable value, and reachability depends on the current network.

nameserver configures conventional resolution upstreams, while default-nameserver is commonly used to resolve the domain names of those upstream DNS servers themselves. If an encrypted DNS server uses a hostname, the core must first resolve that hostname to an IP before it can establish the encrypted connection. That bootstrap process cannot fully depend on the same channel before it exists, or it may create a dependency loop. Before changing upstreams, confirm that they are reachable on the current network.

Fake-IP stores domain-to-address mappings

Fake-IP mode can return a virtual address for a domain while the core retains the mapping between them. When the application later connects to that virtual address, the core uses the mapping to recover the domain and continue processing. A virtual address is not the real server address, so seeing one in system query results is not immediate proof of DNS poisoning. Successful connectivity still depends on the same core taking over the connection and the mapping remaining valid.

Traditional real-address responses are generally more compatible with programs that require real IPs, but the connection stage may need another mechanism to preserve or recover the domain name. Choose a mode based on application compatibility and the takeover design, not on the assumption that one mode is always faster. After switching enhanced modes, the system or application may still cache old results; clear relevant caches and rebuild connections before comparing behavior, so cache differences are not mistaken for mode differences.

fake-ip-filter excludes domains that should not receive virtual addresses; common starting points include LAN services and applications that require real addresses. The example shows only the list structure and does not cover every internal hostname. In particular, .local services may rely on multicast DNS, so adding an exclusion cannot solve every discovery issue. Excluding a virtual address also does not specify direct routing; resolution and connection policy must be checked separately.

Selecting upstreams by domain and assessing DNS leaks

# Merge into the existing dns mapping; do not add a second top-level dns key
# The internal DNS address is for teaching only and must be replaced with a reachable address
nameserver-policy:
  "+.corp.example":
    - 192.168.1.1

This policy shows how certain domains can be sent to a specific resolver, which is useful on networks with internal names. The internal resolver must know the domain and be reachable from the device's current network. After switching to an external network, that internal address may no longer exist; do not attribute a timeout directly to the remote proxy node. The matching syntax for policy keys is not the same as rule-list syntax, so do not copy a DOMAIN-SUFFIX rule here unchanged.

In mihomo versions that support these fields, proxy-server-nameserver can resolve the server domains of proxy nodes, while respect-rules makes DNS upstream connections follow routing rules. Pay close attention to dependencies between node resolution and proxy connections. fallback should not be read simply as a sequential backup after the first server times out; filtering conditions may also influence the selected result. Until the implementation is confirmed, use fewer resolution paths.

Test an ordinary domain, an internal domain, and a domain that requires the proxy separately. Record the resolution result and the rule matched by the subsequent connection. If only LAN applications fail, narrow the exclusion scope first; if every request waits on resolution, investigate upstream reachability and dependency loops. For virtual-address queries and connections, continue with Fake-IP Mapping and Exclusions.

4. Proxies: Protocol Fields and Connection Requirements

proxies is a static node list; each node describes one way to connect to a remote service. A node is not a policy group and does not decide which websites use it. It participates in a connection only when referenced directly by a rule or selected by a policy group. When troubleshooting a node definition, check the service address, credentials, transport, and TLS parameters separately. A node appearing in the client does not prove that its protocol parameters have passed a connection test.

General fields and protocol-specific fields

# Node snippet for teaching; the example domain and password cannot be used for a real connection
proxies:
  - name: "Teaching Node"
    type: ss
    server: edge.example.com
    port: 8388
    cipher: aes-128-gcm
    password: "your-password"
    udp: true

name is a local reference identifier and should be stable and unique; it does not have to equal the server hostname. type determines which protocol the core uses and how subsequent fields are interpreted. server and port must match the service's actual listening address; do not infer them from a webpage URL or subscription endpoint. Replace the reserved domain and teaching password with legitimately obtained parameters; renaming the node will not improve server connectivity.

Protocol-specific fields must correspond as a set. A Shadowsocks cipher and password must match the server; other protocols may require a UUID, authentication secret, additional handshake parameters, or different transport settings. Do not change a node's type to another protocol while keeping the remaining fields unchanged. A client recognizing a share link only means it has the relevant import logic; the generated fields must still be supported by the current core.

Do not mix TLS names with transport parameters

# Standalone proxy-list snippet; do not paste it alongside the earlier top-level proxies
proxies:
  - name: "TLS Teaching Node"
    type: trojan
    server: edge.example.com
    port: 443
    password: "your-password"
    sni: edge.example.com
    skip-cert-verify: false
    udp: true

For TLS-based protocols, the connection address and certificate verification name may be related, but they are not always identical. SNI selects the service name during the TLS handshake, while the HTTP Host and WebSocket path belong to different layers. When a provider specifies different values, use those parameters rather than swapping hostnames to silence an error. Certificate errors also require checking the system clock, server certificate, and intermediary devices; certificate verification should not be disabled permanently.

udp: true allows use of the UDP capability supported by the node; it cannot add UDP support to a server that lacks it. If games, voice, or other applications fail, check whether the application entered the proxy, whether the protocol supports it, whether the server permits it, and whether the chosen takeover entry can handle the traffic. A webpage test usually covers only part of the transport path, so one successful page load cannot prove that a node suits every application.

Choosing between static nodes and proxy providers

A small set of fixed nodes can be written directly under proxies for easy reading and comparison. A periodically updated node collection can be managed by proxy-providers and referenced by a policy group through use. The content returned by a provider URL must meet its expected format; a node collection and a complete configuration are usually different inputs. Putting a full subscription into an entry that accepts only a node collection can cause a structure mismatch rather than a network download failure.

Providers also involve update intervals, cache paths, and health checks. If remote content fails to update, the core may continue using its existing cache, so nodes shown in the interface do not prove that the latest refresh succeeded. Check the last load result and cached content instead of merely counting list entries. If downloading the provider requires a proxy that the provider itself is supposed to supply, the first load has a dependency problem; retain a working bootstrap path.

After renaming a node, check policy-group members, direct rule references, and client-saved selections. During troubleshooting, keep one trusted node with complete parameters, verify service status and authentication, then restore the collection gradually. When sharing a configuration, remove access credentials from subscription URLs, node passwords, and identifiable personal information. Public examples should use teaching values rather than merely masking a short section in a screenshot.

5. Policy Groups: Organize Nodes and Preserve Rule Entry Points

A policy group is a stable interface between rules and nodes. Rules can continue pointing to a group named “Exit Selection” while its members change with subscription updates or user choices. This reduces rule dependence on specific node names and lets different types of traffic use different exits. A policy group does not create a remote connection by itself; it must ultimately resolve to a real node or built-in target. When reading a group, check its type, member source, and final destination, not just the name shown in the interface.

Manual selection groups and built-in targets

# This snippet has no external node dependency, making group and rule references easy to verify
proxy-groups:
  - name: "Exit Selection"
    type: select
    proxies:
      - DIRECT
      - REJECT

rules:
  - DOMAIN-SUFFIX,example.com,Exit Selection
  - MATCH,DIRECT

A select group lets the user choose a member manually. This example intentionally includes only the built-in direct and reject targets, so structural testing does not depend on a remote service. Choosing reject blocks connections matched by the group; it does not fall through to another member. In real use, add names of already defined nodes to the list. List order and the client's saved selection may both affect the initial display, so do not assume every reload selects the first item.

DIRECT means the current device connects to the target directly, while REJECT refuses the matched connection. Do not reuse built-in target names for groups, and do not confuse a group name with a protocol type. If a rule targets “Auto Select,” an object with exactly that name must exist in the configuration; a different character, space, or punctuation mark can invalidate the reference. Chinese names can be readable, but the more complex the update chain, the more important stable naming becomes.

Automatic selection, failover, and load distribution

# Prerequisite: “Teaching Node” is already defined and verified under proxies
proxy-groups:
  - name: "Auto Select"
    type: url-test
    proxies:
      - "Teaching Node"
    url: "https://www.gstatic.com/generate_204"
    interval: 300
    tolerance: 50

  - name: "Exit Selection"
    type: select
    proxies:
      - "Auto Select"
      - "Teaching Node"
      - DIRECT

url-test tests connectivity to a specified address and selects a member based on the result. The interval and tolerance in this example are teaching values; tolerance reduces frequent switching caused by small differences and is not a promise about real-world latency. The test address must be reachable through the node's exit, so a failed test may mean that the address is restricted rather than that the node is entirely unavailable. With only one member, automatic selection has no alternative exit to compare.

fallback is closer to availability-based failover in member order and suits primary/backup setups. load-balance distributes connections; confirm its exact strategy and options in the current core documentation. Load balancing normally does not split one download connection across multiple nodes, nor does it add their bandwidth together. For applications involving login sessions or exit-IP sensitivity, frequently changing exits may trigger additional verification; stability should take priority.

Health checks reflect only a particular time, target, and test method. They do not cover every regional restriction, UDP capability, authentication renewal, or long-connection behavior. Do not pursue seemingly fresher status with extremely short intervals: tests consume device and node resources and may cause more switching during network fluctuations. Establish a stable baseline with a manual group first, confirm that the service works, then introduce an automatic group and compare its real benefit.

Provider references, nesting, and recovery choices

When nodes come from a proxy provider, a policy group usually references the provider name through use; static nodes are referenced through proxies. These are different reference objects, so a download URL cannot be placed where a member name belongs. Node filters may also exclude every member and leave an empty group. After an update, check provider loading, filter matches, and the group's actual members instead of relying only on the subscription refresh notice.

A policy group can reference another group, but the dependency chain must have an endpoint. For example, a manual group referencing an automatic group that references nodes is clear; two groups referencing each other form a cycle. Keep nesting shallow so troubleshooting remains traceable. If the interface shows “Exit Selection” set to an automatic group, continue by checking which node the automatic group ultimately selected; otherwise the actual exit in the logs may differ from the user's expectation.

Some clients or cores save policy selections and try to restore the previous member after a configuration update; behavior may differ when a member is renamed or removed. Record important group selections before updating rules or subscriptions, then check the actual destination afterward. If a rule matches correctly but the result is wrong, first check whether the group selected direct or an invalid node, then investigate deeper DNS and routing issues. The rule-and-policy workflow is also covered in the connection verification steps.

6. Rule Syntax: Match Conditions, Order, and Final Targets

rules are typically matched from top to bottom, and the first match is handed to its specified target. Ordering is part of the logic: put precise exceptions before broad rules and the final catch-all at the end. Do not treat the rule list as a freely sortable category table; a broad rule placed too early can prevent later specific rules from ever running. Before editing, identify which connections should change and where they previously matched.

Domains, address ranges, and catch-all rules

# Partial rule snippet: demonstrates match order with built-in targets
rules:
  - DOMAIN,blocked.example.com,REJECT
  - DOMAIN-SUFFIX,example.com,DIRECT
  - IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
  - IP-CIDR,10.0.0.0/8,DIRECT,no-resolve
  - IP-CIDR,172.16.0.0/12,DIRECT,no-resolve
  - MATCH,DIRECT

DOMAIN matches an exact domain, DOMAIN-SUFFIX matches a domain suffix and its subdomains, and DOMAIN-KEYWORD matches a keyword in the domain. Keyword matching is usually broader than expected and may catch unrelated domains containing the same string; when the suffix is known, prefer a suffix rule. Domain rules do not inspect paths, query parameters, or page content in a full webpage URL, so they cannot route traffic directly by URL directory.

IP-CIDR matches an IPv4 address range; IPv6 ranges use the corresponding IPv6 rule type. The private ranges in the example do not cover every local connection, which must be considered against the actual network and routes. MATCH takes no match value and directly specifies the final target, so it belongs at the end. If placed first, all later ordinary rules become ineffective.

Domain information and the boundaries of no-resolve

A domain rule can match only if the core has the relevant domain information when evaluating the rule. If an application resolves the name itself and sends only the destination IP, the core may not be able to apply a domain rule directly. Fake-IP mappings, hostnames carried by proxy protocols, or supported sniffing can provide clues, but none guarantees recovery of the original domain for every connection. When a domain rule stops working, first check whether the log shows a hostname or an address as the target.

An address rule may trigger resolution to determine which range the target belongs to. Adding no-resolve tells that rule not to initiate domain resolution; it does not disable global DNS or prevent resolution required later to establish the connection. If the connection already has a destination IP, the rule can still match it. Putting domain rules first and necessary address rules afterward can reduce unnecessary resolution dependencies, but the exact order must still serve the intended traffic policy.

Rule providers and local rule maintenance

# Prerequisite: create the rule file at the corresponding path
rule-providers:
  local-policy:
    type: file
    behavior: classical
    path: ./rules/local-policy.yaml

rules:
  - RULE-SET,local-policy,DIRECT
  - MATCH,DIRECT

# Contents of rules/local-policy.yaml, not the main configuration
payload:
  - DOMAIN-SUFFIX,example.com
  - IP-CIDR,192.168.0.0/16,no-resolve

A rule provider moves a match set into a separate file, while the main configuration assigns a policy to that set. The example uses classical behavior, so the rules in the set do not include a final target; domain and address sets require their corresponding behavior and content format. Remote rules also require checking download format, cache path, and update results. Matching file extensions do not guarantee matching structures: treating an ordinary text list as YAML with payload can cause a load error.

Geographic data, process-name, and process-path rules depend on additional conditions. Geographic classification varies with database coverage and update time; process rules are limited by system permissions, platform, and takeover method, so one platform's syntax is not universal. When maintaining rules, record why each was added and keep the match scope minimal. Test a new rule with a new connection, because an existing long-lived connection usually will not choose a new exit merely because rules were reloaded.

7. Overrides and Merging: Preserve Subscription Updates and Local Changes

Directly editing a downloaded subscription file often loses the changes at the next update. Overrides separate provider-managed nodes and base rules from device-specific ports, DNS, and rule preferences. There is no merge algorithm shared by every client: some replace fields, some support prepending or appending rules, and some run scripts over the complete object. Before using an entry, confirm whether it processes a YAML fragment, a complete configuration, or an executable script.

Understand scalars, mappings, and lists separately

# Related fields in the original configuration
mixed-port: 7890
mode: global
allow-lan: true

# For client override entries that support this type of field replacement only
mode: rule
allow-lan: false

# Assumption: the same-named scalar is replaced by the local override
mixed-port: 7890
mode: rule
allow-lan: false

This example demonstrates scalar replacement only: the original port remains, while mode and LAN access are replaced by local values. It does not prove that nested DNS fields are merged item by item, nor that rule lists are appended automatically. If the client's general settings are written again after the override, the final result may change. In practice, compare the client's generated final configuration rather than inferring execution order from the override entry's name.

Mapping merges can use shallow replacement or recursive merging. For example, the original DNS mapping may contain upstreams, a filter list, and a listening address while the local override specifies only enable: true. If the entire mapping is replaced, the other values may disappear; with recursive merging, unspecified keys may remain. Deleting a field is not guaranteed to work by writing null: some mechanisms preserve null values, some reject the input, and others provide a dedicated delete operation.

List append direction determines behavior

Rules, nodes, and policy groups are all lists, but they cannot share one undifferentiated append strategy. Rules have ordering semantics, so adding a local exception after an existing MATCH usually has no effect; node lists require attention to duplicate names; policy-group lists involve both group names and member references. Do not interpret “supports merging” as automatic handling of duplicate nodes, circular references, and rule priority.

# This illustrates the order in the final configuration, not a universal override instruction
rules:
  - DOMAIN,printer.lan,DIRECT
  - DOMAIN-SUFFIX,example.com,DIRECT
  - MATCH,Exit Selection

The example assumes that the original configuration already defines an “Exit Selection” group and that printer domains should indeed go direct. Putting this rule first changes only rule-level exit selection; incorrect printer DNS, failed multicast discovery, or broken LAN routing still require separate handling. In a configuration with more specific reject rules, also confirm that the prepended rule does not accidentally allow a target that was meant to be blocked.

Build a repeatable, reversible workflow

Save the original subscription, local override, and final runtime configuration separately. The original reveals provider-side structural changes, the override records local intent, and the final file is used for core testing. Add one processing step at a time and note the group names or fields it depends on. If the provider changes a group name, local rules can lose their target even when their syntax remains valid; recheck references after each subscription update.

Scripted overrides should be idempotent: processing the same input once or repeatedly should produce the same result. A common mistake is inserting the same rule into the list on every run until it accumulates, or mutating a shared object directly so later steps see unexpected state. Defend against missing fields and type changes as well; do not assume every subscription contains a DNS mapping or a same-named policy group. When script behavior is difficult to explain, prefer simpler field operations.

Client upgrades, core changes, and subscription updates can all alter the merge chain. Before applying changes in production, generate the result from a copy, compare ports, mode, DNS, group names, and the final rules, and confirm that provider paths or security settings were not cleared. When something breaks, disable the most recently added override, restore the original configuration and known-good choices, then restart the processing steps one by one. A minimal diff is easier to diagnose than repeatedly copying an entire configuration.

8. Validation and Troubleshooting: From Syntax Checks to Real Connections

Validate in layers: the file parses, references load, listeners start, the application reaches the entry point, rules match, and the exit reaches the target. Passing one layer does not guarantee the next. Configuration test commands mainly check format and loadability; they do not perform live authentication for every node or complete business testing on your behalf. Record the layer where the failure occurs, then choose the shortest validation path to avoid repeated reinstalls and unrelated parameter changes.

Check the final configuration with the same core

# macOS / Linux: mihomo executable is available in the current directory
# check.yaml is an exported copy of the final configuration
./mihomo -t -f ./check.yaml

# Windows PowerShell: mihomo.exe is available in the current directory
.\mihomo.exe -t -f .\check.yaml

Before running the command, confirm that it points to the same core and runtime environment used by the client, and check the arguments against that executable's help output. A graphical client name is not the executable name; another program with the same name on the system may support different fields. Test in a controlled directory where providers, rule files, databases, and other dependencies are accessible. Relative paths usually depend on the core's working directory or configuration handling, so copying only the main file does not reproduce the same environment.

When an error reports a line number, inspect that line and the preceding lines together. An unclosed quote, incorrect indentation, or shifted list level may not be detected until the next field. For reference errors, trace names upward and check group, node, and provider names; for missing resources, check paths, permissions, and content format. Do not attribute every error to YAML indentation, and do not delete security or routing fields you do not understand merely to make the test pass.

Validate entry, rules, and exit step by step

# Prerequisite: mixed-port is 7890 and the core has started successfully
curl --proxy http://127.0.0.1:7890 --head https://example.com/

# Use curl.exe on Windows to avoid command-alias differences
curl.exe --proxy http://127.0.0.1:7890 --head https://example.com/

Explicitly specifying the proxy entry temporarily removes system proxy settings from the equation. A successful HTTP response shows that this request completed the relevant path, but the status need not be successful and does not prove that every application is being taken over. The test domain is only a basic connectivity target; to verify a specific service, use an address that service permits and confirm the matched rule and final policy in the client's connection log.

If explicit proxying works but the browser fails, focus on the browser's independent proxy, encrypted DNS, extensions, and system settings. If both fail, first check whether the core is listening and whether the ports match, then inspect DNS and remote-connection errors. If direct access works but a proxy node times out, check subscription validity, node address, authentication parameters, and the upstream network instead of immediately changing the entire rule set. See Proxy Node Timeout Troubleshooting for the layered order.

Cache, logs, and safe rollback

After changing DNS, Fake-IP mode, or rules, start a new connection. Browser connection pools, application long connections, system DNS caches, and core caches may preserve old state temporarily. Close the target application's relevant connections first, then use the appropriate cache-clearing method provided by the system or client; do not delete the entire user directory to solve a one-off cache issue. Record the time of requests before and after testing so they can be matched accurately to log events.

Logs should retain the error type, time, matched rule, and necessary connection stage while removing subscription credentials, authentication details, and domains that do not need to be public. A UI crash and a core failure are different branches: the former calls for checking the runtime environment and interface components, while the latter calls for configuration, permissions, and listener errors. If the client cannot open, preserve the scene first with Launch Failure and Configuration Recovery instead of immediately clearing data.

When rolling back, first disable the most recently enabled takeover method, restore a known-good configuration and policy selection, then check whether system proxy and DNS settings were left behind manually. Exiting the client does not necessarily undo network parameters written by the user, so keep records from before the change. Final acceptance should cover at least one ordinary request, one target-service request, and one LAN request. After confirming that logs and paths behave as expected, restore the usual log level and back up the configuration.

If you only need to complete your first connection, return to the Getting Started path. If you need to choose a different graphical client, compare configuration management approaches in the selection guide, then open the appropriate platform from the download page. The goal of this manual is to give every change a clear prerequisite, observable result, and recovery method—not to enable every optional field at once.