CLASH · IPV4 · OPEN-SOURCE CLIENTS

Clash Open Source HubClient Downloads & Setup

Choose a client for your device, follow the English setup guide to import your config, then check how ports and rules work.

  • CoreMihomo
  • LicenseGPL-3.0
  • Rule targetDIRECT

127.0.0.1 / Client downloads

Download Clash clients by operating system

Check your operating system and processor architecture before choosing an installer. Desktop clients typically offer config import, proxy group selection, and logs in one interface, making them a good starting point. If you already use a command-line core, find its download separately on the downloads page so you don’t mistake a core package for a desktop installer.

Windows

Check your system type on the About page, then match it to the processor architecture listed for the client. For a first install, test your browser connection with the system proxy before enabling a virtual network interface. If the installer or operating system asks for permission, check whether the request concerns installation, a service, or network access. Don’t disable the entire firewall to get past a single prompt. Before replacing an existing client, quit its processes and keep a copy of your config.

Go to downloads

macOS

In About This Mac, check whether your processor is Intel or Apple silicon, then choose the matching installer. If macOS shows a security warning at launch, check the project’s release notes for installation requirements. If the app launches but can’t route traffic, check the system proxy settings and the client’s network permissions. When moving to another Mac, migrate your config rather than copying the old app’s data directory.

Go to downloads

Android

Choose a package that matches the operating system and architecture supported by your device, not just the processor’s advertised specs. On the first connection, the system will usually ask for VPN permission; approve it, then check that the client shows a connected status. If the issue only occurs after the screen locks, check whether the system is suspending background activity. If the connection drops as soon as it starts, check whether another app is already using the VPN.

Go to downloads

iOS

Open the store listing from the downloads page, check the system requirements, then decide whether to install. On first connection, follow the system prompt to allow a VPN configuration. Importing a config and connecting are separate steps, so seeing it in the config list doesn’t confirm a successful connection. If you already use a work VPN, check whether you can switch between VPNs, especially on a managed device.

Go to downloads

Linux

Desktop users should check their distribution, package format, and processor architecture before choosing a graphical client. Desktop environments handle system proxies differently: a browser using the proxy doesn’t mean terminal commands will use the same settings. If you run the core on a server, also check the config path and service permissions, and make sure the listening address matches your intended use.

Go to downloads

If both clients support your device, compare how they import configs, their maintenance status, and where to find logs. For LAN access, a virtual network interface, or config overrides, check that the interface has the relevant options and that the core supports those fields. If you’re considering an archived client just to open an old config, test a copy in a maintained client first instead of repeatedly changing the original file.

Browse all clients → Compare clients

DIRECT / Config basics

Clash config fields and traffic flow

Local listening, traffic interception, and rule-based routing are three separate things. Ports determine where an app sends requests; the interception method determines which requests reach the core; rules decide where those requests go. Keep these roles distinct when troubleshooting: you can tell whether a request never arrived or took the wrong route after reaching the core.

Rule order and the fallback target

In rule mode, rules are checked from top to bottom. The first match determines the target; later, more specific rules are not considered. This example handles private IP ranges, an example domain, and all remaining traffic in that order: the first rule sends a specified address range direct, the second lets you observe domain matching and rejection, and the last provides a fallback. It doesn’t rely on remote nodes, so you can check the logs in a test config before using the same order in your own. When editing, avoid rejection rules with domain suffixes that are too broad.

  • Put specific conditions first and MATCH last.
  • no-resolve prevents this address rule from actively resolving a domain to an IP address.
mode: rule
rules:
  - IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
  - DOMAIN,example.org,REJECT
  - MATCH,DIRECT

The mixed-port: 7890 on this note is an example, not a port used by every client. 127.0.0.1 points to the current device; the same address on your phone won’t point to your computer. For local use only, keep allow-lan: false and use the listening port shown in the client. If there’s a port conflict, confirm that the current port is in use before changing it, then update any apps where you manually entered the old port.

See ports, modes, and other common fields →

mixed-port / First connection

Import a config, choose a mode, and test the connection

For your first setup, keep the original network settings that are known to work and change one option at a time. First check that the config loads, then whether requests reach the core, and finally where the rules route them. This way, if the second step fails, you won’t have to reimport your subscription to start over.

  1. 01 / config.yaml

    Import and enable a config

    On the config or subscription page, add an existing local file or subscription URL. After importing, check that the proxy groups and rules appear, then select the profile and confirm it’s active. If the interface reports a successful download but shows no loaded content, check the import logs for format or network errors. Subscription URLs may contain credentials; don’t include the full URL in screenshots when sharing an issue.

  2. 02 / mode: rule

    Choose a rule mode and traffic interception method

    For everyday use, start with rule mode. Confirm that the rules you need to route point to the right proxy group, then check the selected outbound in that group. On desktop, test an app that follows the system proxy settings. On mobile, complete the system authorization through the client’s connection flow. Rule mode and the system proxy aren’t alternatives: rule mode controls routing, while the system proxy controls how requests enter the client.

  3. 03 / 127.0.0.1

    Check connection logs and rule matches

    Open a new webpage, then check the client’s connection log for the domain, matched rule, and outbound. If no new entry appears, first check whether the app is using the proxy. If there’s an entry but the request fails, check the proxy group, DNS, and connection errors. To test command-line traffic, check which proxy settings the terminal program reads rather than assuming the browser’s results apply.

