Clash Configuration File
Complete Reference

01 / DOCUMENT MAP

YAML structure overview and reading order

How top-level fields form a configuration

A Clash configuration file is usually named config.yaml. At its core, it is a data tree made up of mappings, lists, and scalars. Top-level mappings divide the configuration into functional areas: ports and runtime mode determine how traffic enters the kernel, dns controls domain resolution, proxies describes individual proxy nodes, proxy-groups organizes nodes into selectable or automatically tested strategies, and rules sends connections to a strategy in order. mihomo also supports extended sections such as proxy-providers, rule-providers, tun, and sniffer.

When YAML is parsed, indentation expresses parent-child relationships. Fields at the same level must use a consistent number of spaces; two spaces per level is common. List items begin with a hyphen, and the object after the hyphen may contain further nested fields. YAML allows unquoted strings, but node names, passwords, regular expressions, and values containing colons or special characters can be misread. The safer approach is to quote such values. Use true and false for booleans, and keep port numbers numeric rather than turning them into strings with extra text.

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

dns:
  enable: true
  listen: 0.0.0.0:1053
  enhanced-mode: fake-ip
  nameserver:
    - 223.5.5.5
    - 1.1.1.1

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

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

rules:
  - DOMAIN-SUFFIX,example.org,Node Selection
  - GEOIP,CN,DIRECT
  - MATCH,Node Selection

Mappings, lists, and name references

The fields after dns: form a mapping, while proxies: is followed by a list of objects. The proxies field inside a proxy group is also a list, but it stores name references rather than declaring nodes again. Names must match exactly, including case, spaces, and symbols. If a node is named “Hong Kong 01”, writing “Hong Kong01” in a group creates a reference to a node that does not exist. The final segment of a rule likewise references a proxy group or a built-in policy such as DIRECT or REJECT. When renaming anything, check every reference in proxy groups, rules, and interface overrides.

YAML anchors and aliases can reduce repetition, but not every graphical client's save, conversion, and override workflow preserves them completely. For public configurations intended for long-term maintenance, clear explicit fields are preferable. For large configurations, split nodes and rules into provider files and reference them from the main configuration. This is easier to update than stacking thousands of lines in one file, and it keeps node data separate from routing logic.

Minimal configuration and loading boundaries

A minimal configuration that starts successfully is not necessarily one that can connect correctly. With only a port and mode configured, the kernel may listen normally while missing proxy-group references or failing to resolve node domains. Check in this order: syntax, complete references, then network behavior. A client message saying “configuration loaded successfully” only means the structure is broadly parseable; it does not prove that node credentials, remote provider URLs, or rule targets are valid.

The fields supported by different kernel generations are not identical. For naming changes and compatibility between original Clash, Clash Meta, and current mihomo, see the kernel version comparison. If the client uses mihomo, its extended fields are available. For configurations shared across clients, first confirm the kernel actually bundled with each client rather than relying only on the product name shown in its interface.

02 / RUNTIME

Common fields: ports, mode, and control interface

mixed-port, port, and socks-port

mixed-port accepts both HTTP and SOCKS5 proxy connections on one listening port, making it suitable for desktop clients and most manual proxy setups. port provides HTTP proxy access only, while socks-port provides SOCKS5 only. Combine them as needed, but do not assign the same port to multiple fields or conflict with another local service. If a graphical client manages ports, its interface values may override the configuration file at startup, so check both the interface and the runtime log when troubleshooting.

Applications running on the same device usually connect to 127.0.0.1. Other devices on the LAN must connect to the LAN address of the device running Clash, with allow-lan enabled and the corresponding port allowed through the firewall. LAN listening expands the accessible surface, so use bind-address to limit the interface and configure authentication when needed. After setting a port, verify its listening state through the operating system's network information instead of repeatedly changing it by trial and error.

mixed-port: 7890
allow-lan: false
bind-address: "*"
mode: rule
log-level: info
ipv6: false
unified-delay: true
tcp-concurrent: true

rule, global, and direct modes

