Clash for Every Platform
Setup Guide

Before You Begin

Clients, Cores, and Subscriptions

In the Clash ecosystem, the client provides the interface, stores configurations, and uses system networking features. The core parses configuration, matches rules, and establishes connections. Downloading a client does not give you access to a proxy service. To connect, you also need a valid node configuration or subscription link, and a network where you’re allowed to use the service. Start by choosing the right app for your platform on the client download page, then get a subscription from your provider. Clash Plus is the first option to check for Windows, macOS, Android, and iOS; for Linux, start with Clash Verge Rev. Apps with similar names may use different cores, so compatibility depends on the protocols and fields they support.

A subscription may contain a complete Clash YAML configuration, nodes only, or a format that requires a provider-specific import option. Before importing, confirm what the link is for. Don’t mistake an account page, payment page, or web share link for a subscription URL. Treat subscription links like passwords because they often contain account identifiers. When troubleshooting, share the response status and error text—not the full URL—in public forums. Redact node passwords, tokens, and API keys from screenshots. If a link has been exposed, reset it in your provider’s account dashboard and replace the saved link in your client.

System Architecture and Installation Scope

Before downloading, check your system architecture and package type. Windows commonly uses x64 or ARM64; for a Mac, identify whether it has Apple silicon or an Intel processor. On Android, check whether you need an ARM64, ARM, or universal package. On Linux, consider your distribution’s package format. You can’t reliably determine processor architecture or system bitness by looking at a device. Check system information or use a system command. The download page lists the packages available from this site. If a client has no package for your architecture, choose one that supports your device rather than renaming an installer from another platform and trying to install it.

Importing a Subscription and Initial Checks

In the client’s configuration or subscription section, add a new entry, choose the URL import option, paste the link, and download it. After the import, check that a configuration name, update time, and proxy groups appear, then set the configuration as active. Some clients separate adding an entry from enabling it; downloading alone won’t change the configuration in use. If you import a local file, keep the original as a backup. Direct edits to a client-generated runtime configuration may be overwritten on the next update. For lasting changes, use the client’s supported override, merge, or scripting features.

If an import fails, first check the device clock, basic network access, and whether the link is complete. If the subscription server returns a web page, the client may report a parsing error; that’s separate from whether nodes can connect. Don’t assume every failure is a format issue or keep switching cores to mask an expired account. Confirm the subscription is still valid, then check the client logs for network errors or field-related messages. If updating requires a proxy, connect with a working configuration first. If you can’t connect during initial setup, download the configuration file using a method your provider allows, then import it locally.

Proxy Groups, Modes, and Verification

For your first connection, use Rule mode and manually select an available node from one of the configuration’s selection groups. Global mode can help as a short-term comparison, but it changes how requests that would normally connect directly are routed. Direct mode doesn’t use proxy nodes. A latency test only measures the test endpoint; it doesn’t prove every website will work or predict your actual download speed. Open a familiar site, then check the connection log for the matched rule and outbound route. Once you’ve confirmed the request uses the intended proxy group, consider testing another region, protocol, or endpoint. For help choosing a node, see Proxy Nodes Compared: Latency, Traffic Multipliers, Regions, and Protocols.

Windows Setup

Download, Install, and Migrate

Go to the Windows downloads. Check Clash Plus first, then compare Clash Verge Rev, FlClash, and Clash Nyanpasu if needed. Before downloading, check your system type under Settings → System → About and choose a package actually listed on the download page. During installation, review the destination folder and permission prompts, then launch the app from the Start menu. For a portable package, extract it to a stable local folder. Don’t run it from the archive preview or store it in a temporary folder that may be cleaned automatically. If security software raises an alert, verify the file source and the specific behavior it flagged rather than disabling all protection.

Clash for Windows is no longer maintained. Its archived releases may help with older setups, but they aren’t recommended as the default choice for a new device. Before moving to a maintained client, back up your subscription link, rule changes, and proxy group selections. Then quit the old app and turn off its system proxy. Client databases and interface settings may not be compatible, so the most reliable way to migrate is usually to import the subscription again—not copy the entire app folder. Check whether the new core supports any custom scripts or fields used by your old configuration. Themes, shortcuts, and startup options will generally need to be set up again.

