Open-source core · Cross-platform clients and setup guides

Clash Knowledge Base · Downloads & Setup

Download Clash Browse tutorials

Choose a client for your device, then follow the steps for importing a subscription, setting routing rules, and troubleshooting connections.

Open-source mihomo core Step-by-step documentation Config and log walkthroughs
Troubleshooting order

Check traffic capture first, then rules and DNS

When a connection fails, test one layer at a time to preserve useful clues instead of switching nodes, modes, and DNS settings all at once.

Importing subscriptions and setting up the system proxy

Get a working config before choosing nodes. After installing a client, import an existing subscription or local config. Make sure it appears in the config list, then select it as the active config. A subscription URL is a source of configuration—not an installer or a public share link. If importing fails, determine whether the download failed, the content is malformed, or the core does not support a field. Keep the error message and avoid repeatedly pasting the URL without changing what you're testing. Hide any access credentials in subscription URLs before sharing screenshots or logs.

A running status doesn't mean your apps are using the proxy. Once the config loads, enable the system proxy, send a fresh request from a browser, and check the client's connection log. Some terminals, games, and apps with their own networking stack ignore the system proxy, so a working webpage doesn't prove that all traffic is being captured. Test the same app against the same destination each time. If you need to route more apps, look into TUN permissions and routing first; there's no need to enable every feature on your first launch.

To verify a connection, check both the route and the result. Select a node in the proxy group, visit a test destination, then check the connection details for the target domain, matched rule, and actual outbound route. A latency test only shows how quickly that test address responded at that moment; it can't prove that every site or UDP app is working. If switching nodes fixes the issue, investigate the node. If no requests appear in the log, check traffic capture first. Identify the failing layer before changing the config or rules.

Custom rules and proxy groups: what each does

Rules decide where traffic goes; proxy groups decide which outbound to use. In Rule mode, the core checks rules in config order and typically applies the action from the first match. Domain suffixes, exact domains, and destination IPs use different matching criteria—you can't expect a rule to work just by placing a domain anywhere. When adding a custom Clash rule, define what it should match, put specific conditions before broader ones, and make sure every referenced proxy group exists. Reload the config and use a new connection to verify the match.

Automatic selection doesn't always work the same way. select lets you choose an outbound manually; url-test selects a node based on test results; fallback prioritizes config order and availability; and load-balance distributes connections according to its configured strategy. For your first setup, keep one manual selection group. Once a single node works, add an automatic group. If the outbound keeps changing, check the test URL, interval, and group members—"auto" in a group name doesn't guarantee a stable connection.

Manage subscription updates separately from local changes. Edits made directly to a downloaded config may be overwritten by the next update. For persistent changes, use the client's supported override, merge, or standalone rule-set features. The merge order depends on the client, so don't assume every interface behaves the same way. Export a restorable config before editing, add one set of conditions at a time, and inspect the effective config after updating the subscription. When merging subscriptions, check for duplicate node names and proxy groups so references don't point to the wrong entries.

DNS, Fake-IP, and connection logs

A domain that won't load doesn't necessarily mean the node is broken. A request passes through domain resolution, rule matching, and outbound selection before a connection is established. First identify whether the error is a DNS timeout, a refused connection, or a handshake failure, then compare the domain and destination address in the log. If your browser uses its own Secure DNS, it may resolve domains differently from the system. Before changing the core's DNS settings, confirm which resolver is handling the request. System lookup tools alone can't show the full path a browser takes.

Fake-IP maps domains to virtual addresses; it isn't an outbound route. When enabled, the core can return a virtual address from a reserved range to an app, then use the mapping to recover the original domain and route the traffic. Seeing one of these addresses in a tool doesn't mean DNS is broken. For LAN services that need real IP addresses, configure targeted filters based on actual compatibility rather than excluding every domain. After switching DNS modes, old entries may remain in app or system caches. Close existing connections, clear the relevant cache, and compare new requests.

Troubleshooting TUN means checking routes and permissions. A virtual network interface can capture more traffic, but it also introduces variables such as permissions, DNS interception, and routing conflicts. If LAN devices become unreachable after enabling TUN, check excluded routes and other VPN apps first, then verify that the default route is as expected. Keep a working system-proxy setup as a baseline, and avoid changing the network stack and rule set at the same time. When you're done, restore the normal log level. Share only the necessary log lines, with subscription details, control-interface credentials, and personal browsing activity removed.

How config snippets map to the interface

Trace rule routing in config.yaml