To restore your network connection, first turn off the traffic interception method you just enabled, then check that the system proxy is back to its original state. Quitting the client process directly may leave the system proxy pointing at a local port. Once your connection is restored, note which setting changed the symptoms so you can pick up from there next time instead of reinstalling.

Read the full guide → Find troubleshooting steps by symptom

config.yaml / Project sources

The Clash open-source ecosystem and the Mihomo core

Clash Open Source Hub is an independent resource site covering client downloads, config examples, and troubleshooting. Check each project’s documentation for release notes, maintenance status, and feature support. When reading source code, first distinguish the core that handles network traffic from the client interface that controls it.

Project history: different projects, shared name

The original Clash project brought proxy nodes, proxy groups, and routing rules together in one config. Although the original project is no longer maintained, other community projects continue to build on its config structure and the practices around it. Interfaces, menu paths, and fields in old guides aren’t instructions for today’s clients. Use old screenshots to understand concepts, but check the current project for exact steps.

When migrating an old profile, keep the original file and work from a copy. Then compare common fields, node types, and rule targets. A profile that loads successfully doesn’t necessarily mean every setting will work as it did before. Test the basic connection first, then restore features with more dependencies one at a time; this makes issues easier to pinpoint than rewriting the entire file during migration.

How community projects divide responsibilities: interfaces and traffic handling

Graphical clients typically manage config profiles, system integration, and logs. Even clients built around similar cores can differ in tray controls, startup behavior, background services, and override options. For system authorization or installer issues, start with the client project’s documentation. For rule matching and protocol support, check the core’s documentation.

When reviewing public issue reports, check the operating system and reproduction steps described. The same error message can result from file permissions, system network services, or config syntax. When reporting an issue, share a minimal config snippet, the steps that trigger the error, and relevant logs. Remove node details, subscription URLs, and personal data from logs first.

Core lineage: from Clash.Meta to Mihomo

Mihomo is the project name for the continued development of Clash.Meta. Its public repository is maintained under MetaCubeX and is licensed under GPL-3.0. Clients that support the relevant features can pass the selected config to the core, which handles listening, rule matching, and connection forwarding. A client may also merge its interface settings into the final config, so the imported file may differ from what the core actually loads.

To check whether a field is taking effect, compare the saved config with the effective config provided by the client, then check the core logs. Don’t infer the underlying state from a button label alone. For example, seeing that the system proxy is enabled doesn’t mean the virtual network interface is active; they provide different ways for traffic to enter.

Updates: check the app, core, and subscription separately

An app update changes the client itself; whether it also updates the core depends on the project. Refreshing a subscription updates config content, while rule sets may have their own refresh schedule. The interface may call all these actions “Update,” but each changes something different. If a problem appears, note which item was updated most recently and check the corresponding project’s changelog.

Before making changes, keep a copy of a config that worked before. Afterward, retest a request that used to work. If an issue starts after a subscription refresh, check whether proxy groups or rule references changed. If it starts after an app upgrade, check system permissions and startup logs. Don’t refresh the subscription, overwrite the config, and replace the core all at once just to restore a single connection.

View Mihomo source code

Visit the MetaCubeX/mihomo repository to browse the source code, license, and release history. The command below requires Git and clones the source into a mihomo subdirectory in the current directory; it doesn’t install a client or change your system proxy. To download a runnable app, choose a package for your operating system on the downloads page.

git clone https://github.com/MetaCubeX/mihomo.git

127.0.0.1 / Troubleshooting notes

Clash installation and troubleshooting guides

Troubleshooting guides are organized by symptom. If the app won’t open, check the startup logs. If it opens but no traffic flows, check the connection between the app and the local port. If only one app is affected, start with that app’s proxy settings. Choose the guide that best matches what you’re seeing.

Troubleshooting

Clash client crashes on launch: fix config syntax, port conflicts, and missing core files

Crashes at startup are often caused by YAML syntax errors, a port conflict, or missing core files. Follow the log clues to get the app running again.

For cases where the app quits before showing its main window. First find out whether it exits before or after reading the config, then decide whether to restore a copy, free up a port, or repair the installation.

Platform Guides

Install and set up Clash on Windows: firewall, UAC, and TUN mode explained

A complete Windows setup walkthrough, from choosing an installer and granting administrator permissions to configuring firewall access and enabling a TUN virtual network interface.

For users stuck on a system permission prompt or service installation. First identify which step requires permission, then decide whether to grant it as expected or switch back to using only the system proxy.

Troubleshooting

Clash system proxy not working: troubleshoot browsers and terminals separately

Browser extensions taking over proxy settings, terminals ignoring the system proxy, and missing environment variables are common causes. Troubleshoot browsers and terminals separately to find the issue.

For cases where webpages and command-line requests behave differently. Check whether both apps use the same local port, then determine whether the problem is with the app’s proxy settings or the routing rules.

Browse all articles →