Importing a Subscription and Setting Up the System Proxy

Add and update your subscription on the configuration page, enable it, then open the proxy page and choose Rule mode and an available node. Next, turn on the system proxy from Settings or the home page and check the listening port shown by the client. The Windows system proxy mainly affects apps that respect the system proxy settings; it doesn’t route all network traffic. A separate browser proxy extension may override the system settings. During troubleshooting, configure the browser to use the system proxy so you aren’t testing two proxy settings at once. Other VPNs, accelerators, or old clients may also keep changing the proxy address, so quit them before testing.

In Windows Network & Internet settings, check that the manual proxy address points to your own device and that the port matches the client. If the address points to your device but the client has quit, the browser will try to connect to a service that isn’t running, making it seem as if the entire network is down. Turn off the system proxy first to restore basic connectivity, then restart the client. Don’t assume that a webpage loading in the browser proves the configuration is correct: the request may have gone direct or been served from cache. Check the client’s connection list for the new request and review its rule and policy to see how it was actually routed.

TUN, Service Mode, and Permissions

If an app doesn’t respect the system proxy, you can enable TUN if your client supports it. TUN uses a virtual network adapter and routing to capture traffic, so it usually requires more permissions than a standard system proxy. Some clients need a helper service installed; others require administrator authorization. Follow the prompts in your client. After enabling TUN, check the logs for failures creating the adapter, adding routes, or configuring DNS. Running the entire interface as administrator all the time isn’t necessarily the best solution. If the client offers a service mode, configure it as documented, then verify that the service starts successfully.

TUN may compete with other VPNs for the default route, and corporate security software may block virtual network adapters. Before testing, note your existing VPN and network settings, then temporarily use only one traffic-capturing tool. If enabling TUN cuts off your connection, turn it off and check whether the system proxy still works. Then investigate permissions, routes, and DNS separately. If the system proxy works but TUN doesn’t, you usually don’t need to buy a new subscription or repeatedly reinstall the client. The node connection may be fine; the problem is more likely in the local traffic-capture layer.

UWP Loopback and Command-Line Proxies

Some apps running in Windows app containers can’t access a local proxy port directly. You may see the browser work while an app from the Microsoft Store fails. First check whether the app runs in a restricted container, then consider using the client’s loopback exemption tool if available. Don’t grant access to every app—configure only the ones that clearly need it. TUN is another option, but it requires client and system support, and you’ll still need to check routing. Desktop apps, conflicting browser extensions, and app container restrictions are different issues. A Microsoft Store download alone doesn’t mean an app needs a loopback exemption.

Command-line tools don’t necessarily use the Windows system proxy. You can test the local HTTP proxy with an explicit argument, replacing the port below with the one shown in your client. Use curl.exe to avoid confusion with a same-named alias in some PowerShell environments. If the explicit proxy works but the usual command doesn’t, check the tool’s supported environment variables or proxy settings instead of changing your subscription.

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

Launch at Startup and Restoring Connectivity on Exit

Enable launch at startup only after you’ve confirmed a manual connection works. Check what each option actually means: “start the client,” “start the core,” and “restore the system proxy” may be separate settings. Launching at sign-in doesn’t necessarily start a system service, and a helper service won’t necessarily select a configuration for you. After restarting, check the tray icon, active configuration, and proxy toggle, then test a request. Before quitting, consider turning off the system proxy and TUN, especially when migrating or uninstalling. If you still can’t connect after uninstalling, check for leftover system proxy settings and VPN routes before resetting all network settings.

macOS Setup

Choosing a Build and Launching for the First Time

Check About This Mac for your chip or processor, then choose a package from the macOS downloads. Clash Plus is the first option to check, with Clash Verge Rev and FlClash as alternatives. ClashX Meta is no longer maintained, so check compatibility carefully if you’re using an archived release. Don’t identify Apple silicon or Intel packages by file size alone. Whether macOS can run an app built for another architecture through a compatibility layer depends on the app’s requirements; use a native build when available. Quit older clients before installing to avoid two menu bar apps listening on ports or changing proxy settings at the same time.