This example covers a local mixed port, a manual proxy group, and rule order. The sample group contains only the built-in direct action; it has no proxy nodes and is not a complete working proxy config. To use it, add existing nodes or a subscription provider to the group, and make sure each rule references the correct group name.

config.yaml · Structure overview
  • Profiles
  • Proxies
  • Rules
  • Logs
mixed-port: 7890
allow-lan: false
mode: rule
log-level: info

proxy-groups:
  - name: Manual selection
    type: select
    proxies:
      - DIRECT

rules:
  - DOMAIN-SUFFIX,example.com,Manual selection
  - IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
  - MATCH,Manual selection

Rules are checked in order
and the first match decides the route

Clash client downloads

Choose your OS and processor architecture

Identify your device first, then compare clients. If you already have a working config, keep a copy of the original file so you don't change both the subscription and network settings during migration.

Windows

Choose Clash Plus or Clash Verge Rev for your system architecture. Import your config, check the core status, then test the system proxy. Avoid copying an old client's settings directory.

Download Windows client

macOS

Check About This Mac to choose Apple Silicon or Intel. Follow the app's permission prompts and test the system proxy first. Install the client's service only if you need TUN.

Download macOS client

Android

Check device compatibility, import your subscription, and allow the VPN connection. Stop conflicting VPN apps. If connections drop in the background, review battery and background activity restrictions.

Download Android client

iOS

Find Clash Plus on the App Store via the download page, or visit clashplus.io. Import your config and allow the VPN connection. Check logs when migrating desktop configs: scripts, overrides, and rules may differ.

Download iOS client

Linux

Compare Clash Verge Rev and FlClash for desktops. Terminal apps may need separate proxy settings. For servers and routers, download the core and configure service permissions and listening addresses for that host.

Download Linux client

Browse all clients →

Linux penguin graphic: Font Awesome Tux, CC BY 4.0; inline vector only.

Open-source projects and documentation

Know the difference between clients, cores, and subscription providers

This site collects download links and troubleshooting notes; it is not affiliated with every client developer. Check the documentation for your project and its actual runtime behavior to understand what the software supports.

How Clash and mihomo fit into the ecosystem

Clash is a widely used name in the rule-based proxy ecosystem. Existing guides may cover the original Clash, Clash Meta, and mihomo. mihomo continues the technical direction of Clash Meta, providing core features such as proxy protocols, proxy groups, rule matching, and DNS. Clients build on the core with a graphical interface, subscription management, system proxy controls, and service management. When names are similar, check which core is actually in use instead of judging config compatibility by the app's appearance.

Fields and interface labels in older guides may not apply to your current client. If you encounter an unknown field, an unsupported protocol, or a config load failure, note the client name, core details, and exact error message, then check the project's documentation. Being able to save a copied snippet doesn't mean the core uses every setting in it. Verify both the load result and actual connection behavior.

Open-source code makes behavior easier to verify

Open-source repositories let you review licenses, config implementation, issue discussions, and release notes. The command below points to the public mihomo repository for anyone who wants to read the source or investigate specific behavior; you don't need to compile the core for everyday use of a graphical client. When behavior changes, start with the release notes and related issues. This is usually more useful than replacing the entire config from scratch.

An open-source core doesn't mean the same project provides every related service. Node quality, subscription contents, and account status depend on their respective providers; a client can't fix a node that the service provider has taken offline. Before filing an issue, reproduce it with a minimal config, describe your system and the steps you took, and remove credentials and unrelated rules. That makes it easier to distinguish a core bug from a client integration difference or a subscription issue.

Keep a rollback option when updating

Clients, cores, and subscriptions can be updated independently, and their versions don't always change in sync. Before upgrading, export your config and local overrides, and note the proxy mode and DNS settings that currently work. After the update, test against the same destination. Confirm the system proxy, TUN permissions, rule-set loading, and subscription refresh before restoring automatic updates or complex policies. If something regresses, keeping before-and-after configs is more useful than repeatedly reinstalling.

Connection logs show what happened to a request; they don't give a complete diagnosis. A timeout can occur during DNS resolution, the outbound connection, or the destination's response, so the same error message can mean different things depending on context. These guides follow an “action, symptom, verification” sequence so each change has an observable result. For cases not covered here, check the FAQ, then use the Getting Started guide to return to a minimal working setup.

Technical notes

Troubleshooting traffic capture and proxy groups

Pick a guide based on the issue. First check whether traffic reaches the core; then investigate how it gets routed.

Browse all articles →