Core mihomoLicense GPL-3.0Config format YAMLPlatforms 5
Mihomo Configuration and Network Traffic Routing
First identify how traffic enters the core, then decide where requests go. The system proxy and TUN route requests into the core; rules and proxy groups choose an outbound route; DNS resolves domain names. The mock windows below show settings only. Labels may differ in your client.
config.yaml
mode: rule
rules:
- MATCH,DIRECT
Proxy Mode
RuleGlobalDirect
moderule
Rule orderTop to bottom
RULES
Proxy Modes and Rule-Based Routing
In Rule mode, the core checks domains, destination addresses and other conditions in configuration order, then applies the matching policy. Global mode uses the global proxy group; Direct mode connects without a proxy. For everyday use, keep the rules from your subscription initially, then check connection logs to see which rule matched. To change how a site is routed, put more specific rules before broader ones and verify that the policy name exists. Changing modes affects outbound routing decisions; it does not enable the system proxy or confirm that a proxy node is reachable.
TUN receives traffic through a virtual network interface, which is useful for apps that ignore system proxy settings. Before enabling it, grant the permissions required by your client and make sure no other VPN is managing the default route. Auto-route configures which traffic enters TUN. Strict-route behavior depends on the operating system, so don’t assume its effects from the toggle label alone. First verify your configuration with the system proxy, then enable TUN separately. If local network or remote connections stop working, check routing and excluded addresses.
Fake-IP returns a mapped address for a domain, allowing the core to associate the original domain with subsequent connections. It is not the remote server’s real address, nor does it mean the website content is coming from your device. Configuration involves DNS servers, how traffic is intercepted and the app’s own DNS behavior; changing enhanced-mode alone does not guarantee that every query passes through the core. For local network services that require real addresses, consider using fake-ip-filter. When troubleshooting, first distinguish a DNS resolution failure from a connection failure instead of repeatedly replacing the entire configuration.
Importing Subscriptions and Updating Configurations
Clients can load a configuration from a subscription URL or local file, but a successful download doesn’t mean it’s active. After importing, select the configuration, review any parsing messages and check that proxy groups have usable options. A full configuration subscription is different from a provider that supplies proxy nodes only; they aren’t interchangeable. Automatic update intervals are controlled by the client or provider. The value shown here is illustrative. Save personal rules using the client’s override mechanism so subscription updates don’t overwrite your changes.
There’s no need to change every toggle at once. Select the issue you’re seeing, check the relevant layer first, and open the full guide only if needed.
First confirm that Rule mode is active. Then check the connection log for the domain, matched rule and final policy chain. Rule evaluation stops at the first match, so a broad condition earlier in the list can take precedence over a more specific one. Note the original result before making changes, then start a new connection to test them; an existing connection won’t verify the updated rule.
First check whether the app uses the system proxy. If a browser is proxied but a game or command-line tool connects directly, the issue may be how traffic enters the core, not the rules. Before enabling TUN, grant any required service or network permissions and pause other VPNs. After enabling it, check the connection log for requests from the app, then review the outbound policy.
Note the failing domain and error message first, then distinguish a DNS lookup failure from a connection timeout or certificate error. Check that client DNS is enabled, upstream DNS servers are reachable, and the browser isn’t using its own encrypted DNS. With Fake-IP, seeing a mapped address is expected; check whether the request actually passes through the core to determine where the issue lies.
Determine whether the URL is inaccessible, returns content in the wrong format or fails to parse as a configuration. Don’t save a login page or error page and use it as YAML. If your existing configuration still works, keep it and check the subscription URL, network access and client logs. Before sharing troubleshooting details, remove access tokens from URLs and any personal account information.
GUI clients manage configuration, permissions and runtime controls; the core handles network requests. If you’re new, start with a client for your operating system—you don’t need to install the standalone core first. Each link below opens the corresponding platform tab in the download center, where you can compare installation methods and processor architectures.
Windows
Choose a GUI client such as Clash Plus, Clash Verge Rev or FlClash. Before installing, check your processor architecture in system information. After installation, import a configuration before enabling the system proxy. To use TUN, install the service and grant permissions as directed by the client. Migrate settings from an older client in stages to avoid two proxy apps competing for the same listening port.
Identify whether your Mac has Apple silicon or an Intel processor, then choose the matching installer. If you see a security warning on first launch, verify the app’s source and follow the instructions in System Settings. The system proxy, background services and TUN permissions are separate settings; an open app doesn’t mean the proxy is active. After upgrading, check the required permissions and active configuration again.
Choose among Clash Plus, Clash Meta for Android, FlClash and Surfboard based on the features you need; supported configuration formats vary between clients. The first time you connect, you’ll usually need to approve the system VPN request. If the connection drops in the background, check battery optimization and background activity permissions. For per-app proxying, confirm whether the selected apps are included or excluded.
The download center links to Clash Plus on the App Store. Official website: clashplus.io. After installing, follow the app’s prompts to add a configuration and allow VPN access, then select a policy to connect. Don’t assume desktop options such as process rules, file paths or system routes work the same way on a phone; check what the app actually supports.
For desktop Linux, see Clash Verge Rev and FlClash, and choose an installer format for your distribution. Server and router users can run the standalone Mihomo core and manage configuration directories, services and permissions themselves. Command-line apps may not use the desktop system proxy. When testing, specify the proxy environment variables or TUN route in use instead of relying on the tray icon.
Configurations can be migrated, but system settings must be checked again. The same YAML file can behave differently across clients due to core capabilities, override mechanisms and operating system permissions. Before migrating, export a working configuration and note your proxy group selections and custom rules. After migration, verify a basic connection first, then restore TUN, DNS and other advanced settings one at a time. Treat subscription URLs as sensitive information; don’t share them in public screenshots, repositories or forums.
Mihomo, GUI clients and subscription providers each have different roles. Knowing how they fit together makes it easier to choose a client and diagnose issues than relying on the app’s name alone.
From Clash Meta to Mihomo
Mihomo began as Clash.Meta and is an open-source proxy core in the Clash ecosystem. Older guides may say Clash Meta, configuration references may use mihomo, and client settings may show the core under another historical name. Check the project source and the core information in your client rather than judging by the installer’s filename. Browse the code and changelog in the MetaCubeX/mihomo repository.
The core provides protocol handling, rule matching, DNS and networking capabilities. GUI clients build on these to offer configuration selection, subscription updates and logs. If a setting isn’t shown in the interface, that doesn’t necessarily mean the core lacks the feature. Conversely, a setting shown in the interface doesn’t guarantee that the current core accepts it. Before changing newer options, consult documentation for your current environment.
What the Client and Configuration Each Do
A client installer usually doesn’t provide a working remote proxy service. Node settings, credentials and subscription content come from your own configuration source. Whether a connection succeeds also depends on the remote service, your network and protocol settings. If a subscription is unreachable, an account has expired or a remote server refuses the connection, check the relevant source first rather than assuming the client installation failed.
GUI clients may merge configurations in different ways. For example, interface settings may be applied as an override to subscription data, while directly editing a downloaded file may mean your changes are replaced on the next update. Keep the original subscription, personal overrides and runtime configuration distinct. Store rules you want to keep in a persistent location supported by the client, then check the effective configuration after updates.
Open-Source License and Community Resources
The Mihomo repository is licensed under GPL-3.0. Source code, issue discussions and release notes provide information you can verify. Check each client and bundled component’s own license file for its licensing terms. This site doesn’t use download counts, proxy node counts or speed test results as substitutes for those sources. When choosing software, focus on its feature set, operating requirements and the clarity of its maintenance documentation.
When searching community discussions, look for cases with the same operating system, core and error message. Similar symptoms can have different causes: a page timeout might stem from routing, DNS resolution or the remote connection. When reporting an issue, include reproduction steps and logs with sensitive details removed. Delete subscription credentials, passwords and personal network information. A reproducible description is more useful than a full-screen settings screenshot.
Keep a Recoverable State Before Updating
GUI client updates, core updates and subscription updates are separate processes. A client update may change the interface or permission management; a core update may change which configuration options are supported; a subscription update replaces configuration content from a remote source. Don’t make all three changes before testing, or it’ll be hard to identify the cause of a problem. Save a working configuration, then update one item at a time and review the logs.
For routine maintenance, keep a brief record of your configuration source, whether TUN is enabled, your DNS mode and where custom rules are stored. After upgrading, test regular websites and local network services before testing apps that need UDP. UDP forwarding depends on support across the protocol, node, remote service and local traffic path; enabling a single toggle doesn’t guarantee the same results for every app.
If Git is installed, run the command below to download the source code. Cloning the repository only downloads project files; it doesn’t install or launch a client.
git clone https://github.com/MetaCubeX/mihomo.git
Using Clients and Troubleshooting
The latest three articles cover Android background activity, step-by-step checks after connecting, and macOS permissions. When troubleshooting, check each layer in order: traffic entry, DNS resolution, rule matching and outbound connection. Change one setting at a time and compare what happens before and after.
Learn how to handle the VpnService permission prompt, always-on VPN, per-app proxy settings and battery optimization exemptions on popular Android devices to reduce background disconnects.
Check whether the system proxy is active, then work through port conflicts, DNS resolution, rule matching and proxy availability to identify why you’re connected but can’t access the internet.
Resolve unidentified developer warnings, allow system extensions, grant the Network Extension permission required by TUN and handle recurring Keychain prompts. Also covers differences between Apple silicon and Intel Macs.
