FlClash Configuration Field Reference

YAML Structure Overview: Understand the Hierarchy Before the Fields

Root Objects, Mappings, and Sequences

The root layer of a mihomo configuration file is a YAML mapping. A mapping consists of a “key, colon, and value,” such as mode: rule; a sequence begins with a hyphen and commonly appears in proxies, proxy-groups, and rules. Indentation defines the hierarchy, and fields at the same level must use the same indentation depth. Two spaces are conventional; tabs should not be used. YAML does not require exactly two or four spaces, but inconsistent indentation changes the data structure. The parser may fail outright, or it may assign a field to the wrong parent object. The latter is harder to spot: the file loads, but an option never takes effect.

Scalar values include strings, numbers, booleans, and null values. When written as 7890, a port is a number; true and false are booleans; node names, domains, and modes are usually strings. Strings containing colons, hash signs, brackets, braces, or leading or trailing spaces should be quoted. In an unquoted string, a hash sign starts a comment, so passwords or names containing one must be quoted. YAML is case-sensitive: Rule, RULE, and rule are different values. Field names must also use the spelling specified by the documentation; Chinese labels shown in the interface cannot replace configuration keys.

# Typical root structure of config.yaml
mixed-port: 7890
allow-lan: false
mode: rule
log-level: info

dns:
  enable: true
  enhanced-mode: fake-ip
  nameserver:
    - https://dns.example/dns-query

proxies:
  - name: "Example Node"
    type: socks5
    server: proxy.example.com
    port: 1080
    username: "your-user"
    password: "your-password"

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

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

Field Order Is Not Traffic Processing Order

YAML mappings are not semantically dependent on writing order, so placing dns before or after proxies usually does not change the result. People still need a consistent structure to read. A sensible order is common settings, DNS, inbound listeners, proxy nodes, proxy providers, proxy groups, rule providers, and rules. Sequences are where order matters: rules are matched from top to bottom and stop at the first match; node order inside a proxy group affects the default option or candidate order during automatic selection; objects with identical names may also replace one another during an override.

References must resolve. The policy name at the end of a rule must exist in proxy-groups, or be a built-in policy such as DIRECT or REJECT. A proxy group’s referenced node names must correspond to nodes in proxies, other defined proxy groups, or proxy providers brought in through use. When renaming an object, do not update only its definition; check proxy groups and rules as well. Chinese characters, spaces, and punctuation are all part of a name, so “Node Selection” and “Node Selection ” are different strings.

Anchors, Aliases, and Advanced YAML Syntax

YAML supports anchors and aliases for reusing a set of parameters, such as sharing udp and skip-cert-verify across multiple nodes. However, subscription converters, override engines, and graphical editors do not preserve every advanced YAML feature consistently. Saving through an interface may expand anchors into ordinary fields, and some merge keys may be re-serialized. For long-term, cross-device maintenance, explicit and readable fields are usually safer. Anchors work well in independently maintained local files, but are a poor fit for subscription content that is updated remotely.

Comments can also disappear after graphical saves or subscription updates. Do not keep important maintenance notes only in a subscription cache. Record rule intent and source in separate documentation, or put custom content in a stable override file. FlClash loads and manages the configuration, while the mihomo core interprets the actual fields. If something is visible in the interface but not used by the core, first check parser messages in the runtime log and then inspect the final effective configuration instead of checking only the raw subscription text.

Common Fields: Ports, LAN Access, Modes, and Logs

How to Divide Listening Ports

port is the HTTP proxy listening port, socks-port is the SOCKS5 proxy listening port, and mixed-port accepts both HTTP and SOCKS5 on one port. Desktop environments usually need only mixed-port, allowing the system proxy and different applications to share one entry point. Multiple listeners can coexist, but their port numbers must not conflict or be occupied by another program. If FlClash assigns ports through its interface, values in a manually edited configuration may be overridden by the client. During troubleshooting, check the final listening address and runtime log rather than relying only on the numbers in the editor.

Fields such as redir-port and tproxy-port serve transparent proxy paths, typically used with Linux firewall rules, routers, or specific traffic interception methods. Ordinary desktop users should not enable every port simply for completeness. A port only accepts traffic; it does not automatically change system routing. System proxy mode requires the operating system to direct proxy-aware applications to an HTTP or SOCKS port. TUN mode creates a virtual network interface to handle a broader range of traffic, with different permissions, coverage, and troubleshooting steps.

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

