First, understand the difference between the client, core, and configuration file. The client provides the interface, the mihomo core handles network connections, and the configuration defines how proxies, policy groups, and rules work together. Select an item on the left to see what it controls, then check the corresponding setting in your client. Change one thing at a time so you can tell what caused the result.
The program that handles connections
mihomo Core and GUI Clients
mihomo is the core that parses configuration, matches rules, and establishes proxy connections. GUI clients build on it with subscription lists, mode controls, and log views. Different client interfaces do not necessarily mean the underlying configuration is entirely different. Before choosing a client, check which core and configuration fields it supports, then import your existing subscription. If parsing fails, check the field names in the logs; a client launching successfully does not prove the subscription is compatible. The example below shows basic fields, not a complete, working configuration.
mixed-port: 7890
allow-lan: false
mode: rule
log-level: info
A subscription URL retrieves configuration, while YAML is a common configuration file format. Open the client’s configuration or subscription page, choose the option to import from a URL, paste the full address from your provider, and select the configuration once the update completes. Use the file import option for local files. A proxy node share link may not be a complete configuration, so check its format before deciding whether it needs conversion. Subscription URLs may contain credentials. When troubleshooting, share only the error details—never the full URL.
https://example.com/sub?token=xxxx
This is a format example only; it does not provide a working subscription service.
Traffic rules use conditions such as domains and IP addresses to decide whether a connection goes direct or through a proxy. The core usually checks rules from top to bottom, and the first match determines where traffic goes—so both rule order and content matter. After importing a subscription, start in rule mode and check that each policy group has an available node selected. Global mode sends more connections through the global policy, but it cannot fix an unavailable node. In this example, DIRECT means a direct connection for matching domain suffixes only; it does not mean all Apple services will connect directly.
The system proxy writes the local proxy address into your operating system settings. Apps that honor those settings then send their connections to the client. For a first test, enable the system proxy, open a browser, and check the connection log for the browser’s requests. Terminal tools and some apps may ignore system proxy settings; configure their proxy address separately or use TUN instead. Turn off the system proxy before quitting the client. If pages stop loading after an unexpected exit, check whether your system still points to a local port that is no longer listening.
# Use the port configured in the client
HTTP / SOCKS: 127.0.0.1:7890
mixed-port: 7890
TUN captures network traffic through a virtual interface, making it useful for apps that ignore system proxy settings. It usually requires the client to install a helper service and obtain system authorization. First confirm that a regular proxy connection works, then enable TUN and check the logs and DNS resolution. VPNs, other proxy clients, and container networks can create routing conflicts, so keep to one traffic-capture method while troubleshooting. TUN expands which traffic can be captured; whether that traffic goes direct or through a proxy still depends on the mode and rules.
Open About This Mac from the Apple menu. If it shows a chip name such as Apple M-series, choose the Apple silicon or ARM64 build. If it lists an Intel processor, choose the Intel or x64 build. A native build avoids relying on translation, but it must still meet the client’s stated macOS requirements. Quit any older client before installing, drag the app to Applications, and launch it from there. Before switching clients, back up your configuration and custom rules. Avoid running two apps that both change system proxy settings.
uname -m
# arm64: native Apple silicon environment
# x86_64: Intel environment or translated terminal
Feature notes rotate every 8 seconds; clicking, keyboard input, or focus stops the rotation. Field examples explain settings only. Actual configuration depends on the selected client and subscription.
Downloads / Choose a Platform
Clash Downloads for Every Platform
Choose your operating system, then your processor architecture. For desktop devices, start with a GUI client; consider running the core directly only for servers and routers. The links below open the relevant platform section on the downloads page—they do not start a download. Review system requirements, maintenance status, and installation notes before choosing a client.
Choose a build for Apple silicon or Intel. Start with Clash Plus, or compare Clash Verge Rev and FlClash. Open the DMG, drag the app to Applications, then launch it from the Applications folder. The installer window is not where you run the app day to day.
When you first launch the app, follow macOS prompts to confirm its source. To use TUN, install the helper service as directed by the client. If macOS blocks the app, check the download source, system requirements, and exact warning. Disabling system security is not a general installation fix. Archived clients can help with older configurations, but for everyday use, prefer an actively maintained option.
Compare desktop clients such as Clash Plus, Clash Verge Rev, and FlClash, then choose one for your operating system and processor. After installation, import your configuration, select a node in the policy group, and enable the system proxy. For virtual-interface traffic capture, install the service or grant permissions as required by the client.
Clash for Windows is no longer maintained. The downloads page retains archive notes; do not treat it as equivalent to actively maintained clients. Some Store apps are affected by UWP loopback restrictions, which should be investigated based on the app type. If your browser works but another app cannot connect, first check whether that app uses the system proxy—you may not need to reinstall anything.
Compare installation options for Clash Plus, Clash Meta for Android, FlClash, and Surfboard. Most recent phones use ARM64, but check your device details before choosing a build. After installing, import a configuration format supported by the client. The first time you connect, Android will ask you to approve the VPN connection.
Android's VPN permission creates a local traffic-capture path; it does not provide working proxy nodes. If the connection keeps dropping in the background, check battery optimization, background activity, and whether another VPN app is active. Clients may support different subscription formats. A link opening in your browser does not guarantee that it can be imported directly.
Use the downloads page to open Clash Plus in the App Store, then check device compatibility and the app details there. The client’s official site is clashplus.io. After installation, add a configuration, allow the VPN configuration when prompted, then return to the app and connect.
You can use the same provider’s subscription on your phone and Mac, but check its supported formats and device limits. If the connection fails after switching between Wi-Fi and cellular, check the app status and subscription validity before reconnecting. The authorization prompt grants permission for traffic capture; it does not check whether nodes work. Verify nodes, rules, and DNS in the client.
For desktop Linux, choose Clash Verge Rev or FlClash. Select a package format for your distribution and verify the package architecture. After installing, import your subscription in the GUI and check your desktop environment’s proxy settings. The settings location varies by desktop, and command-line apps may not automatically use the proxy enabled by a GUI client.
On a server or headless device, you can run mihomo directly and manage the process with systemd. You are responsible for the configuration path, runtime user, listening address, and log permissions. Do not expose the control interface to the public internet or open LAN listening without a clear need. See the installation guide for details on command-line deployment versus desktop setup.
Open-Source Ecosystem / Know What Each Project Does
Clash Clients and the mihomo Project
Clash for Mac is a resource site for Mac users, with client downloads and setup guides for different apps. This site is independent of the client and core project maintainers. To check feature support and maintenance status, refer to the release notes for the specific project—not just whether its name includes Clash.
Explore the mihomo Core Source Code
The core repository provides a reference for configuration behavior, issue reports, and release notes. Running the command only fetches source code; it does not install a GUI client or establish a proxy connection.
The Clash ecosystem has evolved through the original project, various forks, and community-built clients. mihomo continues and extends the Clash Meta line, and several GUI clients use it to handle proxy connections. Older guides may still use legacy names and interfaces, but that does not mean current menus, supported fields, or maintenance status are unchanged.
When consulting a guide, first check whether it covers the core or a GUI, then verify which client it uses. Archived builds of Clash for Windows and ClashX Meta can help explain older setups. If you run into compatibility problems, consider moving to a maintained client rather than repeatedly following screenshots from an older release.
Open-Source Code and Configuration Boundaries
Open-source repositories make configuration parsing, rule behavior, and bug fixes easier to inspect. That does not mean every client supports the same features, or that the core project provides subscription services. GUI clients, proxy nodes, and subscription providers each have different roles; troubleshoot them separately.
If the logs report an unsupported configuration field, check the core documentation and client release notes. If the configuration loads but every node fails to connect, check the subscription validity, network reachability, and node details. When posting publicly, hide subscription credentials, account information, and control-interface keys. Share only reproduction steps and the relevant error excerpt.
Core Updates and Client Updates
Client updates may change the interface, helper service, or how the core is bundled. Core updates may affect protocol support, rule handling, and network behavior. The two do not always ship together. Read the release notes before upgrading, save custom rules and your current configuration, then verify subscription loading, system proxy, and TUN after the update.
Don’t assume a page failing to load means the software is outdated. First check whether the problem affects one site or all sites, then investigate DNS resolution, rule matching, or node connectivity. A clear troubleshooting sequence is more useful than repeatedly switching clients. The downloads page lists available packages; the homepage avoids specific version details that can quickly become outdated.
Subscription Updates and Routine Maintenance
Updating a subscription fetches remote configuration again; it does not update the client. Set the update interval according to your provider’s requirements and how often nodes change. Requests that are too frequent may trigger service limits. Manage custom rules through the client’s supported override or merge features so a future update does not overwrite them.
Disconnect the proxy before quitting the client to reduce the chance that your system keeps pointing to a local proxy. If you leave TUN off for a long time, check the helper service and routing state. When something fails, note the time, network, mode, and error message, then follow the troubleshooting steps in the installation guide. Avoid changing several settings at once and trying to remember what they were afterward.
Three Common Issues After Installation
Why can’t I open websites after importing a subscription?
Importing only saves the configuration. Make sure it is selected, a working node is chosen in the policy group, and the system proxy or TUN is enabled. Check the connection log to see whether requests reach the core. If there are no requests, check traffic capture; if requests appear but fail, check the node and DNS. See troubleshooting tips in the FAQ →
How do rule mode, global mode, and the system proxy work together?
The system proxy determines whether an app sends requests to the client. Rule mode and global mode determine how the core routes those requests. They operate at different stages and cannot replace one another. Start with rule mode, confirm that your browser works, then adjust traffic capture for specific apps as needed. See how to choose a mode →
Do I need to keep the system proxy enabled when TUN is on?
Whether to enable both depends on the client and your use case. TUN can usually capture more connections, but you should still check routing, DNS, and bypass settings. When troubleshooting, test each method separately first, then combine them as the client recommends. Avoid running multiple proxy or VPN apps that change the network route at the same time. See connection method FAQs →
Setup Notes / Recent Articles
Choosing a Client and Capturing Traffic
Once installation is complete, look up how things work when you need to troubleshoot. To switch clients, compare platform support and workflow. If a terminal, game, or LAN device cannot connect, first identify which part of the traffic path is handled by the system proxy, virtual interface, or router. These three guides approach the topic from different angles and help avoid applying desktop settings to other devices.
Compare popular clients by platform support, core compatibility, interface, and ease of use, with recommendations for Mac, Windows, and mobile users. Check your devices and each project’s maintenance status before deciding whether to migrate your configuration.
Compare the traffic captured by the system proxy and a TUN virtual interface, including how terminal commands, games, and DNS are handled. First check whether requests reach the core, then decide whether to change the capture method or investigate rules and nodes.
Understand the roles of the main router and bypass router, plus gateway and DNS settings. Learn about architecture choices, resource requirements, and common causes of network outages. For readers familiar with desktop proxies who want to extend traffic capture to LAN devices.