mode: rule matches rules from top to bottom and is the primary mode for everyday use. global sends all proxyable traffic through the global strategy, which is useful for temporarily testing a node but bypasses the intended routing design. direct connects traffic directly and is useful for quickly determining whether the proxy path is responsible for a problem. After switching modes in the interface, some clients change only runtime state rather than the YAML file; whether the setting survives a restart depends on the client.

For troubleshooting, compare modes. If rule mode fails but global mode works, the problem is usually a rule target, rule order, or proxy-group reference. If global mode also fails, continue with the node, system proxy, TUN, DNS, and network environment. If direct mode cannot reach a local service either, the problem may be unrelated to Clash. Mode switching is a diagnostic tool; restore rule mode after testing to avoid permanently losing domain and regional routing.

Logs, IPv6, and the external controller

Common log-level values include silent, error, warning, info, and debug. Use info for everyday operation. Temporarily switch to debug when rule matches or connection stages are unclear, then switch back to prevent rapid log growth. Focus on the destination domain, matched rule, final policy, DNS errors, and connection timeouts rather than only the last line.

ipv6 controls whether the kernel handles IPv6 capabilities, while the DNS section has its own IPv6 setting. Enable it when IPv6 is stable and the node path supports it. If the local network provides IPv6 but no usable route out, applications may try IPv6 first and then time out. Check the system network, DNS responses, Clash's top-level switch, and DNS subfields separately instead of changing only one option.

external-controller provides an API for control panels and client front ends, such as 127.0.0.1:9090. If it listens beyond the local machine, set secret and restrict firewall access. The control interface is not a proxy port; browsers and applications cannot use it as an HTTP proxy. external-ui points to the directory containing static panel files. Its path should match the actual runtime environment, so do not sync one device's absolute path directly to another system.

external-controller: 127.0.0.1:9090
secret: "your-controller-secret"
external-ui: ui

profile:
  store-selected: true
  store-fake-ip: true

profile.store-selected saves proxy-group selections so the last choice can be reused after a restart; store-fake-ip controls persistence of Fake-IP mappings. When syncing a configuration across devices, do not assume runtime state is synced with the YAML. For the boundaries between subscriptions, overrides, and private repositories, see Clash configuration sync across devices.

03 / DNS PIPELINE

DNS configuration and the Fake-IP resolution flow

What happens during a DNS request

Clash's DNS module does more than forward a domain to a server. Once enabled, it receives application queries, selects upstreams according to nameserver-policy, fallback, and other rules, then passes the result to rule matching and connection handling. If a node server itself uses a domain, bootstrap resolution is also involved: the kernel must resolve the node domain before it can establish an encrypted connection. DNS failures may therefore appear as either inaccessible websites or simultaneous timeouts across every domain-based node.

listen sets the address on which the DNS service listens. Desktop clients often already handle system DNS or TUN hijacking, so users may not need to point system DNS manually at this port. Routers and LAN gateways commonly forward client queries here. If listening on 0.0.0.0, restrict access with the firewall; for local-only use, prefer the loopback address.

dns:
  enable: true
  listen: 127.0.0.1:1053
  ipv6: false
  enhanced-mode: fake-ip
  fake-ip-range: 198.18.0.1/16
  use-hosts: true
  respect-rules: true
  default-nameserver:
    - 223.5.5.5
    - 119.29.29.29
  nameserver:
    - https://dns.alidns.com/dns-query
    - https://doh.pub/dns-query
  proxy-server-nameserver:
    - https://1.1.1.1/dns-query
  direct-nameserver:
    - https://dns.alidns.com/dns-query
  fake-ip-filter:
    - "*.lan"
    - "*.local"
    - "time.*.com"
    - "+.stun.*.*"

default-nameserver vs. nameserver

default-nameserver primarily resolves the hostnames of encrypted DNS upstreams. It usually contains directly reachable IP-form DNS addresses, avoiding the loop where DoH must be resolved before it can be contacted, while that resolution itself depends on DoH. nameserver contains the main query upstreams and may use UDP, TCP, DoT, or DoH. More upstreams are not always better; mixing resolvers with very different behavior makes results less predictable and troubleshooting harder.