allow-lan and Listening Boundaries

allow-lan controls whether devices on the local network can connect to the local proxy port. Set to false, it is commonly used for desktop configurations intended only for local applications. After setting it to true, you must also configure the listening address correctly and ensure that the operating system firewall allows the port. This field does not automatically provide other devices with a gateway or proxy address, nor does it replace access control. If a LAN proxy is genuinely needed, use a fixed private address, restrict trusted subnets, and enable authentication. Never expose the listening port directly to the public internet.

bind-address determines the listening scope. A wildcard address listens on available interfaces, while a specific address restricts the entry point to one network adapter. On mobile devices, switching between Wi‑Fi and cellular networks can make the original binding invalid. If the proxy works locally but other devices are refused, check allow-lan, the binding address, the firewall, whether the devices share a subnet, and whether the proxy type is correct. If the connection succeeds but the destination cannot be reached, continue with the proxy group, DNS, and outbound node.

Three Operating Modes

mode: rule determines where traffic goes from the rule list and is the main mode for everyday configurations. global sends traffic through the global policy and is useful for temporarily verifying whether a node works; direct connects directly and helps determine whether a problem comes from the proxy path. Switching modes does not delete rules; it changes the decision entry point. For troubleshooting, switch briefly: if global mode works but rule mode does not, the issue is usually a rule match or policy reference; if direct mode also fails, check the local network, DNS, or system interception state.

Common log-level values include silent, error, warning, info, and debug. Keep info for normal use; temporarily switch to debug when investigating rule matches, DNS queries, or handshake failures. Detailed logs greatly increase output and may contain runtime information such as destination domains and node addresses, so restore the normal level when finished. The first error is often more useful than the chain of errors that follows. Read the log in order: configuration loading, listener startup, DNS initialization, and proxy handshake.

Latency Tests, Concurrent Connections, and Process Detection

unified-delay standardizes latency testing so results from different proxy types are easier to compare. A speed-test result describes one connection to the test URL under current network conditions; it is not a fixed latency for every website. tcp-concurrent allows parallel attempts to multiple candidate connections for a destination. It may shorten connection setup on dual-stack or multi-address networks, but creates extra attempts. On restricted networks, resource-constrained routers, or systems where connection counts must be controlled, disable it and compare the results.

find-process-mode controls how the core identifies the process that owns a connection. Process-based rules depend on operating-system capabilities and permissions, which vary by platform. Android, macOS, Windows, and Linux represent process paths, package names, and permissions differently, so a process rule should not be assumed to be fully portable. If domain or IP conditions are sufficient for routing, prefer network-layer rules. Use process matching only when application-level separation is genuinely required, and verify the process name on the target platform.

DNS Fields: Resolution Paths, Fake-IP, and Consistent Routing

DNS Configuration Is About More Than Resolution Speed

In a proxy environment, DNS handles domain resolution, rule evaluation, proxy server address resolution, and preventing requests from bypassing the intended path. After dns.enable activates the core DNS module, queries can follow the configured upstreams, but whether every query reaches the core also depends on TUN, system DNS settings, and application behavior. Browsers may enable their own encrypted DNS, while some applications cache addresses or connect directly to fixed IPs. When resolution results and rules disagree, map the query path first: which resolver the application asks, which upstream the core uses, who resolves the proxy server’s domain, and which rule ultimately matches the connection.

nameserver is the primary list of DNS servers for ordinary domain queries. default-nameserver is commonly used to resolve the domains of encrypted DNS servers themselves, avoiding the circular dependency of needing to resolve a DNS server before connecting to it. It therefore usually contains directly reachable IP-address servers. proxy-server-nameserver can resolve proxy node domains separately from ordinary business domains. direct-nameserver can provide a dedicated path for domains explicitly sent direct. Configure only what the actual network topology requires; more fields do not automatically mean more stability.

dns:
  enable: true
  listen: 0.0.0.0: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://dns.google/dns-query
    - tls://1.1.1.1
  proxy-server-nameserver:
    - https://dns.google/dns-query
  respect-rules: true

Fake-IP vs. Redir-Host

enhanced-mode: fake-ip first returns an address from a reserved mapping pool to the application. The core then restores the original domain from that mapping and evaluates the rules. Even when an application passes only a destination IP to the network layer, the core can retain domain information, making domain rules and sniffing work more directly. fake-ip-range defines the mapping pool and must not overlap with local, container, or corporate VPN subnets. An address conflict may affect only a particular subnet rather than causing every connection to fail.

