CONFIGURATION · TERM INDEX
Find a concept by its configuration key, then check its platform and usage requirements. These 24 common terms are organized into six categories. Card headings link directly to each entry for easy reference alongside logs, subscriptions, and client settings.
New to configuration? Start with the Getting Started guide. For installation, permissions, and platform-specific details, see the all-platform guide. Field descriptions assume a Clash ecosystem core that supports the relevant features; not every client exposes the same options.
PROTOCOLS
First distinguish remote connection settings from the local proxy listener, then check authentication and transport requirements.
proxies
A proxy is a set of server parameters used to establish a connection, usually including an address, port, protocol, and authentication details—not just an IP address. The proxies section can define proxies, which proxy groups can then reference by name. If a connection fails after import, check address resolution, port reachability, authentication, and core protocol support separately. A name appearing in the list does not prove the proxy is usable.
type: ss
Shadowsocks is an encrypted proxy protocol. Common configuration fields include server, port, cipher, and password. The client and server must use compatible encryption methods and matching authentication parameters. Support for encryption methods and extensions varies by core, so check the documentation for the core in use rather than copying only the server address when migrating a configuration.
type: trojan
Trojan carries proxy traffic over TLS. A connection typically requires a server, port, password, and server name for TLS verification. The server address and certificate hostname may differ; do not replace hostname fields with an IP address without checking. For certificate errors, check the system clock, hostname, and certificate chain first. Disabling certificate validation changes the security boundary and is not a routine fix.
mixed-port
These protocols are commonly used by apps connecting to a local proxy listener; they are separate from the protocol used by a remote proxy. mixed-port can provide both HTTP and SOCKS proxy access on one port, but apps still need to follow system settings or have proxy parameters configured individually. If a port is already in use, check which local process is listening. After changing the port, update the settings of apps that use it.
RULES & ROUTING
Rules determine where traffic goes; subscriptions provide configuration content. Check them separately.
rules
Traffic routing selects an outbound based on the domain, destination IP, or other connection attributes. rules are usually evaluated from top to bottom, and the first match determines the policy. DOMAIN-SUFFIX matches a domain suffix; the result also depends on whether the core can identify the domain for the connection. Put custom rules before broader rules that could override them, reload the configuration after saving, and check the matched rule in the connection details.
direct / reject / match
DIRECT and REJECT are built-in policies for direct connections and rejected connections. MATCH is a rule type that matches all remaining traffic; these are not the same kind of field. MATCH,DIRECT sends remaining traffic directly, while MATCH,PROXY requires a policy group or outbound named PROXY in the configuration. Catch-all rules usually go at the end of the list.
geoip
GeoIP maps IP addresses to geographic regions. The common rule GEOIP,CN,DIRECT sends destination IPs classified as China by the database directly. Region classifications can be affected by database updates, IP reassignment, and CDN routing; they do not indicate proxy latency or provider identity. When updating, check the database format and source expected by the client. The running core may still be using old data even after the file has been replaced.
subscription / proxy-providers
A subscription URL fetches updateable proxies or a full configuration; proxy-providers load a set of proxies from within the configuration. A client's subscription update may overwrite the entire configuration, while a provider update usually changes only its proxy set. Put local rules in an override or merge location supported by the client. Subscription URLs may contain access credentials, so redact the full URL when troubleshooting and never post it in public logs or screenshots.
PROXY GROUPS
Rules reference proxy groups, and proxy groups select proxies. The group type determines whether selection is manual, test-based, or ordered.
type: select
select lets users manually choose an outbound from candidate proxies or nested groups, making it useful when an app needs a fixed route. Rules reference the group name, not the proxy currently shown in the interface, so switching candidates usually does not require changing rules. Whether the last choice is remembered depends on the client and configuration. If it changes after a restart, check selection persistence and subscription update behavior first.
type: url-test
url-test checks a specified test URL and automatically selects an outbound based on the results. interval sets how often to test, while tolerance can reduce switching caused by small latency differences. The test result reflects the path to that target at that time; it is not download bandwidth and does not show that every website will work. For a meaningful comparison, use the same test URL and network conditions, and distinguish a test timeout from an app access failure.
type: fallback
fallback selects an available outbound in candidate-list order, making it suitable for using a preferred route and switching to a backup if it fails. Its priority is order, not continuously choosing the lowest-latency candidate. Put the primary route first and make sure the test target reflects the service you need to reach. Switching outbounds does not guarantee existing connections will continue.
type: load-balance
load-balance distributes different connections across candidate outbounds according to the selected strategy; check which algorithms the current core supports. It does not combine multiple proxies into one faster connection, and a single connection is usually carried by one outbound. For logins, payments, or session-based services that rely on a consistent source IP, use a fixed-selection group to avoid triggering extra verification when the outbound changes.
DNS & NETWORK STACK
Separate how traffic enters the core from how domains are resolved; an outbound proxy test alone does not verify the whole network path.
tun
TUN captures traffic through a virtual network interface and routing, including traffic from some apps that ignore system proxy settings. It does not guarantee that every connection will be captured. Desktop clients may require a service component or administrator privileges; Apple mobile clients typically use the system's tunnel capabilities. If problems occur after enabling it, check routing and DNS, as well as conflicts with other VPNs. Avoid stacking capture methods while an existing system proxy issue is still unresolved.
enhanced-mode: fake-ip
Fake-IP returns a synthetic address for a domain and keeps a mapping, allowing the core to associate later connections with the original domain for routing. The synthetic address does not mean the website is hosted there, and should not be used to identify the real server. Local network services and apps that require real DNS results may need exceptions. After changing settings, check system and app caches to avoid using stale mappings.
dns routing
A DNS leak occurs when domain queries bypass the expected path and reach another resolver. Whether that is a problem depends on the intended resolution policy. Browser secure DNS, system resolution, app-specific DNS, and core DNS can all be active at once; a website's outbound IP alone cannot prove that DNS followed the expected path. Troubleshoot with resolver tests and connection logs to confirm where queries go, then adjust the traffic capture scope.
system proxy
System proxy settings register a proxy address and port with the operating system for apps that choose to use them; they do not force all traffic through a proxy. Browsers, command-line tools, and apps with their own network stacks may use different settings, so a working browser does not mean every app is proxied. If the network stops working after quitting the client, check whether the system proxy still points to a local port that is no longer listening, then restore the setting or restart the service as appropriate.
APPLE PLATFORM
Installer architecture, network permissions, and credential access are separate concerns; granting permission does not mean a proxy is connected.
network extension
Network Extension is Apple's framework for extending network functionality. Apps can use it to create tunnels and process traffic. Implementations vary between clients, and not every macOS client requires the same extension approval steps. When the system prompts for permission, verify the app and developer, then follow the instructions for your macOS version. If the client uses a different helper service, follow the permissions it actually requests.
vpn configuration
When an iOS client creates a tunnel for the first time, it usually asks permission to add a VPN configuration. Approval lets it create a system connection entry point; it does not validate the remote proxy or mean all traffic will use it. Routing and rules determine where traffic goes. If the connection cannot be established, check the system VPN status and conflicts with other tunnels, then review the client logs and active configuration.
keychain
Keychain is Apple's facility for storing sensitive data such as passwords and certificates. A client may use it to store or retrieve connection credentials. When an access prompt appears, verify the requesting app and specific item before choosing the appropriate level of access. Keychain access, Network Extension approval, and administrator privileges are separate. Repeated prompts may relate to the app's identity or a saved item; avoid deleting the entire Keychain as a first step.
arm64 / x86_64
macOS installers often distinguish between arm64 for Apple Silicon and x86_64 for Intel. Check the chip or processor in Apple menu > About This Mac before choosing. Some Intel apps can run on Apple Silicon through Rosetta, but that does not guarantee their helper components or networking features are compatible. Prefer a native installer for your architecture and check the minimum macOS version as well.
CORE & CLIENT
Identify the core actually running before checking whether it can parse a field or whether the interface may override configuration.
mihomo
mihomo continues the development of the Clash Meta line and handles low-level features such as protocol connections, rule matching, DNS, and network processing. A graphical client can bundle mihomo, but its name alone does not reveal the core version. Check the client's core information to assess configuration compatibility. If a field is not recognized, first check the running version and the documentation that applies to it, then verify whether the client filters, rewrites, or regenerates the configuration.
graphical client
A graphical client provides interfaces for managing subscriptions, selecting outbounds, viewing logs, and integrating with the system; the core handles the actual connections. They are separate components. Even with the same core, permissions, background operation, and available settings can differ by platform. Compare operating system support, core capabilities, and configuration management separately. For client recommendations, see the client comparisons.
config.yaml
YAML uses indentation to represent mappings and lists, and is a common configuration format in the Clash ecosystem. Keep fields at the same level consistently indented, using spaces rather than tabs. A successful parse only means the structure is readable; it does not mean the current core supports every field or that proxy and policy references are valid. Keep a recoverable copy before editing. After changes, review parse errors and verify the active configuration to avoid losing local edits on subscription refresh.
external-controller
external-controller lets clients or dashboards read status, switch policies, and manage connections. Its listening port is not an HTTP or SOCKS proxy listener. Restrict access to localhost and enable authentication; expose it to other devices only when you understand the access controls. If a dashboard cannot connect, check the listen address, authentication, and core status first. Do not enter a proxy port as the controller address.