Clash MetaSetup for Every Platform

# Chapter 01 · preparation

General Prerequisites and Configuration Basics

Understand the Client, Core and Subscription

Clash Meta is a longstanding name in the ecosystem; its core is now generally known as mihomo. The client displays configuration, manages nodes, requests system permissions and starts the core. The core handles proxy protocols, DNS and rule matching, while a subscription provides nodes or a complete configuration. Installing a client does not give you a working proxy by itself—you still need a subscription you are authorized to use or your own nodes. Check the provider's documentation for subscription validity, supported protocols and device limits; a successful installation says nothing about these.

For desktop and mobile, start with Clash Plus; on Linux, consider Clash Verge Rev or FlClash. Browse all options in the Download Center. Before choosing, check your operating system, processor architecture and installation method. Don't rely on platform names in a package filename alone. A desktop GUI suits interactive use; a mihomo core package is for users who want to manage configuration, processes and services themselves. Subscription workflows vary across GUIs. The instructions below describe what to accomplish, not buttons that every app must have.

Prepare a Compatible Configuration and a Way Back

Check whether you have a Clash YAML configuration, a collection of nodes or a configuration in another app's format. A complete configuration usually includes proxies, proxy groups and rules; a nodes-only file still needs proxy groups and rules. Base64-encoded node links are not complete Clash configurations, and renaming a sing-box JSON file won't make it importable. For format details and conversion limits, see the Subscription Format Comparison. Keep a copy of the original before converting, and never submit links containing access credentials to an untrusted service.

Before configuring for the first time, close other proxy clients and note your current system proxy and VPN settings. If your device is managed by your employer or school, check whether you can change proxy settings, install network extensions or add routes. Check the system clock, subscription account status and whether the current network can reach the subscription URL. Give the imported configuration a recognizable name, then explicitly select it as active. Seeing a file in the configuration list does not mean the running core has switched to it.

Start with a Minimal Connection, Then Expand Coverage

Recommended order: import a configuration, choose rule mode, select a node in the relevant proxy group, then enable the system proxy and test in a browser. Rule mode determines how traffic entering the core is routed; the system proxy directs apps that follow system settings into the core. TUN uses a virtual network interface to capture more traffic, requires additional permissions and can affect routing and DNS. Establish the basic path first, then enable TUN to avoid conflating node, permission and routing issues.

The example below only illustrates configuration fields. It contains no nodes and cannot establish a proxy connection on its own. Match the port numbers to your current client settings. If the client manages these fields, use its settings or override mechanism rather than editing a generated runtime file. Keeping the listener local is the safer starting point; for LAN sharing, check authentication and firewall rules first.

mixed-port: 7890
allow-lan: false
bind-address: 127.0.0.1
mode: rule
log-level: info

# Chapter 02 · windows

Windows Installation and Traffic Routing

Choose an Installer and Launch the App

Choose Clash Plus from the Windows downloads. For other workflows, consider Clash Verge Rev, FlClash or Clash Nyanpasu. Clash for Windows is discontinued and archived, so it is not recommended for new devices. Check your processor type under Settings > System > About, then compare it with the package's supported architectures. Don't confuse ARM devices with the more common x64 installers, and don't use whether a file opens on double-click as a compatibility test.

Read system prompts while running the installer, and verify the file's source before continuing. For a portable release, extract it to a stable folder instead of launching it from the archive preview. After first launch, check that both the tray icon and main window open, then review the logs for configuration parsing or port-binding errors. Installation privileges are separate from everyday use: grant elevation only when installing a service, virtual network adapter or other component that explicitly requires it. You don't need to run as administrator for routine system-proxy testing.

Import a Subscription and Select the Active Configuration

Open the configuration or subscriptions page, paste the full subscription URL using the URL import option, and wait for the download and parsing to finish. For a local YAML file, make sure hidden extensions haven't left it with a double suffix. Select the imported configuration, then check that the expected proxy groups appear. If an update succeeds but the node list is unchanged, check the active configuration, subscription expiry and provider response before reinstalling. Reinstalling won't fix an error page returned by the server.

