CONFIG.YAML / Glossary

Clash Configuration Glossary.

Match interface labels to their configuration meanings. Browse 25 common terms across five topics to distinguish traffic capture, DNS resolution, and rule selection—and avoid conflating issues from different layers.

Follow the step-by-step guide Browse the full documentation

Cores and Clients

Identify the application, core, and configuration source in use. The same button can trigger different configuration behavior in different clients.

mihomo / Clash.Metamihomo Core: mihomo is a proxy core evolved from Clash.Meta. It handles protocol connections, DNS, and rule matching; Clash.Meta is an earlier name in its history. A GUI is usually just the interface for managing the core, and GUI updates do not necessarily include core updates. If a configuration field is unsupported, check the actual core version in the client’s About or core information screen instead of relying on the application name.

client / GUIClient: A client is the application you install and use to import subscriptions, select nodes, configure the system proxy, and manage the core. Before starting, it may merge subscriptions, override settings, or apply additional configuration, so editing the source subscription does not always change the effective configuration. When troubleshooting, check both the client’s settings and the active configuration. To choose an app, see the client comparison.

subscription / profileSubscription: A subscription is usually a remote source for nodes or a complete configuration. Refreshing it requests that resource again. It may return a full YAML configuration or just a node list, which the client or a conversion tool must handle; not all subscription links are interchangeable. Subscription URLs often contain personal access credentials, so don’t share them in screenshots, public logs, or support requests. For import instructions, see Import a subscription.

proxies / serverNode: A node contains the parameters needed to connect to a proxy server, usually its address, port, protocol, and authentication details. The region in a node’s name is a provider label and does not prove the location of the entry server or actual egress. If one node fails, try another in the same configuration to compare results. Then determine whether the server is unreachable, the credentials have expired, or local traffic capture is misconfigured.

config.yaml / indentationYAML Configuration: YAML is a text format for representing configuration hierarchies. Indentation separates parent and child fields, and list items usually begin with a hyphen. Use spaces, not tabs, and align fields at the same level. A field can still appear in the file but behave unexpectedly if its indentation puts it under the wrong parent. Save a copy of the original configuration, change one thing at a time, validate it in the client, and then check the result at runtime.

Proxy Protocols

The protocol an application uses to connect to a local proxy endpoint is different from the one the core uses to connect to a remote node. Before entering settings, confirm which part of the connection they apply to.

HTTP / CONNECTHTTP Proxy: An HTTP proxy lets an application send requests to a proxy endpoint. When accessing an HTTPS site, the application typically uses the CONNECT method to establish a tunnel. An HTTPS destination does not mean the local proxy endpoint also uses TLS. When entering an address in a browser or command-line tool, use the port the client is actually listening on. mixed-port accepts both HTTP and SOCKS connections on the same endpoint.

SOCKS5 / UDP ASSOCIATESOCKS5: SOCKS5 is a proxy protocol that applications can specify explicitly. It supports TCP and defines a mechanism for forwarding UDP, but actual UDP support depends on the application and the entire connection path. Some tools let you choose between resolving domains locally and resolving them through the proxy, which changes the DNS path. If an application has its own SOCKS5 setting, include it in your troubleshooting rather than checking only the system proxy.

ss / cipherShadowsocks: Shadowsocks is an encrypted proxy protocol used between the core and a remote proxy server. It is commonly marked as type: ss in the configuration. The address, port, encryption method, and password must match the server; some nodes also require plugin parameters. A successful import only means the configuration was recognized—it does not guarantee authentication or connectivity. Older cores may not support newer encryption methods.

trojan / TLS / SNITrojan: Trojan typically carries proxy traffic over a TLS connection. Along with the password, check the server name and certificate validation. If the connection address does not match the domain on the certificate, verify the SNI and other parameters provided with the subscription rather than disabling validation. An incorrect system clock, expired certificate, or wrong server name can all cause a handshake failure; this is separate from whether the node responds to basic network probes.

hysteria2 / QUICHysteria 2: Hysteria 2 is a QUIC-based proxy protocol that requires the network to allow the relevant UDP traffic. It can work well on some lossy links, but its name alone does not guarantee higher speeds. If TCP-based nodes work on the same network while Hysteria 2 repeatedly times out, check for UDP restrictions, the server port, and firewall rules. Set bandwidth parameters according to the server’s requirements.

Operating Modes

Traffic capture determines whether requests reach the core; the operating mode determines what happens after they arrive. Distinguish these two layers before changing settings.

mode: ruleRule Mode: Rule mode uses the configured match conditions to decide whether connections handled by the core go direct, through a proxy, or get rejected. It’s the usual starting point for everyday use. Check the connection list to see which rule matched the destination. Rule mode does not automatically send traffic from every application to the core. If the request does not appear in the connection list, check how traffic is being captured first. For mode comparisons, see Choose a mode.

mode: global / GLOBALGlobal Mode: Global mode sends connections handled by the core through the global policy, making it useful for briefly checking whether rules are causing a difference in access. “Global” does not mean the entire device is captured: applications that ignore the system proxy may still bypass the core. Switch back to rule mode after testing, and check which node the global policy currently selects. Otherwise, using a different node in the global group and your usual policy group can lead to misleading results.

