Cross-platform client setup guides for the mihomo core

Clash Setup Guide

Download Clash View Tutorials

Choose a client, then set up subscription import, routing mode, and system proxy settings.

  • Free to use
  • Open-source code
  • Documentation in Chinese
01 / quickstart

Three Steps to Your First Connection

Check the client, configuration, and traffic entry point separately to troubleshoot in a clear order.

View the full tutorial
01

Import a Subscription Link

Open the client's configuration or subscription page, paste the full link provided by your service, save it, and update. A subscription link provides nodes and configuration; it is not a regular web address. Once the configuration appears, set it as the active profile. Saving the link alone does not enable it.

Check that the subscription is valid before changing client settings. Links may contain account credentials, so hide them in screenshots and never paste them into unfamiliar online conversion tools.

Configuration → New → Import → Enable
02

Choose a Routing Mode

Set the operating mode to Rule, then choose an available outbound in a proxy group. A proxy group organizes multiple nodes in the configuration; group names depend on the subscription and may differ from those in tutorial screenshots. Rules decide whether requests use a proxy or connect directly, while the proxy group selects the specific outbound.

Start with the routing settings provided by your subscription and change them only after connecting successfully. Global mode can help with temporary comparisons during troubleshooting; you don't need to rewrite all your rules just to connect for the first time.

mode: rule
03

Enable the Proxy and Test

Enable the system proxy in your desktop client, then visit the target page in a browser and check the connection log for the corresponding domain. The system proxy setting provides applications with a proxy address, but not every program uses it. Check terminal commands and some games separately.

Note where to turn the proxy off after testing. Disable the system proxy before quitting the client to avoid applications sending requests to a local port that is no longer listening.

Application → Local port → Rule → Outbound
02 / downloads

Choose a Clash Client for Your Device

Check your operating system and processor architecture, then choose the matching installer on the download page.

Browse all clients

Choose a client with a graphical interface to import configurations, switch proxy groups, and view logs using its controls. The mihomo core handles the actual network traffic; running it directly means preparing your own configuration file. Most desktop and mobile users should start with a client, while server and router users can consider the core downloads on the download page. Menus vary between clients, but Configuration, Mode, Proxy, and Logs are useful places to look for settings.

Windows

A good choice for everyday desktop use. Check your system information for the system type, then select a client built for your architecture. After installation, check its status in the system tray. If a port is already in use, see whether another proxy app is running.

Go to Downloads

macOS

Check About This Mac to see whether your device has Apple silicon or an Intel processor, then choose the matching installer. If macOS requests authorization on first launch, review each prompt carefully. If connections fail after switching networks, check the proxy settings for the active network service.

Go to Downloads

Android

Install an app that matches your device architecture, and approve the system's VPN permission on first connection. The VPN interface routes traffic from your device. If another app is already using it, stop that app before starting this client.

Go to Downloads

iOS

Open the Clash Plus store listing from the download page. After installation, import a compatible configuration and allow the VPN configuration when prompted by Android. Use the in-app connection switch; check the client documentation for supported features and configuration options.

Go to Downloads

Linux

For a desktop environment, start with Clash Verge Rev or FlClash, then choose a package format for your distribution. Server users can run mihomo directly, but must manage the configuration directory, process permissions, and service startup themselves.

Go to Downloads
03 / configuration

Understand Four Common Settings

Identify what each setting controls before deciding whether to change it.

Read the configuration glossary
mode

Rule, Global, and Direct Modes

Start with Rule mode so requests are routed according to the conditions in your configuration. Global mode sends traffic entering the core to the global proxy group, making it useful for checking whether a routing rule is causing a problem. Direct mode connects requests entering the core straight to their destinations. These modes change how the core handles traffic; they don't mean every app's traffic is going through the client. After switching modes, make a new request and check the connection log. Existing connections may continue using their previous outbound. Switch the explanation below to see an illustration; it won't change your device settings.

mode: rule

Rules are checked from top to bottom. The first match uses its assigned policy or proxy group.

proxy-providers

Import and Update Subscriptions

First, distinguish a full configuration subscription from a proxy provider. A full configuration may include proxy groups, rules, and DNS settings; a provider usually supplies nodes that a main configuration references. A client's subscription update button and the core's proxy-provider update are not necessarily the same operation. After importing, check the last update time, confirm the configuration is enabled, and make sure proxy groups have available outbounds. Set automatic updates as needed. To preserve custom rules, use the client's override feature if available, rather than risk overwriting manual changes during a remote update.