In rule mode, find the proxy group referenced by the rules and manually select an available node. Some groups are nested, so the final outbound depends on the selection in the innermost group—not necessarily the most prominent node shown. Run the client's latency test, choose a candidate with a successful result, then try an actual connection. A failed test only means that particular test request didn't complete; it doesn't prove that every protocol or destination is unreachable.

Test the System Proxy, Then Add TUN

Enable the system proxy, then check Windows network settings to confirm that the proxy address points to the local listener and the port matches the client. Most browsers follow the system proxy, but terminals, games and some download tools may manage their own network settings. Visit a site with a known routing expectation while watching the client's connection panel. If no corresponding connection appears, investigate how the app enters the proxy first—not the rule order. A browser extension can override system settings, so temporarily rule that out during testing.

Enable TUN only if you need to capture apps that ignore the system proxy. If the client asks to install a service or grant permissions, do so, then check the logs for virtual adapter creation, route installation and DNS capture. Corporate VPNs, virtual machine adapters and security software can interact with the default route. If enabling TUN cuts off all connectivity, turn it off to restore the previous setup, then investigate one factor at a time. You don't need to enable the system proxy and TUN together from the start; testing them separately makes it easier to identify which traffic path changed.

Test-NetConnection -ComputerName 127.0.0.1 -Port 7890
curl.exe --proxy http://127.0.0.1:7890 --head https://example.com

This PowerShell example assumes a mixed port of 7890; adjust it to match your settings. A successful port test only confirms that the TCP listener is reachable. The request still depends on the node, DNS, destination and rules. Use curl.exe to call the command-line program explicitly and avoid parameter differences caused by an alias with the same name in some PowerShell environments. This test specifies the proxy directly, so it doesn't depend on whether the app reads the system proxy; it's useful for distinguishing a local listener issue from a system settings issue.

Quitting, Sleep and Port Conflicts

Turn off the system proxy and confirm that Windows settings have reverted before quitting the client. If your browser loses connectivity after an unexpected exit, check for a leftover proxy address pointing to localhost; restore the system proxy first rather than deleting all network settings. If a node stops working after sleep, reconnect or restart the core before deciding whether to update the subscription. For a port conflict, identify the process already listening instead of masking duplicate launches by changing ports repeatedly. For first-connection checks, see Choosing a Node and Verifying the Proxy.

# Chapter 03 · macos

macOS Permissions and Network Services

Choose a Client for Your Mac's Processor

Open About This Mac to check whether your processor is Apple silicon or Intel, then choose the matching package from the macOS downloads. Start with Clash Plus, or consider Clash Verge Rev or FlClash. ClashX Meta remains available as a discontinued, archived option. Read the download page's architecture choices alongside its system requirements; a client's name alone doesn't establish compatibility. Translation and native execution may have different limitations, so prefer a release built for your Mac's architecture.

If the release is a disk image, follow the installer instructions to move the app to Applications, then launch it from there rather than running it long-term from a temporary mounted image. Handle security prompts based on the app's source and signing information. If the source is unknown, the file is damaged or a prompt is unexpected, return to the download page to verify the release instead of disabling system security. First check the menu bar icon and logs to confirm the app and core are running before granting system proxy or network extension permissions.

Import a Configuration and Apply Local Overrides

Import the subscription from the configuration manager and set it as active after the download and parsing finish. Check the proxy page for the expected groups, nodes and rules. If the subscription name appears but there are no proxy entries, check its format and response content. Configuration data for macOS apps usually lives under a user-level application data directory; the exact path depends on the client. Use the client's Open Configuration Folder option or equivalent rather than guessing based on another app's layout.

A subscription update replaces remote configuration content, so edits to the downloaded file may be overwritten next time. To add personal rules or change DNS or ports, use the client's supported override, merge or extension mechanism and verify the generated result. Clients may replace or append arrays differently; check in particular that custom rules appear before fallback rules. Save a recoverable local copy before editing, but don't sync credential-bearing backups to a public repository.

