Clash Configuration File Reference

CHAPTER 01

YAML Structure Overview

How the configuration file is read

A Clash configuration file is, at its core, a YAML document. When the core starts, it parses the syntax, reads top-level fields such as listening ports, DNS, proxies, proxy groups, and rules, then builds the local proxy entry point and traffic-matching chain. A syntax error usually prevents the client from becoming usable. If the syntax is valid but field relationships are wrong, Clash may start without offering selectable nodes or may fail to match rules. Configuration troubleshooting therefore requires more than checking whether the file opens: verify YAML syntax, field names, object references, and the runtime environment in order.

Common top-level fields include port, socks-port, mixed-port, mode, log-level, dns, proxies, proxy-groups, rules, proxy-providers, and rule-providers. Not every configuration needs all of them. For example, when only mixed-port is used, separate HTTP and SOCKS ports are unnecessary. If nodes are loaded from a remote provider, proxies may be empty, but a proxy group must reference the provider with use.

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

dns:
  enable: true
  listen: 127.0.0.1:1053
  enhanced-mode: fake-ip
  nameserver:
    - 223.5.5.5
    - https://dns.alidns.com/dns-query

proxies:
  - name: Example-Trojan
    type: trojan
    server: edge.example.net
    port: 443
    password: your-password
    sni: edge.example.net

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

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

The example above shows the shortest complete chain: a local application connects to port 7890, the DNS module resolves domains, proxies defines an exit, proxy-groups organizes that exit into a selectable policy, and rules decides which policy receives the traffic. Real subscriptions usually contain more nodes and rules, but the relationship remains “entry point—resolution—exit—policy—matching.” Once this chain is clear, connection failures are easier to place in the correct layer.

Indentation, Lists, and Data Types

YAML uses indentation to represent hierarchy. Two spaces are recommended; do not use tabs. Leave one space after each colon, start list items with a hyphen and a space, and keep fields at the same level equally indented. dns is a mapping object, so its child fields are indented one level further; nameserver is a list, and each address is indented one additional level. If enable and nameserver are accidentally placed at different levels, the parser may fail outright or interpret the structure differently from what you intended.

Use true and false for Boolean values, integers for ports, and strings for names and addresses. Quoting is safer when a value contains a colon, hash, comma, or text that could be interpreted as a Boolean. For example, an unquoted hash in a password starts a comment, while names such as on and off may be interpreted differently by different YAML parsers. Single quotes are recommended for subscription URLs, regular expressions, and complex passwords; use double quotes when escape sequences are required.

Names used in references must match exactly

Proxy groups and rules reference other objects by name, and names are sensitive to full-width versus half-width characters, spaces, and letter case. A node named “Hong Kong 01” is not the same object as “Hong Kong01”; likewise, a rule ending in “Node Selection” will point nowhere if the configuration only defines “Proxy Selection.” When editing a subscription, search for every reference instead of changing only the definition. Avoid duplicate node names as well: the interface may show only one entry, making the actual selection difficult to identify.

YAML supports comments, but comments are best used to explain a field rather than store large blocks of inactive configuration. A commented-out node may still be referenced by a proxy group, and deleting a node without removing its references is a common mistake. A safer workflow is to keep a base configuration and place experimental fields in a separate copy, moving them into the everyday configuration only after confirming that it loads. With graphical clients such as Clash Plus, Clash Verge Rev, and FlClash, run the built-in configuration check before switching to the active profile. See Get the Client for client entry points and platform details.

CHAPTER 02

Common Fields, Ports, and Operating Modes

Local listening ports

port provides an HTTP proxy entry point, socks-port provides a SOCKS5 entry point, and mixed-port accepts both HTTP and SOCKS requests on the same port. Most desktop setups need only mixed-port, after which the client’s system proxy feature can point the operating system at that port. If a development tool accepts only SOCKS5, enable socks-port separately. When multiple fields are enabled, their port numbers must be different and must not conflict with ports used by other local programs.

port: 7890
socks-port: 7891
mixed-port: 7892
redir-port: 7893
tproxy-port: 7894

redir-port and tproxy-port are mainly used for Linux routing and transparent proxying. They are not required for ordinary desktop system-proxy settings, and adding them alone does not create firewall or routing rules. Transparent proxying also requires traffic forwarding, policy routing, and permissions at the system level. If the goal is to route applications that ignore the system proxy through Clash, learn about TUN mode first. See how to enable Clash TUN mode for the principles and setup steps.

LAN access and bind addresses

allow-lan determines whether other devices can connect to the proxy port on the current device. With false, local applications can still use the proxy, but phones, TVs, or another computer on the LAN cannot use it as a proxy server. After setting it to true, also verify bind-address, the operating system firewall, and the network type. On a trusted LAN, limit listening to a specific private address instead of exposing the port on every network interface.

allow-lan: true
bind-address: 192.168.1.20
authentication:
  - local-user:your-password

