CLASH / LINUX / CONFIG REFERENCE

Clash Terminology Guide

Look up terms by deployment stage, from the core and config fields to system services. First distinguish how traffic reaches the core from how it is routed once there, then find the setting to change.

This page covers 24 terms. Each card has its own linkable URL anchor. For complete YAML examples, see the Config Reference; for your first setup, follow the Quick Start.

mihomo Subscription mixed-port Fake-IP TUN systemd

CORE / CLIENT

Core and Client

The client manages the interface; the core handles connections. Subscriptions and nodes are config data, not runtime status.

mihomo Core: mihomo is the proxy core that connects to proxy servers, processes rules, and handles DNS. It builds on the Clash configuration ecosystem and continues to evolve. It can be managed by a GUI client or run as a standalone process on Linux; the core and GUI client have separate version numbers. To check whether a field is supported, look up the version of the core actually running—not just the version shown on the client's About page.; mihomo -v

GUI Client: A GUI client provides interfaces for importing subscriptions, choosing policies, viewing logs, and managing services. It typically runs the proxy core in the background. The settings shown in the client may not match the config actually loaded by the core. When troubleshooting, check the active config, overrides, and core logs. When choosing Clash Verge Rev or FlClash, make sure the package matches your Linux distribution and CPU architecture.; Browse Linux Clients

Subscription: A subscription is usually a remote URL used to fetch proxy nodes or a complete config; it is not a proxy protocol. The response may contain a node list or include policy groups, DNS settings, and rules. Check format compatibility before importing, and treat the URL as sensitive because it may contain access credentials. Subscription updates may overwrite local changes, so keep settings you need in an override mechanism supported by the client.; proxy-providers

Node: A node contains the parameters needed to connect to a proxy server, including the protocol, server address, port, and authentication or transport options. Its display name is just a reference in the config; it doesn't tell you the server's location, exit IP, or availability. After adding a node to the config, a policy group or rule must select it before it can handle connections.; proxies / type / server / port

Latency and Health Checks: The latency shown by a client usually measures the time taken to reach a specified test URL, and the network path measured depends on how the test is implemented. It is not download bandwidth and doesn't reflect how every website will perform. For a fair comparison, use the same test URL; if a test times out, check the logs and try an actual request. Health checks determine whether a node is available; checking too often adds network requests and can wake mobile devices.; health-check / url / interval

PROTOCOL

Proxy Protocols

The local proxy endpoint an app connects to and the protocol the core uses to connect to a remote node are two separate links.

HTTP Proxy: An HTTP proxy is an endpoint that an application connects to explicitly. HTTPS requests usually use CONNECT to establish a tunnel. An HTTP proxy endpoint can still carry traffic to HTTPS websites; configure the correct proxy address and port in your browser or command-line tool. The scheme in a proxy address describes how the app connects to the proxy; don't switch to an HTTPS proxy just because the destination URL uses HTTPS.; http://127.0.0.1:7890

SOCKS5: SOCKS5 is a general-purpose proxy protocol for TCP connections. It can also relay UDP when both the application and server support it. Whether the hostname is resolved locally or by the proxy depends on the application; for example, curl's socks5h scheme sends hostname resolution to the proxy. If only some apps work with a SOCKS endpoint, first check whether the others support SOCKS before changing routing rules.; socks5h://127.0.0.1:7890

Shadowsocks: Shadowsocks is an encrypted proxy protocol. Its config typically includes the server address, port, encryption method, and password. It describes the connection from the core to a remote server, not a local listening endpoint. The encryption method must match the server, and both ends must support any configured plugins. If a connection fails, check the protocol settings and server connectivity separately; don't use the local mixed-port as the remote server port.; type: ss / cipher / password

Trojan: Trojan typically connects to a remote proxy server over TLS. Its config includes the server address, port, password, and certificate-related settings. SNI supplies the server name during the TLS handshake and may differ from the connection address. If certificate validation fails, check the hostname, system clock, and certificate chain first. Disabling certificate verification changes the security boundary and should not be your default long-term fix.; type: trojan / sni / password

CONFIG.YAML

Config Fields

Keep field names unchanged. After changing nesting, ports, or DNS behavior, test the config before reloading the service.

YAML: YAML is the data format used by mihomo config files. Indentation defines the structure, and list items usually start with a hyphen. Keep fields at the same level consistently indented; use spaces, not tabs. Test the config before reloading the service. Quote strings containing special characters to prevent subscription URLs or passwords from being interpreted as YAML syntax.; mihomo -t -d ~/.config/mihomo

mixed-port: mixed-port sets a local mixed proxy port that supports both HTTP and SOCKS, so compatible applications can use the same endpoint. Having the port open doesn't make every app use it automatically; configure the system proxy, app proxy, or relevant environment variables, and check the listening address. 7890 is a common example, not a required value. If the port is already in use, choose another and update the app settings accordingly.; mixed-port: 7890

external-controller: external-controller sets the listening address for the core's control API, which a dashboard can use to view connections, switch policies, or change runtime settings. It is not a proxy endpoint for web traffic. For local access, bind to a loopback address; for remote management, set secret and restrict network access. If you enter the dashboard port as the system proxy port, the core may start while apps still can't connect properly.; external-controller: 127.0.0.1:9090