Check the Active Network Service's Proxy Settings

After enabling the system proxy, open network settings and check the proxy options for the Wi-Fi or wired service currently in use. Network services can have separate settings, so recheck the active service when switching from Ethernet to Wi-Fi. The client determines how HTTP, HTTPS and SOCKS are configured; don't copy values field by field from a screenshot of another app. System commands can show whether settings are active, but their output may also contain environment details—redact it before sharing.

scutil --proxy
curl --proxy http://127.0.0.1:7890 --head https://example.com

If an explicit proxy request succeeds but browser traffic doesn't appear in the connection panel, check browser proxy extensions, custom proxy settings and the active network service first. Terminal commands don't always inherit system proxy settings from graphical apps; configure proxy arguments or environment variables for the specific tool. Environment variables only affect processes that read them, and a new terminal may differ from an already-running development tool. Repeat the test in the same terminal to keep the conditions consistent.

TUN Permissions, Network Changes and Recovery

When using TUN, grant the network extension or helper service permissions requested by the client; the exact authorization depends on its implementation. A dismissed permission prompt doesn't mean traffic capture is active. Check the logs for successful interface creation, route installation and DNS startup. If you also use a corporate VPN, it may enforce its own routes and DNS; handle any conflict according to your organization's network policy rather than trying to override managed settings. Test each tool on its own first, then determine whether they can coexist.

Waking from sleep, switching hotspots and captive portals can all change the default route. On hotel or public Wi-Fi, pause traffic capture to complete the browser sign-in, then restore the proxy and test again. If connectivity doesn't return after disabling TUN, check for a leftover system proxy on the current network service and confirm that other VPNs are stopped. Don't delete all network services, reset DNS and reinstall the client at once. Change one thing at a time to see what restores connectivity and preserve useful troubleshooting evidence.

# Chapter 04 · android

Android Permissions and Background Operation

Installation and Configuration Sources

Start with Clash Plus from the Android downloads, or consider Clash Meta for Android, FlClash or Surfboard. Check your device's processor architecture before downloading; Android devices don't all use the same architecture. If Android asks you to allow app installation from your browser or file manager, grant permission only for this installation source and restore the previous setting afterward if you prefer. If installation fails because of a conflict, check whether an app with the same name but a different signing key is already installed. Don't delete the old app's data without checking first.

On first launch, import a subscription URL or local configuration file. When using the system file picker, confirm the client actually has permission to read the file—not just that it can display the filename. Once the configuration downloads, select it and check that its proxy groups appear. If it uses fields or protocols the client doesn't support, parsing may fail or some features may be unavailable. Check the import logs; don't assume configurations are fully interchangeable just because both clients support proxies.

VpnService and How Traffic Reaches the Core

Android proxy clients typically use VpnService to create a local VPN interface and pass device traffic to the app. The system's VPN permission prompt allows the app to capture network traffic; it doesn't mean you're connected to a remote node. The configuration, proxy group and rules determine the final outbound. After granting permission, start the connection, check the system VPN status and client logs, then visit a test destination. A key or VPN icon alone doesn't prove the subscription, node and DNS are all working.

A desktop system-proxy switch doesn't map directly to Android. A manual proxy configured for a Wi-Fi network only applies to supported networks and apps; it's not the same as traffic capture through VpnService. Android generally can't run two ordinary VPN apps in the same VPN slot at once. Starting another VPN, VPN-based filtering app or firewall may displace the current client. If the connection gets replaced, check Android's VPN settings before repeatedly switching nodes—the issue may be a conflict at the traffic-entry layer.

Rules, Per-App Routing and Background Limits

Test the default configuration in rule mode before setting up per-app routing. Per-app settings choose which apps enter the VPN; domain rules choose their outbound after they do. These are separate layers. If the target app is excluded from the VPN, adding a proxy rule for its domain won't help. After changing the allowlist or exclusion list, some clients need to recreate the VPN interface. Disconnect and reconnect the target app to avoid an existing connection continuing on its previous route.

