Configuration Reference

Clash Glossary

Understand the names, purposes, and requirements of each layer, from client to network stack. Look up a term, then check the active configuration.

Core and Client

The core handles connections, the client provides the interface, and system settings determine how apps use a proxy. Keep these three layers distinct when troubleshooting.

Clash CoreProxy engine: The core is the network engine that reads configuration, establishes proxy connections, matches rules, and handles DNS. A GUI is just one way to manage it. The original Clash and later derivative cores do not support exactly the same fields; being able to import an older configuration does not mean every feature will work. If a field triggers an error, first confirm which core is running, then consult its configuration documentation.

mihomoFormerly Clash Meta: mihomo is an open-source proxy core evolved from the Clash Meta project, with support for rule-based routing, TUN, Fake-IP, and multiple protocols. It can run as a standalone program or be used by GUI clients such as Clash Verge Rev. When choosing a client, compare interface preferences and core compatibility separately; the word Clash in an app's name does not tell you everything.

GUI ClientGUI client: A GUI client handles everyday tasks such as importing subscriptions, switching proxy groups, viewing logs, and launching at startup. It often manages the core process and system proxy as well. A UI toggle may first change the client's own settings before generating the runtime configuration, so the original subscription file may not contain a field with the same name. Browse the client list by operating system, then confirm where to configure the features you need.

System ProxySystem proxy: The system proxy is an address setting the operating system provides to apps, usually pointing to an HTTP or SOCKS port listened to by the local core. Apps such as browsers that honor this setting will use it, but programs that create their own network connections or ignore system settings may not. If some apps connect directly, that does not necessarily mean the proxy is broken; check their own proxy options or learn how TUN routing works.

Mixed Portmixed-port: mixed-port defines a local listener that accepts both HTTP and SOCKS proxy connections. A common example is 7890, but this is not a requirement. The port entered in an app must match the core setting, and no other process can use the same port on the same address. This is a local entry point, not a remote proxy port. See port configuration for details.

Proxy Protocols

A protocol defines how a connection is established. Server address, authentication details, transport, and certificate settings need to be considered together.

Proxy nodeProxy outbound: A proxy is a set of parameters for a proxy outbound, typically including server, port, type, and authentication details, and may appear under proxies. A proxy name is just an identifier in the configuration; it does not prove the server's location, bandwidth, or availability. A proxy and a proxy group are different: the former defines a connection, while the latter selects among outbounds.

Shadowsockstype: ss: Shadowsocks is an encrypted proxy protocol, represented in mihomo by type: ss. It typically requires an encryption method in cipher and a password. The encryption method, server port, and password must match the server; some configurations also include plugin settings. Copying only the address and port is not enough—missing protocol parameters can cause a connection or handshake failure.

VMesstype: vmess: VMess is a proxy protocol that identifies users with a UUID. Its configuration type is vmess and it may use transports such as WebSocket. Along with uuid, check network, TLS, the request path, and the host name. Parameters cannot be mixed freely between transport combinations. If authentication or handshake fails, compare the full proxy configuration instead of repeatedly changing its display name.

VLESStype: vless: VLESS is a lightweight proxy protocol configured with type: vless, and commonly uses a UUID as the user identifier. The protocol itself does not encrypt traffic; connection security depends on specific settings such as TLS or REALITY. Keep the server name, transport, and authentication parameters provided for the proxy. Do not reuse another protocol's configuration block by changing only the type name.

Trojantype: trojan: Trojan typically uses TLS and password authentication, and is configured with type: trojan. In addition to the password, a connection may depend on the correct sni and server certificate; some setups also use extra transport settings. If a certificate error occurs, check the system clock, server name, and configuration source first. Disabling certificate verification is not a suitable long-term fix.

Rules and Routing

Rules match connections; proxy groups select an outbound. A connection's destination depends on the mode, rule order, and final group selection.

Rule-Based Routingmode: rule / rules: In rule mode, connections are matched against rules from top to bottom. The first matching rule selects an outbound or proxy group, so put specific domain rules before the catch-all MATCH. For example, DOMAIN-SUFFIX,example.com,DIRECT sends that domain and its subdomains directly. DIRECT only selects the outbound for that connection; it does not disable the client. In global mode, traffic no longer follows rule-mode routing.

GeoIPGEOIP: GeoIP matches using the geographic location associated with a destination IP in a database, for example GEOIP,CN,DIRECT. Results depend on database updates and the destination address; CDNs, deployments across regions, or database errors can make results differ from expectations. Adding no-resolve prevents the rule from triggering a DNS lookup, but it may not match if the connection has no usable IP yet.

GeoSiteGEOSITE: GeoSite matches services or websites using predefined domain categories, unlike GeoIP, which matches IP locations. A category name in a rule must exist in the data actually loaded, and different data sources may have different labels and coverage. GeoSite is not a real-time website classification service. If a domain does not match, check the data contents, update status, and earlier rules rather than changing only the proxy.

