Clash Configuration File Reference

YAML Structure Overview and Load Order

How the top-level sections work together

A working Clash or mihomo configuration usually consists of five parts: general settings, DNS, proxy nodes, proxy groups, and rules. They are not isolated lists but a chain of references: proxies defines nodes that can establish connections, proxy-groups organizes nodes or other proxy groups into selectable exits, and rules sends different connections to a proxy group, DIRECT, or REJECT. The DNS section brings domain resolution into this chain, while common fields determine the listening ports, operating mode, LAN access, and control interface.

Indentation determines field placement. Top-level keys must start at the beginning of a line, child fields are usually indented by two spaces, and list items begin with a hyphen. YAML does not use tabs for nesting, and the same level should not switch between two and four spaces. A configuration that displays correctly in a text editor may still be rejected by the parser; Chinese punctuation, full-width colons, invisible tabs, and incorrect indentation are common causes of load failures. When a string contains a colon, hash, braces, or leading or trailing spaces, enclosing it in single or double quotes is safer.

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

dns:
  enable: true
  enhanced-mode: fake-ip
  nameserver:
    - 1.1.1.1
    - 8.8.8.8

proxies:
  - name: "Example Node"
    type: ss
    server: 192.0.2.10
    port: 443
    cipher: aes-128-gcm
    password: "your-password"

proxy-groups:
  - name: "Node Selection"
    type: select
    proxies:
      - "Example Node"
      - DIRECT

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

Mappings, lists, and scalars

When reading a configuration, start by distinguishing three basic data types. A mapping pairs a key with a value, such as mode: rule; a list is a series of entries beginning with hyphens, such as the addresses under nameserver; a scalar is a string, number, or Boolean value. true and false do not need quotes, ports are usually written as numbers, and node names are strings. If a Boolean is written as the quoted value "false", some implementations treat it as ordinary text, which may produce unexpected results.

YAML also supports inline arrays, such as proxies: [Node A, Node B, DIRECT]. This is suitable for very short lists, but readability drops quickly when there are many nodes, punctuation in names, or frequent edits. For systematic configuration, use a one-item-per-line list. Anchors, aliases, and complex types are part of the YAML standard, but not every client's override system preserves them completely. For cross-client configurations, ordinary mappings and lists are the safer choice.

Checks from parsing to activation

Configuration loading can be checked at three levels. The first is YAML syntax, mainly indentation, colons, and list formatting. The second is field structure—for example, whether a node is missing server or a proxy group references a name that does not exist. The third is runtime behavior, such as an unreachable remote server, an upstream DNS timeout, or system traffic that is not being intercepted. Do not change rules immediately after seeing “connection failed.” First check whether the client log reports a configuration parsing error, then confirm that the target proxy group can select a node, and only afterward inspect the connection and DNS paths.

Common Fields, Listening Ports, and Operating Modes

What the port fields do

port is the HTTP proxy port, socks-port is the SOCKS5 proxy port, and mixed-port accepts both HTTP and SOCKS5 requests on one port. Desktop graphical clients usually need only mixed-port, after which the client can configure the system proxy automatically. Split the ports only when a particular application requires a specific proxy type. Multiple fields may coexist, but port numbers must not conflict with another program on the system or another Clash instance.

Typical signs of a port conflict include the core exiting immediately after startup and log messages containing bind, listen, or address already in use. Close any leftover process first, or change the configured port to an unused value, then update the port in your browser, development tools, or system proxy settings. Changing only the YAML while leaving manually configured applications unchanged can leave the core running while the application cannot connect. If the client provides a port settings screen, change it there when possible, because some clients use an override layer that replaces the original subscription port.

LAN listening and the control interface

allow-lan controls whether other devices can connect to the proxy ports on the current device. Set it to false when the proxy is for local use only. With true, also consider bind-address and the system firewall to determine the actual accessible range. Exposing the proxy to the LAN means devices on the same network may try to connect, so do not expose the control interface or proxy ports unconditionally to an untrusted network. When temporarily sharing the proxy with a phone or test device, verify the nature of the current network and restore the restriction afterward.