Battery-saving policies can restrict a client when the screen is locked. If the connection only drops in the background, check the app's battery settings, background activity, auto-start and any vendor-specific task locking features; the locations vary by device. Allow only the background activity the client needs, then check whether its logs continue while the screen is locked. Don't exempt every app. For more on vendor-specific settings, see VpnService Permissions and Battery Optimization Allowlisting. A VPN running continuously uses device resources, and behavior can vary by device.

Private DNS, Network Switching and Updates

Android Private DNS, browser secure DNS, client DNS and mobile network DNS may all be active at once. If the configuration enables DNS capture, keep to one understandable resolution path and note the original Private DNS setting before comparing results. Don't change servers, Fake-IP and every DNS toggle just because a lookup failed. First check whether the request enters the core, then see whether the resolution error affects only particular domains. Check IPv6 alongside route capture; the network icon alone doesn't tell you whether it works.

If the connection drops briefly when switching from Wi-Fi to mobile data, wait for the network to come up, reconnect the client and check whether the subscription URL is reachable on the new network. Hotspot traffic from connected devices may not pass through the phone's VPN; successful browsing on the phone doesn't prove hotspot sharing is covered. Subscription auto-updates can also be affected by background limits and network availability. If needed, update manually in the foreground and verify the active configuration. Keep any settings you need before updating the app, and only remove old app data when migration or a signing conflict requires it.

# Chapter 05 · ios

iOS Configuration Import and VPN

Get Clash Plus and Check Configuration Support

Open Clash Plus from the iOS downloads via its App Store page. You can also find app details on the official site, clashplus.io. Read the store listing's system requirements and feature notes before installing. Clash configuration is an ecosystem format; support for importing it doesn't mean every client implements every mihomo field. For advanced DNS, scripts or specific protocols, confirm the app's supported features instead of assuming a desktop configuration will work unchanged.

iOS proxy apps use system network extensions to capture traffic; they don't run a desktop core process directly. Don't look for the exact same service installation buttons as on Windows or expect desktop virtual network adapter settings to map one-to-one to a phone. Check whether the configuration is recognized, the VPN extension starts successfully and target connections follow the expected route. If the interface lacks a switch with a familiar name, consult the app's documentation rather than importing an unknown system profile to add it.

Subscription URLs, Files and QR Codes

On the configuration page, choose URL import, paste the full subscription address and fetch it. Check that the scheme, path and query parameters are intact; avoid trailing spaces or line breaks. If the client supports file import, select a YAML file through the system file picker or share sheet. If the file is in cloud storage and hasn't downloaded locally yet, wait until it's available before importing. When the import finishes, set it as the active configuration and confirm the expected nodes appear in its proxy groups—not just as a subscription entry.

A QR code is usually just another way to share a subscription URL or node link; it won't fix an incompatible format. Check the source before and after scanning, and never post a subscription QR code in a public forum. If the client isn't listed in the system share sheet, return to the app and use a supported import method rather than repeatedly trying to open YAML in a browser. If a subscription request returns a login page or error message, the app may report a parsing failure. Resolve access to the subscription first, then check format support.

VPN Permission and First Connection Test

Select an active configuration and node, then start the connection. iOS may ask to allow a VPN configuration and confirm with device authentication. This permission lets the app manage a VPN connection; it doesn't prove that the subscription is valid. After authorization, return to the app and check the startup result, then open a browser and visit a test destination. If the app has a connection or log view, check the destination domain, rule and outbound. If it doesn't provide enough detail, compare access to a known direct destination and a known proxied one, but don't treat one site's failure as a complete diagnosis.

Rule mode is a good default for testing. Global mode generally sends connections entering the app to its global policy, but the name doesn't mean all system traffic is captured; the actual scope depends on iOS and the app's implementation. Direct mode also doesn't necessarily disconnect the VPN—DNS and route capture may remain active. To test with the original network fully restored, stop the app's VPN connection and try the same destination again so that capture state is the only changed condition.

Network Changes, DNS and Maintenance