proxy-server-nameserver can resolve proxy node hostnames through a dedicated path, preventing them from following an incorrect route. direct-nameserver handles direct-connection domains and is useful for sending local traffic to a nearby resolver. With respect-rules enabled, DNS queries follow routing rules more closely, so ensure node hostnames have an independent resolution path or a policy dependency loop may occur.

Choosing between Fake-IP and Redir-Host

enhanced-mode: fake-ip assigns temporary addresses from a reserved range to domains. The application receives the mapped address; when the connection arrives, the kernel restores the original domain and applies domain rules. This preserves domain information at connection time and avoids cases where resolving to an IP leaves only IP rules available. Fake-IP does not mean the destination is actually in that reserved range; it is an internal domain-mapping identifier.

redir-host returns the real resolved address, with transparent proxying or sniffing supplying domain information where available. Applications that depend on LAN discovery, local domains, special authentication, or direct inspection of resolved addresses may work better with real addresses, but rule precision and caching must be evaluated on the target platform. For most desktop and mobile proxy setups, start with Fake-IP and add incompatible domains to fake-ip-filter instead of switching the entire mode whenever one case fails.

Keep exclusions as specific as possible. *.lan and *.local are commonly used for local-device discovery; time synchronization, STUN, gaming platforms, and some corporate intranet domains may also require real results. Broad wildcards send too many domains around Fake-IP and reduce routing consistency. For the full mapping, rule-match, and exclusion workflow, see How Fake-IP mode works.

How to diagnose DNS leaks and resolution failures

An abnormal DNS path usually breaks down into three questions: which component sent the query, which upstream received it, and which policy handled the final connection. Browsers may use their own secure DNS, system services may bypass the application proxy, and TUN may take over queries through DNS hijacking. The resolver name shown by a webpage cannot establish the full traffic path. Disable browser-specific DNS that is not part of the test, then inspect query and rule records in the Clash log.

If a subscription updates successfully but every node reports domain-resolution failure, first check default-nameserver and node-domain resolution. If ordinary websites fail while IP addresses work, check the main nameserver, listening port, and system DNS interception. If only a few LAN devices fail, inspect Fake-IP exclusions. For intermittent timeouts, temporarily keep only one confirmed reachable upstream to isolate upstream differences, network blocking, and cache effects before restoring the others.

04 / PROXY OBJECTS

Proxy node fields and protocol objects

Shared identity fields for every node

Each object in proxies must have at least name, type, server, and port; the remaining fields depend on the protocol. name is the unique internal identifier and is also shown in the client interface. Duplicate names can make group references and interface selections ambiguous, so ensure uniqueness when generating configurations. server may be a domain or IP. A domain makes server-side address changes easier, but adds node-domain resolution as a prerequisite.

udp indicates whether a node may carry UDP, but actual support also depends on the protocol, server, and client entry point. Games, voice calls, QUIC, and some DNS traffic may require UDP. Enabling the field does not guarantee support; if the server or intermediary network blocks it, logs may show a successful handshake followed by no UDP response. interface-name and routing-mark are mainly controls for multi-interface or Linux routing setups and need not be added to ordinary desktop configurations.

Shadowsocks and Trojan examples

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

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

The Shadowsocks cipher must match the server, and the password must be entered exactly as provided. Do not exchange credentials between protocols merely because field names look similar. Trojan relies on TLS; sni specifies the server name sent during the handshake and should normally match a domain covered by the server certificate. skip-cert-verify: false enables certificate verification and is the preferred normal setting. If verification fails, check the device clock, certificate domain, SNI, and server certificate chain rather than disabling verification permanently.

network describes the underlying transport, such as TCP, WebSocket, or gRPC. WebSocket also requires a path and request headers; gRPC usually requires a service name. Transport fields must match the server entry point completely. A common mistake is copying only the protocol, address, and password while omitting the transport path, leaving TCP able to reach the port but the handshake unable to complete.

VMess and VLESS layered fields