A common installation method is to open the disk image, drag the app into Applications, and launch it from there. Don’t keep running it from the disk image: after ejecting it, restarting, or updating, you may not be able to find the app. If you see a security prompt the first time you open it, confirm the download source and follow the available option under Privacy & Security. Don’t disable macOS security protections for a single app. If macOS says the app is damaged, try downloading it again and check system compatibility before running online commands that remove restrictions in bulk; they may affect more files than intended.

Enabling the Configuration and Setting Up Network Proxies

Import the subscription on the configuration page and set it as active, then choose Rule mode and a node on the proxy page. After turning on the system proxy, check the network service in use. Wi-Fi, Ethernet, dock interfaces, and other network locations may each have their own proxy settings. Some clients configure the current service for you, but check again after switching networks. If the browser works but the terminal doesn’t, check whether each one uses the system proxy instead of assuming both follow the same network path.

In Network settings, check whether web proxy, secure web proxy, or SOCKS proxy matches the client’s listening capabilities. A mixed port accepts both HTTP and SOCKS5 requests, but each protocol still needs to be entered in the correct system field. The address is usually the local loopback address, not the subscription server. A subscription URL retrieves configuration; it isn’t the address of the local proxy service. Always recheck the port after switching clients—don’t assume the old app’s default port applies to the new one.

Helper Services and TUN Traffic Capture

TUN and enhanced traffic capture usually require additional network permissions, and some clients install a helper service. Before granting permission, check which app is requesting it and confirm it came from the client you just installed. If the toggle immediately switches off after authorization, check the logs for service connection, adapter creation, and routing details. A running menu bar app doesn’t guarantee its helper service is working. Updates, moving the app, or restoring a backup can also leave the service and main app out of sync. Start with the client’s service check or repair option.

Management policies on company devices may restrict proxies, network extensions, or helper services; repeatedly clicking the toggle won’t resolve those restrictions. Use the client only within the limits of your device management policy. Other VPNs, virtual machine software, and container networks may also add routes. If TUN causes problems on only some subnets, first identify the affected destination addresses and check existing routes. Don’t clear every system route. Temporarily quit other traffic-capturing apps and compare results; this preserves evidence and makes it easier to restore your work setup.

Terminal, DNS, and Network Changes

Terminal tools often need an explicit proxy. The commands below check the local listener and request path; use the port shown in your client. The second command reads the current system proxy settings without changing them. If the request succeeds, configure the tool using its supported proxy settings. Adding variables to your shell configuration affects future terminal sessions, so test them temporarily in the current window first. Make sure you know how to clear them when quitting the client, or development tools may keep trying to connect to a closed local port.

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

After switching Wi-Fi, connecting to a phone hotspot, or waking from sleep, the client may need to reconnect. Check basic network access first, then the core and proxy toggle. If only domain names fail, check the DNS logs and the current network’s resolver settings. Hotels and public networks may require web-based sign-in. Temporarily turn off the proxy to open the sign-in page, then turn it back on afterward. Don’t permanently change DNS across all networks because a sign-in page failed on just one; that can spread a local issue to other networks.

Launch at Login, Migration, and Uninstallation

If you want the client to launch at login, check its settings and the system login items. Closing a window may only hide the app; use the menu bar to quit it. Check whether the core is running and listening to tell if traffic is still proxied—not whether a window is visible. Before switching clients, back up subscriptions and local rules, then turn off the old app’s system proxy. Uninstall helper services using the client’s recommended method. Afterward, check whether the current network service still has a local proxy configured. Remove only confirmed leftovers; you don’t need to rebuild your entire network setup just to migrate apps.

Android Setup

Package Architecture and Choosing a Client