external-controller is the control address used for communication between the client interface and the core, commonly in the form 127.0.0.1:9090. Bind it to the loopback address when it is used only locally. secret authenticates control-interface requests; once set, panel requests must include the corresponding value. It is not a proxy-node password and does not change the proxy protocol. If the graphical client manages the control interface automatically, avoid repeatedly editing it in the raw subscription, as this can prevent the interface from reading the core status.

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"
secret: "your-controller-secret"

Rule, Global, and Direct

mode: rule matches connections against rules from top to bottom and is the most common mode for everyday use. global skips rule evaluation and sends all traffic to the global proxy group; it is useful for briefly testing whether a node works, but it does not prove that the rule configuration is correct. direct connects directly without using a proxy node and can help determine whether the problem lies in the proxy path. Many clients let you switch modes in the interface and override the file's mode at runtime, so check both the interface state and the effective configuration during troubleshooting.

log-level commonly supports silent, error, warning, info, and debug. Keep it at info for normal use; temporarily switch to debug when investigating rule matches, DNS queries, or connection handshakes. Debug logs are verbose, so restore the normal level after confirming the issue. ipv6 controls whether the core handles IPv6-related features, but the result also depends on the system network, DNS responses, and node support. If the network has no stable IPv6 connectivity, disabling this field can reduce failed paths; enable it when the environment genuinely supports IPv6.

DNS, Fake-IP, and Resolution Paths

What the DNS section does

Proxy rules often depend on domain names, but an application may provide only an IP address when it opens a connection. If resolution happens entirely outside the core, the rule engine may lose the original domain and be forced to match by IP. Once dns.enable enables the core DNS module, domain queries can work together with rules, proxy exits, and caching. This does not simply replace the system DNS with another address; it makes resolution part of the traffic-processing path.

nameserver lists the primary upstream resolvers. default-nameserver is mainly used to resolve the domain names of encrypted DNS servers themselves and should usually contain directly reachable IP addresses, avoiding a circular dependency in which the resolver's domain must be resolved first. fallback provides another set of resolution sources, with filtering conditions determining when backup results are used. Newer mihomo configurations also support proxy-server-nameserver for resolving proxy-server domains, keeping node resolution from interfering with ordinary website queries.

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"
    - "localhost.ptlogin2.qq.com"
    - "+.stun.*.*"
  default-nameserver:
    - 1.1.1.1
    - 8.8.8.8
  nameserver:
    - "https://1.1.1.1/dns-query"
    - "https://8.8.8.8/dns-query"
  proxy-server-nameserver:
    - 1.1.1.1

How Fake-IP works

With enhanced-mode: fake-ip enabled, the core returns a mapped address from a reserved range to the application and records the original domain associated with it. When the application later connects to that address, the core can restore the domain and apply domain rules. This means that even if an application initiates an IP connection, rules such as DOMAIN, DOMAIN-SUFFIX, and GeoSite may still match accurately. The default reserved range is usually 198.18.0.0/16, which is intended for network benchmarking and should not be treated as a public Internet destination.

Fake-IP does not mean that a website really resolved to a reserved address, and a reserved address should not be used to test public Internet connectivity directly. It depends on traffic continuing to pass through the current core. If an application bypasses the system proxy and TUN, it may receive a mapped address and then try to connect to it directly, causing the request to fail. Therefore, seeing a result beginning with 198.18 is not, by itself, evidence of a fault; check whether the application's traffic is actually being intercepted.

fake-ip-filter excludes domains that are unsuitable for mapping. Local-device discovery, printers, multiplayer games, STUN, time synchronization, and some services that require real addresses may need genuine DNS results. Do not copy an oversized list from the Internet and use it indefinitely, because broad exclusions weaken domain restoration. A safer approach is to start with a minimal configuration, add a specific domain only after a confirmed compatibility issue, and record why it was added.

Redir-Host and DNS leak troubleshooting

redir-host returns the real IP, then attempts to associate it with a domain through sniffing, mapping, or existing resolution data. It is more straightforward in some environments that are incompatible with Fake-IP, but domain-rule reliability depends more heavily on the request path. Neither mode is universally better outside its operating environment. On desktops using TUN and requiring complete domain-rule coverage, try Fake-IP first; for routers, special LAN services, or confirmed mapping-compatibility issues, evaluate Redir-Host.