Enabling LAN access allows devices on the same network to attempt connections to the listening port, so do not judge safety solely by the network’s name. Disable allow-lan on public networks, temporary hotspots, and shared dorm networks. If sharing is necessary, use authentication fields and restrict access to an approved subnet in the system firewall. A remote control interface and a proxy entry point are separate services: exposing a proxy port does not mean the control interface should also be exposed to the LAN.

Rule, Global, and Direct Modes

mode: rule matches rules from top to bottom and is the most common mode for everyday configurations. global sends connections to the global proxy group instead of applying rules one by one; direct connects without a proxy. A graphical client may override the file’s default at runtime, so a file set to rule can still show Global in the interface. When troubleshooting unexpected routing, check both the configuration field and the client’s current state.

Global mode is useful for briefly confirming whether a problem comes from the rules, but it should not replace a complete routing configuration. If a site is unreachable in Rule mode but works in Global mode, the domain may be assigned to the wrong policy, the rule order may be incorrect, or the selected proxy group may currently point to an unavailable node. Direct mode helps determine whether the local network itself is reachable. If Direct also fails, check the network, DNS, and target service before repeatedly changing proxy nodes.

Logs, IPv6, and the Control Interface

Common log-level values include silent, error, warning, info, and debug. info is usually sufficient for daily use; temporarily switch to debug when investigating configuration loading, DNS queries, or connection handshakes. Logs may contain visited domains, node names, and local connection details, so review them before sharing troubleshooting screenshots. Restore the normal level after resolving the issue to reduce irrelevant output.

ipv6 is not a simple “make the network faster” switch. If the local network has unreliable IPv6 but DNS returns AAAA records, the program may try unreachable addresses first; disabling IPv6 entirely may also break environments that provide only IPv6. Choose the setting based on actual network capability and keep top-level ipv6, the DNS module, and TUN settings consistent. If the same domain works intermittently, compare IPv4-only results with results that include IPv6 to determine whether the address families behave differently.

external-controller provides a control interface for a graphical client or external panel. Desktop clients often manage this field automatically, so it usually does not need to be opened manually. When configuring it yourself, bind to a loopback address such as 127.0.0.1:9090 and set a control secret. Writing 0.0.0.0:9090 permits access through other network interfaces and should be used only when remote management is explicitly required and access restrictions are in place. external-ui is only the directory for static panel files; it does not download or update the interface automatically.

external-controller: 127.0.0.1:9090
secret: your-control-secret
external-ui: dashboard

Add common fields starting from the minimum usable setup. First confirm that one mixed port, Rule mode, and basic logging work, then enable LAN access, TUN, the control interface, or advanced network options step by step. Adding many fields at once may make the file look complete but makes the source of an error difficult to isolate. Support for advanced fields varies across Clash forks, so with a graphical client, follow the core it actually bundles and the result of its configuration check.

CHAPTER 03

DNS Configuration and the Resolution Path

What the DNS module does

When an application accesses a domain, it first needs the destination address before it can connect. If DNS resolution bypasses Clash while the connection itself enters the proxy, the result may not match the proxy exit, a polluted answer may be used directly, or rules may lose the original domain. Clash’s DNS module can receive local queries, resolve them through configured upstreams, and in Fake-IP mode map virtual addresses to domains so subsequent traffic can still be matched by domain rules.

dns.enable controls whether the module is enabled, listen sets its listening address, nameserver lists the primary upstreams, and fallback provides another resolution source. A desktop client may redirect queries to its built-in DNS through TUN or system settings. Merely adding listen: 127.0.0.1:1053 does not change the operating system’s DNS automatically. If ordinary system queries still go to the router, check the client’s DNS interception settings.

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
  nameserver:
    - 223.5.5.5
    - https://dns.alidns.com/dns-query
  fallback:
    - https://1.1.1.1/dns-query
  fake-ip-filter:
    - '*.lan'
    - localhost.ptlogin2.qq.com
    - time.*.com

Fake-IP and Redir-Host

enhanced-mode: fake-ip returns a virtual IP from a reserved range to the application and records the original domain behind it. When the application connects to that virtual address, Clash restores the domain and applies the rules. This generally preserves domain information more reliably and reduces routing errors caused by an application resolving the domain itself before connecting. Use a dedicated reserved range for fake-ip-range; do not replace it casually with a home LAN, corporate network, or real public address range, or it may conflict with existing routes.

Some LAN services, game-device discovery, printers, time synchronization, and applications that require real addresses do not work well with Fake-IP and can be excluded through fake-ip-filter. More exclusions are not automatically better: an overly broad list sends many domains back to real resolution and weakens Fake-IP’s domain-awareness benefits. If an application can open websites but cannot discover local devices, start with the LAN domains it uses instead of adding every domain to the filter.