Other VPN apps, network policies on managed devices and system privacy features can all change the route traffic takes. If connections replace one another, check the system VPN list to see which app is active. Don't remove enterprise configurations that aren't part of the current client. Public Wi-Fi captive portals may require you to pause the proxy and sign in first. Restore the connection afterward and verify DNS resolution rather than repeatedly switching nodes before the network login is complete.

If problems start after locking the screen or switching between Wi-Fi and cellular, reconnect in the app first and check whether the issue affects only one network. Low Power Mode, background scheduling and network extension status can all play a part; whether the app stays open on screen isn't the only indicator. After a subscription update, check whether the selected proxy group is still available. If a node was removed or renamed, select a replacement. For the full workflow, see iOS App Download and Configuration Import. For troubleshooting, rely on options the current client actually supports.

# Chapter 06 · linux

Linux Desktop Apps and Core Services

Choose a GUI or Standalone Core

For desktop use, start with the recommended Clash Verge Rev from the Linux downloads, or try FlClash. Check your distribution's package manager, processor architecture, desktop session and package requirements; DEB support doesn't mean compatibility with every Linux environment. For a server or router, see the mihomo Core downloads. A standalone core doesn't provide a GUI to manage subscriptions, system proxy settings or startup permissions. You'll need to configure those yourself and know which configuration directory and user the process uses.

After installing a desktop client, launch it as a regular user first and confirm the logs and configuration page work. Install required system components using methods supported by your distribution; don't download identically named shared libraries from unrelated sites. If the desktop menu has no app icon, use the launch entry provided by the package to check for startup errors before troubleshooting desktop integration. On a server, test the core and configuration in the foreground before registering a startup service. This makes errors easier to see and avoids a service restart hiding the first failure.

Import a Configuration, Check Paths and Validate Syntax

GUI users can import a subscription from the configuration page and set it as active. Standalone core users should put the complete YAML file in a known directory and check that the process can read it. Restrict access to configurations containing credentials, and secure backups the same way. Relative paths usually depend on the core's working or configuration directory. If rule sets, geodata or local provider files can't be found, check how paths are resolved instead of copying the same file into several directories and hoping one works.

mkdir -p "$HOME/.config/mihomo"
chmod 700 "$HOME/.config/mihomo"
mihomo -t -d "$HOME/.config/mihomo"
mihomo -d "$HOME/.config/mihomo"

These commands assume mihomo is installed and executable, and that the complete configuration has been saved as config.yaml in this directory. Test the configuration before starting the core in the foreground. A successful test means the configuration was accepted; it doesn't guarantee remote nodes are reachable or external rule resources will update at runtime. For permission errors, check directory ownership and the process user. Don't make the entire configuration directory writable by everyone.

Test Desktop Proxy Settings and Terminal Traffic Separately

Linux desktop environments store system proxy settings differently, and apps vary in whether they follow them. After enabling the system proxy in the GUI, check the active desktop network settings and see whether the target app's connection appears. Command-line tools often need explicit proxy arguments or environment variables. A working browser and a failing package manager don't automatically indicate a node problem. Testing with temporary environment variables is easier to undo than changing every shell startup file; decide whether to persist the settings only after testing.

curl --proxy http://127.0.0.1:7890 --head https://example.com
export http_proxy=http://127.0.0.1:7890
export https_proxy=http://127.0.0.1:7890
export no_proxy=localhost,127.0.0.1,::1
unset http_proxy https_proxy no_proxy

https_proxy still points to an HTTP proxy here. HTTPS destinations tunnel through that proxy; the local proxy listener itself doesn't need TLS. Tools vary in their support for uppercase variables and bypass lists, and commands run with elevated privileges may not inherit your current environment. Don't add proxy variables to every system service to make one tool work. Check the tool's documentation and which user runs it, then limit the settings to the right scope.

TUN, Service Management and Firewalls