proxies:
  - name: "VLESS-WS-Example"
    type: vless
    server: edge.example.com
    port: 443
    uuid: "00000000-0000-4000-8000-000000000000"
    network: ws
    tls: true
    servername: service.example.com
    udp: true
    ws-opts:
      path: /network-path
      headers:
        Host: service.example.com

  - name: "VMess-gRPC-Example"
    type: vmess
    server: grpc.example.com
    port: 443
    uuid: "00000000-0000-4000-8000-000000000000"
    alterId: 0
    cipher: auto
    tls: true
    servername: grpc.example.com
    network: grpc
    grpc-opts:
      grpc-service-name: proxy-service

VLESS and VMess both use UUID-style identities, but their protocol behavior and field sets differ. ws-opts and grpc-opts are nested mappings corresponding to network; incorrect indentation places their parameters at the wrong level. In TLS setups, the connection address, SNI or servername, and HTTP Host may differ: the connection address determines where the socket connects, SNI is used for TLS certificates and virtual-host selection, and Host belongs to the HTTP or WebSocket request headers. Whether they match depends on the server deployment; do not substitute one for another by habit.

The example UUIDs and domains only demonstrate field structure and cannot be used for a connection. Actual node data must come from a service the user is authorized to use. Subscription-generated nodes are usually better loaded through a provider than rewritten field by field, since one missing transport option can create hard-to-identify differences. Manage them through proxy groups and rules instead.

Reality, certificates, and fingerprint fields

Some VLESS configurations supported by mihomo include Reality parameters such as a public key, short ID, and client fingerprint. Field names and nesting must follow the format supported by the current kernel and match the server configuration. Because older kernels or clients may lack these capabilities, confirm kernel compatibility before syncing the configuration to another device. When you see “field not supported” or “configuration parse failed,” first identify the kernel used by the client, then decide whether to adjust the fields or switch to a compatible client.

client-fingerprint affects TLS client-fingerprint simulation, but it is not a universal switch for fixing handshake problems. Certificate-name errors, clock drift, SNI mismatches, and network blocking still require separate diagnosis. For client selection, use the package download page to choose Clash Plus first on desktop and mobile. If you need another interface or platform adaptation, compare Clash Verge Rev, FlClash, Clash Nyanpasu, Clash Meta for Android, Surfboard, ClashX Meta, and the archived Clash for Windows.

05 / POLICY GROUPS

Proxy-group fields and selection logic

select: let the user choose

A proxy group sits between rules and nodes. Rules should not point directly to a node name that may change; they should target a stable group such as “Node Selection,” “Streaming,” or “Download Services.” When nodes change, update only the group members while keeping the rule structure intact. A select group lets the user choose one member manually; members may be nodes, other groups, or built-in policies.

proxy-groups:
  - name: "Node Selection"
    type: select
    proxies:
      - "Auto Select"
      - "Failover"
      - "Hong Kong Nodes"
      - "Japan Nodes"
      - DIRECT

  - name: "Hong Kong Nodes"
    type: select
    use:
      - subscription-main
    filter: "(?i)港|hk|hong kong"

proxies references static nodes or other groups, while use references proxy-providers. Both can be combined where supported by the kernel. filter usually uses a regular expression to select provider nodes by name, so naming conventions directly affect the result. If a subscription changes its region labels, an existing filter may produce an empty group. Treat the filter expression as a data rule that depends on subscription naming, and check that the group still has members after updates.

url-test: choose automatically from probe results

url-test periodically requests a specified URL and selects a suitable node in the group based on the results. url should point to a small, stable resource that reflects the intended network path; interval sets the test period; tolerance reduces frequent switching when results are close. A speed test reflects only the probe target at a particular moment, not download speed, video throughput, or the experience across every site.

  - name: "Auto Select"
    type: url-test
    use:
      - subscription-main
    url: https://www.gstatic.com/generate_204
    interval: 600
    tolerance: 80
    lazy: true
    expected-status: 204