redir-host returns real resolution results and is closer to traditional DNS compatibility, but it may preserve the original domain less reliably in complex transparent-proxy setups. The right mode depends on the client, operating system, and traffic-interception method. Desktop and mobile graphical clients can generally start with their default mode and change it only for a clear compatibility issue. After switching modes, old DNS caches and connections may remain; restart the client’s DNS module before testing, and clear system caches or reopen the target application if necessary.

Nameserver, Fallback, and Bootstrap Resolution

nameserver can contain ordinary UDP DNS addresses or DoH URLs. Ordinary addresses are simple, but the query path depends on the local network. DoH uses HTTPS and must resolve the DoH server’s own hostname first, creating a bootstrap-resolution problem. Cores that support the relevant fields can use default-nameserver with plain IP-based DNS servers to resolve hostnames for encrypted DNS services. Enter IP addresses in this list; do not add DoH URLs that themselves require hostname resolution.

dns:
  enable: true
  enhanced-mode: fake-ip
  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://dns.alidns.com/dns-query

proxy-server-nameserver resolves proxy server addresses. If a node’s server is a hostname, Clash must resolve it before establishing the proxy connection; it cannot depend on a proxy tunnel that does not yet exist, or a loop results. Providing directly reachable resolvers for proxy servers separates “resolving node addresses” from “resolving ordinary domains through the proxy.” This field matters less when all subscription nodes use IP addresses.

fallback does not simply send every query to a second group of servers at the same time. The exact selection logic depends on the core and filtering fields. With fallback-filter, results can be selected by geographic databases, IP ranges, or domain rules, but overly complex filtering increases troubleshooting cost. For a basic setup, first make sure one stable nameserver works, then consider fallback. If every resolver is unreachable, adding more addresses will not fix the network path.

DNS Troubleshooting Order

During troubleshooting, first confirm that queries enter Clash, then verify that Clash can reach the upstream, and finally check how the response is used by rules and connections. If the logs contain no DNS query for the target domain at all, the system or application may be using another resolution path. Queries that consistently time out point to upstream addresses, network firewalls, or proxy dependencies. If queries succeed but access fails, inspect rule matches, policy selection, and the destination address family. Do not classify every connection problem as DNS, and do not repeatedly change resolvers before confirming the path.

Browsers may enable their own Secure DNS, and mobile operating systems may use Private DNS; both change the query path. TUN interception covers more traffic but still requires attention to system permissions and route conflicts. If the symptoms include node timeouts, intermittent domain failures, and mixed system-proxy states, follow the troubleshooting order from subscription to DNS layer by layer. The goal of DNS configuration is a clear, repeatable resolution path—not as many upstream addresses as possible.

CHAPTER 04

Proxy Node Fields

Common fundamentals for every node

proxies is a list of node objects. Each object needs at least a name, protocol type, server address, port, and the authentication fields required by that protocol. name is used by proxy groups and the interface, type determines how later fields are interpreted, server can be an IP address or hostname, and port must match the server’s listening port. Node details usually come from a subscription; do not copy fields from one protocol to another based on guesswork.

Passing a YAML check only means the fields can be read; it does not prove that the remote server is reachable. An incorrect server address, closed port, mismatched credentials, inaccurate system time, TLS hostname mismatch, or local network filtering can all cause connection failures. Start by confirming that the original subscription is still valid, then inspect the failure stage in the client logs. If nodes using several different protocols all time out at once, the subscription, DNS, local network, or system proxy is more likely at fault than every node failing simultaneously.

Shadowsocks and Trojan Examples

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

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

Shadowsocks cipher must match the server and should not be changed casually based only on the client’s supported list. Treat password as a string and quote it when it contains special characters. udp allows the node to carry UDP, but actual support also depends on the server, network path, and client mode. With only a system proxy, much UDP traffic will not naturally enter the proxy; TUN or transparent proxying is more commonly required for UDP interception.

Trojan usually connects over TLS, with sni specifying the server name used during the handshake. If the node’s server is an IP address but the certificate is issued to a hostname, the correct SNI is especially important. skip-cert-verify: true disables certificate verification and should not be treated as a general fix. If enabling it is the only way to connect, check the server name, system time, certificate chain, and subscription fields. Keeping verification enabled helps expose mismatches between the handshake target and the certificate identity.

VMess and VLESS Transport Fields

proxies:
  - name: Example-VMess
    type: vmess
    server: vmess.example.net
    port: 443
    uuid: 11111111-2222-3333-4444-555555555555
    alterId: 0
    cipher: auto
    tls: true
    servername: vmess.example.net
    network: ws
    ws-opts:
      path: /proxy
      headers:
        Host: vmess.example.net

  - name: Example-VLESS
    type: vless
    server: vless.example.net
    port: 443
    uuid: aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee
    network: tcp
    tls: true
    servername: vless.example.net
    udp: true

