Glossary · macOS Config Guide

Clash Glossary

Look up terms by where they come up in your setup, from protocol names to system settings. Each entry explains what a term means, what it does, and where its limits are. Once you understand the terminology, adjust the corresponding client settings.

For a first-time setup, start with the Quick Start. To compare protocols and cores, see the Protocol Guide. Every entry has its own anchor, so you can share a direct link.

Which protocol does the connection use?

Proxy protocols

A protocol defines how a client and server exchange data. It is not the same as a proxy name or outbound mode; changing a protocol label in the client cannot make the server support a different protocol.

ShadowsocksSS: A proxy protocol built around encrypted forwarding, commonly configured with a server address, port, password, and encryption method. Client and server settings must be compatible. Legacy methods and Shadowsocks 2022 have different key requirements, so changing the encryption method name alone is not enough to migrate. If an imported config reports an unsupported method, check the core’s capabilities rather than repeatedly toggling the system proxy.

VMessVMess protocol: A proxy protocol in the V2Ray ecosystem, typically using a UUID to identify the user and supporting different transport methods. A valid UUID alone does not guarantee a connection: TLS, server name, and path settings must also match the server. A significantly incorrect system clock can affect authentication. On a Mac, start by checking the date and time in System Settings.

TrojanTLS-based proxy protocol: A proxy protocol that typically uses TLS to protect connections, often configured with a password, server address, and server name. The certificate name, validity period, and trust chain all affect the handshake. Check each one if you see a certificate error rather than disabling verification. Trojan does not require installing an extra root certificate in macOS; verify the purpose if asked to do so.

VLESSVLESS protocol: A lightweight proxy protocol in the V2Ray and Xray ecosystems that does not encrypt payloads by itself. Connection security depends on mechanisms such as TLS or REALITY and correct configuration. Support for a particular VLESS combination depends on the core version and transport parameters. Successfully importing a subscription only means the file was accepted; it does not guarantee that every connection configuration in it will work.

Hysteria2Hy2 · QUIC: A QUIC-based proxy protocol that typically uses UDP and is designed with performance on unstable networks in mind. In practice, results still depend on network quality, UDP availability, and bandwidth settings; a newer-sounding protocol name does not guarantee higher speed. If it stops connecting on a particular network, check whether that network allows the required UDP traffic.

TUICQUIC-based proxy protocol: A QUIC-based proxy protocol that can carry TCP and UDP traffic and reuse connections to reduce some connection setup overhead. Protocol versions and implementations have compatibility limits, so client settings must match the server. Consider network restrictions on UDP as well as core support; toggling the system proxy cannot fix blocked UDP traffic.

The interface and the underlying engine

Cores and clients

The menu bar app provides the controls; the proxy core handles connections. To determine whether a feature is available, check the app version, bundled core, and macOS permissions—not just the client name.

Original ClashOriginal Clash core: An early rule-based proxy core in the Clash ecosystem that established config structures reused by many later projects. The original project is no longer maintained. Later cores may read basic nodes, proxy groups, and rules from older configs, but that does not mean newer protocols and fields are backward-compatible. When following an older guide, cross-check its steps against the current client documentation.

Clash MetaFormer name of mihomo: An earlier project name for mihomo, so Meta still appears in older guides, config comments, and some app names. It is not a generic name for every GUI client, nor does it tell you how current a bundled core is. If a field is unrecognized or a protocol is unsupported, check the actual core information shown by the client.

mihomoRule-based proxy core: A rule-based proxy core developed from Clash Meta. It handles protocol connections, DNS, rule matching, and outbound routing. It is not a complete macOS menu bar app; a GUI client typically launches and manages it. Whether a new config works depends on the specific core version—do not assume every client supports every mihomo feature.

GUI clientGUI client: An app that provides a menu bar, subscription management, proxy group selection, and settings, usually calling a separate proxy core in the background. Writing system proxy settings, launching at login, and authorizing helper services involve the client and macOS, not just the core. The steps for using the same config can differ between apps, and updating the app does not always update the core.

How connections are routed after reaching the core

Rules and proxy groups

Rules determine how a connection is handled; proxy groups organize the available routes. To troubleshoot routing, first check which rule matched, then see which option the referenced group selected.

Rule-based routingRule-based routing: Choose an outbound action—such as direct, proxy, or reject—based on criteria like domain, destination IP, or process. Rules are generally evaluated in order, with earlier matches taking precedence; the final MATCH rule catches connections not covered above. Changing rule order changes the outcome, so after adding a rule, check the connection log rather than just confirming the file saved.