Subscription link · example addresshttps://example.com/subscription
Import from clipboard
Auto-update interval · secondsinterval: 3600
rules

Choose an Outbound Based on Conditions

Check which rule a connection actually matched before changing rule order. Domain suffix rules match domain names; GeoIP rules use regional data for the destination IP; MATCH catches requests that did not match an earlier rule. The core typically checks rules from top to bottom and stops at the first match, so put specific conditions before broad ones. PROXY in the example must match a proxy group that exists in your configuration. Check the group name before copying a rule, and make sure the data files used for regional matching are available.

DOMAIN-SUFFIX,google.com,PROXYGEOIP,CN,DIRECTMATCH,PROXY
PROXYDIRECT
tun

System Proxy vs. TUN

Enable the system proxy to test your browser before considering TUN. A system proxy provides an address that apps can choose to use; TUN is a virtual network interface that can route more traffic when combined with routing settings, but requires appropriate permissions and can affect DNS and network paths. They are not interchangeable connection switches. When setting things up for the first time, change one setting at a time and check the connection log before proceeding. If you're using a corporate network, another VPN, or a virtual machine interface, check for routing conflicts instead of enabling every traffic-capture option at once.

TUN mode
System proxy
Mixed port mixed-port: 7890Accepts both HTTP and SOCKS proxy connections; use the port in your active configuration.

Keep the local listening port and the controller separate. The mixed port accepts proxy requests from apps; the controller provides access to runtime status and configuration management. They are not interchangeable. The snippet in the homepage terminal is only a field reference, not a complete working configuration with nodes, proxy groups, and rules. For first-time use, import a valid configuration, then set the port shown by your client.

04 / source & maintenance

Open-source Core, Clients, and Project Boundaries

Check project source code and release notes instead of judging by download counts.

View mihomo source code

Understand the Clash Ecosystem

Thinking of the core and interface as separate layers explains why different clients have similar settings. The Clash ecosystem centers on configuration parsing, rule-based routing, and proxy forwarding. The original Clash and its later derivatives are not the same continuously updated software package. Clash Meta was later renamed mihomo, so older tutorials and configurations may still use its former name. When reading older articles, first identify which core and client they cover before applying their instructions.

Check Which Core Your Client Uses

Check the client's About page, core settings, and release notes. A graphical client handles configuration management and controls such as the system proxy and system tray; the core processes connections. Similar labels in different interfaces do not guarantee identical features. Protocol support, configuration fields, and update methods can change between projects. Don't assume a menu path from one desktop client applies to every mobile app. This site provides introductory guides and download links; it is not the official release channel for every upstream project.

Check Three Types of Updates Separately

Check updates for the client, core, and subscription separately. Client updates may fix interface or system integration issues; core updates may change protocol and configuration support; subscription updates refresh the nodes and rules provided by your service. Regional and domain classification databases such as GeoIP and GeoSite have their own update mechanisms. When something breaks, note which layer changed so you can narrow down the cause instead of updating everything at once.

Keep a Rollback Copy Before Editing Configuration

Save a working copy of your configuration, overrides, and key settings before making changes. If you run mihomo directly, test the configuration before starting the service. In a graphical client, use its built-in configuration checker and logs first. When reporting an issue publicly, include only the error details needed and redact subscription URLs, node credentials, and account information. This helps explain the problem without exposing private configuration.

When a Connection Fails, Find Where the Request Stops

First confirm that the client is running and the active configuration is enabled. Then check whether the app's request appears in the connection log. If there's no record, check the system proxy, the app's own settings, or TUN routing first. If a request appears but fails, check the matched rule, selected proxy group, and node availability. If a browser works but a terminal command doesn't, check the command-line tool's proxy settings separately; a working browser doesn't prove every app is routed through the client.

Keep the full error message and note what changed before the problem started; this is more useful than repeatedly reinstalling. If the internet still doesn't work after closing the client, restore the system proxy settings first. If only certain domains fail, check DNS resolution and routing rules. Look up basic terms in the glossary, common procedures in the FAQ, or visit the troubleshooting page for a step-by-step diagnosis.

05 / reading notes

Configuration and Troubleshooting Tips

After your first connection, explore the guides that address the issues you actually encounter.

Browse all articles