Troubleshoot DNS by confirming the request path layer by layer: whether system requests enter the core's listening port, which upstream the core uses, whether the upstream connection goes direct or through a proxy, whether the result is cached, and which rule ultimately handles the connection. Merely changing nameserver rarely solves every issue. Browsers may use their own secure DNS, and the system may cache old results. After changing the configuration, reload the core and clear system and browser caches when necessary.

If a test shows that the DNS exit differs from what you expect, first check the browser's independent DNS settings, then inspect nameserver-policy, fallback resolvers, and the rule mode. For detailed steps, see Clash DNS Leak Testing and Prevention Guide. Do not confuse the resolver's location with the connection exit: the upstream that answers a DNS query and the node that carries the website connection are related but not identical paths.

Proxy Node Fields and Protocol Differences

The common structure of a node definition

Each item under proxies represents an available exit. Every node needs at least a unique name, protocol type, server server, and port port; the remaining fields vary by protocol. Node names are not only displayed in the interface—they are also referenced as strings by proxy groups, so renaming one requires updating every proxy-groups reference. Names are case-sensitive, and extra spaces at either end can also break references.

server can be an IP address or a domain name. When a domain is used, the node server itself must resolve successfully before the subsequent connection can be established; this is why proxy-server-nameserver can be useful. Write the port as a number and usually keep credentials as strings. Addresses and credentials in example configurations only illustrate the structure. Use the parameters supplied by the subscription or service provider, and do not infer encryption, transport, or server names from the protocol name alone.

Shadowsocks, Trojan, and VLESS Examples

proxies:
  - name: "SS Example"
    type: ss
    server: 192.0.2.10
    port: 443
    cipher: aes-128-gcm
    password: "your-password"
    udp: true

  - name: "Trojan TLS Example"
    type: trojan
    server: 192.0.2.20
    port: 443
    password: "your-password"
    sni: "edge.example.net"
    skip-cert-verify: false
    udp: true

  - name: "VLESS WS Example"
    type: vless
    server: 192.0.2.30
    port: 443
    uuid: "11111111-2222-3333-4444-555555555555"
    network: ws
    tls: true
    servername: "edge.example.net"
    ws-opts:
      path: "/proxy"
      headers:
        Host: "edge.example.net"

The key Shadowsocks fields are cipher and password, and both must match the server. Trojan usually runs over TLS, with sni specifying the server name used during the handshake. VLESS has more possible combinations, commonly involving TLS, Reality, WebSocket, gRPC, or plain TCP. After setting network: ws, make sure the path and Host in ws-opts match the server. With the wrong transport layer, the server port may accept a TCP connection while the protocol handshake still fails.

skip-cert-verify: true skips certificate validation and should not be treated as a universal fix. Certificate errors may result from an incorrect device clock, a mismatched server name, a broken certificate chain, or interference somewhere in the network. Check sni, servername, and the system time first, then decide whether testing genuinely requires this option. Keeping certificate verification enabled in production makes real configuration errors easier to detect.

UDP, Network Interfaces, and Chained Proxies

udp: true allows the core to attempt UDP forwarding, but actual usability also depends on the protocol, server, and network environment. Enabling the field does not make every UDP application work automatically; application traffic must also be correctly intercepted by TUN or a transparent proxy. When games, voice calls, or QUIC fail, first use the logs to confirm that the UDP session entered the core, then check the node's capabilities.

interface-name can select the system network interface used for outbound traffic and is useful on multi-NIC systems, dial-up connections, or routers. Most desktop users do not need it; an incorrect interface name can send every connection toward a nonexistent or unreachable adapter. routing-mark mainly serves Linux policy routing and should not be copied directly from another configuration.

mihomo supports mechanisms such as dialer-proxy that let one node establish its underlying connection through another proxy or policy, which can be useful for specific chained exits. The longer the chain, the more complex DNS, handshakes, and fault isolation become. Verify each segment independently before combining them. Do not add chaining, special transports, and interface binding while the base node has not yet passed testing.

How to modify nodes from a subscription