Rule Setrule-providers / RULE-SET: A rule set stores many matching conditions in a separate file. Load it with rule-providers, then reference it in a rule with RULE-SET. The provider's behavior determines how its contents are interpreted; common types include domain, ipcidr, and classical. A rule set supplies conditions, while the main configuration's rules still determine outbound selection and priority.

Proxy Groupproxy-groups: A proxy group defines outbound selection logic in proxy-groups and can contain proxies, other groups, or built-in outbounds. Use select for manual selection, url-test to choose based on test results, and fallback to switch based on availability. Automatic selection is not ideal for every use case; the test URL and detection settings affect the result. See the proxy group selection tutorial for practical steps.

DNS and Network Stack

DNS resolution, traffic interception, and outbound selection are separate steps. TUN and Fake-IP can work together, but they are not substitutes for each other.

DNSDomain Name System: DNS resolves domain names into addresses and other records. In the dns section, mihomo can configure upstream resolvers and resolution policies. nameserver specifies regular DNS upstreams, while proxy-server-nameserver can be used specifically to resolve proxy server names. Adding DNS settings does not mean every query reaches the core; check the actual resolution path through the system, browser, and TUN.

Fake-IPdns.enhanced-mode: fake-ip: Fake-IP returns a mapped address for a domain lookup. When the connection reaches the core, the mapping is used to recover the domain and match routing rules. Enable it with dns.enhanced-mode: fake-ip; the returned address is not the website's real server address. Some apps need real DNS results, so you can configure fake-ip-filter for compatibility. Understand the selected filtering mode rather than excluding every domain by default.

TUN Modetun.enable / auto-route: TUN uses a virtual network interface and routing settings to send traffic from more apps to the core, including apps that ignore the system proxy. tun.enable turns it on; options such as auto-route and stack also affect how traffic is intercepted, and service mode or system authorization is usually required. Once traffic reaches the core, it is still routed according to the mode and rules, so enabling TUN does not mean every connection is forwarded through a remote proxy.

Domain Sniffingsniffer: Domain sniffing attempts to extract domain names from supported HTTP, TLS, or QUIC handshake information, helping connections with only a destination IP match domain rules. It is controlled by the sniffer setting; detection depends on traffic type and core support, and does not decrypt app content. If the original destination differs from the sniffed domain, understand what override-destination does before changing it.

DNS LeakDNS leak: A DNS leak occurs when a query takes an unexpected resolution path and is sent to a local ISP or another resolver. Routing a web connection through a proxy does not prove that DNS queries follow the same path. Browser Secure DNS, IPv6, and other network tools can also affect test results. When investigating, compare results from a leak test with system DNS settings, browser settings, and core logs to distinguish resolver identity from the route the query actually takes.

Subscriptions and Configuration

Subscriptions provide content, clients import and merge it, and the core runs the resulting configuration. Before and after updates, check whether the configuration was replaced and whether local changes were preserved.

SubscriptionSubscription: A subscription is typically a URL that a client periodically fetches for configuration or a proxy list. It may return a complete Clash YAML file or a Base64-encoded list of proxy links. The two formats may require different import options, so check what the client supports. Subscription URLs often contain access credentials: treat them as private, and do not share screenshots or paste them into untrusted conversion services. A failed update does not necessarily mean existing proxies have stopped working.

YAMLconfig.yaml: YAML is a common text serialization format for Clash configuration. Indentation defines structure, and list items usually start with -. Use spaces, not tabs, and preserve each field's indentation level; special characters may need quotes. A successful parse only means the text structure is valid. It does not confirm that the current core supports the fields or that proxy group names match the rules that reference them.

Proxy Providerproxy-providers: proxy-providers manages a separate set of proxies. You can configure its source URL, cache path, update interval, and health checks, then reference it from a proxy group with use. Unlike a subscription for the full configuration, it lets you update the proxy list while keeping the main routing structure. A proxy provider supplies outbounds; rule-providers supplies matching conditions. They are not interchangeable.

Local OverrideLocal override / merge: A local override merges or adjusts local settings on top of a remote subscription, often to preserve ports, DNS, TUN, or custom rules. The option may be called an override, merge, or script, and whether lists are replaced or appended depends on the client. Editing a downloaded subscription directly can be undone by the next update. Use the client's supported method for persistent changes, and check the final runtime configuration rather than only the editor contents.

Proxy LatencyLatency test / url-test: The latency shown by a client is usually the time taken to reach a specified test URL. It may include DNS lookup, connection setup, or protocol negotiation, and is not necessarily an ICMP ping. Results depend on the test URL, timeout, and network conditions; a lower number does not mean faster downloads. Compare proxies under the same test conditions where possible, then verify performance with your actual use case. A timeout means only that this test did not complete—it does not prove that every service is unreachable.

External Controller APIexternal-controller: external-controller defines the listening address for the core management API, which dashboards can use to query connections, switch proxy groups, or change some runtime settings. It is not an HTTP or SOCKS proxy endpoint; do not enter this port in an app's proxy settings. Keep access local in most cases. For remote management, consider the listening scope, authentication, and firewall rules together—do not expose the API to the public internet just for convenience.