redir-host is closer to traditional real-address resolution: the application receives the actual IP for the destination domain, and the core processes the traffic using the information available afterward. This is more intuitive for some device discovery, LAN services, and special protocols that do not accept Fake-IP, but domain information may be lost during the subsequent connection, making rule matching more dependent on DNS cache and sniffing. Choose the mode based on application compatibility and routing accuracy rather than treating one mode as universally correct. In most cases, start with Fake-IP and add clearly incompatible domains to the filter list instead of abandoning domain mapping altogether.

Keep fake-ip-filter Explainable

Domains in the filter list bypass Fake-IP mapping and receive real resolution results. LAN discovery, time synchronization, STUN, some game platforms, and device pairing may require exclusions. Every addition should have a clear symptom and a way to verify it—for example, an application cannot discover devices on the same subnet only under Fake-IP, then works after the relevant domain is added. Do not casually add broad top-level domains or wildcard rules, or many requests will fall back to real-address resolution. This reduces the visibility of domain rules and can make behavior diverge between devices.

Distinguish exact domains, single-level wildcards, and suffix matching. Different fields may support different wildcard semantics, so do not copy DOMAIN-SUFFIX syntax from the rule list directly into the filter list. After changing the list, clear the application’s DNS cache, establish a new connection, and check the log to confirm that queries use the intended upstream. Refreshing a page alone may reuse the browser’s connection pool and old cache, creating the false impression that the configuration did not change.

Rule-Based Routing and DNS Upstream Selection

respect-rules makes DNS requests follow the rule system where applicable, but the proxy policy used for DNS must be able to connect before resolution completes, otherwise a recursive dependency can occur. For example, if the proxy node is named by a domain and encrypted DNS must itself go through that proxy, the node domain must first be resolved by proxy-server-nameserver or a directly reachable bootstrap resolver. Separate node-address resolution from business-domain resolution so the lowest layer always has a path that does not depend on a proxy that has not been established yet.

nameserver-policy selects a specific upstream by domain, which is useful for corporate intranet domains, LAN services, or zones that require a fixed resolution source. Keep policies narrow: match explicit suffixes first and retain the general nameserver as a fallback. If one domain may match multiple policies, check match priority and the final log. For domain collections maintained by rule providers, also confirm that the rule-set behavior and DNS policy fields support the intended reference method.

dns:
  enable: true
  enhanced-mode: fake-ip
  nameserver:
    - https://dns.google/dns-query
  nameserver-policy:
    "+.internal.example":
      - 192.0.2.53
    "geosite:private":
      - system
  direct-nameserver:
    - system
  direct-nameserver-follow-policy: true

Break common failures down by layer. If domains cannot resolve at all, check the DNS listener, upstream reachability, and certificate time. If they resolve but cannot connect, check the rule policy and node. If only the node domain fails, check bootstrap resolution and proxy-server-nameserver. If LAN devices behave unexpectedly, check Fake-IP pool conflicts and filter entries. If old and new results appear intermittently, clear system, browser, and core caches. For a fuller troubleshooting path, see the DNS and connection sections of the FAQ.

Proxy Node Fields: Common Properties, Protocol Parameters, and Transports

Every Node Starts with a Name, Type, and Server

proxies is a sequence of manually defined nodes. Each node needs at least a unique name, protocol type, server server, and port port, plus the authentication fields required by that protocol. The node name is the primary key referenced by proxy groups and rules, so keep it stable. If an upstream changes names during a subscription update, manually defined groups may contain dangling references. Dynamic subscriptions are therefore better organized through proxy providers and filters than by hard-coding many changing node names into groups.

server can be an IP address or a domain. A domain makes server migration easier but requires a stable node-resolution path; an IP avoids one lookup but cannot follow address changes automatically. udp controls whether the node carries UDP, while actual support also depends on the protocol, server, and network path. interface-name and routing-mark fields can bind connections to a particular egress, which is useful on multi-homed systems but may fail after a mobile device changes networks. Unless multiple exits are required, avoid locking platform-specific fields into cross-device configurations.