Start with Clash Plus in the Android downloads, then compare Clash Meta for Android, FlClash, or Surfboard based on your configuration needs. ARM64 is for compatible 64-bit environments, ARM is for compatible ARM environments, and a universal package may be an option when the client offers one and you’re unsure of the device architecture. A 64-bit-capable processor doesn’t guarantee that the operating system can install every ARM64 app. Check the actual runtime environment on older devices or custom systems. If you see “App not installed,” check system compatibility, available storage, and signature conflicts before trying to rename and reinstall the same package.

To update an app using an installation file, the package name and signature must match the existing app. A build from a different branch or signed with a different key may not install over it. Back up subscriptions and local changes before uninstalling, since app data may be deleted. If Android asks you to allow installs from a source, grant permission only to the file manager or browser you’ll use to open the package, then revoke it after installation. Menus vary between Android brands, but check the source permission, app compatibility, and existing installation—not whether every security prompt is turned off.

Subscriptions, Active Configurations, and Rules

Open the configuration page, add the link using the remote subscription option, download it, and explicitly select the configuration you want to run. After downloading, check the proxy page for the expected groups and nodes before connecting. Clash Meta for Android and FlClash may use different menu labels, but the steps are similar: get a configuration, set it as active, choose a policy, and authorize the system connection. Surfboard uses a different configuration format from Clash YAML. Use a format your provider explicitly supports rather than importing an incompatible file and hoping a different mode will fix it.

Remote updates often replace subscription content. Whether local names, added rules, and selected groups are preserved depends on the client. For rules you need to maintain, use a separate override or local configuration supported by the client, then check the result after each update. Providers may rename proxy groups, which can invalidate your previous selection. If nodes are still listed but traffic isn’t taking the expected route, check how the current group is referenced. Don’t rely only on a node’s test button; confirm that the active rules actually point to that group.

VpnService Authorization and Traffic Capture

Android usually routes traffic to the client through the system VpnService. The first time you connect, you’ll see a VPN connection request. After you approve it, Android may display a key or VPN status icon. That means the system has allowed a local traffic-capture tunnel; it doesn’t mean a proxy node connected successfully. If you deny the request, try starting the client again and check the system prompt. If the device is in a work profile or managed mode, or has an always-on VPN policy, system rules determine whether another connection is allowed. Don’t mistake a policy restriction for a subscription format error.

Usually only one VpnService can be active for a user at a time. An ad blocker, firewall, or another VPN may use the same system service. Close other related apps before testing the current client. If per-app proxying is available, distinguish carefully between “proxy selected apps” and “exclude selected apps.” These options mean opposite things, so it’s easy to exclude an app you intended to proxy. Some clients require a reconnect after changing the list. Reopen the target app and check its new connection entries to verify the change.

Background Operation and Disconnects When the Screen Is Off

If the client works while the screen is on but stops after the screen has been off for a while, check battery optimization and background restrictions first. In the app’s system settings, allow background activity and use the options provided by your device to exempt it from battery optimization, enable auto-start, or lock it in the background. Not every device offers all these options, and none guarantee uninterrupted operation—check how your device actually behaves. The persistent notification for a foreground service is usually tied to ongoing operation. Don’t disable necessary notifications just to hide the status. Background limits and notification permissions are separate settings; check them separately.

Try a repeatable test: connect and note the time, turn off the screen, then reopen the same app after a while and check whether it reconnects. Review the client logs for a restart or network change. If the process is still running but fails only on mobile data, check data permissions, Data Saver, and network conditions. If the process has stopped, the system may be terminating it. For more details, see VpnService Permissions and Battery Optimization Exceptions, but look up the specific menu on your device.

Hotspot Sharing, DNS, and Reconnecting

A VPN connection on your phone doesn’t mean other devices using its hotspot are also routed through the proxy. Hotspot traffic may fall outside the app’s VpnService capture, so don’t assume sharing works just because the phone itself can connect. To use a computer’s proxy on a tablet, follow a LAN sharing setup: configure the tablet with the computer’s proxy address and port, and make sure the computer accepts connections. Android Private DNS, browser Secure DNS, and client DNS may also use different resolution paths. Compare them one at a time only when you see a specific domain error; don’t turn off every DNS feature at once.

