Choose a client for your OS, then use mihomo config examples to import a subscription and set up rule-based routing. Adjust DNS and traffic interception as needed.
Proxy groups determine the outbound route; rules decide which connections use it. Check both when troubleshooting routing, then verify that DNS returns the expected result and traffic reaches the core.
config.yaml
Proxy group names and outbound selection
Point rules to a proxy group so you can change the outbound route without rewriting domain lists. select lets you choose a member; url-test selects one based on probe results; fallback prefers the first available member in the list. This example uses built-in strategies to show how references work. After adding a subscription, check group and member names, then use the connection log to confirm which group a rule matched and which outbound was ultimately selected. Client interfaces may hide some fields, so troubleshoot against the active configuration.
Move domain lists out of the main config to manage rules independently while keeping outbound selection in rules. This example loads a local file; its contents must match domain behavior and YAML syntax. Check the core's config directory for the file path. For HTTP rule sets, configure an update interval as well. Rules are evaluated from top to bottom; once an earlier direct-connection rule matches, later rules are not checked. If traffic takes the wrong route, first confirm the rule set loaded, then check rule order.
After enabling the core's DNS, configure a reachable default upstream, then use nameserver-policy for domains that genuinely need special resolution. This policy determines which DNS server to query; it does not select the connection's outbound route. If some sites won't load, distinguish DNS failures from connection failures: compare client logs with system resolver results, and check whether the browser uses its own DNS. This example uses a standard upstream; choose one that fits your network reachability and operational requirements.
TUN receives traffic through a virtual network interface, making it useful for apps that ignore system proxy settings. Fake-IP maps addresses to preserve domain information in the core; the two features solve different problems. This example requests automatic route setup and sends traffic to the standard DNS port through the core. Before enabling it, check system permissions, the default network interface, and routes from any existing VPN. If local network services stop working, check route and DNS exceptions one at a time rather than changing several settings at once.
Some apps provide only a destination IP when they open a connection, so domain-based rules may not match. Sniffing can recover domains from supported protocol metadata, but whether that data is available depends on the connection, and a result is not guaranteed. This example checks TLS traffic on specified ports and preserves the original destination address. Compare domain and rule records for the same connection before and after enabling sniffing. If nothing changes, check the port range, protocol, and existing DNS mappings.
Keep subscription sources and local changes separate
Don't store long-term changes only in files generated from a remote subscription; a refresh may overwrite them. Define separate proxy providers for different sources, then reference them from the same proxy group. This example shows the structure with two local provider files. After combining them, check for name collisions, group members, and rule priority. If your client has an override feature, confirm whether it replaces or appends settings. Override script entry points and execution order are client-specific, not standard core interfaces.
The controller API lets compatible dashboards view connection details and switch strategies; it is not a mixed port for routing app traffic. For local management only, bind the controller to the loopback address and set a separate authentication secret locally. allow-lan controls proxy access, not the controller's own listening address. If a dashboard won't open, check the controller port, process listener, and authentication in that order. There's no need to change the proxy port or expose the listener more broadly first.
Start with your operating system and processor architecture, then compare clients. A GUI client is useful for managing configuration visually; running mihomo on its own means handling the config directory, process management, and system network settings yourself. When replacing an existing client, save local overrides and proxy group selections before quitting the old one. If a port is already in use, check that the old process has exited instead of changing ports in the subscription to work around it.
Best for desktop users who prefer a GUI and need to troubleshoot proxy behavior by app. Check your processor architecture on the system About page, then match it to the package type on the download page. To test your first connection, enable the system proxy and try a browser; consider TUN only if the target app ignores system proxy settings. Before upgrading, quit the old client and make sure its background services have stopped. If the browser still can't connect after the client exits, check whether the system proxy still points to a local port. Follow your organization's device management requirements for administrator access and firewall settings.
Check the chip details in About This Mac to distinguish Apple Silicon from Intel. Use the architectures listed on the download page; don't guess based on the system interface or device age. If you switch proxies from the menu bar, verify the status in Network settings. If the app quits on launch, check the installer architecture and system requirements first. If only one app can't connect, check that app's own proxy settings. When migrating an old setup, verify the subscription URL, local files, and proxy selection separately; don't assume the new client will use another app's working directory.
Choose an APK for your device's architecture. If the download page offers a universal package, it can reduce the chance of picking the wrong one. On the first connection, you'll usually need to approve the system VPN request. If another VPN is installed, check which app is currently allowed to establish a connection. Keep the default battery settings for an initial foreground and lock-screen test, then adjust background permissions if needed. Disconnects after locking and after switching Wi-Fi networks may have different causes: first check whether the process was suspended; for network switches, confirm that the system VPN reconnected on the new network.
Use the download page to open the client's App Store listing, then check the system requirements. After installing, follow the app prompts to add a VPN configuration and import your existing subscription. If a subscription works on desktop but won't import on mobile, check which config formats and fields the client supports before changing the server URL. Test on both Wi-Fi and cellular to see whether the issue is limited to one connection type. On devices managed by an employer or school, VPN settings may be restricted by policy; check what's allowed first.
For desktop Linux, choose a package based on your distribution's package manager and processor architecture. Desktop proxy settings may not apply to the terminal, so check separately whether command-line tools use the relevant proxy environment variables. Servers and routers are often better suited to running the core on its own, with the config directory, service user, and log location specified explicitly. If startup fails, distinguish package incompatibility from missing dependencies or insufficient service permissions. For connection failures, check the listening address and routes. These issues have different troubleshooting paths; there's no need to change both the firewall and system routes just to test.
Keep a copy of a configuration that starts successfully, then adjust routing rules and traffic interception one step at a time. Change one setting at a time and test the same destination so you can tell which setting made a difference.
Import and enable a configuration
After installing, open the Configuration or Subscription page and import an existing subscription from a URL, or import a local YAML file. When the new entry appears, select it manually and confirm that it has been applied. Seeing a config name only means it was saved; it doesn't necessarily mean the core loaded it successfully. If loading fails, check the reported field or line number, then verify indentation, referenced names, and client support for the fields used. When asking for help, share only the relevant fields and error message—not your subscription URL or full config in a public forum.
Choose a routing mode and traffic interception method
Set the mode to Rule to keep the routing logic supplied by the configuration. On desktop, start by testing apps that support system proxy settings; on mobile, establish the VPN connection as prompted by the OS. If the target app doesn't appear in the connection list, consider an app-specific proxy or TUN. The system proxy determines whether an app sends requests to the client; the mode determines how the core handles those requests. Neither setting replaces the other. If another traffic interception tool is already running, stop it for the test to avoid mistaking a route conflict for a broken subscription.
Verify rule matches in the connection log
Choose one destination expected to connect directly and one that should use a proxy, then make a new request to each. In the connection log, check the destination domain, matched rule, and final outbound route; don't judge routing only by whether a page loads. If there is a log entry but the route is wrong, check rule order and the proxy group's selected member. If there's no entry, confirm that the app's traffic is being intercepted. After changing rules, make a new connection before comparing results; an app may reuse an existing connection and show behavior from before the change.
After the original Clash project was discontinued, related clients and core projects continued evolving in their own repositories. mihomo originated as a Clash.Meta fork. It retains familiar rules, proxy groups, and YAML configuration, while developing its own fields and behavior. A project with Clash in its name doesn't necessarily share the same maintainers or release schedule. When reading older guides, first identify whether they cover the original core, a successor, or a particular GUI client. Pay close attention to differences in installation, service mode, and DNS configuration.
When migrating a configuration from an archived client, import a copy first and check the core startup log and the actual config generated by the client. A legacy field being accepted doesn't mean the old network behavior will be preserved. System permissions, routes, and DNS defaults may also have changed.
How clients and the core work together
mihomo parses runtime configuration, accepts connections, applies rules, and selects an outbound route. GUI clients such as Clash Verge Rev and FlClash add configuration management, menu controls, and connection views. Tray behavior, subscription update controls, and override editors usually belong to the UI layer; rule matching failures and module initialization errors should be checked in the core log. Two clients may both offer a System Proxy toggle but manage system settings differently. Identify which layer the issue belongs to before troubleshooting; there's no need to rewrite the entire YAML file to fix a UI problem.
If the same subscription behaves differently in different clients, check which local overrides each one applies and which proxy entry points are enabled. If you can export the active configuration, comparing the relevant fields side by side is often easier than comparing entire settings screens.
Repositories, issues, and where to report problems
Use upstream repositories to find source code, changes, and public issues. For configuration problems, search using the exact error message or field name. If an installer for a specific client won't start, begin with that client's releases and issues. When reporting a problem, include your OS architecture, traffic interception method, reproduction steps, and actual results. A minimal config helps identify whether the cause is a field interaction, network environment, or UI setting; there's no need to attach a full subscription. This site provides client downloads and documentation in Chinese. For project features and maintenance status, refer to each project's upstream records.
If the problem occurs only on a particular network, note when it started and whether switching back to the previous network resolves it. This helps maintainers distinguish environmental restrictions from reliably reproducible regressions.
Read the release notes before updating
GUI client releases and mihomo core releases follow separate tracks. A UI update may not include a core update, and replacing the core separately may fall outside the client's supported setup. Before installing, distinguish stable releases from prereleases, check the package's OS and architecture, and read notes on DNS, TUN, permissions, or config migration. After updating, test startup, subscription loading, direct connections, and proxy routing with your existing config. If something breaks, keep the old config and notes on how things worked before the update so you can roll back or isolate the change.
You don't need to update the client while also replacing rule sets, changing upstream DNS, or enabling a new mode. Make upgrades and config changes separately so if something breaks, you'll know which step to undo first.
Get mihomo source code
Use this command to browse the source code. To install a ready-made client, use the download page. To build the core, follow the repository's setup instructions.
Trace the forks that followed the end of development on the original Clash core. Learn how mihomo and GUI clients differ, their maintenance status, and how to choose between them.
Covers installer selection, first launch, subscription import, system proxy and service mode, plus common Windows issues like firewall blocks, port conflicts, and antivirus false positives.
Follow the config file from top to bottom to understand general ports, mode, dns, proxies, proxy-groups, rule-providers, and rules—and avoid common placement mistakes.