Clash Client · Setup Guide
Choose a client for your platform, then complete subscription import, rule-based routing, and connection verification.
Check your operating system first, then confirm your processor architecture. The downloads page covers client options, installation methods, and system requirements. These links take you straight to the relevant platform page.
Ideal for desktop browsing and everyday apps. Check your processor type in system information, install a client, import your profile, then enable the system proxy. If an app does not use system proxy settings, follow the TUN guide. Avoid changing several network settings before your first connection.
Go to downloadsChoose the right installer for Apple Silicon or Intel. Check your chip under About This Mac, then grant network permissions when prompted. Before switching clients, turn off the old client's system proxy to prevent background processes from occupying ports or changing network settings.
Go to downloadsFor phones and tablets. Choose an installer for your device architecture, import a subscription, and allow the VPN connection. Most systems let only one app use the VPN at a time, so check for other VPN apps if the connection fails to start. If background connections drop, review battery optimization and background activity permissions.
Go to downloadsFor iPhone and iPad. The downloads page links to Clash Plus on the App Store; the official site is clashplus.io. After installation, import a profile, grant VPN permission, then start the connection in the client. Check that your subscription format is supported by the client.
Go to downloadsDesktop users can choose a graphical client and install it using their distribution's package manager. Server and router users can find core downloads on the downloads page, but must manage configuration, service permissions, and routing themselves. A successful launch does not mean traffic is being routed; check the proxy entry point and matching rules.
Go to downloadsFrom traffic routing to network interception, each of these five features serves a different purpose. Understand what each layer does before enabling it. The examples below illustrate mihomo configuration; client menus and available options may differ. These snippets are not complete configurations and should not be imported as-is.
Rule mode checks connections against the configured rules in order, then applies the policy for the first match. Put specific domain rules before broader ones, and use MATCH to handle anything left over. Policy groups define the available outbound options; rules decide which connections use them. In contrast to Global mode, which sends everything through one outbound, Rule mode preserves direct connections and routes proxy traffic by purpose. After making changes, check the connection log for matched rules before adjusting their order.
mode: rule
rules:
- DOMAIN-SUFFIX,example.com,DIRECT
- IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
- MATCH,DIRECTRules are checked from top to bottom; put MATCH last.
Profile management stores subscriptions from different sources and local YAML files. After importing a profile, give it a recognizable name and check which one is active. A successful download does not mean the core has switched to it. Updating a remote subscription refreshes its contents; local files are useful for configurations you want to manage yourself. Use client-supported overrides to keep personal settings separate from the subscription source. Switching profiles typically replaces the entire configuration—it does not merge policy groups or rules automatically.
Keep local overrides before updating, then confirm the active profile after switching.
TUN routes connections into the core through a virtual network interface and routing rules, making it useful for apps that ignore system proxy settings. It is not the same as a browser proxy setting, and enabling it does not mean every connection will use a proxy: traffic entering the core is still routed according to the selected mode and rules. First-time setup usually requires a service component or system permissions. Verify that a regular proxy works before enabling TUN, then check local network access and DNS resolution. If another VPN conflicts, disable one before changing routing settings again.
tun:
enable: true
stack: mixed
auto-route: true
auto-detect-interface: trueAutomatic routing requires platform support and the right permissions.
DNS resolves domain names; Fake-IP maps domains to synthetic addresses so the core can associate them with subsequent connections and apply domain rules. Fake-IP is not a public DNS address and cannot fix an invalid subscription on its own. Unlike direct resolution to real addresses, Fake-IP relies on the core to maintain mappings; some local network services may need to be excluded. Before changing settings, confirm that DNS requests reach the core and that the upstream resolver is reachable. Troubleshoot one setting at a time instead of changing the mode, upstream, and traffic interception together.
dns:
enable: true
enhanced-mode: fake-ip
fake-ip-range: 198.18.0.1/16
fake-ip-filter:
- "*.lan"
nameserver:
- 1.1.1.1The core handles address mappings; choose an upstream DNS server for your network.
An external controller lets compatible dashboards read core status, view connections, and switch policies. Its port is different from the listener port that provides proxy services; using the wrong port will prevent the dashboard from connecting. Graphical clients usually include these management features, while server users are more likely to deploy a separate dashboard. A dashboard is useful for monitoring and temporary changes, but whether settings persist depends on the implementation. Bind the controller to localhost by default and set an access secret. Never expose it directly to the public internet.
external-controller: 127.0.0.1:9090
secret: "your-password"Bind to localhost only; replace the example password locally.
Start with the client's defaults to establish a stable baseline, then add features one at a time. For advanced parameters, policy group types, and rule set management, see Advanced Configuration. If a field is unfamiliar, check its purpose in the Glossary.
For your first setup, follow the shortest path to verify that the configuration loads, connections reach the client, and requests are handled as expected. These three steps cover the essentials—you don't need to learn every parameter first. Button locations vary by client, but the relationship between profiles, modes, and network entry points is the same.
Open profile management, paste the subscription URL into the link field, and click Import. When the profile appears, select it as the active one. To use a local file, import it from disk and make sure it contains YAML supported by the client—not a web page or an error message.
Next, check for parsing errors. Seeing a profile name in the list does not confirm that the core loaded it. If importing fails, check that the URL is complete, the subscription is valid, and the system clock is accurate. Leave DNS and TUN settings alone for now to avoid obscuring the cause.
For everyday use, start in Rule mode, then select a policy group and outbound on the proxy page. On desktop, enable the system proxy; on mobile, grant VPN permission when prompted. If you need TUN, enable it only after the basic connection works, and install any required service or grant permissions as instructed by the client.
Global mode can help distinguish a rule issue from a connection issue during troubleshooting; Direct mode sends requests without applying proxy policies. Switching modes is not a substitute for checking your configuration. If an app has its own proxy settings or another VPN is running, first work out which network entry point is handling the request.
Open a page you want to access, then check the connection log in the client. Confirm that the request appears, the matched rule is expected, and the selected policy and outbound are correct. Also test a site that should connect directly or a local network service, so you don't overlook normal network access by checking just one website.
If a page won't load, first distinguish between no connection entry and an entry showing a failed connection. The former usually points to system proxy settings, VPN permissions, or app settings; the latter calls for checking the outbound, subscription, and DNS resolution. Save the error message and test changes one at a time to narrow down the cause.
The Clash ecosystem includes cores, graphical clients, configuration tools, and dashboards. Similar names do not mean they belong to the same project. The original Clash project and later community implementations are distinct; mihomo continues the Clash Meta technical lineage and is the open-source core used by many current clients. Screenshots, menus, and fields in older guides may come from clients that are no longer maintained. Follow the documentation for the project you're actually using.
Archived clients are labeled separately on the downloads page to help users identify options for older environments. Prefer actively maintained implementations compatible with your current system rather than choosing based on a familiar name. The homepage does not list specific release numbers; client releases are covered on the downloads page to keep core releases distinct from graphical client releases.
The core parses configuration, establishes connections, matches rules, and handles DNS and network interception. The graphical client provides controls for managing subscriptions, switching modes, setting the system proxy, and viewing logs. As a result, the same core feature may have different names in different clients or be managed by a service component. Before using a configuration field, check both that the core supports it and that the client allows direct editing or overrides.
Updating a client is not the same as updating its core. A new interface version may not change network behavior; replacing the core may affect configuration compatibility. When troubleshooting, record the client name, system environment, active mode, and error message—this is more useful than saying only that the software is updated. To reproduce an issue, use a minimal configuration and remove unrelated rules and overrides first.
The public mihomo repository includes source code, licensing, issue discussions, and release notes. It is licensed under GPL-3.0. Open source makes the implementation available for inspection, and public records help assess maintenance status—rather than relying on claims on a download page. Check the core documentation and release notes for protocol support, field behavior, and known issues. For features in a specific client interface, consult that client's documentation.
Before filing an issue with the community, search for similar reports and prepare clear reproduction steps. Logs may contain sensitive information, including subscription URLs, access secrets, outbound addresses, and browsing history. Don't publish them unredacted. Share a sanitized error excerpt, relevant configuration fields, and what you observed to make discussion more useful. This site provides navigation and setup guidance; each project's repository is the authority on its maintenance and license.
Software updates change the client or core; subscription updates refresh connection details, policies, and rules. Handle them separately. Before updating a subscription, make sure personal changes are saved as local overrides. Before updating software, back up your current configuration and essential settings, and review changes that affect network behavior. Don't use the remote subscription source to store personal settings permanently—an update may overwrite your edits.
If something breaks after an upgrade, check whether the core loaded successfully, overrides are still applied, and the system proxy or TUN is enabled again. If your network is working, there is no need to change settings repeatedly just to chase a version number. Update when you need a feature or want to address a known issue, following the release notes. Keep a recoverable baseline before each change so you can tell whether a difference came from the software, configuration, or network.
Once the basic connection works, troubleshoot further based on the specific symptoms. These articles cover certificate verification, startup logs, and connection paths. Each explains which layer is involved before giving you an order of checks. Keep your current configuration and test one change at a time.
Learn common causes of certificate errors, how to tell proxy-related issues from system clock problems or network interception, and what to try in each case.
Read article →Track down startup crashes by checking for configuration syntax errors, missing core files, insufficient permissions, and leftover processes. Find log locations and configuration reset steps for each platform.
Read article →Troubleshoot node timeouts step by step: check subscription validity, system time, port conflicts, DNS resolution, and matched rules. Each step explains what to look for and how to respond.
Read article →