Before quitting, uninstalling, or switching clients, stop the current connection and check the system VPN page for configurations that need attention. Keep only the subscription and local rules you need in your backup. Don’t leave exports containing account details in shared storage or folders that are automatically made public. After switching, check app proxy settings and background permissions again; system permissions granted to the old client usually don’t carry over.

iOS Setup

App Store Installation and Device Compatibility

On iPhone or iPad, visit the Clash Plus App Store page from the iOS downloads, or go directly to the Clash Plus App Store listing. The official website is clashplus.io; check that domain if you need to verify the product page. Before installing, review the device and OS compatibility shown in the App Store. Use its current requirements rather than those for installers on other platforms. Once installed, open the app and prepare to import your subscription. If your device already has a VPN configuration, note what it’s used for and whether it’s connected.

This page covers the client on your device and its system connection settings; you still need a valid configuration for a proxy service. Successful App Store installation, opening the app, and connecting to a node are three separate checkpoints. If the app won’t open, check available storage, OS compatibility, and installation status. If it opens but can’t download a subscription, check the link and network. If the subscription contains nodes but they won’t connect, check authorization and the node connection. Working through these steps in order helps prevent an installation issue from turning into a complete account or network reconfiguration.

Importing, Updating, and Selecting a Subscription

In Clash Plus, find the configuration or subscription section and add a remote link using the option shown in the current interface. Before pasting, make sure you copied the complete subscription URL—not explanatory text from a message. After downloading, check that the configuration is enabled and that proxy groups appear. If file import is supported, use a compatible configuration file from your provider. The returned format must be supported by your client. Don’t assume every subscription works just because its name includes Clash, especially if it uses newer protocols or core-specific fields.

Before updating a subscription, note the proxy group you selected and any local settings you need. An update may rename nodes, rearrange groups, or change rules. Afterward, check that the intended outbound route is still selected. If the subscription has multiple selection groups, check which one the final request matches instead of choosing a low-latency node on the home screen and assuming it’s in use. An automatic selection group may switch routes based on its test target. To keep a specific region or connection behavior, use the manual selection group provided by the configuration and confirm the rules actually reference it.

VPN Authorization and Connection Status

When you connect for the first time, the app may request permission to add a VPN configuration. The system will ask you to confirm or authenticate on the device. After approving, return to the app, continue connecting, and check the VPN status in Settings. This system permission enables traffic capture; it isn’t where you enter your proxy provider account password. If no authorization prompt appears or the connection drops immediately, check for another active VPN, a management policy, or a pending system configuration, then review the error in the app. Reimporting the same subscription usually won’t fix a system permission issue.

iOS handles connections differently from desktop system proxies and usually relies on a network extension permitted by the system. Don’t apply desktop TUN toggles, service installation steps, or command-line environment variables directly to a phone. If the app offers on-demand connections, rules, or other network options, configure them according to the current feature documentation. Before enabling them, understand how they behave on Wi-Fi, cellular, and while the device is locked. On a company-managed device with an existing VPN, follow your organization’s policy rather than removing a work configuration to run two traffic-capture tools at once.

Wi-Fi, Cellular, and Domain Troubleshooting

For an initial test, use a stable Wi-Fi connection, choose Rule mode and an available node, then open a target site and check the connection log. Repeat the test over cellular. If only one network fails, check its basic connectivity and the app’s cellular data permission. If both fail while another device works with the same node, check the current device’s configuration and authorization. Switching networks interrupts existing connections. Record brief reconnects separately from persistent failures; a momentary drop during a switch doesn’t mean the subscription has expired.

Public Wi-Fi often requires sign-in through a captive portal. Complete that step before enabling the proxy. If the sign-in page won’t load with the proxy on, pause the connection, finish signing in, then reconnect. For DNS issues, check whether the client reports a DNS error and whether privacy or network features are changing the request path. One website failing doesn’t automatically mean system DNS is broken: the request may match a direct rule or the site may block the current exit. Compare Rule mode with a brief test in Global mode, then check the connection log. That’s usually more useful than repeatedly changing system settings.

Background Connections and Sharing with Home Devices

