Clash ecosystem · Clients and configuration guides
Choose a client for your device, manage connections with rule-based routing, and set up subscriptions with our English-language guides.
Features and configuration
Browsers, developer tools, and local services may need different outbound routes. Rule mode reads rules from the configuration and checks them from top to bottom. The first match determines the policy. Select rule mode on the client's Proxy page, then check the match order on the Rules page. Unlike global mode, rule mode can keep LAN traffic and specified sites on a direct connection, but the result depends on the rules themselves. The Proxy target below must match an existing proxy group, and the fallback MATCH rule should come last so earlier, more specific conditions can take effect.
Clash Client Download Hubmode: rule
rules:
- DOMAIN-SUFFIX,github.com,Proxy
- GEOIP,CN,DIRECT
- MATCH,ProxyA subscription downloads a remote configuration to your device, so you don't have to enter proxy settings one by one. On the Configuration page, choose Import from URL and paste the configuration address provided by your service. After importing, you still need to select and enable the configuration. Subscriptions are convenient for ongoing updates compared with editing a YAML file directly, but remote updates may overwrite local changes. To preserve custom rules, use the client's override or merge feature when available. The example below shows only the structure of a remote proxy list. Its sample address won't connect and is not a complete subscription file.
proxy-providers:
remote:
type: http
url: "https://example.com/proxies.yaml"
path: ./providers/remote.yaml
interval: 3600Rule, Global, and Direct control how the core handles requests it receives; they don't determine which apps send traffic to the core. Rule mode is usually best for everyday use. To check whether a rule is matching incorrectly, switch to Global and review the selected global proxy group. Choose Direct when you need a direct connection. Global mode does not route every app's traffic: programs that ignore the system proxy may bypass the client. Switching modes makes it easier to compare results than repeatedly editing rule files, but restore your original settings afterward to avoid disrupting access to local network resources.
# rule / global / direct
mode: ruleSome games, command-line tools, and background services don't use the system proxy. TUN can route more connections through a virtual network interface. In the desktop client's Settings, install the required service and then enable TUN mode; follow the client's prompts for permissions. Compared with the system proxy, TUN operates closer to the network layer and is more likely to conflict with other VPNs, virtual adapters, or corporate routing. Before enabling it for the first time, make sure the regular proxy works, then check your routes and DNS. The snippet below is for mihomo; it may not apply to every mobile app, and you shouldn't replace your entire existing configuration with it.
tun:
enable: true
stack: mixed
auto-route: true
auto-detect-interface: true
dns-hijack:
- any:53If a webpage won't load, first check the Connections page for a request to the destination, then look for errors from the same time on the Logs page. Connection details can show the matched rule and proxy chain; logs can help distinguish DNS resolution, connection establishment, and configuration loading issues. Full context for a failed request is more useful than a speed test alone. Keep the log level at info for everyday use; switch to debug briefly when reproducing an issue, then switch back. Before sharing logs, remove subscription URLs, credentials, and personal browsing records. Hiding only proxy names isn't enough to make a full log safe to share.
# Temporarily set to debug for troubleshooting
log-level: infoDesktop, mobile, and router configurations can use similar rule structures, but client controls, core capabilities, and system permissions differ. Choose a client for your device on the downloads page, then check which configuration features it supports. A successful import doesn't mean every field is supported. Compared with running the core directly, graphical clients bring configuration and controls together for everyday use. When moving between devices, check local file paths, listening ports, and TUN settings. The example below limits the control interface to the local machine and keeps LAN access off by default. Don't carry desktop settings unchanged into a different network environment.
mixed-port: 7890
allow-lan: false
external-controller: 127.0.0.1:9090Choosing a download
Choose your operating system, then check the processor architecture. After installation, import and enable a configuration.
Browse all clients →Clash is the name of an ecosystem of rule-based proxy tools, not a single app with the same interface on every system. Before downloading, check your device's operating system and choose between a graphical client and a core. A client provides configuration and proxy screens plus system controls; a core mainly reads configuration and handles connections. If you're new to Clash, start with a graphical client—there's no need to learn service management or command-line launch options first.
Make sure the processor architecture in the package name matches your device. Packages aren't interchangeable just because they target the same operating system, especially on desktop platforms. Before updating, quit the running client and keep your configuration and essential settings. When moving to another client, it's usually best to import your subscription again rather than copy the entire application data folder.
A good fit if you want browsers and desktop apps to share a proxy. The downloads page lists options such as Clash Plus and Clash Verge Rev. On first launch, make sure a configuration is enabled before turning on the system proxy.
If the app reports that a port is already in use, quit other proxy tools first. Avoid running multiple clients and TUN at the same time from the outset, or it will be difficult to tell which one is routing your traffic.
Go to downloadsCheck About This Mac to see whether your device uses Apple Silicon or Intel, then choose the matching package. The downloads page brings together clients such as Clash Plus, Clash Verge Rev, and FlClash.
After installation, follow system prompts for any required permissions. If a network extension or Keychain dialog appears, first verify the app's source and what you're trying to do. Don't bypass prompts by disabling system protections across the board.
Go to downloadsClash Plus, Clash Meta for Android, FlClash, and Surfboard each have their own interface and supported configuration features. Check your subscription format before choosing a client; don't assume the same link works everywhere.
Allow the system VPN request the first time you connect. If the connection drops when the screen locks, check background activity and battery restrictions. Per-app proxy settings also affect which apps use the proxy tunnel.
Go to downloadsThe downloads page links to Clash Plus on the App Store. Its official website is clashplus.io. After installing, import a configuration and follow the prompts to allow a VPN configuration.
An active connection switch only means the tunnel is up. Visit the destination site to confirm it works. If problems arise after switching Wi-Fi or cellular networks, reconnect and check the logs.
Go to downloadsDesktop users can start with Clash Verge Rev or FlClash; server and router users can consider running mihomo directly. Choose a package format that matches your distribution's package manager.
A graphical system proxy usually affects only apps that follow the desktop proxy settings. Terminal tools may need proxy environment variables set separately, so don't rely on a browser loading a webpage as your only test.
Go to downloadsFor your first setup, do only what's necessary: import a subscription, select the active configuration, choose rule mode, and enable the connection option for your system. Then visit a specific website and check which policy it matches on the Connections page. Verify this path before trying TUN, launch at startup, or LAN sharing. Changing one thing at a time makes it easier to identify the cause of a problem.
A Clash proxy speed test shows connectivity to one test target at a particular moment; it doesn't reflect how every site will perform. If the test succeeds but an app request fails, check the destination domain, matched rule, and full log output. If only one app fails, first check whether it uses the system proxy. For connection issues, start with Troubleshooting instead of repeatedly uninstalling the client.
The system proxy tells apps that support it where to find a proxy. Global mode controls how the core routes requests it receives. TUN changes how more requests enter the core. Each handles a different part of the connection, so they aren't interchangeable. To learn how the modes differ, see choosing a mode. To enter a proxy address in an individual tool, see port settings.
Projects and maintenance
Understand what each project does before deciding whether its docs and configuration apply.
View mihomo source →The Clash ecosystem has evolved through the original project, later core implementations, and a range of graphical clients developed in parallel. Tutorials you find today may show interfaces from different eras, or use the same button labels with different cores underneath. This site separates downloads, getting started, and troubleshooting: the downloads page helps you choose a device and client, the setup guide covers your first configuration, and the troubleshooting guide explains why an existing setup may not behave as expected.
Older screenshots can help explain concepts, but shouldn't be your only reference for current button locations or supported fields. If a configuration errors, first identify the client and core you're running, then check whether they support the field. Don't switch back to discontinued software just to follow an old tutorial. If you need an archived client, make sure you understand its compatibility and maintenance status.
mihomo is one actively developed core project in the Clash ecosystem. It handles rule matching, proxy connections, and related network tasks. Graphical clients build on it to provide subscription management, proxy group selection, log viewing, and system integration. Client and core updates are separate: an interface change doesn't necessarily alter rule syntax, and a new core feature may not appear in the client right away. Check the relevant project's release notes and documentation for current support.
That's why configuration examples should specify their intended environment. A snippet that works with mihomo on desktop may not import directly into every mobile app. Before switching clients, keep your subscription source, override rules, and essential local settings, then migrate them one at a time. Copying configuration sections you understand is easier to troubleshoot than replacing an entire old file in a new environment.
Public source code can help you understand configuration fields, review issue discussions, or contribute to development. The command below clones the mihomo repository; Git must be installed, and your device must be able to access the repository. It won't install a client or automatically create a ready-to-use graphical app. Most users can simply choose a package on the downloads page. Clone the repository only if you plan to read the source or build from the project's documentation.
git clone https://github.com/MetaCubeX/mihomo.gitClients, cores, and subscriptions each have their own update sources. Updating a client mainly changes the application and its integrations; updating a subscription may change proxy lists, proxy groups, or rules. If something that worked yesterday fails today, first review what changed, then check the relevant logs. Keep a recoverable copy of your configuration and note any local overrides so you don't lose your own rules while restoring the connection.
After an update, check that the intended configuration is still selected, rule mode is set as expected, proxy groups still have usable options, and local ports haven't changed. A successful update message only confirms that fetching and parsing completed; it doesn't verify a real request to your destination. For rule database issues, see GeoIP troubleshooting. For connection timeouts, follow the timeout troubleshooting steps.
A proxy group isn't a proxy protocol. It organizes multiple outbound options for selection, latency testing, or failover. The actual proxies in the group each have their own protocol settings. Manually switching the selected option may change the route for new connections, but existing long-lived connections may not reconnect right away. If proxy group names or nesting are unclear, see Clash proxy groups. Don't delete groups that are referenced by rules.
Updating a subscription doesn't necessarily update rules. Some subscriptions provide only a proxy list; others include a full configuration, while some rules come from separate rule sets. What the update button changes depends on the client and configuration structure. If a site still connects directly after you change proxies, check the matched rule instead of repeatedly refreshing the subscription. Find explanations of configuration layers by topic in the glossary.
Launch at startup doesn't mean connect automatically. Starting the app, restoring the previous configuration, and enabling the system proxy may be separate options. System permissions can also affect whether settings are restored. To have a working connection after startup, first verify the entire connection process manually, then enable startup and test after rebooting. If the app opens but doesn't route traffic, check launch-at-startup settings; it doesn't necessarily mean your subscription has expired.
Recent guides
Get a basic connection working first, then read the guide for your specific issue. Configuration structure, subscription format, and system permissions affect different parts of the setup; there's no need to change everything at once.
Follow the order of config.yaml to understand each field and common patterns, so you can read and safely edit your own file.
Read articleFollow every step from copying a subscription URL to applying an update. Compare common subscription formats and learn what to check first if an import fails.
Read articleLearn what causes the “app is damaged” warning on first launch, how to allow a network extension, and how to stop repeated Keychain prompts on macOS.
Read article