Configuration Reference / macOS

Clash Glossary

System proxy settings determine which apps send connections to the core; rule routing determines where those connections go. Browse settings, configuration fields, and log terms by category.

Cores and Protocols

Understand the difference between the interface, the core, and remote connections.

mihomo

mihomo is a proxy core that continues the Clash.Meta project. It loads configuration, listens for local connections, matches rules, and establishes outbound connections. Clients such as Clash Verge Rev provide the interface; the core handles the network traffic. When troubleshooting configuration compatibility, distinguish the client version from the core version: an option may appear in the interface, but its behavior depends on how the core implements it.

Proxy Protocol

A proxy protocol defines how a connection is established, authenticated, and used to transfer data. Examples include Shadowsocks and Trojan. A node's protocol and parameters must match the server; a server address and port alone are not enough to connect. The HTTP or SOCKS5 inbound protocol an app uses to connect to a local proxy is a separate setting from the protocol the core uses to connect to a remote node.

Proxy Node

A node is a proxy outbound entry in the configuration, typically containing a name, protocol, server address, port, and connection parameters. Proxy groups can include multiple nodes as well as other policies, such as direct connections. Two nodes labeled with the same region may use different protocols or routes. After switching nodes, retest with the app that originally had the problem.

Latency

The latency shown for a node is usually measured by connecting through it to a test endpoint, in milliseconds. The result can vary with the endpoint, test time, and connection conditions. Low latency does not mean high bandwidth. If downloads are slow, check the actual transfer speed rather than relying on a single latency test.

Proxy Modes

First check how a connection reaches the core, then how the core handles it.

System Proxy

When system proxy is enabled, the Clash client writes the local proxy address and port to macOS network proxy settings. Only apps that read and follow those settings send applicable requests to the core; apps that establish connections themselves may be unaffected. If a browser works but the terminal does not, check whether the command-line tool reads system settings before configuring a separate proxy for it.

TUN Mode

TUN mode uses a virtual network interface and system routes to send matching traffic to the proxy core, without requiring apps to read system proxy settings. It may require system authorization, and the traffic it captures depends on route configuration and exclusions. If another VPN or virtual network interface tool is running, try disabling them one at a time to check for connection issues before assuming the node is at fault.

Outbound Mode

Outbound mode only determines how the core handles connections it has already received. Rule mode checks rules in configuration order; global mode typically uses the policy selected in the global group; direct mode connects captured traffic straight to its destination. Switching to global mode does not automatically capture apps outside the proxy, and switching to direct mode does not disable TUN or clear system proxy settings.

Mixed Port

The mixed port is the core's local listening port, set by the mihomo configuration field mixed-port. It accepts both HTTP proxy and SOCKS5 requests. Apps still need the proxy type they support; entering only the port is not enough. The port number depends on the client's current settings, so check which port is actually listening on your Mac before copying a value from a guide.

Rules and Routing

Use the matched rule in the logs to understand where a connection goes.

Rule Routing

In rule mode, the core checks connection attributes such as the domain and destination IP in configuration order, usually applying the first matching rule. A rule can send a connection to a proxy group, connect directly, or reject it. If a new rule has no effect, check the connection log to see which rule matched, then determine whether the new rule needs to go before a broader rule.

DOMAIN-SUFFIX

This rule type matches by domain suffix. DOMAIN-SUFFIX,example.com,DIRECT matches example.com and its subdomains, such as www.example.com, when the domain is available. It does not match notexample.com. To match only one exact domain, use DOMAIN.

GeoIP

GeoIP rules match connections using the destination IP's classification in geolocation data, not the website's language, domain suffix, or the Mac's location. If the destination starts as a domain and the core does not yet know its IP address, checking an IP-based rule may trigger a DNS lookup. A website served by CDN nodes in different regions may match differently as its destination IP changes.

MATCH

MATCH is an unconditional rule, usually placed at the end of the rule list to handle connections that didn’t match any earlier rule. For example, MATCH,DIRECT sends all remaining connections directly. If you place it before a specific domain rule, connections will match MATCH first, so the domain rule will never take effect.