VMess and VLESS both use UUIDs, but they are different protocols. WebSocket transport also requires checking network, the path, and Host. If the server expects a specific path, one missing slash or a case difference can break the handshake. TLS field names may differ across configuration formats and core forks, so preserve the structure generated by the subscription rather than renaming fields for consistency. A configuration check can identify unknown fields, but it cannot verify that a remote reverse proxy forwards the same path.

Nodes using gRPC, HTTP/2, Reality, or other extended transports may include additional service names, public keys, short IDs, or flow-control fields. These values must come as a complete set from the server configuration. Omitting one may still pass syntax validation while making the handshake impossible. When migrating a node manually, move the complete object instead of copying only server, port, and the UUID. Support for extended protocols also varies by core, so choose a core compatible with the subscription requirements.

DIRECT, REJECT, and Built-in Exits

DIRECT and REJECT are common built-in policies and do not need to be declared in proxies. DIRECT connects without a proxy; REJECT refuses the connection. They can appear in a proxy group’s proxies list or directly at the end of a rule. Still check for naming conflicts with custom subscription nodes, and do not create a regular proxy node named DIRECT, which can make reading and troubleshooting ambiguous.

Some configurations also use built-in types for compatibility, packet dropping, or DNS-related handling; support depends on the current core. To keep configurations portable across Clash Plus, Clash Verge Rev, FlClash, and similar clients, use common fields in the base file and place core-specific extensions in a separate override. Mobile and desktop system interception differ, but the node objects themselves should remain as consistent as possible. Put differences mainly in ports, TUN, DNS listening, and interface settings.

Layered Diagnosis of Node Failures

A failed latency test does not necessarily mean every business connection fails, and the test target is not the same as the actual destination. First identify whether the failure is DNS resolution, a TCP timeout, a TLS handshake error, or rejected authentication. For resolution failures, check server and proxy-server DNS; for timeouts, check the network and port; for TLS errors, check SNI, system time, and certificates; for authentication failures, return to the subscription details. Do not delete the entire client configuration first, or you may lose logs and fields that explain the problem.

Manual nodes are useful for testing and learning fields, while a subscription provider is better for maintaining a long-term node list. Subscription updates can add and remove nodes consistently, but local proxy groups and rules still need stable references. The next chapter explains how to place nodes in proxy groups; Chapter 7 covers loading remote nodes through proxy-providers. If you are unsure how to select and verify a node after the first import, read the first connection guide.

CHAPTER 05

Proxy Group Fields and Selection Logic

Proxy groups sit between rules and nodes

proxy-groups organizes multiple proxy nodes, other proxy groups, and built-in exits under a referenceable name. Rules generally point to groups such as “Node Selection,” “Auto Select,” or “Streaming,” rather than to individual nodes. When nodes change, rules do not need to be edited one by one; adjust the group members or current selection instead. Groups may be nested, but avoid circular references: if A contains B and B contains A, the configuration relationship cannot be resolved.

The most common types are select, url-test, fallback, and load-balance. Select lets the user choose a member explicitly; URL-Test periodically tests members and selects one that meets the criteria; Fallback searches for an available member in order; Load-Balance distributes connections across members. Each type solves a different problem, and “automatic” does not simply mean faster. Latency tests reflect the test target and the network at that moment, while the actual service may use another path.

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

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

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

Select and Automatic Test Groups

The advantage of select is predictability. After the user chooses a node in the interface, the policy keeps that selection, making it suitable for a fixed exit, an existing login session, or a specific region. The drawback is that a failed node is not replaced automatically. Making an automatic test group the first member of Select preserves both automatic and manual entry points: use “Auto Select” day to day, then switch to a specific node when a fixed route is required.

url-test uses url to perform reachability tests, interval sets the testing period, and tolerance prevents frequent switching between nodes with nearly identical latency. An interval that is too short creates constant requests and may make the interface selection change repeatedly; one that is too long delays failure detection. Choose a test URL with a simple, stable response rather than a page requiring login, complex redirects, or often blocked by the local network. A successful test only proves that the node can reach that test target.

fallback emphasizes member order. It generally stays with the first available member and moves to the next after failure, making it suitable for a clear primary-and-backup arrangement. Its difference from URL-Test is the selection principle: URL-Test favors measured results, while Fallback favors order and availability. For stable sessions, frequent changes between nodes can trigger login-state or source-address changes, so a primary/backup group is often preferable to chasing the lowest test value.

Load Balancing and Session Consistency

load-balance can distribute different connections across multiple nodes, but it does not combine their bandwidth for a single download. One webpage may open multiple connections, which can leave through different exits. If the destination requires a session to keep the same source address, split exits may trigger CAPTCHAs, invalidate logins, or cause requests to be rejected. Cores that support the relevant policy fields may use consistent hashing to keep the same destination on one member more reliably, but this still needs validation against the actual service.

  - name: Balanced Exit
    type: load-balance
    strategy: consistent-hashing
    proxies:
      - Example-Trojan
      - Example-SS
    url: https://www.gstatic.com/generate_204
    interval: 300