Closing the app’s interface may not stop an active network extension. To disconnect, use the connection toggle or check the system VPN page. Whether a connection survives force-quitting the app depends on the implementation and system state; don’t judge traffic routing by whether the app appears in the background. After a long break, check VPN status and confirm the subscription is still valid. If a connection fails after an app or system update, disconnect and reconnect, and note the exact error text. Only change a configuration or permission when there’s a specific indication that it’s the cause.

To route an iPhone or iPad through a computer’s proxy, set up a manual HTTP proxy in the Wi-Fi details for a trusted LAN. Enter the computer’s LAN address and the actual listening port. This affects only requests that follow that Wi-Fi proxy setting; it isn’t equivalent to full traffic capture by a mobile client and usually won’t apply to cellular data. Turn off the proxy setting before leaving that network, or the device may keep trying to reach a computer that’s powered off. For details on sharing limits and firewall settings, see Mixed Ports and LAN Sharing Guide.

Linux Setup

Desktop Clients and the Command-Line Approach

On Linux, choose an approach that fits your environment. Desktop users can check Clash Verge Rev in the Linux downloads, followed by FlClash. For servers, routers, or scripted setups, choose mihomo from the core downloads. A desktop client handles configuration and interaction; a command-line core requires you to manage files, processes, and traffic capture yourself. Installing a core won’t automatically configure the desktop proxy. Before you begin, run uname -m to check the architecture and confirm the package format supported by your distribution. DEB and RPM packages aren’t interchangeable.

For desktop installations, prefer your distribution’s package manager to keep dependencies and uninstall records in order. Use the file actually provided on the download page, open it with the system installer, or run the package manager from your downloads folder. Don’t grant administrator access to an unknown script. If the app won’t start, launch it from a terminal and check for missing libraries or a graphics environment error. A desktop app failing to display on a server without a graphical session doesn’t mean the core lacks Linux support. Use the command-line approach instead of installing unrelated desktop components.

Desktop Subscriptions and Application Proxies

Importing a subscription in a graphical client works much like it does on other desktop platforms: add the link, download it, set it as active, then choose Rule mode and a node. After enabling the system proxy, check the proxy settings for your desktop environment. GNOME, KDE, and individual apps don’t all read system proxy settings the same way. Terminals, containers, and system services usually don’t inherit desktop settings automatically either. Test in a browser first, then use an explicit proxy argument to test command-line tools. This helps distinguish node issues from apps that aren’t using the proxy.

If your graphical client supports TUN, check the helper service, core permissions, and routes—not just whether the toggle is on. Creating a TUN device on Linux usually involves /dev/net/tun and network permissions. Containers also need explicit authorization from the host. Giving an ordinary app elevated privileges indefinitely isn’t appropriate for every environment. Use the service method provided by the client, or configure permissions only after you understand their scope. Take special care with remote SSH sessions: don’t change the default route through your only connection path without a way to recover.

mihomo File Layout and Configuration Validation

For a command-line setup, extract the core for your architecture and place it in a stable location. The examples below use /usr/local/bin/mihomo for the executable and /etc/mihomo/config.yaml for the configuration file. Adjust the paths to suit your setup, but keep the commands and service file consistent. Create the directories, save a compatible configuration you’ve obtained to the specified file, then check its syntax. A successful check only means the configuration can be loaded; it doesn’t prove that your account or target network works. After starting the service, check the logs and test an actual request.

sudo install -d -m 700 /etc/mihomo
sudo chmod 755 /usr/local/bin/mihomo
sudo /usr/local/bin/mihomo -t -d /etc/mihomo -f /etc/mihomo/config.yaml

To check whether the core can start, use the minimal direct-connection configuration below. It contains no proxy nodes and provides no proxy exit. It only tests the listener, logs, and basic configuration format. For actual use, replace it with a valid subscription configuration or add nodes and proxy groups once you understand how the fields work. Binding only to the local device and keeping LAN access off provides a safer starting point. Don’t expose the management interface to the public internet for convenience.

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

Running mihomo with systemd and Checking Logs

