Clash Ecosystem · Configuration Guides

Clash Proxy Client

Choose a client by operating system, explore the mihomo core and YAML configuration, and follow the steps from importing a subscription to verifying routing rules.

Open-source coreConfiguration guides

Client configuration features

Import the full subscription in the client; the core reads proxy providers from the configuration.

Subscriptions and proxy providers

Paste a compatible subscription URL into the configuration list, wait for it to download and parse, then set it as the active configuration. Unlike manual entry, a remote subscription can be refreshed, and renamed proxies may affect existing selections. If you only have a proxy provider, load it separately with proxy-providers and reference it from a proxy group. The two types of links may both return YAML, but they are not necessarily interchangeable. If an update succeeds but no proxies appear, first check what type of content was delivered, then verify that the proxy group references the right provider.

providers.yaml
proxy-providers:  office:    type: file    path: ./providers/office.yamlproxy-groups:  - name: PROXY    type: select    use: [office]

Browse the YAML Configuration Reference →

Choose a package by platform

Filter by operating system first, then check the CPU architecture, installation method, and maintenance status. When moving from an older client, import the subscription or configuration file instead of overwriting the new app's data directory.

Windows

Check the device architecture in system information. For a first-time setup, enable the system proxy and see whether the browser produces connection logs. If you need to route apps that ignore the system proxy, check the client's TUN support and permission prompts. Before migrating an old configuration, quit the previous app to avoid two clients changing proxy settings or competing for the same listening port.

Go to downloads

macOS

Check About This Mac to see whether your device has Apple silicon or an Intel processor, then choose the matching package. After enabling the proxy for the first time, check in Network settings that the active network service is using the expected configuration. If apps keep trying to connect to a local proxy port after the client quits, check whether the system proxy was restored instead of repeatedly reimporting the subscription.

Go to downloads

Android

Choose a package that matches the ABI supported by your system; a processor's support for an instruction set does not mean your current system can install the corresponding package. Authorize the VPN when prompted on the first connection. If the connection drops when the screen locks, note the notification shade status and check background-running restrictions and whether another VPN service has taken over.

Go to downloads

iOS

Check the App Store listing for client and system compatibility requirements. After importing a configuration and allowing the app to add a VPN configuration, return to the client to confirm the selected configuration and proxy group. If the status bar says VPN is connected but the target app still cannot connect, test the same destination in a browser first, then check the app's connection log to distinguish tunnel startup from request forwarding.

Go to downloads

Linux

On desktop Linux, choose a package format for your distribution, such as DEB for Debian-based systems or RPM where supported. The core can run independently on a headless device, but you will need to manage the configuration directory, service permissions, and logs yourself. After startup, also confirm that apps are sending requests to the core through system settings, environment variables, or another integration method.

Go to downloads

Browse all clients →

Three steps to your first connection

  1. Import and activate a configuration

    Add a compatible link from your provider on the subscription or configuration page, or choose a local YAML file. Once it appears in the list, set it as the active configuration. If the import fails, first check that the response contains configuration data, not a login page or service notice. Never share subscription URLs in screenshots, logs, or bug reports.

  2. Choose rule mode and route traffic

    Choose rule mode and select the proxy to use in the proxy group. On desktop, start with the system proxy; on mobile, authorize the VPN when prompted. Verify one connection method before considering TUN. A running core only means it has started; it does not mean app traffic is reaching it. Check these two states separately.

  3. Verify routing in the connection log

    Choose one destination expected to connect directly and another expected to use a proxy. Visit each and check the connection log for the domain, matched rule, and final proxy. If there are no entries, check how traffic reaches the proxy. If there are entries but the proxy is wrong, check rule order. Investigate remote connectivity only after the matched rule and proxy are as expected.

Read the full guide →

Open-source cores and project maintenance

Original Clash and its successors

Original Clash configurations are built around proxies, proxy groups, and rules. Later projects have continued or extended this approach, but similar project names do not mean they share release channels or maintenance schedules. Older guides may refer to UI options that have since moved. First identify whether a guide covers core fields, client workflows, or conversion rules from a subscription provider.

How the client, core, and subscription fit together

The client manages configurations, system integration, and connection views. The core parses configurations, matches rules, and establishes connections. The subscription provider maintains the content it delivers. The same subscription may behave differently in two clients—for example, one may add DNS or listener settings. When troubleshooting, keep both the original subscription and the final active configuration; comparing them is more reliable than checking UI toggles alone.

mihomo and field compatibility

mihomo continues the development of the Clash Meta core, adding options for proxy protocols, rule sets, and network stack configuration. Common fields from original configurations can be a starting point for migration, but check the target core for supported values and dependencies, even when field names match. If parsing fails, use the error to locate the first problematic field, then consult the configuration reference. For unfamiliar terms, see the glossary.

Release notes and upgrade rollback

Read client release notes and core change logs separately. Before upgrading, keep a working configuration and any necessary local overrides. After upgrading, first confirm the configuration loads, then check the system proxy, DNS path, and rule matches. When filing a reproducible issue, include the platform, integration method, and a minimal configuration, removing personal domains, subscription parameters, and proxy credentials. Describe what actually happened before stating what you expected; this helps maintainers identify the affected layer.

Get the mihomo source code

The core is released under GPL-3.0. The commands below check out the source code; they do not install the desktop client. To install a GUI client, return to the downloads page and choose a package for your system.

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

Client news

Browse all articles →