Load balancing is better suited to multiple independent targets or connections and should not be the default exit for every rule. Before configuring it, confirm that each member works independently and has comparable regions, permissions, and protocol capabilities. Combining very different nodes makes the same service difficult to reproduce consistently. If the goal is automatic switching when a node fails, Fallback is usually a better fit.

Filter members by node name

With proxy-providers, a proxy group can import an entire provider through use, then filter by name with filter or exclude-filter. Filters usually use regular expressions, so first inspect the provider’s actual naming. A filter that depends too heavily on one symbol or fixed prefix may leave the group empty when the subscription changes its names. A safer approach is to start with simple keywords and keep a manual selection path for important groups.

proxy-groups:
  - name: Hong Kong Nodes
    type: select
    use:
      - remote-nodes
    filter: '(?i)香港|HK|Hong Kong'

  - name: Node Selection
    type: select
    proxies:
      - Hong Kong Nodes
      - DIRECT
    use:
      - remote-nodes

Put parentheses, vertical bars, and other special characters in regular expressions inside quotes. If filtering returns no results, first check that the provider loaded successfully, then check the name match; do not assume the subscription contains no nodes. If the client shows the provider’s raw node list, copy one or two names for a minimal test. Name filtering is only a management tool, not a measure of node quality; labels such as “high speed” or “dedicated line” do not prove the route is healthy.

Proxy Group Hierarchy Guidelines

The outermost rules should reference a small number of stable policies such as “Node Selection,” “Direct Services,” and “Blocking.” Put regional groups, automatic groups, and individual nodes beneath them. Excessive depth makes the interface harder to navigate and makes the final exit difficult to trace after a rule matches. Two or three layers are usually enough to express “service policy—regional policy—node.” Every additional layer should answer a clear selection problem.

After editing a proxy group, check three things: every member exists, every policy referenced by a rule exists, and the groups contain no cycles. Subscription updates may also delete a specific node referenced by a manually maintained group. For long-term configurations, reference providers and filters instead of copying remote node names one by one into the local file. If the client shows a group but cannot expand it, check for an empty group, invalid references, and the provider’s load status first.

CHAPTER 06

Rule Syntax and Match Order

Rules run from top to bottom

rules is an ordered list. Each connection is checked from the first rule, and matching stops immediately; later rules are not considered. A rule can therefore have the right type but still produce the wrong result if it is ordered incorrectly. Put specific rules first, broader rules later, and MATCH at the end as the final fallback. If MATCH appears in the middle, subsequent rules can never run.

rules:
  - DOMAIN,api.example.com,Node Selection
  - DOMAIN-SUFFIX,example.com,Node Selection
  - DOMAIN-KEYWORD,example,Node Selection
  - IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
  - GEOIP,CN,DIRECT
  - MATCH,Node Selection

A standard rule contains a rule type, match value, and target policy separated by English commas. The policy name must match a name defined in proxy-groups or a built-in policy. Chinese commas, trailing spaces, and spelling differences can all prevent the rule from loading as expected. If a rule value contains commas, confirm that the rule type supports the required escaping instead of placing complex text directly into the ordinary three-part format.

Differences Between Domain Rules

DOMAIN matches a complete domain exactly. For example, DOMAIN,api.example.com matches only that host and does not automatically match www.example.com. DOMAIN-SUFFIX matches a domain suffix and is suitable for a root domain and its subdomains. DOMAIN-KEYWORD matches a keyword, has the broadest scope, and is easiest to overmatch. When domain boundaries are known, prefer DOMAIN or DOMAIN-SUFFIX; use keyword rules only when target domains are scattered but share a stable keyword.

Whether a domain rule can work depends on whether the core receives a domain during the connection. If an application connects directly to an IP, or DNS queries completely bypass Clash, DOMAIN rules may have nothing to match. Fake-IP, TUN sniffing, and the system proxy can help preserve domains, but each uses a different path. When a domain rule does not match, check whether the connection log shows a domain or an IP before investigating DNS, sniffing, or the rule itself.

Define rule scope around the service boundary. Sending an overly broad top-level suffix through a proxy may change the exit for unrelated services; matching only one login domain may omit static assets, APIs, or content domains. Watch the connection log during a complete operation, then add domains belonging to the same service and requiring the same policy. Do not infer every request from the address shown in the browser bar.

IP Addresses, Subnets, and no-resolve

IP-CIDR matches IPv4 networks, while IP-CIDR6 matches IPv6 networks. The number after the CIDR slash is the network prefix length; for example, 192.168.0.0/16 covers a common private address range. IP rules are useful for LANs, fixed servers, or ranges from an address database, but a single IP can change quickly when a service uses dynamic addresses or a content delivery network.