Subscription updates usually replace the entire node list. Direct edits to subscription-generated proxies may disappear at the next refresh. When you need to pin an SNI, exclude a node, or adjust UDP, use the client's override, scripting, or node-conversion features first. Clash Plus, Clash Verge Rev, FlClash, and Clash Nyanpasu organize their override entry points differently, but the principle is the same: keep the original subscription as the data source and put local differences in a separate layer.

Proxy Group Types, References, and Selection Logic

Select, URL-Test, Fallback, and Load-Balance

Proxy groups are the scheduling layer between rules and nodes. select lets the user manually choose a node or lower-level proxy group and suits exits that need explicit control, such as “Node Selection,” “Streaming,” or “Downloads.” url-test automatically selects a node that meets the test conditions and suits users who want to switch to an available connection automatically. fallback chooses the first available node in list order, prioritizing order rather than the lowest test result. load-balance distributes connections across multiple nodes according to a strategy and is best suited to users who understand the effects on session consistency.

Automatic tests usually require url and interval. The test URL should be stable, lightweight, and representative of the target network path. A very short interval creates unnecessary requests, while a very long one delays detection of node changes. tolerance reduces frequent switching when test values are close; it should not be interpreted as a single measurement of actual download speed. Node latency tests, webpage time to first byte, sustained throughput, and peak-hour stability are different metrics.

proxy-groups:
  - name: "Node Selection"
    type: select
    proxies:
      - "Auto Select"
      - "Failover"
      - "SS Example"
      - "Trojan TLS Example"
      - DIRECT

  - name: "Auto Select"
    type: url-test
    url: "https://www.gstatic.com/generate_204"
    interval: 600
    tolerance: 80
    proxies:
      - "SS Example"
      - "Trojan TLS Example"

  - name: "Failover"
    type: fallback
    url: "https://www.gstatic.com/generate_204"
    interval: 600
    proxies:
      - "Trojan TLS Example"
      - "SS Example"

Proxy groups can reference other proxy groups

The proxies list inside a group can contain not only nodes but also another proxy group and the built-in exits DIRECT and REJECT. This supports a layered design: lower-level groups handle node health checks, middle-level groups handle service selection, and a top-level group serves as the target for rules. For example, a “Streaming” group can contain “Node Selection” and several region-specific groups, while each regional group uses automatic testing.

References must not form cycles. If group A contains B and B contains A, the core cannot determine a final exit. Proxy group names must also be kept distinct from node names. For large configurations, use a consistent prefix for group names, but avoid excessive symbols; clear service-oriented names are easier to search in logs than decorative characters. Rule targets must exactly match proxy group names, or the configuration will report a missing policy during loading.

Use Providers to populate nodes

When nodes come from proxy-providers, a proxy group can reference a Provider through use instead of listing every node name in proxies. When the remote node list changes, the automatic test group can receive the new nodes. filter and exclude-filter can filter by name, but the result depends on regular expressions and subscription naming; a provider renaming its nodes may leave the result empty. Keep a way to inspect filtered groups and do not assume region keywords will remain unchanged.

proxy-providers:
  main-subscription:
    type: http
    url: "https://config.example.net/subscription.yaml"
    path: "./providers/main.yaml"
    interval: 3600
    health-check:
      enable: true
      url: "https://www.gstatic.com/generate_204"
      interval: 600

proxy-groups:
  - name: "Subscription Nodes"
    type: select
    use:
      - main-subscription

  - name: "Automatic Test"
    type: url-test
    use:
      - main-subscription
    url: "https://www.gstatic.com/generate_204"
    interval: 600

How to design maintainable group layers

More proxy groups do not necessarily mean finer control. Each additional layer increases the number of selection states and troubleshooting branches users must understand. A basic configuration can stay at three layers: one main entry group, one automatic selection group, and a few service groups with clear purposes. Point rules to the main entry group by default, creating a service group only when a service truly needs an independent exit. This preserves manual control without leaving dozens of similarly named groups to sort through after every subscription import.

When troubleshooting a rule that matches but does not use the expected node, start with the rule target in the logs and expand the proxy groups layer by layer: identify the group receiving the rule, check which child group it currently selects, and finally confirm the actual node underneath. Looking only at the top-level group name can hide a lower-level automatic selection. Existing connections may not move immediately after a node switch, so re-establish the connection or close the relevant application session during verification.