Subscriptions and Configuration Files

Distinguish the configuration source, file format, and policies that rules can reference.

Subscription

A subscription lets a client fetch and update a configuration or node list from a remote URL. A link opening in a browser does not guarantee it can be imported: the response might be a sign-in page or use a format the client does not support. If an update fails, check that the URL is still valid and that its response is compatible with the client. Do not share the full subscription URL when reporting an error.

YAML

YAML is a text data format commonly used in the Clash ecosystem to define ports, proxy groups, and rule lists. Indentation indicates hierarchy, so use consistent spaces rather than tabs; list items usually start with a hyphen. A file can parse as valid YAML while still containing fields the core does not support. If you get an error, check the field names and values as well.

Proxy Group

Proxy groups are defined by proxy-groups in the configuration. They let rules reference a stable policy name instead of a specific node. A select group lets you choose a member manually; a URL-test group selects one based on its testing behavior. Before changing a policy, check which group the connection matched. Switching nodes in a different group will not change the policy used by that connection.

Rule Set

A rule set keeps a collection of domains, addresses, or other matching conditions in a separate source for easier updates. In mihomo, define its source with rule-providers, then reference it in the rule list with RULE-SET. The rule that references the set specifies the outbound policy. Updating the rule set does not change that rule's priority in the list.

macOS Networking

Check whether a setting applies to the Mac, the current network service, or a specific app.

Loopback Address

127.0.0.1 is the commonly used IPv4 loopback address, which points to the device making the connection. When entered in macOS proxy settings, it connects an app to a port listening on the Mac, not to a remote node server. Entering the same address in a phone's proxy settings points to the phone itself. If the core is not listening on the specified port on the Mac, connections from the Mac will fail too.

Network Service

macOS uses network services to manage connections such as Wi-Fi and Ethernet. Each service can have its own proxy and DNS settings. To check the system proxy, open the active service under System Settings → Network, then review its proxy settings. After switching to Ethernet or a dock, do not assume the system proxy is still active based only on your previous Wi-Fi settings.

Proxy Bypass List

The bypass list in network settings tells apps that follow those settings which hosts or domains to access without the system proxy, such as the local host localhost. Bypassing happens before an app sends a request to the local proxy; it is separate from the core applying DIRECT after receiving a connection. With TUN enabled, do not treat the bypass list as a route exclusion list.

Proxy Environment Variables

Some command-line tools read https_proxy, all_proxy, or no_proxy to decide whether to use a proxy; check the tool's documentation for supported variables. Variables exported in a terminal session are passed to child processes launched from that session and do not automatically change system settings. If the terminal and browser behave differently, check each one's proxy source separately.

DNS and Name Resolution

Check who handles the DNS lookup separately from which route the connection takes.

DNS Resolution

DNS resolution looks up records such as the address associated with a domain. A successful lookup only means that records were returned; it does not prove the app can connect to that address or show which proxy rule the connection will use. When troubleshooting, distinguish between no address being returned and an address being returned but the connection failing. The first points to the DNS path; the second calls for checking connection logs, the matched policy, and node status.

Fake-IP

The core can return a synthetic address in a DNS response and store its mapping to the original domain. When the subsequent connection reaches the core, it can recover the domain for rule matching, so seeing a synthetic address does not necessarily indicate a DNS problem. If a local network service requires the real address, first check whether it conflicts with this mode, then consider adding the domain to fake-ip-filter.

DNS Leak

A DNS leak can occur when a query is sent to a resolver other than the one intended for the expected DNS path. Routing web traffic through a proxy does not mean DNS queries follow the same route. Check the client's DNS settings, the resolver currently used by the system, and whether the browser has its own Secure DNS enabled. Compare test results with the DNS policy you expect.

DNS Routing

DNS routing selects an upstream resolver based on the domain or other conditions—for example, sending internal service domains to an organization resolver that can resolve them. In mihomo, use nameserver-policy to assign resolvers to matching domains. This controls who looks up the address, not which outbound route the connection uses. Check the criteria for these two stages separately.