no-resolve tells an IP rule not to trigger an additional lookup just to obtain an IP. For LAN ranges and connections already established by IP, this can avoid unnecessary DNS queries. It is not a decorative field that every IP rule must include; if the matching process genuinely needs a resolved address, understand the effect before adding it. During troubleshooting, use logs to determine whether the rule sees the original IP, a resolved address, or a Fake-IP.

rules:
  - IP-CIDR,10.0.0.0/8,DIRECT,no-resolve
  - IP-CIDR,172.16.0.0/12,DIRECT,no-resolve
  - IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
  - IP-CIDR6,fc00::/7,DIRECT,no-resolve
  - MATCH,Node Selection

LAN direct rules should usually come before general proxy rules so printers, routers, and internal services are not sent to remote nodes. Corporate networks may use complex routes that overlap common private ranges, and TUN setups also depend on the actual routing table. If an internal address is unreachable, check whether the system routes that subnet to the correct local interface in addition to checking the rules. Clash can handle connections that enter it, but it cannot replace a missing underlying network route.

GEOIP, Rule Sets, and Databases

GEOIP determines an IP’s region from a local address database. Accuracy depends on the database contents and update status, so no address should be treated as permanently fixed. Service migrations, CDN changes, and database lag can all produce different classifications. If an important service is assigned to the wrong policy by GEOIP, add a more specific domain or IP rule instead of waiting for a broad geographic rule to happen to correct it.

Large rule libraries are best managed with rule-providers and referenced through RULE-SET. The main configuration then stores only the order and target policy of each set, while the provider updates the individual entries. Different rule sets may overlap, but the reference order in the main configuration still applies. If an advertising, direct, and proxy set contain the same target, the first matching set determines the result.

rules:
  - RULE-SET,private-domain,DIRECT
  - RULE-SET,direct-domain,DIRECT
  - RULE-SET,proxy-domain,Node Selection
  - RULE-SET,private-ip,DIRECT,no-resolve
  - GEOIP,CN,DIRECT
  - MATCH,Node Selection

Troubleshooting Rules That Do Not Match

Find the target request in the connection log first, then record its displayed domain or IP, matched rule, and final policy. If a broad earlier rule matched, change the order or narrow its scope. If the request falls directly into MATCH, check whether the rule content matches the object shown in the log. If the correct policy matched but the wrong node was used, the problem is the group’s current selection, not the rule. Separating these three layers prevents endless rule edits that never change the final exit.

When testing rules, change one condition at a time and confirm that the active configuration was reloaded after each change. Browser connection reuse, DNS caches, and background application processes may continue using old connections, so close the application and retry if necessary. Keep rules readable: specific exceptions first, rule sets in the middle, and regional policies plus the final fallback later. Brief comments should explain unusual entries; large collections of undocumented temporary rules become increasingly difficult to maintain.

CHAPTER 07

Subscriptions, Proxy Providers, and Rule Providers

Local Nodes Versus Remote Providers

Writing nodes directly in proxies suits a small set of fixed nodes and temporary tests. With proxy-providers, a remote address can refresh the node list periodically, while proxy groups reference it through use. Providers separate “how node data is updated” from “how nodes participate in policies”: when remote content changes, the names of local policies and rules do not need to change with it.

A provider is not synonymous with a full-configuration subscription. Some subscription URLs return an entire Clash configuration containing ports, DNS, proxy groups, and rules; proxy-providers generally expects a node collection. Putting a full configuration URL directly into a provider may fail because its structure is incompatible. A client’s ordinary subscription import and a proxy provider inside a configuration are also different layers, so confirm what type of file the service provides.

proxy-providers:
  remote-nodes:
    type: http
    url: https://config.example.net/nodes.yaml
    path: ./providers/remote-nodes.yaml
    interval: 21600
    health-check:
      enable: true
      url: https://www.gstatic.com/generate_204
      interval: 600

proxy-groups:
  - name: Node Selection
    type: select
    use:
      - remote-nodes
    proxies:
      - DIRECT

type: http fetches content from a remote address, url is the subscription URL, path is the local cache location, and interval sets the update interval. The cache lets the client continue using the last successful content when the remote address is briefly unreachable. Store the path in a configuration directory the client can write to; do not use a location requiring extra system permissions. Multiple providers must not share one cache file, or updates will overwrite one another.

Subscription URLs commonly grant access to private data, so do not put them in publicly shared logs, screenshots, or example files. The domains in this article are examples and cannot be used for a real service. When a subscription fails to load, check the HTTP status, TLS errors, response format, and local write permissions—not only whether the proxy group is empty. A successful remote request containing unexpected YAML can still cause a parse failure.

Health Checks and Policy Testing

health-check can periodically test whether provider nodes can reach a specified URL. It is related to, but not the same layer as, a proxy group’s URL-Test: provider health checks maintain node availability status, while group testing decides how to select members. Setting very short intervals in both places creates duplicate traffic. Choose reasonable periods based on the number of nodes and how they are used; constant high-frequency probing is unnecessary.