proxies:
  - name: "Office SOCKS"
    type: socks5
    server: proxy.example.com
    port: 1080
    username: "your-user"
    password: "your-password"
    udp: true

  - name: "Example HTTP"
    type: http
    server: gateway.example.net
    port: 8443
    username: "your-user"
    password: "your-password"
    tls: true
    skip-cert-verify: false

TLS Fields and Server Identity

Protocols that support TLS commonly include tls, servername, skip-cert-verify, ALPN, and fingerprint-related options. servername is the server name used during the TLS handshake and must match the server certificate and deployment configuration; it is not an arbitrary camouflage domain. skip-cert-verify: true disables certificate validation and is appropriate only for clearly controlled testing environments. Normal configurations should retain validation and fix the system clock, certificate chain, server name, or intermediate network interference. If the connection log reports a certificate-name mismatch, verify the subscription parameters first instead of hiding the configuration error by disabling validation.

WebSocket, gRPC, HTTP/2, and similar transport parameters are usually nested under the options for their respective protocols. The path, Host, service name, and request headers must match the server. Fields that look similar may have different nesting levels; a WebSocket path does not become effective simply because it is written at the node’s root. When migrating a configuration from another client, do not copy items solely by matching Chinese labels. Compare the node structure supported by mihomo. When a subscription is generated by a service provider, preserve its original transport parameters unless the server requirements have been confirmed.

Protocol-Specific Fields Are Not Interchangeable

The core Shadowsocks fields are cipher and password; Trojan primarily uses a password, TLS server name, and transport parameters; VMess commonly requires uuid, encryption options, and transport settings; VLESS requires a UUID and may include flow, Reality, or other extension fields; Hysteria2 and TUIC also involve UDP-based transport, congestion control, or bandwidth parameters. Fill out each protocol according to its own structure. Putting one protocol’s authentication fields into another does not create a compatibility layer; the fields are usually ignored or cause loading to fail.

Protocol capabilities come from the mihomo core, while FlClash provides configuration management and a cross-platform interface. A field supported by the core does not mean that system networking conditions are identical on every platform. UDP-based protocols may be restricted by public Wi‑Fi, corporate networks, or carrier paths; TUN permissions and background execution also affect mobile use. When validating a node, start with a simple connectivity test and then inspect the handshake log. A failed node speed test does not necessarily mean the subscription is invalid; the test address may be unreachable, DNS may not be ready, UDP may be blocked, or the policy may form a loop.

Node Names, Sensitive Fields, and Sharing Boundaries

Node configurations contain server addresses and authentication data and should not be pasted directly into public support pages. For troubleshooting, preserve the field structure but replace the address with proxy.example.com and passwords or UUIDs with clearly fake test values, while keeping the protocol type, nesting, and boolean fields. Do not show only a single error line while hiding its context; many problems come from indentation or a parent field. Do not publish subscription URLs either. They often function as access credentials, so if one leaks, reset it at the service provider instead of merely deleting it from a post.

Duplicate node names make policy references and interface selection ambiguous. Manual configurations should use unique names. When aggregating nodes from multiple proxy providers, add a source prefix or suffix during the override stage. If name filters use regular expressions, account for parentheses, plus signs, and other metacharacters. Test a filter against a small set of nodes before applying it to the full subscription. If you need to choose another graphical client, the Download Center lists Clash Plus, Clash Verge Rev, FlClash, Clash Nyanpasu, and other platform options, with Clash Plus as the recommended cross-platform entry point.

Proxy Group Fields: Selection, Health Checks, Failover, and Chained References

Proxy Groups Form the Decision Layer Between Rules and Nodes

proxy-groups organizes nodes, built-in actions, and other proxy groups into outbound sets that rules can reference. Rules usually point to stable policy names such as “Node Selection,” “Auto Select,” or “Traffic Outside Mainland China” instead of specific nodes. When subscription nodes change, only the group’s candidates need updating. Each group requires at least name and type. Candidates are listed explicitly through proxies or imported from proxy providers through use.

select lets users choose a candidate manually and works well as a top-level entry point. A group can contain specific nodes, an automatic test group, and DIRECT at the same time. The first item usually has default significance, but a client may also save the previous choice, so reordering candidates does not necessarily change the current selection immediately. When a rule reaches the correct group but traffic still uses the wrong node, check both the group’s current selection and its persisted state.