TUN uses a virtual network device, routes and DNS, and typically requires appropriate network permissions. Containers also need the host to expose the required device and capabilities; a correct configuration inside a container doesn't mean host traffic is being captured. If your desktop client has a service mode, follow its installation process. With a standalone core, use your distribution's service manager only after understanding the permission boundaries. Don't run all graphical apps as root for convenience.

When registering a service, specify the binary path, configuration directory and run user explicitly. Set it to start automatically only after foreground testing succeeds. To troubleshoot, first check whether another core is already using the port, then review the service logs for the exit reason. Firewalls, other VPNs and container networking can all alter routes. Opening a mixed port doesn't mean it should be reachable from the internet. Keep the listener local by default. If LAN sharing is required, consider the access scope, authentication, host firewall and trustworthiness of the network; don't expose the proxy to arbitrary sources.

# Chapter 07 · configuration-faq

Configuration FAQ and Troubleshooting Steps

Identify the Layer Where the Failure Occurs

Start by recording the scope: can't import the configuration, can't start the core, all apps fail, or only one destination has a problem? For import failures, check the subscription response, file format and parsing errors. For startup failures, check ports, paths and permissions. If connections appear but access fails, check rules, DNS, nodes and the destination response. Change one variable at a time and save log excerpts from before and after each test. Updating the subscription, changing modes, enabling TUN and altering DNS all at once may restore access temporarily, but you won't know why—and it will be harder to reproduce the fix.

A timeout in the logs doesn't point to one cause. It may occur while fetching a subscription, querying DNS, handshaking with a node or reaching a destination. Check the target address and surrounding log lines. A connection refused error is a reason to check the listener and port; for certificate errors, start with the clock, destination name and network environment. Raising the log level temporarily can reveal more, but restore an appropriate level once troubleshooting is done to avoid recording excessive domain and connection details. Redact sensitive fields before sharing logs.

Rule Matching and the Actual Proxy Group Outbound

Rules are generally matched in order; the first match selects the specified policy. A custom rule placed after the final MATCH usually won't be reached, and referencing a nonexistent proxy group can make the configuration invalid. The example below assumes the configuration already defines a proxy group named PROXY. It illustrates matching only and isn't a complete subscription. GEOIP matching depends on the relevant data and resolution conditions; you can't infer whether a domain or IP rule matched just from the destination site's name.

rules:
  - DOMAIN-SUFFIX,github.com,PROXY
  - GEOIP,CN,DIRECT
  - MATCH,PROXY

If a proxy rule matches but traffic still goes direct, check whether the selected proxy group points to DIRECT or nests another group that does. After switching to global mode, check the global policy selection rather than assuming it automatically uses the node you picked earlier. For details, see Rule, Global and Direct Modes Explained. When testing a new rule, close existing connections and reconnect; long-lived connections may not switch to a new outbound immediately after a rule change.

How Fake-IP, DNS and TUN Work Together

Fake-IP makes DNS return virtual addresses that the core maps back to domain names for routing. These are not remote node addresses, and their presence alone isn't evidence of DNS poisoning. An app may cache a virtual address after the client exits or the traffic-capture path changes, leaving DNS resolution and routing out of sync. Restore a consistent DNS and traffic-capture setup first, then restart the app or clear its relevant cache. Don't add virtual addresses to persistent host mappings.

Enabling TUN doesn't guarantee that every DNS request is handled as expected. App-level encrypted DNS, system Private DNS, IPv6 routing and other VPNs can all affect the path. Check the actual requests and rules before deciding whether the configuration works. Local device names, printers and corporate domains may need access to local DNS resolvers; use targeted DNS policies or Fake-IP exclusions where needed rather than sending every domain direct. For background, see DNS and Network Stack Terms.

Keep Configuration Recoverable and Know What Updates Change

Before automatic subscription updates, preserve local override rules. After updating, check proxy group names, node selections and generated DNS settings. If the upstream renames a group, an old override may refer to an object that no longer exists. When a configuration loads but behaves differently, inspect the final effective configuration rather than only the editor's source file. The client, core and subscription have separate update paths; an update to one doesn't mean the others changed. Record each of them separately when troubleshooting.