Rule Syntax, Match Order, and Fallback Policies

Rules match the first item from top to bottom

rules is an ordered list. The core checks entries from the top, stops at the first match, and sends the connection to the policy specified at the end of that rule. Order therefore matters more than the number of rules. Exact domains, special services, and items that should be rejected usually come first; broad domain suffixes, IP ranges, and geographic rules come later, with MATCH handling connections that match nothing else.

Putting MATCH in the middle makes every rule after it ineffective. Placing an overly broad DOMAIN-SUFFIX before an exact exception can also intercept subdomains that should use another policy. When editing a rule, do not check only whether that line is correct; inspect whether a broader match already appears above it. The rule type and policy name in the logs are the direct evidence of where a connection actually matched.

rules:
  - DOMAIN,api.example.com,Node Selection
  - DOMAIN-SUFFIX,example.net,Node Selection
  - DOMAIN-KEYWORD,stream,Streaming
  - IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
  - IP-CIDR,10.0.0.0/8,DIRECT,no-resolve
  - GEOIP,LAN,DIRECT
  - GEOSITE,private,DIRECT
  - GEOSITE,category-ads-all,REJECT
  - MATCH,Node Selection

Domain rule differences

DOMAIN matches only the complete domain, such as api.example.com; it does not automatically match other subdomains. DOMAIN-SUFFIX,example.com matches the root domain and its subdomains, making it suitable when an entire site should use the same policy. DOMAIN-KEYWORD may match whenever the domain contains the specified fragment, so its scope is broad and short keywords can affect unrelated sites. When a complete domain or suffix is available, prefer it over a keyword rule.

GEOSITE references domain collections in a category database and is useful for maintaining large service categories. Its results depend on local GeoSite data being present, the rule-set name being correct, and the data being up to date. With an outdated database, newly added domains may not match; a wrong category name may surface during configuration loading or rule initialization. For maintenance methods, see GeoIP and GeoSite Database Update Guide.

IP rules and no-resolve

IP-CIDR matches IPv4 ranges, while IP-CIDR6 matches IPv6 ranges. The trailing no-resolve means that when the current connection has no destination IP yet, the core should not start an extra DNS query just to evaluate this rule. It is often used for LAN ranges and known IP sets, reducing unnecessary resolution and preventing another query after domain rules. However, do not add it mechanically when an IP rule must rely on a DNS result to make its decision.

GEOIP classifies connections according to the geographic database associated with the destination IP. It operates at the IP layer and differs from the domain classification performed by GEOSITE. A domain may use globally distributed addresses, and resolution results can vary by network location, so GeoIP does not always represent a service's business location. Prefer domain collections when routing a website or service; use IP rules when handling the actual destination ranges.

DIRECT, REJECT, and MATCH

DIRECT sends a connection directly through the local network and suits LAN destinations, system services, or targets that explicitly require a local exit. REJECT denies a connection and is commonly used for confirmed advertising or tracking domains. Rejecting too broadly can remove page resources, break sign-in, or cause an application to retry repeatedly, so adjust it one item at a time using the logs. MATCH is the final fallback; it does not test domain or IP conditions, so every connection not matched earlier enters this policy.

An easy-to-understand default design is to send LAN and private domains direct, handle explicit allow or reject items according to need, route specific services to service groups, and send everything else to the main entry group. Do not merge large sets of rules from unknown sources and expect them to work perfectly on the first attempt. Rules can override one another, and different lists may assign opposite policies to the same domain. After adding a rule set, inspect several representative domains in the logs to verify their match order.

Proxy Providers, Rule Sets, and External Files

The maintenance problem Providers solve

As the number of nodes and rules grows, putting everything into one YAML file becomes difficult to update. proxy-providers loads node collections, while rule-providers loads rule collections. The main configuration keeps only the source, cache path, update interval, and references, so the entire main file does not need to be rewritten when remote content changes. Providers work well for subscriptions and public rule sets, but they introduce dependencies on downloads, caching, and file format. During troubleshooting, distinguish a main-configuration parsing failure from a remote-file update failure.