proxy-groups:
  - name: "Node Selection"
    type: select
    proxies:
      - "Auto Select"
      - "Failover"
      - "Office SOCKS"
      - DIRECT

  - name: "Auto Select"
    type: url-test
    proxies:
      - "Office SOCKS"
      - "Example HTTP"
    url: https://www.gstatic.com/generate_204
    interval: 300
    tolerance: 80
    lazy: true

  - name: "Failover"
    type: fallback
    proxies:
      - "Office SOCKS"
      - "Example HTTP"
    url: https://www.gstatic.com/generate_204
    interval: 300
    lazy: true

url-test, fallback, and load-balance

url-test periodically requests a test URL and selects a suitable candidate based on the result. interval sets the testing interval; testing too often increases the load on nodes and devices. tolerance adds a switching margin to prevent minor fluctuations from causing frequent changes. lazy reduces active testing while the group is unused. The test URL should be stable, lightweight, reachable on the target network, and representative of the actual connection path. The lowest latency only means the request was established fastest to that test target; it does not guarantee the best bandwidth, packet loss, or route to the destination website.

fallback selects the first available candidate in order, which suits a primary-and-backup setup. It does not distribute requests evenly or guarantee seamless migration of existing long-lived connections. load-balance distributes connections among candidates, commonly using consistent hashing or round-robin. Use round-robin carefully with login sessions and services sensitive to source addresses, because connections for one activity may leave through different exits. When session stability matters, consistent hashing or manual selection is usually more predictable.

Proxy Providers and Dynamic Candidates

When nodes come from a remote subscription, proxy-providers can manage node data, update intervals, and health checks independently, while proxy groups reference providers through use. After remote nodes are added or removed, the groups do not need individual renaming. Provider filter, exclude-filter, and override rules can select regions, protocols, or use cases by name, but filtering depends on consistent upstream naming. When names are unstable, a more reliable approach is to layer multiple conditions and retain an unfiltered master group for inspection.

Health checks at the provider level overlap with proxy-group testing. Provider health checks determine basic node availability, while a group’s url-test drives candidate selection. Very short intervals at both levels create duplicate traffic. On resource-limited devices or with many nodes, lengthen the provider interval and let frequently used automatic groups perform more timely tests. If every node suddenly appears unavailable, check the test URL, DNS, and network entry point before concluding that all nodes have failed.

proxy-providers:
  remote-main:
    type: http
    url: "https://subscription.example.com/your-token"
    path: ./providers/remote-main.yaml
    interval: 21600
    health-check:
      enable: true
      url: https://www.gstatic.com/generate_204
      interval: 600

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

  - name: "Auto Subscription"
    type: url-test
    use:
      - remote-main
    url: https://www.gstatic.com/generate_204
    interval: 300
    tolerance: 100

Chained References Must Not Create Loops

Proxy groups can reference other proxy groups to build layers such as “service group → master selection group → automatic test group → nodes.” For example, a streaming group can be selected independently or fall back to the master selection group. No reference chain may return to itself. If A references B and B references A, a loop forms and the connection cannot resolve to a final outbound. In complex configurations, arrange node groups, automatic groups, master selection groups, and service groups by dependency order, and make their responsibilities clear in their names.

The built-in policy DIRECT connects directly, while REJECT denies the request. Both can be candidates in a proxy group or written directly at the end of a rule. Adding DIRECT to a top-level selection group makes it easy to bypass the proxy temporarily, but also increases the risk of selecting it accidentally. For fixed-device configurations, explicit rules can handle direct traffic without repeating the option in every service group. Use reject policies for destinations that definitely should not connect. Broad reject rules can remove page resources or break application features, so start with narrow matches.

Rule Sets and Rule Providers: Splitting, Updating, and Behavior Types

Why Move Large Rule Tables Out of the Main Configuration

rule-providers declares rule sets that can be loaded and updated independently. The main configuration keeps only the provider name, source, cache path, update interval, and behavior type, then references the set with a RULE-SET rule. This separates advertising blocks, LAN direct rules, specific services, and regional domains, shortening the main file and allowing independent updates. A rule set is not a proxy group; it supplies match conditions only. The policy after a match is still determined by RULE-SET,provider-name,policy-name in the main configuration.

Common provider type values are http and file. A remote provider needs url, a local cache path, and an update interval; a local provider reads a file on the device. Cache paths must be unique so providers do not overwrite one another. After a remote update fails, the core will usually continue using the existing cache, but a first load without a cache may leave the rule set unavailable. Keep a small built-in fallback for critical direct rules rather than making basic connectivity depend entirely on a remote file that has not downloaded successfully.

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

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

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