Proxy groupProxy group: A config unit that groups proxies or other groups for use by rules. Common types include manual selection, automatic testing, and fallback. Automatic testing checks responses from a test target; fallback tries available routes in a configured order. They are not the same strategy. Switching a group affects only connections that reference it; rules using other groups remain unchanged.

Outbound modeRule / Global / Direct: Common options are Rule, Global, and Direct. They determine how traffic that has reached the core is routed. Rule mode follows the config, Global mode typically uses the global proxy group, and Direct bypasses remote proxies. Global mode is not TUN and cannot capture app traffic that never reached the core.

GeoIPIP geolocation data: Data that maps IP addresses to geographic regions, often used by rules to select an outbound route based on the destination IP. It is not a directory of domains; stale data, shared addresses, and CDN routing can all produce unexpected results. Whether a domain connection is resolved to an IP first also depends on rule settings, so do not infer the match from a website name alone.

GeositeDomain classification data: Domain data organized by region, service, or purpose, which rules can reference by collection name. It matches domain collections, unlike GeoIP, which uses the destination IP’s region. A website may also rely on multiple resource domains. Collection names and coverage depend on the data source; a category name does not guarantee that every related service is included.

macOS traffic capture and DNS routing

Networking and system settings

These settings determine how apps hand traffic to the client and which resolver handles domain lookups. Confirm the traffic path first, then check the outbound route to avoid confusion from changing several settings at once.

System proxySystem proxy: Proxy settings saved by macOS for a network service. Apps that follow system settings send requests to the specified address and port. Browsers generally use this route, but some command-line tools, games, and apps with their own network stack may ignore it. If the system proxy is not restored when you quit the client, apps may keep trying to reach a local port that is no longer listening.

TUN modeVirtual network interface: Routes matching IP traffic into the proxy core through a virtual network interface, often used to capture apps that ignore the system proxy. On macOS, this usually requires authorization or a helper service. Routes, exclusions, and DNS settings together determine what is covered. If TUN conflicts with another VPN, check routes and interface status first rather than just switching proxies.

Fake-IPSynthetic DNS mapping: A DNS handling method that returns a virtual address for a queried domain; the core then uses its mapping to recover the domain and handle the connection. This helps preserve domain information for routing, but the address is not the website’s real server address. Some local network services and apps that rely on real DNS results may need to be added to the Fake-IP filter list.

DNS leakDNS leak: A DNS query handled by a resolver other than the one intended by the configured resolution path. The key question is whether the actual path matches the intended setup. Browser Secure DNS, the system resolver, client DNS settings, and TUN routes can all affect the result. A resolver name shown by a test page is not conclusive on its own; compare it with your config and client logs.

Mixed portmixed-port: A listener that accepts both HTTP proxy and SOCKS requests on the same port, allowing different apps to share a local proxy. 7890 is a common example; use the value in the client config. If you change it, update apps where the proxy was entered manually. Access from other devices also depends on the listening address, firewall, and local network settings.

LatencyLatency / URL test: The time a client takes to test connectivity to a specified target. The test URL, connection setup, and network conditions all affect the result. Low latency does not mean high download speeds or guarantee that every website will work; throughput and routing to a particular destination are different measures. A timeout may involve the proxy, DNS, or test target, so check real-world access and logs.

Where config comes from and how it is stored

Subscriptions & Config

A subscription distributes config, YAML is a common file format, and a proxy entry is an outbound item in that config. These are different layers: verify file import and connection setup separately.

SubscriptionSubscription: A way to distribute proxy entries or a full config through a link. It is neither a proxy protocol nor a connection resource automatically included with a client app. Links may return Clash YAML, an encoded proxy list, or another format; direct import depends on client support. Subscription URLs may contain access credentials, so do not post the full link publicly when troubleshooting.

Proxy entryProxy entry: A config entry with the parameters needed for an outbound proxy connection, usually including a server address, port, protocol, and authentication details. The displayed name is only a label; it does not confirm the location, network quality, or protocol. Rules must still route traffic through the selected entry—a proxy appearing in the list does not mean current connections are using it.

YAMLConfiguration data format: A text data format commonly used for Clash configs, representing hierarchy with indentation, key-value pairs, and lists. Use spaces, not tabs, for indentation. Successful parsing only confirms that the syntax is readable; field names, referenced items, and core support must also be checked. Keep a copy before editing by hand, then review the load log to avoid mistaking a syntax error for a network problem.

Automatic subscription updatesScheduled profile refresh: The client periodically fetches subscription content to update proxies, rules, or other config; what gets replaced depends on the subscription. This does not update the app or core, and updates may not run on schedule while the Mac is asleep or offline. Direct edits to a subscription file may be overwritten; for lasting changes, use the client’s override, merge, or local config features.