lazy: true defers testing until the strategy is actually used, reducing probes from idle groups. If the test URL is redirected, blocked, or returns varying statuses on the current network, every node may be falsely marked unavailable. Check the URL directly first and replace it with a stable resource rather than removing the automated strategy. Auto-selection suits ordinary web traffic, while logins, remote administration, and allowlisted services that require a fixed egress address are better served by manual selection and a persistent node.

fallback and load-balance

fallback maintains an available order using the list or probe results and switches to another member when the current node fails; its priority is continuity, not the lowest latency every time. load-balance distributes different connections across multiple nodes and suits concurrent requests that can tolerate multiple egress addresses. If a website treats an egress change during one login session as abnormal, load balancing may disrupt the session.

  - name: "Failover"
    type: fallback
    proxies:
      - "Hong Kong Node 01"
      - "Japan Node 01"
      - "Singapore Node 01"
    url: https://www.gstatic.com/generate_204
    interval: 600

  - name: "Concurrent Distribution"
    type: load-balance
    use:
      - subscription-main
    url: https://www.gstatic.com/generate_204
    interval: 600
    strategy: consistent-hashing

With load balancing, consistent hashing tries to keep the same destination on a stable node, while round-robin emphasizes spreading connections. Confirm first that the service allows changing egress addresses; “using multiple nodes at once” does not mean one connection's bandwidth is automatically combined. A single TCP connection normally remains on one node, while multiple nodes mainly share different connections.

Nested proxy groups and loop prevention

Groups can reference other groups, allowing a hierarchy such as “service strategy → regional strategy → nodes.” For example, video rules can point to “Streaming,” which then offers “Hong Kong Nodes” or “Japan Nodes.” This reduces repetition, but excessive nesting makes troubleshooting harder. Most importantly, do not create circular references: if A contains B and B contains A, validation may fail or runtime behavior becomes undefined.

Names should describe function rather than temporary node status. Use stable targets such as “Messaging,” “Development Services,” and “Fallback Proxy” for rules; use “Hong Kong Nodes” and “Japan Nodes” for regional groups; keep individual node names at the bottom level. Then subscription updates, node changes, and region-filter changes do not require rewriting upper-level rules. If selections disappear after a restart, check profile.store-selected and the client's persistence behavior instead of hard-coding the selected node into every rule.

06 / ROUTING RULES

Rule syntax, match order, and fallback

Rules match the first applicable entry from top to bottom

rules is an ordered list. When a connection arrives, the kernel checks entries from the top and immediately applies the policy of the first match; it does not continue searching for a “more specific” rule. Put specific domains, service rules, and special direct routes first, broader domain suffixes and IP-region rules later, and finish with MATCH for everything else. Reversed rule order is a major reason rules can appear present but never take effect.

Standard rules are usually comma-separated: rule type, match value, and target policy, with some types accepting additional parameters. For example, DOMAIN-SUFFIX,example.com,Node Selection matches the domain and its subdomains; DOMAIN,api.example.com,DIRECT matches only the complete domain; and DOMAIN-KEYWORD,example,Node Selection matches domains containing the keyword and therefore has a wider scope. Avoid overly common keywords.

rules:
  - DOMAIN,router.local,DIRECT
  - DOMAIN-SUFFIX,example.cn,DIRECT
  - DOMAIN-SUFFIX,example.com,Node Selection
  - DOMAIN-KEYWORD,video,Streaming
  - IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
  - IP-CIDR,10.0.0.0/8,DIRECT,no-resolve
  - GEOIP,CN,DIRECT
  - MATCH,Node Selection

Differences in domain-rule precision

DOMAIN exactly matches one complete domain and suits a specific API, download host, or LAN machine. DOMAIN-SUFFIX matches a registrable domain and its subdomains at domain boundaries and is the most common form for maintaining site rules. DOMAIN-KEYWORD may match whenever the specified text appears in a domain, which can affect unrelated sites. Place it after precise rules and choose a distinctive keyword.