behavior Determines How the Rule Payload Is Interpreted

The domain behavior is for domain collections, whose payload is usually made up of full domains, domain suffixes, or supported domain expressions. ipcidr is for IPv4 and IPv6 networks. classical allows each item in the rule set to carry a traditional rule type such as DOMAIN-SUFFIX, IP-CIDR, or PROCESS-NAME. The behavior must match the file content. Declaring a classical file with rule-type prefixes as domain does not automatically strip and convert those prefixes; it usually causes loading to fail or all entries to miss.

Choose the narrowest behavior model that fits. Use domain for a pure domain list, ipcidr for a pure network list, and classical only when mixed conditions are required. Clear behavior types help the core optimize processing and make it easier to tell whether DNS resolution is needed. Do not put every rule into one huge classical file just because it accepts more formats. Split sets by responsibility and data type so matches are easier to troubleshoot.

Rule-Set File Formats and Payloads

YAML rule sets usually use payload as the root key, followed by a sequence of rules. Under domain behavior, a suffix expression can match the root domain and its subdomains, while an exact domain matches only the specified host. Under ipcidr behavior, use standard CIDR networks. Under classical behavior, write complete rule conditions, but do not append the final policy to rule-set entries; the main configuration supplies it when referencing the set. The same rule set can be sent to different policies—for example, direct in a work configuration and proxied in a travel configuration.

# private-domain.yaml
payload:
  - "+.lan"
  - "+.local"
  - "router.example"
  - "intranet.example.org"

# private-network.yaml
payload:
  - "10.0.0.0/8"
  - "172.16.0.0/12"
  - "192.168.0.0/16"
  - "127.0.0.0/8"
  - "::1/128"
  - "fc00::/7"

format must match the actual format of the remote file. A filename extension is not enough; inspect the response body and structure after downloading. If a remote URL returns a login page, rate-limit message, or HTML error page, the file may still be saved successfully but cannot be parsed as a rule set. When the log reports a rule-set format error, inspect the final response rather than checking only whether the URL opens in a browser. For private rule sets requiring authentication, account for credential rotation and device synchronization, and never put real access parameters in public examples.

Update Intervals, Caches, and Atomicity

interval specifies the update interval in seconds. If rules change once a day, there is no reason to fetch them every few minutes. Frequent updates increase requests and upstream load and make transient failures more likely to produce repeated errors. A sound approach is to keep a stable cache, continue using the last parseable local copy, and record update failures in the log. After changing a rule source, trigger an update manually or clear its cache to verify the change. Do not delete every provider cache at once, or a single-file problem will make all rule sets unavailable simultaneously.

Updating rule sets and updating the main configuration are separate operations. If the main configuration references a provider that has not downloaded successfully, the set may be temporarily missing. An incompatible change in remote content may not appear until the next scheduled update. Important configurations should retain a short main-rule fallback, such as direct private-network rules and a final MATCH, while external sets are placed appropriately. Sources should be clear, single-purpose, and recoverable. Large collections of unknown origin may overlap and cause some domains to use the wrong policy intermittently.

Rule Syntax: Match Top to Bottom and Stop at the First Hit

Basic Structure of a Rule

rules is an ordered sequence. Traditional rules usually contain a rule type, match value, target policy, and optional parameters separated by commas. For example, DOMAIN-SUFFIX,example.org,Node Selection sends domains ending in example.org to “Node Selection.” The core checks rules from the top and stops after the first match. The key to rule design is therefore not whether each rule is individually valid, but whether narrower rules appear before broader ones.

MATCH needs no match value and is normally placed last to receive all traffic not matched earlier. If it appears in the middle, later rules never get a chance to run. A rule target can be a proxy group, a specific node, or a built-in action, but proxy groups are usually more stable. When node names change, the rules remain intact as long as the proxy group still offers valid candidates.

rules:
  # Exact domains first
  - DOMAIN,api.example.org,DIRECT
  # Then process the entire domain suffix
  - DOMAIN-SUFFIX,example.org,Node Selection
  # Broader keyword matches go later
  - DOMAIN-KEYWORD,example,Node Selection
  # Connect private networks directly
  - 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
  # Final fallback
  - MATCH,Node Selection

How Domain Rule Scopes Differ