On a systemd-based distribution, you can run the core as a service. The example below is a starting point for local HTTP or SOCKS listening without TUN, using an unprivileged dynamic user. The service user must be able to read the configuration directory, and any file paths in the configuration must be accessible. The example stores runtime data in a state directory, separate from the configuration and writable data. If the service needs to read local rule files, grant the required read access separately. Don’t make an entire directory containing credentials writable by everyone.

[Unit]
Description=mihomo local proxy
Wants=network-online.target
After=network-online.target

[Service]
Type=simple
DynamicUser=yes
StateDirectory=mihomo
ExecStart=/usr/local/bin/mihomo -d /var/lib/mihomo -f /etc/mihomo/config.yaml
Restart=on-failure
RestartSec=5
NoNewPrivileges=yes

[Install]
WantedBy=multi-user.target

Save the file as /etc/systemd/system/mihomo.service. The directory above is readable only by the administrator, so before enabling this dynamic-user example, make the configuration available to the service. You can use systemd credentials or switch to a dedicated fixed user with precise read permissions. Don’t enable the example unchanged and ignore the permission mismatch. For a dedicated user, update the service’s user field and directory ownership too. A TUN deployment needs additional network permissions and routing design; this example doesn’t cover that setup. Once permissions are in place, reload systemd, enable the service, and check the logs. If it fails, start with the specific error message.

sudo systemctl daemon-reload
sudo systemctl enable --now mihomo
sudo systemctl status mihomo
sudo journalctl -u mihomo -b --no-pager

Remote Access Security and Updating

After starting the service, test the listener with an explicit proxy request before changing all of the server’s outbound routes. If you need to share access, restrict the listening interface, source network, and firewall rules. Management interfaces and proxy ports serve different purposes and need separate access controls. Before updating the core, back up the configuration and service file. Stop the service, replace the binary, test the configuration, then restart it. If an error appears, restore the original files rather than masking a compatibility issue with repeated restarts. For a full comparison of desktop and command-line setups, see Linux Desktop Clients and systemd Deployment.

Configuration Issues and Troubleshooting Steps

Ports, Rules, and Overrides

First identify which layer has the problem: whether the file parses, the node connects, the rules select the intended route, or the app uses the local proxy. A mixed port accepts HTTP and SOCKS5 requests. The system proxy tells some apps which address to connect to; TUN captures traffic at a lower level. These features are related, but they aren’t interchangeable. If the logs show a listener failure, check whether the port is in use. If a policy can’t be found, check the proxy group references. If the request appears in the connection list but uses the wrong route, check rule order. Identify the failing layer before making changes so each adjustment has a clear purpose.

Rules are generally matched from top to bottom. Place the final MATCH rule after any rules that need to take priority. An outbound name in a rule must exactly match an existing node or proxy group; case, spaces, and renaming can all break the reference. In the example below, PROXY must already be defined as a policy in the current configuration. The core doesn’t create it as a generic outbound. When modifying a remote subscription, also check the client’s override order. Differences between the subscription source and the runtime configuration may be expected after merging; review the final active configuration before diagnosing the issue.

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

Common Issues: What to Check

Logs, Rollback, and Further Reading

When reporting an issue, note the operating system, client name, core version, traffic-capture method, target app, and shortest steps to reproduce it. Start with the normal log level; enable more detail temporarily only when needed, and remove account information before sharing. No request in the connection log, a request matching the wrong rule, and a failed node handshake are three different problems. Troubleshoot the relevant branch instead of repeatedly reinstalling. For core field differences, see Compatibility Guide: Original Clash, Meta, and mihomo. For terminology, consult the Glossary.

If you can’t identify the problem yet, return to the last known working state: turn off newly enabled traffic capture, restore your backed-up configuration, and make sure the system proxy doesn’t point to an app that’s no longer running. Once you’re back online, reproduce the issue one step at a time. If you need a different client, see the Client Comparison Guide. To repeat the basic setup steps, return to the Quick Start Guide. Handling downloads, configuration, and system permissions separately makes future migrations and updates easier to verify.