If one service uses multiple domains, adding only its homepage is usually insufficient. A page may also request login, API, image, media, and static-resource domains. Inspect actual requests in the connection log and add rules accordingly instead of guessing from the page title. For large services that change frequently, a well-maintained rule provider is more appropriate than manually adding a long list of domains.

IP-CIDR, GEOIP, and no-resolve

IP-CIDR matches IPv4 networks, while IP-CIDR6 handles IPv6. LAN ranges, loopback addresses, and known service networks are often routed directly with CIDR rules. The trailing no-resolve tells the kernel not to trigger an additional DNS lookup when evaluating the IP rule, which suits connections that already have a destination IP. Do not add it mechanically when the rule needs to resolve a domain to obtain an IP.

GEOIP determines a region from an IP database after the destination IP is known, so it cannot fully replace domain rules. A CDN may return addresses in different regions depending on the network, and one site may use infrastructure across multiple regions. A domain's association with a region is therefore not the same as the region assigned to its current IP. For known services, prefer domain rules or rule providers; use GEOIP later as broad regional routing.

Process, port, and logical combination rules

Platforms and kernels with the required capabilities can use rules such as PROCESS-NAME, PROCESS-PATH, DST-PORT, and SRC-IP-CIDR. Process rules depend on information supplied by the operating system and may be unavailable on mobile devices, in containers, in restricted-permission environments, or with different TUN implementations. A port rule identifies only the destination port, not the application type; many services share port 443, so routing by port alone is often too broad.

mihomo logical rules can combine multiple conditions with AND, OR, and NOT, making it possible to express conditions such as “one process accessing one network range.” The more complex the expression, the more carefully parentheses, quotes, and parameter separators must be checked. In practice, validate each condition with ordinary rules first, then combine them. This keeps syntax errors, platform support, and logical results from being investigated together.

rules:
  - PROCESS-NAME,example-client,Node Selection
  - DST-PORT,22,Development Services
  - AND,((NETWORK,TCP),(DST-PORT,443)),Node Selection
  - OR,((DOMAIN-SUFFIX,example.org),(DOMAIN-SUFFIX,example.net)),Development Services
  - MATCH,Fallback Proxy

How to diagnose unexpected rule matches

First inspect the destination domain or IP, matched rule, and final policy in the connection log. Next check whether a broader rule above it intercepted the connection first. Then verify which member the target proxy group currently selects. Confirm that the DNS mode preserved domain information; if the application connects directly to an IP, a domain rule cannot match. Finally check whether the rule provider updated successfully and whether its behavior matches the file content.

For a temporary test, place one precise rule at the top of the list, reload the configuration, and start a new connection. Existing connections may reuse the old path, so refreshing a page may not be enough; close the application's connections or clear its connection list if necessary. Move the rule to its proper level after testing. For a complete regional-routing YAML example, see Clash routing rules in practice.

07 / PROVIDERS

Proxy providers, rule providers, and remote updates

proxy-providers move node data out of the main configuration

proxy-providers loads remote or local node collections. The main configuration keeps only the provider name, source, update interval, and health check, while proxy groups reference the collection through use. Subscription updates then affect only the node layer; ports, DNS, proxy groups, and rules remain controlled locally. Compared with treating a subscription as a complete configuration, this structure is better for maintaining stable routing logic.

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

proxy-groups:
  - name: "Node Selection"
    type: select
    use:
      - subscription-main
    proxies:
      - DIRECT

type: http fetches data from a remote address, path specifies where the download is saved locally, and interval sets the automatic update interval. proxy determines which policy handles the update request. At first launch, that policy may not have a usable node, so DIRECT is usually the starting choice. If the subscription cannot be reached directly on the current network, use the client's subscription-update proxy feature. Do not make a provider update depend on nodes that the provider itself has not loaded yet, or startup dependencies can arise.

A health check only verifies node responses at a fixed URL; it does not repair subscription-download errors. Distinguish HTTP status errors, network timeouts, expired URLs, non-YAML responses, file-write failures, and parse failures. When a client reports the same “update failed” message for all cases, the stage recorded in the log is the useful diagnostic clue. Common handling paths are also covered in the FAQ.