Fake-IP: Fake-IP mode returns synthetic addresses for DNS queries, allowing the core to associate later connections with their original domain names. These are not real server addresses. Some LAN services or apps may need to be added to fake-ip-filter; after changing it, account for existing DNS cache entries. Seeing a synthetic address doesn't mean DNS resolution failed—the key is whether the core can receive the subsequent connection and map it back correctly.; dns.enhanced-mode / fake-ip-filter

DNS Leak: A DNS leak usually means queries are leaving the intended DNS path—for example, a connection goes through a proxy while DNS queries still reach a resolver on the local network. Check system DNS, browser Secure DNS, app-level resolution, and TUN coverage. Whether a webpage loads is not enough to tell. Different apps may use different DNS paths, so use packet captures or logs to verify the actual destination and route.; dns / nameserver / dns-hijack

proxy-providers: proxy-providers store node sources as reusable collections, which policy groups reference by name with use. For HTTP providers, interval sets the refresh schedule and health-check tests nodes. A provider supplies nodes; it doesn't necessarily include rules or DNS settings. If fetching fails, distinguish a failed download request from a content parsing error: the first points to the network path, the second to the data format.; proxy-providers / use / interval

RULES / POLICY

Rules and Policy Groups

Rules decide where a connection goes; policy groups decide which outbound route to use. They are linked by name.

Rule-Based Routing: Rule-based routing directs connections to a proxy, DIRECT, or REJECT based on domains, destination IPs, ports, and other conditions. Standard rules are checked in order, so the first match takes effect. Before changing a rule, check the matching entry in the connection log, then decide whether to move the rule or change its target policy. MATCH is usually the catch-all at the end; placing it too early prevents later rules from matching.; rules / DOMAIN-SUFFIX / MATCH

Policy Group: A policy group combines nodes, built-in policies, or other groups into a target that rules can reference. select lets you choose manually, url-test selects based on test results, and fallback switches according to availability. Group names must match the references in rules, and groups should not reference each other in a cycle. Automatic selection also depends on the test URL, check interval, and tolerance; it doesn't retest every node for every new connection.; proxy-groups / select / url-test / fallback

GeoIP and GeoSite: GeoIP matches addresses against an IP dataset, while GeoSite matches domains against a site-category dataset. Neither provides real-time geolocation, and neither is guaranteed to cover every CDN or new domain. Check the data source, category names, and core support before use. If traffic is routed incorrectly, first check whether the rule matches the domain or the resolved IP, then decide whether to add a domain rule or update the dataset.; GEOIP / GEOSITE

rule-providers: rule-providers store rules in separate collections that RULE-SET rules can reference. The collection's behavior and format must match its contents; for example, a domain list is structured differently from a complete rule set. The policy used is still determined by the reference. Unlike proxy-providers, rule-providers provide match conditions, not connectable proxy nodes.; rule-providers / RULE-SET / behavior

Rule, Global, and Direct Modes: Rule mode routes traffic according to the config rules. Global mode sends connections that reach the core to the global policy, while Direct mode connects straight to the destination. These modes only affect traffic that reaches the core: switching to Global won't capture apps without a proxy configured, and it isn't the same as enabling TUN. To narrow down a problem, switch modes and check whether it lies in rule selection or the node connection, then restore your usual config.; mode: rule / global / direct

LINUX / RUNTIME

Linux System Components

Permissions, processes, and routes belong to the system layer. Valid config syntax alone doesn't mean the runtime requirements are met.

TUN Mode: TUN receives IP packets through a virtual network device and uses routing and DNS settings to capture app traffic. On Linux, it usually requires network administration privileges. After enabling tun.enable, check the device, routes, and potential conflicts with other VPNs—not just the toggle in the UI. tun.stack selects the network stack implementation; it is separate from routing modes such as rule or global.; tun.enable / tun.stack / tun.auto-route

systemd User Service: A systemd user service runs under the per-user manager and is managed with systemctl --user. Service files are commonly stored in ~/.config/systemd/user/. Its management scope, permissions, and logging context differ from those of a system service. Whether it keeps running after logout depends on the user manager's lifecycle and linger settings. After editing a service file, run daemon-reload before restarting the service.; systemctl --user status mihomo

Linux capabilities: Linux capabilities split certain privileges into individual permissions that can be granted to processes. For example, CAP_NET_ADMIN covers network device and route management. Before granting a capability to a binary, verify its source and whether it needs that permission. Replacing the executable may remove its file capabilities, so check them again afterward. File capabilities, systemd capability restrictions, and the runtime environment all affect the outcome; check service logs to diagnose permission errors.; CAP_NET_ADMIN / getcap / setcap

Proxy Environment Variables: http_proxy, https_proxy, and all_proxy provide proxy addresses to apps that support them; no_proxy lists destinations that should bypass the proxy. Variables are usually inherited from the launch environment and won't affect programs that are already running. Support for uppercase names and protocol formats varies by tool. Desktop browsers, terminal commands, and systemd services may have different environments, so a successful terminal test doesn't prove that every app is using the proxy.; http_proxy / https_proxy / all_proxy / no_proxy