system proxy / mixed-portSystem Proxy: System proxy settings register a proxy address and port with the operating system. Applications that honor those settings send requests to the local client. Some games, command-line tools, and applications with their own networking stack ignore them, so an enabled system proxy does not mean all traffic is captured. If websites remain inaccessible after closing the client, check whether the operating system still points to a proxy port that is no longer active.

tun / auto-routeTUN Mode: TUN uses a virtual network interface to receive IP packets and routing settings to pass traffic to the core. It can capture traffic from some applications that ignore the system proxy. Desktop systems often require administrator privileges, a service, or a driver; phones typically require VPN permission. If TUN fails to start, check permissions and conflicts with other VPNs first. TUN only provides a way to capture traffic—it does not ensure that DNS or routing rules are configured correctly.

url-test / timeoutLatency Test: A client’s latency test usually measures how long a request through a node takes to reach a specified address. Whether the result includes connection handshakes depends on the implementation. It is not a download speed test, and results from different test URLs, timeouts, and network conditions are not directly comparable. A timeout does not necessarily mean every website is inaccessible; check actual access and logs. For step-by-step help, see Troubleshoot node latency.

DNS and Resolution

DNS queries and application connections may take different routes. When reviewing the configuration, check who resolves the domain, which resolver they use, and how the query connection is handled.

dns / nameserverDNS Resolution: DNS resolves domain names to IP addresses and other records so applications can find their destinations. The operating system, browser, application, and proxy core may each cache results or send their own queries, so changing the core’s DNS settings may not immediately affect existing connections. If a domain fails but direct access to an address works, check DNS logs and caches. Keep in mind that direct IP access can also fail because of certificate or virtual host settings.

enhanced-mode: fake-ipFake-IP Virtual Address: Fake-IP returns a virtual address to the application and stores a mapping between that address and the domain in the core, so subsequent connections can still match domain rules. Seeing a virtual address does not mean DNS returned the real server address or that the configuration is broken. If a local network service or application is incompatible, check fake-ip-filter for the relevant domain instead of disabling the entire DNS module.

DNS leak / resolver pathDNS Leak: A DNS leak occurs when a DNS query bypasses its expected route and reaches a different resolver. The key question is whether that behavior matches the intended policy. A test page’s reported resolver location is only a clue; on its own, it does not prove that an ISP saw a query. Cross-check browser encrypted DNS, system settings, TUN capture, and connection logs. Local DNS for domains intentionally set to go direct is not automatically a problem.

DoH / DoTEncrypted DNS: DoH sends DNS queries over HTTPS, while DoT uses TLS. Both protect queries in transit, but neither automatically routes them through a proxy node. The resolver still processes the domain names it receives, and the connection path must be checked separately. If an upstream DNS server is specified by domain name, also consider how that address is resolved initially to avoid a circular dependency.

nameserver-policyPer-Domain DNS Selection: nameserver-policy assigns upstream DNS servers to domains or supported match conditions—for example, sending internal domains to an organization’s resolver. It changes the resolver selection, not the final route for application traffic, so check the connection path separately using rule-based routing. This field belongs under dns. Verify that the current core supports any advanced matching syntax instead of copying examples from another version.

Rules and Routing

Rules match connections, proxy groups select policies, and providers load resources. Fields with similar names in a configuration often serve different purposes.

rules / DIRECT / REJECT / MATCHRule-Based Routing: Rule-based routing directs connections according to conditions such as domain names or IP addresses. The standard rules list is checked from top to bottom, and the first match determines where a connection goes. DIRECT means a direct connection, while REJECT blocks it. A final MATCH rule commonly catches anything that did not match earlier rules. Put exception rules before broader rules that could match first, then confirm the result in the connection log.

proxy-groups / select / url-testProxy Group: A proxy group combines nodes or other policies into a target that rules can reference. Common types include manual selection, latency-based selection, and failover. Changing a group does not mean all connections will use the new node: rules may point to a different group, and existing connections may keep using their previous route. To test a change, check which group matched and which member it currently selects; reconnect to the destination if needed.

GEOIP / geodataGeoIP Address Lookup: GeoIP uses an IP address database to identify a destination IP’s region or other location information, often for routing by address range. Databases are updated periodically and can be inaccurate, so results do not indicate a device’s location or a company’s home region. If a match is unexpected, check the actual destination IP and the database source and update status. The use of no-resolve can also affect how domain connections are matched.

rule-providers / RULE-SETRule Provider: rule-providers loads local or remote rule sets, keeping large domain and address lists separate from the main configuration. Declaring a provider does not automatically apply its rules: reference it in the rules list with RULE-SET or a similar rule, and specify the policy to use. If an update fails, check the resource URL, content format, and behavior type. A successful download does not mean the rules are active.

proxy-providers / useProxy Provider: proxy-providers loads and updates a set of nodes separately, typically referenced by a proxy group with use. It is not a full client configuration subscription and cannot replace mode, DNS, or rule settings. Its resource must also meet the core’s requirements. If the group is still empty after an update, check the provider name, filters, and loading logs. For common fixes, see Troubleshoot subscription update failures.