rule-providers and behavior

rule-providers splits large rule sets into separate files, which the main rule list references with RULE-SET. The key field behavior describes the collection's format. domain suits domain entries, ipcidr suits IP ranges, and classical stores complete classic rule expressions. If behavior does not match the file content, the collection may fail to load or may not match as expected.

rule-providers:
  local-services:
    type: http
    behavior: domain
    format: yaml
    url: "https://rules.example.com/local-services.yaml"
    path: ./ruleset/local-services.yaml
    interval: 86400

  private-networks:
    type: file
    behavior: ipcidr
    format: yaml
    path: ./ruleset/private-networks.yaml

rules:
  - RULE-SET,private-networks,DIRECT
  - RULE-SET,local-services,DIRECT
  - GEOIP,CN,DIRECT
  - MATCH,Node Selection

A YAML file with domain behavior usually stores domain entries under payload; an ipcidr file stores network ranges; each item in a classical file resembles a complete rule from the main configuration, but typically does not include the final policy because the main configuration's RULE-SET line supplies it. The referencing layer determines the destination, while the collection file describes what to match. This separation lets the same collection point to different policies in different configurations.

payload:
  - "+.example.cn"
  - "api.example.net"
  - "download.example.org"

Update intervals, caching, and failure fallback

Set update intervals according to how often the data changes. Node subscriptions may need shorter intervals, while stable rule collections can update daily. Excessively short intervals increase remote requests and configuration reloads, and generate more error logs on unstable networks. When a remote update fails, the kernel usually continues using the local cache, so the directory containing path must be writable and should not be routinely removed by system cleanup tools.

If the first load fails, there is no local cache yet, so groups or rule sets that reference the provider may be unavailable. Before deploying to a new device, test remote reachability, response format, and whether the save directory can be created. Use relative paths when syncing across platforms. Configuration roots differ on Windows, macOS, Android, iOS, and Linux; hard-coding one platform's absolute path can prevent other devices from loading the file.

Subscription credentials and configuration layers

Subscription URLs often contain access credentials and should not be placed in public repositories, logs, or screenshots. For multi-device sync, keep the credential-free main configuration, proxy groups, and rules in a private maintenance path, then add the subscription URL through a local client override or device-specific file. This shares routing logic without forcing every device to use identical runtime settings.

Think of configuration as four layers: the main configuration controls runtime behavior, providers supply node or rule data, proxy groups define selectable exits, and device overrides handle local differences. Modify each update only in its appropriate layer. Putting ports, nodes, rules, and device paths into one subscription-generated file greatly increases merge conflicts and troubleshooting cost.

08 / OVERRIDE & DEBUG

Overrides, merging, validation, and troubleshooting

Why subscription updates overwrite manual edits

Many graphical clients convert remote subscriptions into runtime configurations. If you edit the converted file directly, the client regenerates it at the next update, removing added rules, ports, or DNS settings. An override reapplies local changes after the subscription update and before the kernel loads the result. Different clients may call this an override, extension, script, mix-in, or configuration merge, and their supported merge rules vary.

Simple scalar fields usually use last-value-wins behavior; for example, a local mixed-port replaces the subscription's port. Mapping fields may merge recursively, so changing only dns.ipv6 can preserve the other DNS entries. Lists are the most variable: some implementations replace rules wholesale, some support prepend, append, and delete operations, and others require a script to return the complete array. Read the client's override documentation and verify the final generated configuration.

# Local override example: the actual file entry depends on the client
mixed-port: 7890
mode: rule
log-level: info

dns:
  enable: true
  ipv6: false

profile:
  store-selected: true
  store-fake-ip: true

Make rule merging explicitly prepend or append

Because rules use first-match semantics, insertion position changes their meaning. LAN direct routes, single-domain corrections, and rules intended to override subscription defaults should usually be prepended. Supplemental entries that should not affect existing precise rules can go after subscription rules but before the final MATCH. Appending a new rule after MATCH does nothing because MATCH has already captured all remaining connections.