DOMAIN matches only a complete domain and suits an API, login endpoint, or specific host that needs separate handling. DOMAIN-SUFFIX matches a domain and its subdomains, making it suitable for routing an entire service. DOMAIN-KEYWORD matches when a keyword appears in the domain, covering a broader range and creating more false positives; a short keyword may occur in unrelated domains. When an exact domain or suffix is available, do not start with a keyword rule.

Whether a domain rule can match depends on whether the core knows the domain associated with the connection. System proxy requests usually retain the domain; Fake-IP preserves the mapping; transparent connections with only a destination IP may require DNS cache or sniffing. If the log shows only an IP, a missed domain rule is not necessarily a spelling problem. Check whether DNS is handled by the core, whether sniffing supports the protocol, and whether the application connects directly to a fixed address.

IP, Geo, and no-resolve

IP-CIDR and IP-CIDR6 match destination addresses against network ranges. The trailing no-resolve tells the core not to resolve a domain just to evaluate this IP rule, reducing unnecessary queries and avoiding side effects during rule processing. Connections that already have a destination IP can be evaluated directly. Private ranges and local addresses should usually be sent direct near the top, preventing LAN traffic from being routed through a remote proxy.

Geolocation database rules depend on local data files and their update state. Domain classification and IP geolocation are different data sources: a service domain may resolve to globally distributed addresses, so routing by IP region is not equivalent to classifying the service. When using Geo rules, understand their coverage and retain explicit domain rules for critical services. If the database cannot load, those rules may stop working while ordinary DOMAIN and IP-CIDR rules continue to work; the log usually provides clues to distinguish the cases.

Process, Network, and Logical Combinations

PROCESS-NAME, PROCESS-PATH, and similar process rules are useful for routing desktop applications, but depend on system permissions and platform support. Android more commonly uses package names or system-provided application identifiers, while iOS imposes different restrictions. Process paths are represented completely differently on Windows and Unix-like systems, so one absolute path cannot be shared. If a cross-platform configuration must include process rules, inject them through device-specific overrides rather than mixing every platform path into one base file.

mihomo supports logical rules that combine multiple conditions to express “all,” “any,” or “exclude.” The more powerful the combination, the higher the reading and troubleshooting cost. In day-to-day maintenance, prefer rule order for exceptions: write a small number of exclusions first, followed by general rules. Use logical combinations only when ordering cannot express the intent clearly or several conditions genuinely must be true together. Add comments and repeatable test domains to complex expressions, or their original purpose will be difficult to recover months later.

A Stable Template for Rule Order

An explainable order is usually: local and LAN exceptions, explicit rejects, precise rules for critical services, service-domain rule sets, regional or network rules, and a final fallback. This is not a universal answer, but each layer should explain why it comes before the next. If an exact domain must go direct, place it before a proxy suffix rule that includes it. If a subdomain must use a proxy, place it before a direct rule for the entire parent domain.

Do not validate rules by opening a webpage once. Browsers may reuse existing connections, and DNS may return a cached result. After editing, close relevant connections, clear necessary caches, and inspect the log for the destination, rule type, and policy name. If the log shows the correct rule but the exit is wrong, continue through the proxy-group chain. If the log shows no domain, return to the DNS and sniffing layers. Assess rule matching, policy selection, and node connectivity separately.

Overrides and Merging: Preserve Local Changes Across Subscription Updates

Raw Subscription, Generated Configuration, and Final Configuration

A remote subscription is an upstream data source. After import, FlClash may parse it, apply overrides, and adapt it for the core before producing the runtime configuration. Editing the subscription cache directly may appear to work immediately, but the next update will usually replace it. For stable maintenance, separate upstream-owned node data from locally owned policies: the subscription supplies nodes and base groups, while local overrides handle ports, DNS, group structure, rules, and device differences. When a problem occurs, determine whether the raw subscription is correct, whether the override ran as intended, and whether the core accepted the final configuration.

An override is not simple text concatenation. Mapping fields, sequence fields, and same-name objects require different strategies. Mappings may be replaced by key or merged recursively; sequences may be replaced wholesale, prepended, appended, or processed by name. If the current tool’s merge semantics are unclear, start with one observable field such as mode and inspect the final configuration. Do not add a complete DNS section, dozens of rules, and multiple proxy groups at once, or it will be difficult to identify which merge operation caused an error.

