mihomo coreOpen-source clients, regularly updated
Built on the mihomo core, this guide covers everything from subscription imports to routing rules, with proxy, DNS, and TUN settings explained section by section.
CONFIGURATION INSPECTOR
A configuration determines how traffic enters the core, gets resolved, matches rules, and exits. First confirm that requests reach the core, then check the matched rule and policy group. Troubleshooting one configuration section at a time makes the cause easier to identify than changing several settings at once.
Rules are evaluated from top to bottom, and the first match is handled by its assigned policy. Domain suffix rules work well for clearly defined groups of sites, while geographic IP rules match by address location. The final MATCH rule catches everything else. If a site uses the wrong route, check its domain, matched rule, and final policy in the connection log—not just the currently selected node. Rule mode uses this list; Global mode applies the global policy instead. Switching modes does not fix a broken rule. The example references a PROXY policy group that must be defined first, and GEOIP rules also require usable geographic IP data.
mode: rule
rules:
- DOMAIN-SUFFIX,github.com,PROXY
- GEOIP,CN,DIRECT
- MATCH,PROXYTUN sends traffic that matches the routing conditions through a virtual network interface. It is useful for apps that ignore system proxy settings and for handling UDP traffic. Before enabling it, confirm that the client has service or administrator permissions, then check that the virtual interface and routes are in place. TUN captures more traffic; it does not improve the remote connection or make every node support UDP. Running it alongside another VPN may change the default route, so use only one traffic-capture tool during initial setup. This example shows only the capture section; DNS hijacking also requires the core’s DNS feature to be enabled.
tun:
enable: true
stack: mixed
auto-route: true
auto-detect-interface: true
dns-hijack:
- any:53mihomo supports multiple proxy protocols, but using the same protocol name does not mean every field is interchangeable. When importing a configuration, preserve the server, port, authentication details, and transport settings supplied by the provider. For TLS, also check certificate verification and the server name. Do not disable certificate verification as a substitute for checking the system time, domain, and certificate chain. Whether a GUI exposes a particular option depends on the client and its core. The example below uses the reserved example domain to show the structure of a SOCKS5 entry; its address and credentials are not for a real service and cannot be used to connect.
proxies:
- name: example-socks
type: socks5
server: proxy.example.com
port: 1080
username: your-username
password: your-passwordPolicy groups separate rules from specific proxy nodes. Keep rules pointed at a stable group name, then choose nodes within the group manually, by periodic testing, or through failover. select is useful when you want to choose an exit explicitly; url-test evaluates candidates based on test results; fallback selects an available option in the configured order. Test targets, network conditions, and check intervals all affect automatic selection, so the results are not the same as download speed. The example connects a manual group to an existing proxy. Define example-socks under proxies first, and make sure group names match their rule references exactly, including capitalization, or the configuration may not load as expected.
proxy-groups:
- name: PROXY
type: select
proxies:
- example-socks
- DIRECTfake-ip returns a synthetic address for a DNS query while the core keeps a mapping between that address and the domain, allowing later requests to match rules by domain name. It does not permanently replace the real server address with another route; the final destination still depends on the policy. Consider DNS upstream reachability, traffic capture, and local app compatibility together. Some LAN discovery and custom DNS setups may need filtering. The example uses a loopback listener to show the local DNS entry point; do not expose it directly to external networks. After enabling this section, confirm that the system or TUN actually sends DNS queries to the core.
dns:
enable: true
listen: 127.0.0.1:1053
enhanced-mode: fake-ip
fake-ip-range: 198.18.0.1/16
nameserver:
- 1.1.1.1A client’s configuration subscription usually loads a complete YAML file. By contrast, proxy-providers load collections of proxies that policy groups can reference. Do not treat the two as interchangeable without checking the format. If an update fails, first check whether the link has expired and whether the response contains the expected content, then check the network path used for the download. Subscription URLs often include account identifiers and should be treated like credentials—never share real URLs in screenshots, logs, or public repositories. The example below uses a reserved example domain to show an update interval and local cache path. Provider content must follow the provider format and is only available for selection when a policy group references it with use.
proxy-providers:
remote:
type: http
url: "https://subscription.example.com/proxies.yaml"
path: ./providers/remote.yaml
interval: 3600CLIENT ENTRY POINTS
Choose your operating system first, then your processor architecture. A GUI client manages configuration and system traffic capture; the core evaluates rules and forwards requests. Check separately whether the installer runs on your system, what permissions TUN needs, and whether the configuration format is supported. The client’s name alone does not tell you.
Start with a GUI client such as Clash Plus. For your first connection, verify the system proxy before enabling TUN if your apps need it. If you see a port conflict or a service permission prompt, troubleshoot your local environment instead of repeatedly changing subscriptions.
Visit download pageChoose an installer for Apple Silicon or Intel. System proxy and network extension permissions are managed in different places, so follow the prompts after installation. After waking from sleep or switching networks, check that routing and DNS still work.
Visit download pageCheck your device architecture and installation permissions, then allow the VPN connection after importing your subscription. Background battery restrictions may interrupt the service. If the connection drops when the screen locks, check battery settings and make sure another VPN app is not using the traffic-capture interface.
Visit download pageUse the download page to visit the Clash Plus listing in the App Store. The official site is clashplus.io. Before importing, confirm that the configuration format is supported. On first launch, approve the VPN prompt and then verify the rules and exit route.
Visit download pageChoose a GUI client for desktop use, or check the core options for servers and routers. Before installation, confirm the package format for your distribution, processor architecture, and service account. A desktop proxy setting does not necessarily capture traffic from the entire system.
Visit download pageThe download page lists clients, architectures, and system requirements by platform. If you already use another client, export your configuration before migrating and note your local rules, overrides, and policy selections. The same subscription may be converted differently by different tools; similar-looking interfaces do not guarantee identical configuration handling.
Clash for Windows is no longer maintained, though old installers may still appear in tutorial screenshots. For new deployments, prioritize actively maintained options; use archived clients only when you have a specific compatibility need. After migrating, disable the old tool’s startup and system proxy settings to prevent both processes from competing for ports or repeatedly changing system settings.
FIRST CONNECTION
Installing a client does not mean your traffic is going through a proxy. Follow the sequence “Load configuration → Choose a policy → Route traffic and verify” to distinguish subscription download issues from node connection and local traffic-capture issues. The interfaces below illustrate settings only; exact menu names depend on your client.
Open the configuration or subscription page, add a remote configuration, and paste your existing URL. Once the download succeeds, select the configuration and confirm that its policy groups appear. Saving the URL without activating the configuration will not change your current connection.
If the response is a web page, a sign-in prompt, or empty, check with your subscription provider that the link is correct and your account is active. Do not submit URLs containing account identifiers to public conversion sites or post subscription contents in public discussions.
For your first connection, select Rule mode and choose a node in a policy group that your rules actually reference, then run a test. A latency test measures the response to a specific target; it does not represent the speed you will get on every website.
A timed-out test does not necessarily mean the node is unusable; the test target or DNS path may be the problem. Check actual site access and logs. Verify your connection using one fixed exit route before trying automatic testing or fallback policies.
First verify the connection in a browser using the system proxy. For apps that ignore proxy settings, enable TUN if needed. Open a website and check the connection log to confirm that the matched rule, policy group, and final exit route are as expected.
When verifying, check browsers, terminals, and other apps separately. Terminal tools may need proxy environment variables set manually. An IP lookup only shows the route used for that request; it does not prove that all traffic follows the same path.
SOURCE & MAINTENANCE
Clash Meta was an earlier name for this core branch; the core project is now maintained as mihomo. Search results, configuration guides, and some client names may still use Meta. To determine whether a guide applies, check the core actually running and the configuration fields it supports—not just the window title. Button labels in older screenshots may have changed.
mihomo handles configuration parsing, proxy protocols, rule evaluation, and DNS. GUI clients add subscription management, tray menus, system proxy settings, and service management. Client updates and core updates are separate. If a configuration key is not recognized, check the running core version and load logs before deciding which component to update.
Code, licenses, issue trackers, and release notes in public repositories are useful sources for verifying how a project works. If a guide does not match the interface, check the relevant project documentation and release history to see whether a setting was renamed, a default changed, or new permissions are required. This site provides a Chinese-language guide index; it does not replace upstream documentation on feature support.
View the mihomo upstream repository ↗ · About this site’s coverage →
A proxy core or client is not a proxy service. Providers determine the nodes, service status, data allowance, and account validity included with a subscription; downloading a new client will not renew an expired subscription. A Clash proxy subscription is a configuration endpoint supplied by a service provider. Check its source, supported protocols, and terms before use—it is not a network service included with the core project.
Rule lists, geographic IP data, and proxy subscriptions each have their own update cycles. Before updating Clash GeoIP data, check which data format and file path your configuration uses. When updating a subscription, check that the node list and local overrides are preserved. Run these updates separately so you can roll back to a known-good state if something goes wrong.
Keep a copy of your working configuration, important overrides, and startup arguments. Read the change notes before updating. Afterward, check that the app starts and loads the YAML, then verify DNS, commonly used websites, and any apps that need traffic capture. If something behaves differently, save sanitized error details. When reporting an issue, include your operating system, architecture, client, and core environment—never share real subscription URLs, passwords, or full account details.
Clone the source to review the implementation and track changes. Running clone only downloads the repository; it does not install a client. Most desktop users can use the installers on the download page.
git clone https://github.com/MetaCubeX/mihomo.gitCONFIGURATION NOTES
Once the basic configuration is working, use the guides below for specific symptoms. A system proxy that has no effect, a misrouted rule, and an unavailable node are different problems. Preserve the current setup while troubleshooting, find where the request diverges from what you expect, and change only the relevant setting.
Track down system proxy issues in browsers and terminals separately: browser extensions that take over proxy settings, PAC and port conflicts, and terminal tools that need the http_proxy environment variable set manually.
Read the troubleshooting steps →Walk through real rules snippets to explain match order, how GEOSITE and GEOIP differ, and how to reference rule-providers. Build a routing setup that connects directly in mainland China and uses a proxy elsewhere.
Read the configuration guide →What to do on your first connection after importing a subscription: choose a node in a policy group, understand latency test results, then verify that the proxy is working in a browser and with an IP lookup.
Read the connection steps →