A failed health check may indicate an unavailable node, but the test URL itself may be unreachable from the current network or region. If every node fails against the same address at the same time, cross-check with the real target and another stable address. Redirects, CAPTCHAs, or large pages can also cause false negatives. A simple endpoint with a small response is better for reachability checks, but it still cannot replace validation against the actual service.

Rule Provider Structure

rule-providers loads updateable rule sets. Common fields include the behavior type behavior, format format, remote URL, cache path, and update interval. behavior: domain suits domain collections, ipcidr suits IP networks, and classical can contain classic entries with rule types. A RULE-SET reference in the main configuration must match the set’s behavior; IP collections are often used with no-resolve.

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

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

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

YAML with Domain behavior usually contains a list of domain entries, while IPCIDR behavior contains a list of networks. Classical content includes complete rule types such as DOMAIN-SUFFIX and IP-CIDR. Declaring a Classical file as Domain may make the parser reject it or interpret entries incorrectly. When creating your own rule set, choose the behavior first and write the matching format; do not mix different types in one simplified collection.

Updates, Caches, and Failure Recovery

Treat a remote update as a configuration change. After a node provider updates, the currently selected node may be deleted or renamed; after a rule provider updates, the same domain may match a different set. Check provider status, the group’s current selection, and rule matches for critical services after each update. Automatic updates still require observation, especially when local groups depend on name filters: a change in remote naming directly changes group membership.

If a provider fetch fails while a cache remains, the client may continue using stale data. This preserves connectivity but can make a failed update look successful. Distinguish “loaded from cache” from “just completed a remote update” when checking status. If a cache file is corrupt, confirm that the remote URL works, delete only that provider’s cache, and fetch it again; do not wipe the entire client directory. Clearing everything also removes policy selections, configurations, and troubleshooting clues.

When a subscription returns empty content, do not immediately overwrite the long-term local file with the empty result. Graphical clients often keep the old configuration when parsing fails, but implementations differ. Scripts should download to a temporary file, validate the YAML and configuration, and replace the target only afterward. This “validate before replace” workflow prevents a network interruption or server-side error from turning a working configuration into an empty file.

Sensitive Information and Portable Configurations

Subscription URLs, node passwords, UUIDs, and control secrets in a configuration are access-related information. When sharing a configuration for troubleshooting, remove these values while preserving the field structure, protocol type, and indentation near the error. Renaming a node alone does not remove credentials. Logs may also contain complete subscription URLs, so sanitize them before sending them to anyone.

For better portability between desktop and mobile devices, keep remote nodes, common proxy groups, and rules in the base layer, and put device-specific ports, control interfaces, TUN, and DNS listening addresses in an override layer. Clash Plus is available for each operating system from the download page. Other clients may present override controls and local directories differently, but the reference relationships in the base YAML should remain clear.

CHAPTER 08

Configuration Overrides, Merging, and System Troubleshooting

Why an override layer matters

Remote subscriptions are usually maintained by a server and regenerated during updates. If DNS, proxy groups, or rules are added directly to the subscription file, the next update may restore the remote version. An override or merge applies long-term local settings to the update result without modifying the original subscription. Different clients may call this an override, merge, extended configuration, or preprocessing, and their interfaces and supported syntax are not identical.

When designing an override, distinguish four operations: replacing one value, appending to a list, removing existing elements, and modifying an object by name. Ordinary YAML merging can overwrite object keys, but it cannot automatically infer that two proxy groups with the same name should merge their members. A client’s override system may provide special rules, but do not assume all clients use the same semantics. Before migrating a configuration, inspect the generated result rather than only the override source file.

Mapping Overrides and List Replacement

Mapping fields are usually overwritten by key. For example, if the base configuration has mode: rule and the local override sets mode: global, the latter generally wins. Whether nested mappings are deep-merged depends on the tool: some replace only the specified child fields in dns, while others replace the entire new dns object. If nameserver entries suddenly disappear after an override, the nested object was likely replaced wholesale.

# base.yaml
mixed-port: 7890
mode: rule
dns:
  enable: true
  enhanced-mode: fake-ip
  nameserver:
    - 223.5.5.5

# override.yaml
mode: rule
dns:
  ipv6: false
  fake-ip-filter:
    - '*.lan'

An ideal deep merge keeps enable, enhanced-mode, and nameserver, then adds ipv6 and filter entries; a whole-object replacement leaves only the two fields in the override. The filename cannot tell you which behavior applies, so export or inspect the final configuration in the client. When first setting up an override, test with an easy-to-observe, non-sensitive field instead of adding an entire DNS and proxy-group block at once.

Lists require even more care. rules, proxies, and proxy-groups are lists. Some ordinary merge tools replace the entire list, while others support prepending, appending, or inserting by name. If local rules must take precedence over subscription rules, explicitly use a “prepend rules” feature; simply appending them after MATCH will not work. If the client supports only whole-list replacement, preserve the complete remote list or use a rule provider instead of writing only the few new entries.