type: http fetches content from a network address, while type: file reads a local file. path specifies the cache or file location and is usually relative to the runtime directory. Configuration directories differ between clients, so do not copy an absolute path from another device. interval controls the update interval in seconds; a value that is too short causes frequent requests, while one that is too long delays updates. Manually updating a subscription in the client may also trigger a Provider refresh.

rule-providers:
  private-domain:
    type: http
    behavior: domain
    format: yaml
    path: "./rules/private-domain.yaml"
    url: "https://rules.example.net/private-domain.yaml"
    interval: 86400

  private-network:
    type: http
    behavior: ipcidr
    format: yaml
    path: "./rules/private-network.yaml"
    url: "https://rules.example.net/private-network.yaml"
    interval: 86400

rules:
  - RULE-SET,private-domain,DIRECT
  - RULE-SET,private-network,DIRECT,no-resolve
  - MATCH,Node Selection

behavior must match the file content

behavior: domain indicates that a rule set mainly contains domain entries, which may be full domains, suffixes, or equivalent domain-rule forms; ipcidr indicates IP ranges; classical allows a rule set to retain a fuller classic rule syntax. If the behavior type does not match the actual content, the rules may fail to parse or match as expected. Choose the type based on the format supplied by the rule source, not merely on the filename.

Common YAML rule sets place entries under payload. A simplified domain-behavior entry can use a domain-suffix form, while classical behavior can contain complete typed rules. The main configuration assigns a policy through RULE-SET, so a Provider file generally describes only match conditions and does not repeat the proxy group on every line. If the source already includes policy fields, confirm that classical format is genuinely required.

payload:
  - "example.com"
  - "+.example.net"
  - "service.example.org"

Updates, caching, and failure fallback

When a remote rule update fails, the core usually tries to continue using the existing cache. However, a Provider may be unavailable on its first load if no local cache exists. HTTP status codes, timeouts, file permissions, and format errors in the logs point to different problems. First verify in a browser or command line that the address is reachable, then check whether the client can write to the directory specified by path, and finally confirm that the downloaded content is the expected YAML or MRS format rather than a login or error page.

Cache files should not be written by multiple running instances at the same time. Starting two clients on one device with the same configuration directory can cause port conflicts and contention over Provider files. When migrating a configuration, move the required local rule files as well, or ensure that the remote sources are reachable in the new environment. Copying only the main YAML while omitting local Providers can leave references intact while the actual files are missing.

Rule-set order is still determined by the main configuration

A Provider packages many entries into one reference but does not change the first-match-from-top principle. When two rule sets overlap, the earlier RULE-SET gets the first chance to match. Do not place a large rule set unconditionally before every exact rule, or it may hide local exceptions. To override a public rule set, put a small number of exact rules before the relevant RULE-SET.

The more rule sources you have, the more important conflict review becomes. Record each rule set's purpose, behavior, update source, and target policy, and remove collections that are unused or duplicate functionality. When service routing behaves unexpectedly, temporarily disabling the most recently added Provider is more efficient than searching blindly through tens of thousands of remote rules. After updating databases and rule sets, recheck several important domains instead of relying only on a successful download status.

Overrides, Merging, Subscription Updates, and System Troubleshooting

Why local changes belong in an override layer

A subscription configuration typically follows this lifecycle: generated remotely, downloaded by the client, loaded locally, and refreshed periodically. Direct edits to the downloaded file are easily replaced at the next refresh. An override layer preserves local differences such as fixed ports, DNS adjustments, a few additional rules, or a different default proxy-group selection. The subscription supplies nodes and the base structure, while the local layer handles device-specific settings, keeping their responsibilities clear.

Clients do not use exactly the same names or provide identical capabilities for overrides; the feature may appear as an override, extension, merge, script, or preprocessing option. Graphical clients such as Clash Plus, Clash Verge Rev, FlClash, and Clash Nyanpasu generally provide configuration-management entry points, but their merge semantics should be verified in the current client's interface and documentation. Simple key-value overrides are relatively easy to understand, while array merging requires special care because rules, proxies, and proxy-groups are ordered or referenced lists.

The difference between mapping overrides and array merging

