Open source project · mihomo core actively maintained
Choose a client for your platform, organize connections with YAML configuration, and set up network access with routing rules and TUN mode.
TRAFFIC / CONFIGURATION
Decide how traffic enters the core before choosing how connections are routed.
System proxy settings point the operating system to a local listening port on the client. Apps that follow system settings, such as browsers, then send traffic through the core, which selects an exit based on the current mode. For a first-time setup, start here: import a subscription, start the core, then enable system proxy in the client. The difference from TUN is the scope of traffic captured, not node speed; apps that ignore system proxy settings may still connect directly. A mixed port accepts both HTTP and SOCKS requests, but the client toggle is what changes system settings.
mixed-port: 7890allow-lan: falsemode: rulelog-level: info# Enable system proxy in the client UITUN uses a virtual network interface and routing settings to send traffic through the core, including traffic from apps that do not use system proxy settings. Before enabling it, confirm your subscription works in regular proxy mode, then grant the client the required administrator or VPN permissions. Auto-route directs traffic to the interface; DNS hijacking routes DNS requests through the specified resolver flow. Check both against your local network setup. TUN captures traffic more deeply than system proxy and is more likely to conflict with other VPNs, virtual adapters, and routing software. If a conflict occurs, troubleshoot one setting at a time rather than changing everything at once.
tun: enable: true stack: mixed auto-route: true auto-detect-interface: true dns-hijack: - any:53Rule mode checks connection destinations in configuration order and applies the policy for the first matching rule. Domain suffixes, IP ranges, and rule sets can work together to define routing, with a final fallback rule handling anything unmatched. Unlike global mode, which applies one policy across the board, rule mode can send local services direct and route selected sites through a proxy. Before adding a custom rule, confirm its policy exists and place specific rules before broader ones. PROXY in the example is a proxy group name that must be defined elsewhere in the full configuration; this snippet is not a complete subscription to import.
mode: rule# Define PROXY in a proxy grouprules: - DOMAIN-SUFFIX,github.com,PROXY - IP-CIDR,192.168.0.0/16,DIRECT - MATCH,PROXYA subscription link retrieves nodes or a full configuration from a configuration source. To get started, paste the link into the client's configuration page, then select and enable the configuration after it downloads. A full YAML configuration can include proxy groups, rules, and DNS settings; a proxy provider only manages node sources and still needs to be referenced by a main configuration. A full subscription is better than a single node link when you need to keep an existing routing setup. Back up local changes before updating, and check whether the client supports overrides. Direct edits to a cached subscription file may be overwritten during the next automatic update.
# Local proxy provider snippetproxy-providers: local-nodes: type: file path: ./providers/nodes.yaml# Reference local-nodes with use in a proxy groupPACKAGES / PLATFORMS
Choose your operating system, then check the processor architecture and installation method. Downloading a client is separate from getting proxy service; you'll still need a working configuration after installation.
Start with Clash Plus, or compare Clash Verge Rev, FlClash, and Clash Nyanpasu. Import a configuration after installation, then enable system proxy. Set up the service and permissions only if you need TUN. If a local port is already in use, identify the process first instead of repeatedly reinstalling.
Go to downloadsChoose a package for Apple Silicon or Intel. Clash Plus, Clash Verge Rev, and FlClash offer different interfaces; check archive status when looking for ClashX Meta. If macOS displays a security warning on first launch, verify the source before following the system prompts to authorize the app.
Go to downloadsChoose Clash Plus, Clash Meta for Android, FlClash, or Surfboard, and check that your subscription format is compatible with the client. You'll need to approve a VPN request the first time you connect. If the connection drops in the background, check battery optimization and background activity restrictions first, then verify that your subscription is still active.
Go to downloadsUse the download page to open Clash Plus in the App Store; the official site is clashplus.io. Import a configuration and allow the VPN configuration to be added, then choose a policy and node. The system VPN indicator only confirms that a tunnel is active; check request logs to verify how traffic is actually routed.
Go to downloadsFor desktop use, start with Clash Verge Rev or FlClash and choose a package for your Linux distribution. For servers and routers, you can deploy the mihomo core separately and configure its working directory, service permissions, and startup method. Command-line deployment is not the same as installing a desktop client.
Go to downloadsFIRST CONNECTION
Follow this order: configuration source → connection method → request verification. Troubleshoot in the same order if something goes wrong.
Choose a client for your system on the download page. Open its configuration or subscription screen, paste the Clash-compatible subscription URL from your provider, and set the downloaded configuration as active. Seeing a configuration name does not mean it's enabled; check that your node list and proxy groups have loaded.
If you only have a single node link or Base64 text, first check whether your client can import it. If conversion is needed, use a trusted local method where possible. Subscription URLs may be linked to account and traffic information, so don't paste them into online tools from unknown sources.
Manually select an available node in a proxy group, then set the operating mode to Rule. On desktop, start by enabling system proxy and testing with a browser. Once that works, enable TUN if needed. On mobile, approve the VPN permission when prompted by the operating system.
Global mode and TUN are not the same switch. Global mode decides which policy handles connections after they enter the core; TUN decides how traffic gets into the core. Global mode also does not mean every app on your device is being captured.
Visit the destination you want to test while viewing the client's connection list. Check the destination domain, matched rule, proxy group, and final node to confirm the request followed the expected path. A single latency test reflects only its specific test destination; it does not represent download speed or access quality across all services.
If a page won't load, first check whether the request reached the core. If there's no record, check system proxy, VPN permissions, and routing. If a record exists but the connection failed, check DNS, node availability, and the rule target. Change one setting at a time and keep notes on reproducible results.
The client does not include proxy service. It reads configurations and handles connections; nodes come from your configuration source. A subscription can download successfully even when some of its nodes are unavailable. Check service status and test actual requests.
A successful connection does not guarantee correct routing. Local devices, office networks, and printers often need a direct route. If these services stop working after enabling TUN, check local network routes and exclusions before sending all requests through a proxy node.
Local changes need a way to persist. Subscription updates may overwrite manual edits. Put long-term custom rules in an override or merge mechanism supported by your client, then check rule order and proxy group names again after updates. The interface varies by client, so consult the platform-specific documentation.
OPEN SOURCE / RESPONSIBILITY
Understand the roles of the interface, core, and configuration source to identify feature support and troubleshoot issues accurately.
The Clash ecosystem includes cores, desktop interfaces, mobile clients, and configuration tools. Clash Meta is a common name in older references; mihomo continues the development of the related core. Older guides may use both names. For configuration details, refer to the documentation for the core you're using—an app's name alone doesn't tell you which protocols or fields it supports.
ClashX commonly refers to a macOS client line; it does not mean every platform uses the same app. This site organizes downloads and guides by platform to help distinguish maintained clients from archived projects. Projects have their own release schedules, and similar-looking interfaces do not guarantee identical core behavior.
The public mihomo repository provides source code, license terms, issue discussions, and release information. Open-source collaboration makes implementations available for review and gives users a clear way to reproduce issues with specific configurations and environments. GPL-3.0 is the license listed for the mihomo core here; it does not mean every third-party client or store app uses the same license. Check each project's terms before distributing or modifying it.
Before reporting an issue, note your operating system, client name, core information, and the steps that trigger it. Keep only the log details needed to reproduce the issue, and redact subscription URLs, account details, node passwords, and other credentials. Instead of saying a site won't open, identify whether the failure is DNS resolution, a connection, or rule selection; that usually makes troubleshooting easier.
The client typically handles configuration imports, subscription updates, tray menus, system proxy settings, and permission services. The core parses configuration, applies rules, establishes proxy connections, and processes network requests. If a UI toggle has no effect, the cause could be missing system permissions or an overridden configuration—not just a problem with the node list.
When switching clients, export your configuration first and make a note of custom settings. A full YAML file, a single node link, and a proxy provider are different types of content; support for one does not mean the other two can be imported as-is. Check protocol support, the TUN network stack, and rule behavior against the core as well.
Updating the app package, updating the core, refreshing a subscription, and downloading a rule set are four different actions. A successful subscription refresh only means remote content was retrieved; the app may still be using an old configuration, and proxy groups may retain previous selections. After updating, check which items are active instead of relying on the update timestamp alone.
If you run into a compatibility issue, back up your configuration before comparing it with the updated version. Don't change the client, nodes, DNS, and rules all at once, or it will be hard to tell what fixed the problem. For long-running setups, keep a restorable copy of the configuration and record important changes locally.
NOTES / FIELD GUIDES
Find practical guides by issue, from port conflicts and subscription formats to Linux deployment.
If Clash reports a port conflict at startup, use commands such as netstat or lsof to identify the process, then change the mixed-port and external-controller ports and update system proxy settings accordingly.
Read article →Compare the structure of common subscription formats, explain why Clash uses YAML configuration, and show how to convert Base64 node links into a complete, importable configuration, with tips for a safer conversion process.
Read article →Learn two ways to run Clash on Linux: install a desktop client with a graphical interface, or deploy the mihomo binary on a server or headless system, create a systemd service, and connect a web panel.
Read article →