When to Use YAML Anchors

YAML anchors reduce repeated fields within one file. For example, several automatic proxy groups can share a mapping containing the same test URL and interval. Anchors work only within a single YAML parse and cannot be shared automatically between a remote subscription and a local override. Some configuration processors expand or remove anchors during generation, so confirm that the client can read the result before relying on them.

group-test: &group-test
  type: url-test
  url: https://www.gstatic.com/generate_204
  interval: 300
  tolerance: 80

proxy-groups:
  - name: Auto Select
    <<: *group-test
    proxies:
      - Example-Trojan
      - Example-SS

  - name: Backup Auto Group
    <<: *group-test
    proxies:
      - Example-SS
      - Example-Trojan

Anchors are useful for reducing static repetition, not for hiding complex hierarchy. Overuse forces readers to trace merge sources and makes migration between clients harder. For a configuration intended for long-term maintenance or public sharing, a little repetition is preferable to obscuring each group’s core behavior. If the expanded result is difficult to inspect, use an override mechanism explicitly supported by the client.

Validate the Final Configuration in Stages

Validate configuration changes in four stages. First check YAML syntax, including indentation, quotes, and data types. Second check object relationships to confirm that node, group, provider, and rule references exist. Third load the client and verify that ports, DNS, and the control interface do not conflict with system resources. Fourth test real connections to verify rule matches and the final exit. Completing only the first stage does not mean the configuration is usable.

1. Keep the Base File and a Known-Good State

   Keep copies of the original subscription, local override, and final generated configuration, and record the policy that worked before the change. Recovery should return to a known state rather than depend on memory to undo edits one by one.

2. Change One Configuration Layer at a Time

   Update common fields first, then DNS, followed by proxy groups and rules. If you also replace nodes, enable TUN, and rewrite DNS at once, it becomes difficult to identify which layer caused the failure.

3. Inspect the Fully Expanded Result

   Confirm that the original lists remain after the override, same-name policies were replaced as intended, rules appear before MATCH, and provider cache paths are separate.

4. Test the Connection Chain

   Test direct access, the local proxy port, DNS queries, one node, a proxy group, and rule routing in sequence. Move to the next step only after the previous one passes, rather than attributing every symptom to the node.

Common Errors and Troubleshooting Order

You can confirm port conflicts with operating-system network tools. On Windows, use netstat -ano in a terminal to view listening ports; on macOS and Linux, use lsof or ss. After finding the owning process, first determine whether it is another proxy client that is already running. Do not enable system proxy and TUN in multiple clients at the same time. Even with different ports, repeated overrides of routes, DNS, or system-proxy settings can create loops.

# Windows: Check port 7890
netstat -ano | findstr :7890

# macOS: Check port 7890
lsof -nP -iTCP:7890 -sTCP:LISTEN

# Linux: Check listening ports
ss -lntp | grep 7890

Recover from a Minimal Configuration

When a complex configuration is impossible to isolate, create a minimal test file containing only one local port, one confirmed working node, one Select proxy group, and one MATCH rule. Disable TUN, custom DNS, rule providers, and script overrides, then verify the basic proxy chain. Once it works, add layers back in the order DNS, providers, proxy groups, rules, and TUN. This is more reliable than randomly deleting and editing a multi-thousand-line configuration.

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

proxies:
  - name: Test-Node
    type: trojan
    server: edge.example.net
    port: 443
    password: your-password
    sni: edge.example.net

proxy-groups:
  - name: Node Selection
    type: select
    proxies:
      - Test-Node
      - DIRECT

rules:
  - MATCH,Node Selection

If the minimal configuration still fails, use the logs to determine whether the issue is the local port, node resolution, server connection, or TLS authentication. If the minimal setup works but the full configuration fails, the problem lies in one of the layers added later. Save a known-good state after restoring each layer to establish a clear boundary. For more symptom-based fixes, see Troubleshooting. If installation and the first subscription import are not complete, return to Getting Started and follow the main workflow.

Long-Term Maintenance Recommendations

A stable configuration is not measured by the number of fields, but by clear relationships, controlled updates, and recoverable failures. Keep common ports, DNS, and a few stable policies in the base layer; let the remote layer manage nodes and large rule sets; use the device layer for TUN, bind addresses, and system differences; and store only long-term local changes in the override layer. Every layer should have a clear source and purpose.

After a subscription or rule-library update, focus on provider status, empty proxy groups, the current node, and matches for critical rules. After upgrading the client, run a configuration check to confirm that advanced fields are still supported before enabling the everyday profile. When problems occur, keep the logs, the fully expanded configuration, and a minimal reproduction snippet. Do not switch among multiple configuration files without recording the result. Checking in the order “syntax—references—ports—DNS—nodes—policies—rules—system interception” usually narrows the problem to a specific layer.