Replacing Mappings vs. Appending Sequences

Suppose the original configuration already contains a complete dns mapping and the local override contains only dns.enable: true. A recursive merge preserves child fields such as nameserver, while a wholesale replacement may leave only enable. Both results fit some definition of “override,” so rely on FlClash’s current override type and final preview. For a critical DNS section, explicitly writing the complete target structure is usually more stable than relying on partial merging.

rules is an ordered sequence. Simple appending works for adding supplementary rules before MATCH, but if the original list already ends with MATCH, appending new rules afterward makes them unreachable. Prepending suits LAN exceptions and precise overrides; wholesale replacement suits a fully managed rule system. When proxy-group sequences are merged by name, confirm whether same-name groups are replaced, extended, or duplicated. Two groups with the same name make interface behavior and references difficult to determine.

# Base configuration: base.yaml
mixed-port: 7890
mode: rule

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

rules:
  - MATCH,Node Selection

# Local override target: override.yaml
log-level: info
ipv6: false

dns:
  enable: true
  enhanced-mode: fake-ip
  nameserver:
    - https://dns.google/dns-query

Rule Insertion Requires an Explicit Position

When adding custom rules to a subscription, first decide whether each rule is an exception, a normal category, or a fallback. Exceptions usually go at the top; service rules belong before broader collections; fallback rules can exist only at the end. If script overrides are supported, find the index of MATCH in the original list and insert new rules before it. If MATCH is missing, report the condition and decide whether to add one instead of silently appending and assuming the structure is correct.

Deduplication cannot compare full lines alone. Two rules may have identical match conditions but different policies, which is a conflict rather than a duplicate. An exact rule and a suffix rule for the same domain are not duplicates either. A sound process first identifies conflicts by rule type and match value, then uses local priority to decide which stays and where. Output inspectable results before deleting anything automatically. For small custom rule sets, explicit and readable rules are usually better than excessive automation.

Keep Device Differences at the Outer Layer

When sharing a configuration across platforms, nodes, proxy groups, and most domain rules can be common. TUN, process paths, network interfaces, LAN listeners, and system DNS interception are platform-specific. Maintain a platform-neutral base layer, then apply lightweight device overrides for Windows, macOS, Android, and Linux. This avoids filling one file with fields that another platform does not understand or need.

A desktop may need process rules, while Android is better handled through application capabilities. A Linux router may use transparent proxy ports, whereas a regular Windows desktop may need only mixed-port or TUN. macOS network extensions require system authorization; configuration fields cannot replace that approval. For platform installation and permissions, return to Getting Started and the macOS Network Extension Setup Guide instead of trying to bypass system requirements with YAML alone.

Checklist After a Subscription Update

After an update completes, first confirm that the subscription was fetched successfully, then check whether the node count and naming structure changed as expected. Next verify that the override ran without errors and that DNS, proxy groups, and rules remain in the final configuration. Finally start the core and watch the listener, DNS initialization, rule-provider, and proxy-provider load states. Once the configuration loads, check the current proxy-group selection: if the upstream removed a node, a saved old selection may be invalid or may have fallen back.

Do not solve automatic update failures by repeatedly shortening the interval. Check whether the subscription URL is valid, whether the network requires a proxy, whether DNS can resolve the subscription server, whether the update request creates a proxy loop, and whether the operating system restricts the client in the background. See Clash Subscription Update Failures and Automatic Update Settings for related cases. If the client project is no longer maintained and migration is needed, consult Configuration Export and Client Migration Checklist.

A Reversible Maintenance Workflow

Change one clearly defined configuration section at a time and keep the previous working file. Names can indicate purpose and platform, such as base, DNS, rules, and device layers, but do not put dynamic dates or temporary states into policy names, or rule references will change constantly. Before updating, record the current policy selection. Afterward, verify key domains, LAN access, the DNS path, and one proxied destination. Test both direct and proxied traffic instead of checking only whether a webpage opens.

When overrides become difficult to explain, organize them instead of adding more patches. Remove obsolete rule sources, merge proxy groups with overlapping responsibilities, move device-specific fields out of the base layer, and document the purpose of every external provider. The goal of a configuration manual is not to list every available field, but to make every request explainable along the path “entry point, DNS, rules, proxy group, node.” After completing the base configuration, return to Getting Started to verify the connection, or visit the FAQ to continue troubleshooting by symptom.