If the client supports only wholesale list replacement, preserve the complete rule order in the override or use a rule provider and reference the custom collection stably from the main configuration. Do not assume a merge tool will automatically identify the more specific rule; YAML merging handles data structures, not routing semantics. After every merge, open the final configuration, locate the custom rules, and confirm that only one sensible fallback remains.

rules:
  # Prepend local-service and LAN rules
  - DOMAIN,router.local,DIRECT
  - IP-CIDR,192.168.0.0/16,DIRECT,no-resolve

  # Custom rule collection
  - RULE-SET,development-services,Development Services

  # General regional and fallback rules
  - GEOIP,CN,DIRECT
  - MATCH,Node Selection

Syntax and reference checks before loading

Start syntax validation by checking whether the YAML parses, then check whether Clash fields are valid. A general YAML tool can find indentation, colon, and quoting errors, but it cannot tell whether proxy-groups references a missing node. The kernel's configuration test can additionally check field types, policy references, provider definitions, and rule formats. Graphical clients usually show an error location during import or reload; on Linux, use the configuration-test option provided by the installed kernel, following that kernel's help output for the exact command.

When given a line number, do not inspect only that line. YAML parsers often report where they realize the structure can no longer continue, while the real cause may be a missing quote, indentation, or list hyphen several lines earlier. Work upward from the reported line to the nearest field at the same level and compare indentation. For a long configuration, binary-search the problem by commenting out recently added sections.

# Linux example: inspect the parameters of the installed kernel first
mihomo -h

# Common configuration-test forms; adjust the path for the local system
mihomo -t -f ./config.yaml

A repeatable troubleshooting workflow

In phase one, confirm that the kernel starts. Check the configuration-load result, listening ports, and control interface. If startup fails, focus on YAML, field compatibility, and file permissions. In phase two, confirm that traffic enters Clash by checking the system proxy, application proxy, TUN status, and whether the corresponding request appears in the log. If there is no request record, do not start by changing nodes or rules; traffic has not reached the kernel.

In phase three, confirm DNS and the node. Use logs to determine whether the destination domain resolves, whether the node server is reachable, and where TLS or protocol handshaking fails. Temporarily switch to global mode and select one confirmed working node to separate rule issues from node issues. In phase four, check policies and rules: record the matched rule, target group, current group selection, and provider status. Only in phase five should you handle application-specific cases such as browser proxy settings, secure DNS, QUIC, process detection, and LAN discovery.

Safe rollback and change records

Change one functional area at a time and keep a configuration that is known to load. If ports, DNS, TUN, and rules all change together, it becomes difficult to identify the cause. A safer workflow is to copy the original configuration, record the goal, make one set of changes, run a syntax test, reload, and observe new connections. Continue only after it is stable. In a private version-control repository, describe behavioral changes clearly, such as “use real resolution for LAN domains” or “prepend development-service rules,” rather than simply writing “update configuration.”

Rollback requires more than restoring the YAML. Also consider the client's saved proxy selection, Fake-IP cache, provider cache, and system proxy state. If the symptom remains after restoring the file, reload the configuration and create a new connection; restart the kernel if necessary to rule out an old connection retaining the previous policy. Do not clear every cache and setting first; preserving the evidence makes it easier to identify which layer changed.

From the manual back to a working configuration

For a first setup, use a small-step structure: configure mixed-port, rule mode, and one working node; create a “Node Selection” proxy group; then add basic DIRECT and MATCH rules. After traffic works, enable enhanced DNS mode and introduce providers and service-specific rule collections. Each step then has a clear verification result, avoiding the simultaneous introduction of subscriptions, DNS, TUN, and complex rules.

When installing or changing clients, choose the appropriate system from the Clash package download page, with Clash Plus preferred on desktop and mobile. If you only need to import a subscription, choose a mode, and verify connectivity, return to the Clash usage tutorial. For port conflicts, failed subscription updates, unrecovered system proxy settings, or platform-specific permission issues, search the FAQ by problem category. For Linux desktop, command-line, and systemd deployments, see Deploy Clash on Linux.