Mapping fields are usually overridden by key. If the base configuration contains log-level: info and the override sets it to debug, only one final value remains. Nested mappings may be deep-merged or replaced as a whole. If the override system replaces the entire dns block, writing only ipv6: false may remove the original nameserver. After applying an override, inspect the final configuration generated by the client rather than reading only the override fragment.

Arrays are more complicated. When appending rules, consider insertion order: local exceptions that must match first belong before public rule sets, and ordinary fallback rules must not be appended after MATCH. If a proxy-group array is replaced wholesale, all groups from the subscription may disappear; if it is simply appended, duplicate group names may result. Whether node arrays deduplicate by name or append by position also depends on the implementation. When merge behavior is unclear, validate it with a minimal test configuration before applying it to the main subscription.

# Base configuration
mode: rule
log-level: info
rules:
  - GEOSITE,private,DIRECT
  - MATCH,Node Selection

# Local targets
# 1. Preserve existing private-domain rules
# 2. Add exact exceptions before MATCH
# 3. Temporarily change only the log level to debug

The local targets above cannot be achieved merely by appending a rule at the end of the file, because the existing MATCH will catch the connection first. Add exceptions to the rule-prepend area supported by the client, or generate a complete merged rule array. If the client can replace only the entire rules block, include every original rule you want to preserve in the override result.

A repeatable troubleshooting process

First, check whether the configuration parsed successfully. Look for YAML line numbers, unknown fields, duplicate names, and references to missing items. Second, verify that the core started and is listening on the expected port; if it exits immediately, prioritize port conflicts, configuration-directory permissions, and control-interface conflicts. Third, verify that application traffic enters the core by checking whether the logs show the target domain or connection. If no connection appears, inspect the system proxy, TUN, and the application's own proxy settings instead of changing nodes.

Fourth, inspect rule matches. The logs should show which rule type matched the domain or IP and which proxy group received it. If the policy is wrong, check rule order and Provider content; if the policy is correct, expand the proxy group to confirm the actual underlying node. Fifth, check DNS. An unresolvable domain, an unmanaged Fake-IP address, or a browser using independent DNS can all appear as a page that will not open. Sixth, inspect the node connection stage: a timeout usually indicates an unreachable path, connection refused commonly means the port is not listening, TLS errors require checking the server name and time, and authentication errors require checking the credentials.

Leave a clear conclusion after each step. For example: “The configuration parsed successfully, port 7890 is listening, the browser connection entered the core, the Node Selection group matched, but the TLS handshake failed.” Notes like this narrow the problem to the node fields instead of encouraging repeated edits across every configuration block. For startup crashes, see the Clash Client Startup Crash Troubleshooting Checklist; if the interface is unfamiliar, read A Walkthrough of the Proxy, Configuration, and Logs Pages.

Regression checks after a subscription update

A subscription refresh may rename nodes, change proxy groups, alter rule targets, or update Provider addresses. After refreshing, verify at least four things: local overrides are still enabled; every policy referenced by rules still exists; the automatic selection group still has usable nodes; and DNS and ports were not accidentally overridden by subscription fields. If a proxy group suddenly becomes empty, check whether the filter regex still matches the new node names.

For long-term maintenance, minimize dependencies on the subscription's internal structure. For example, having rules point to one stable local main entry group, which then references subscription nodes, is more resilient than having dozens of rules name specific nodes directly. The subscription handles node changes, while the local configuration expresses routing intent. Keeping those responsibilities separate also makes client migration easier.

Final configuration checklist

• YAML uses spaces for indentation, top-level keys and list levels are clear, and there are no tabs or full-width punctuation marks.
• Listening ports do not conflict, and the system proxy or TUN points to the core that is actually running.
• Every proxy group references existing nodes, child groups, and Providers, with no circular references between groups.
• Rules run from exact to broad, all fallback rules are at the end, and target names are accurate.
• DNS upstreams are reachable, Fake-IP filters are limited to what is necessary, and the browser's independent DNS is included in the checks.
• The final configuration after applying overrides still retains the fields required by the subscription, and a regression check is completed after refreshing it.

After checking the fields, return to the Getting Started guide and follow the workflow for importing, choosing a policy, connecting, and verifying. To switch clients, visit the client download page. Common symptoms and short answers are collected in the FAQ, which is useful for quickly finding the appropriate fix once the failure stage has been identified.