Mihomo
A Beginner-to-Advanced Guide

Core Concepts: The Core, Client, and Connection Path

Mihomo is a network proxy core. It reads configuration, accepts connections, matches rules, and selects an outbound. Clash Meta is a name commonly encountered when learning about its history. Desktop and mobile GUI clients handle profile imports, node selection, permission requests, and status displays. An open client window doesn't mean the core is running, and a running core doesn't mean app traffic is being routed through it. Understanding this distinction is the starting point for troubleshooting.

Start by Distinguishing Four Components

The client is the control interface; the core is the program that handles network requests; the configuration file tells the core how to run; and the proxy server is the remote outbound. A subscription typically distributes nodes or a complete configuration, but it isn't the proxy software itself. Installing a client doesn't provide a working server, and a successful connection doesn't guarantee the bandwidth, exit location, or protocol support you need.

A configuration can include listening ports, DNS, proxy nodes, proxy groups, rules, and remote rule providers. A proxy group organizes multiple outbounds into a selectable target, which rules can then reference. Selecting a node in the interface is only one part of the process: if a request matches a direct rule, changing the node in a proxy group won't change its route.

Follow the Request to Understand Routing

When a browser visits a domain, it first needs an address and then establishes a connection. Requests can enter through a local port configured as the system proxy or be captured by a virtual TUN interface. Once a request reaches the core, rules select an outbound based on the domain, destination address, or other conditions. Whether the remote server is reachable and the destination site responds are later steps in the connection path; the client's connection status alone can't confirm them.

The system proxy setting generally tells apps that support it where to find a proxy. Some games, command-line tools, and apps that manage their own networking won't use that setting. TUN captures traffic more broadly, but involves routing, DNS, and permissions. Each approach has its uses: enabling TUN doesn't necessarily make things faster, and a system proxy problem doesn't mean you need to reinstall the client.

Protocols, Transports, and Configuration Formats

Shadowsocks, Trojan, VLESS, Hysteria2, TUIC, and WireGuard each offer different protocol capabilities. A protocol appearing on a support list doesn't mean every node can use it: check the server's parameters and the capabilities of the client core and its build. UDP forwarding likewise requires support from the inbound, outbound protocol, and remote service. A working website only confirms that the relevant web connection works.

YAML is a structured text format. Matching indentation indicates the same level; a space usually follows a colon, and list items start with a hyphen. Use spaces, not tabs, for indentation. Chinese notes are fine in comments, but don't use full-width colons or curly quotes in YAML syntax. After editing, run the client's configuration check before applying changes to the running core.

For practice, prepare a reliable test site, a known-good configuration, and a clear rollback procedure. Note whether you're using the system proxy or TUN, the current mode, and the selected proxy group. Change only one variable at a time when troubleshooting. For unfamiliar terms, start with the glossary, then use the connection path in this chapter to work out where the issue occurs.

Choose and Install: Platform, Architecture, and Permissions

Choose an operating system in the download center, then check your processor architecture. Clash Plus is our recommended first choice. For desktop use, you can also choose Clash Verge Rev or FlClash. Windows users can also try Clash Nyanpasu. Clients differ in their interfaces and how they merge configuration, so it's easier to manage one client and verify the basics before installing several and enabling traffic capture.

Choose Based on Your System and Maintenance Status

On macOS, choose Clash Plus, Clash Verge Rev, or FlClash. On Android, options include Clash Plus, Clash Meta for Android, FlClash, and Surfboard. Surfboard uses a different configuration system, so don't assume it can import Mihomo YAML directly. Install Clash Plus for iOS from the App Store; its official site is clashplus.io. Before moving between clients, check the subscription's output format rather than comparing file extensions alone.

The Linux download section offers Clash Verge Rev and FlClash. Check your distribution's package format before installing. Clash for Windows and ClashX Meta are archived and no longer maintained, so they aren't recommended starting points for new users. The Mihomo core package is for users comfortable managing configuration and processes themselves; most desktop users should choose a GUI client.

Complete a Minimal Installation

Before installing, quit other proxy or VPN apps and turn off their automatic traffic capture. Install desktop packages using the system's normal process. Place portable apps in a permanent directory where you have write access; don't keep running them from inside an archive. On first launch, locate the configuration, proxy, logs, and settings screens. Leave startup, LAN sharing, and complex automatic update options off for now.

On Windows, using the system proxy and installing a TUN service may require different permissions. Grant access only when the installer or a client you've verified explicitly requests it. On macOS, confirm the download source first, then follow system prompts for app and helper-service permissions. Don't disable system security to fix a single app that won't launch. After granting permissions, return to the client and confirm the core is actually running.

On Android, enabling traffic capture usually triggers a system VPN permission prompt. The VPN icon in the status bar confirms permission was granted, but doesn't prove the remote node works. Other VPN services on the device may compete for traffic capture. Keep only one service active at first. Once it works, adjust battery optimization and background settings, keeping permission issues separate from node issues.

Verify the Installation and Test a Clean Exit

Import a trusted configuration and check the core logs. If a port is already in use, check whether an old client or leftover process is listening on the same port; don't terminate unfamiliar system processes. If you change the port, update any app proxy settings that reference it. For a syntax error, fix the configuration file—reinstalling the app usually won't correct an invalid field.

Finally, test a clean exit: turn off the system proxy or TUN, quit the client, and confirm the browser still works over your normal network. If the network stops working, check whether the system proxy still points to a local port. This confirms that you have a controlled installation. For help with system permissions, see the FAQ instead of immediately installing a second client to replace the current setup.

Subscriptions and Configuration: Import, Update, and Local Overrides

A subscription URL distributes configuration and may contain account identifiers or access credentials, so treat it like a password. Get links only from trusted providers, and never expose the full URL in public chats, screenshots, or bug reports. Before importing, check whether it provides a complete Clash configuration, a node list, or a client-specific format; each requires the appropriate import option.

From Import to Active Configuration

Open configuration management and choose the option to add a remote profile or import a subscription. Paste the full URL and save. After the download, check the profile name, update time, and parsing status, then set it as the active configuration. Some clients separate downloading, selecting, and applying, so seeing a file in the list doesn't mean the running core is using it.

If import fails, identify which step failed. A network timeout means the request didn't complete. Authentication errors may mean the link has expired. An HTML response may indicate that the URL points to a login or information page. A parsing error usually means the content format is wrong. Don't send arbitrary web links to a subscription converter, and never upload a private link to an unfamiliar online tool for debugging.

After activation, check for selectable proxy groups, choose a specific outbound, and visit a test site. If the node list is empty, check whether the configuration loads nodes through remote proxy providers and whether those resources have downloaded. Parsing the main configuration and fetching remote resources are separate steps; check their errors and logs independently.

Distinguish Remote Files from the Active Configuration

GUI clients often combine a remote subscription, local overrides, and interface settings to produce the final configuration. If a subscription specifies one port but the active configuration uses another, a client setting may have overridden it. Check the client's runtime configuration or merged output when troubleshooting, and remember it may contain sensitive information. Don't infer current behavior from the downloaded file alone.

For custom rules you need to keep, use the client's supported override, merge, or extension options. Editing a downloaded remote file directly means your changes may disappear on the next update. Merge behavior varies by client, especially whether lists are appended or replaced, so verify it. Start with one easy-to-observe test rule; confirm its position and effect before moving over your production rules.

# Rule snippet: merge at the beginning of the existing rules list
# example.com is a reserved example domain
rules:
  - DOMAIN-SUFFIX,example.com,DIRECT

This snippet demonstrates one rule only; it doesn't include nodes or full network settings. Don't use it to replace an entire subscription. If rules already exists, add the list item using your client's merge method rather than defining the same key twice in one YAML mapping. Check connection details to confirm a match; a successful save in the editor isn't enough.

Plan Your Update and Backup Routine

Set update intervals based on the provider's recommendations and your client's capabilities. Checking too often won't make nodes more reliable and may trigger server-side rate limits. Start with a daily check, and update manually before important changes to confirm the result. Node subscriptions, remote rule providers, and client apps have separate update schedules; one successful update doesn't mean everything is current.

Keep the last known-good configuration and note your current proxy group selections before updating. Some updates remove or rename nodes, leaving the previous selection invalid. After updating, check that the configuration parses, then test commonly used sites and apps that need UDP. If something breaks, restore the old configuration and verify that the network works before comparing changes. Avoid changing DNS and reinstalling the app at the same time.

If you use the same link on multiple devices, check whether your service limits device count and supports each client's format. A configuration backup may include more than the subscription URL: local overrides, proxy group selections, and scheduled tasks could be included too. See how to sync configurations across devices. Before syncing, identify which settings are managed remotely and which belong only to the current device.

Proxy Modes: Test Rule, Global, and Direct Routing

Proxy mode controls how requests that reach the core are routed; it doesn't ensure they reach the core in the first place. The system proxy or TUN provides the entry point, while rule, global, and direct modes determine what happens next. Confirm that the app is connected before switching modes to compare results. If a request never appears in the connection list, changing modes won't fix an issue before the entry point.

What Each Mode Changes

Rule mode follows the configuration's rule order and sends different traffic to different policies. Global mode typically sends all requests entering the core to the global proxy group, making it useful for narrowing down an issue temporarily. Direct mode connects requests entering the core straight to their destinations. Direct mode doesn't stop the client: TUN and local listeners may still be active, and the mode name alone doesn't tell you how DNS is handled.

When getting started, use rule mode and select a specific node rather than relying on an automatic test group. If a page won't load, try global mode temporarily and confirm that the global group has that node selected. If global works but rule mode doesn't, check the rule match and proxy group reference first. If both fail, check the node, DNS, and local network.

Separate System Proxy Settings from Proxy Mode

After enabling the system proxy, test with a browser that follows system settings. Browser extensions, custom proxy settings, and separate browser profiles may override the system choice. Command-line tools may use proxy environment variables rather than the system proxy panel, so browser success doesn't prove that the terminal is using the proxy. Check the entry point for each app instead of relying on the client's main toggle.

To test a local HTTP proxy, first confirm that the mixed port is 7890, then run the command below. If your port differs, use its actual value. This command routes only the current request through the proxy; it doesn't configure a global environment for other programs or enable UDP capture. The destination is an example domain, so the result still depends on your network and selected outbound.

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

Check connection details as the command runs. If the request appears with a clear outbound, the entry path is working. If the connection is refused, check the listening port and core status first. If the proxy accepts the connection but the remote request times out, check the outbound logs. Don't assume every terminal error means a node has failed; certificates, system time, and DNS can fail independently.

Keep Test Conditions Consistent

For each test, keep the app, destination, and node the same; change only the mode and note the final outbound. Browser caches or existing long-lived connections may continue using the old route. Close the page or disconnect the relevant connection before making a fresh request if needed. Don't switch nodes, change DNS, and enable TUN all in one test, or you won't know which change fixed access.

A node latency test measures one specific test destination, not overall speed across all websites. A latency result doesn't prove that a target service works, let alone that UDP forwarding succeeds. Large downloads, video streams, and real-time games have different network requirements. Test with the relevant app, and account for server limits, exit policies, and changes to your local network.

After troubleshooting, return to rule mode and check that commonly used sites reach the expected proxy groups. Include local devices and services—such as printers, router admin pages, and development servers—in your test checklist. Keep a clear shutdown procedure: turn off the system proxy or TUN first, then quit the app. A repeatable test process is your baseline for the next chapter on rules; a page loading occasionally isn't proof that the configuration is correct.

Proxy Rules: Match Order, Proxy Groups, and Rule Providers

In rule mode, Mihomo checks rules from top to bottom; the first match determines how a request is handled. More rules don't necessarily mean more accurate routing—order and scope matter. A broad domain rule near the top can prevent a more specific rule below it from ever being reached. Before editing, define what you want: which app accesses which destination, which outbound it should use, and how you'll verify the result.

Start with a Few Easy-to-Verify Rules

DOMAIN matches an exact domain, DOMAIN-SUFFIX matches a domain suffix and its subdomains, and DOMAIN-KEYWORD matches a keyword in the domain. Keyword rules can be too broad, so beginners should prefer a specific domain or suffix. Don't paste a full webpage URL into a domain field; rules generally don't include the scheme, path, or query parameters.

Address rules such as IP-CIDR apply to destination address ranges. GEOIP depends on the relevant data and doesn't classify traffic by website language or company registration location. MATCH is a catch-all rule and belongs at the end of the list; placed too early, it makes later rules ineffective. Address rules may also trigger domain resolution, so avoid introducing extra DNS requests just to match an IP.

# Learning example: order an exact match, an address rule, and a catch-all
# This example routes everything directly; it doesn't provide a remote proxy
rules:
  - DOMAIN,example.com,DIRECT
  - DOMAIN-SUFFIX,example.org,DIRECT
  - IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
  - MATCH,DIRECT

no-resolve prevents this address rule from actively triggering domain resolution. It doesn't disable DNS for the whole configuration or guarantee that all LAN traffic falls within this address range. Home, office, and container networks may use different subnets, so check your actual routes before adding one. The example ends with a direct rule to demonstrate syntax; don't replace a full configuration that needs proxy outbounds with it.

Have Rules Reference Stable Proxy Groups

The final field in a rule can be a built-in action or the name of an existing proxy group. The group name must match the configuration exactly, including spaces and capitalization. It's usually easier to maintain rules that point to stable proxy groups, letting you switch nodes within the group, than to bind many rules directly to individual nodes. Stable group names also mean fewer edits when a subscription removes nodes.

Manual selection is useful for confirming an outbound; automatic test groups choose from a set of candidates based on test results. Neither is universally better. The test URL, interval, and candidate list all affect automatic group results. Groups can also reference other groups, so the group shown in connection details may not be the final remote node. Follow the selections through each group when troubleshooting.

Understand the Limits of Remote Rule Providers

Rule providers are declared with rule-providers and referenced by RULE-SET rules. The behavior type must match the file contents; domain lists, IP lists, and classical rule formats aren't interchangeable. A failed download, unwritable path, or invalid content format can prevent a provider from loading. Seeing a provider's name doesn't mean its rules are available.

Large rule sets are useful for organizing rules by purpose, but first check who maintains them, how often they update, and what they cover. Keep a small set of essential local rules, add one remote provider, and inspect logs and matches. Don't stack several overlapping rule sets before troubleshooting; otherwise, it's hard to tell whether an earlier rule intercepted the request, the provider changed, or the final proxy group is wrong.

To verify a rule, open the target site and inspect the domain, rule, and outbound in its connection details. A webpage may also request images, sign-in, and API endpoints across multiple domains. A correct match for the main domain doesn't guarantee that every resource follows the same route. If only some content is missing, trace the failed request to its domain instead of switching the entire app to global mode indefinitely.

Add a brief comment explaining the purpose of each local rule change, rather than repeating the field name. After each configuration update, confirm that custom rules remain in the intended order. For DNS-related issues, continue to the DNS configuration section. If the core can't see a domain, adding more domain rules usually won't help; check the request entry point and resolution path first.

TUN Traffic Capture: Routing, DNS, and UDP Limits

TUN receives traffic through a virtual network interface and passes it to the core, making it useful for apps that ignore system proxy settings. It changes how traffic is captured; it doesn't replace nodes, rules, or remote capabilities. Before enabling it, confirm that your configuration already works with the system proxy, and note your current DNS, other VPNs, and virtual network interfaces. That baseline helps isolate issues to the traffic capture layer.

Install the Required Service Before Enabling TUN

Desktop clients may use a service or helper process to get permission to create an interface and modify routes; the steps vary by client. Install the service in the interface and confirm its status before enabling TUN. Android usually uses system VPN permission for traffic capture. Clients don't all use the same permission model, and a clickable toggle doesn't prove that the underlying interface was created.

On first use, keep the default network stack and don't combine strict routing, complex exclusion lists, and multiple DNS upstreams. Check a regular website first, then an app that previously ignored the system proxy. If the core logs show insufficient permissions or an interface creation failure, fix the service or system authorization first; changing nodes won't repair a virtual interface.

# TUN configuration snippet; merge into an existing working configuration
tun:
  enable: true
  stack: mixed
  auto-route: true
  auto-detect-interface: true
  strict-route: false
  dns-hijack:
    - any:53

This snippet shows common fields but may not work on every system. A client interface may override them, so check the active configuration after applying changes. auto-route automatically configures relevant routes, and auto-detect-interface helps select an outbound interface. Multi-interface systems, virtual machines, and unusual dial-up setups may need additional checks. Network stack availability and behavior depend on platform support.

Understand Auto-Routing and Strict Routing

Auto-routing sends eligible requests through TUN, but doesn't necessarily capture every connection on the device. Route priorities, exclusions, app-bound interfaces, and other VPNs can all affect the result. Strict routing tightens traffic capture boundaries and has platform-specific routing or filtering behavior. It isn't a speed optimization or a default fix for every networking problem.

Before enabling strict routing, test LAN access, system connectivity checks, and connections required by your workplace. If printers or corporate services become unreachable, turn off the routing option you just added and see whether the issue disappears, then create exceptions for the actual subnets involved. Don't exclude large address ranges by guesswork; you could bypass traffic you intended to capture.

Test DNS and UDP Separately

dns-hijack sends matching traditional DNS requests to the core's DNS handler. This example targets requests on port 53; it doesn't automatically decrypt encrypted DNS used by an app. Browser Secure DNS and app-specific resolvers may follow different paths. If domain access breaks after enabling hijacking, check the DNS entry point separately from the connection entry point instead of looking only at the TUN toggle.

Test UDP with an app that actually needs it. A node's UDP setting doesn't guarantee that the server and intermediate networks support the required transport. If a game can't connect, check whether its traffic reaches the core, whether the rules select an outbound with the required capability, and whether the remote server responds. A working website or latency test can't replace these checks or prove that real-time traffic will be stable.

After sleep, a Wi-Fi network change, or connecting an Ethernet adapter, the outbound interface and default route may change. If the issue happens only after switching networks, restart traffic capture or recreate the interface using your client's procedure, then compare logs. Enable startup only after confirming that TUN starts and stops reliably on your usual networks. Router and server setups involve forwarding, firewalls, and return paths; treat them as separate projects rather than copying desktop settings.

Maintenance: Updates, Logs, and Rollbacks

Reliable operation depends on traceable changes, not frequent rebuilds. Keep at least one working configuration, necessary local overrides, and a record of the current traffic capture method. Clients, cores, subscriptions, rule providers, and geodata are separate update targets and may be managed in different places. A successful update action doesn't mean every component changed, or that configuration behavior stayed exactly the same.

Follow an Ordered Update Process

Before updating a client, read the release notes and check system compatibility and configuration migration guidance. Export or back up your configuration, then disable traffic capture normally before installing the update. Afterward, confirm that the configuration still loads and the listening ports are unchanged, then test the system proxy and TUN. If the client has a separate core updater, don't replace the app and core in the same test cycle.

After a subscription update, check for changes to nodes and group names. After a rule provider update, check matches for important destinations. Remote resources may download successfully but contain unexpected data, or a permissions error may leave old data in place. Check logs alongside update timestamps. Avoid upgrading several components at once before important work; time to test and recover is more useful than keeping everything updated simultaneously.

Troubleshoot in Order: Entry, Resolution, Rules, Outbound

First confirm that your normal network can reach destinations that should be available, then check the core process and local listener. Next, see whether the failed request appears in the connection list. If there's no record, check the app's proxy settings or TUN. If it appears, inspect DNS resolution, the matched rule, and the selected outbound. Finally, check the remote handshake and destination service response. Following this sequence helps distinguish a stale system proxy setting from a server failure.

In logs, connection refused usually means the destination port didn't accept the connection; a timeout means the operation didn't finish in time; and a resolution error points to domain handling. Check the address, port, and connection stage to determine the actual cause. Certificate errors may also involve the system clock or server name. Don't copy only the final error line; include relevant entries from around the same time.

Temporarily increase log verbosity while troubleshooting, then restore your usual level to limit storage use and privacy exposure. Before sharing logs, remove subscription URLs, authentication fields, controller credentials, and identifying personal information. Screenshots can also expose full node addresses and account details. When describing an issue, share the error type, time, and relevant network stage instead.

Use Rollback to Check the Effect of a Change

If a problem starts after an update, restore the previous configuration and, if needed, the previous traffic capture settings. Once the network works again, compare changes one at a time. If rollback doesn't fix it, the cause may be a local network, server-side, or other external change. Rollback isn't the final diagnosis; it helps determine whether the issue is related to your latest change. A text diff is more reliable than trying to remember which fields changed.

For mobile background disconnects, distinguish system process termination from network changes and remote timeouts. If the connection immediately returns when you reopen the app, check background restrictions and battery settings. If a desktop connection fails after sleep, check interface, DNS, and route recovery. Record device status and timing during tests; don't assume every intermittent issue has the same cause.

When asking for help, include your platform, client name, traffic capture method, type of destination that fails, recent changes, and tests you've already run. “The internet doesn't work” isn't enough to diagnose the problem. Use the connected but can't open websites troubleshooting checklist to gather details, then check the relevant section in the FAQ. A minimal reproducible example is usually more useful than sharing a complete private configuration.

DNS and Advanced Topics: Resolution, Controller, and Deployment

Once you've completed the earlier chapters, study DNS and automation as separate topics. DNS does more than look up an address: it affects which information is visible to rules, the connection destination, and the network path. Before changing settings, note system DNS, browser Secure DNS, client DNS, and TUN hijacking. Map who receives each request and where it goes to avoid resolution layers routing around one another.

How Fake-IP and Upstream Resolution Work Together

In fake-ip mode, the app receives a mapped address that the core uses to associate the domain with a later connection. It doesn't mean the real destination doesn't exist, and it isn't the remote server's address. redir-host returns the actual resolved address to the app. Compatibility and the information available to rules vary between modes, so test them with your apps and traffic capture method instead of treating one as the right setting for every device.

The following DNS snippet is meant to be merged into an existing configuration. A loopback listener limits DNS to the local machine. If TUN or your client uses its own DNS integration, keep the required settings instead of overriding them. The upstream in this example must still be reachable from your network. First confirm that DNS requests resolve successfully; then consider routing and fallback strategies.

dns:
  enable: true
  listen: 127.0.0.1:1053
  enhanced-mode: fake-ip
  fake-ip-range: 198.18.0.1/16
  nameserver:
    - https://1.1.1.1/dns-query
    - https://8.8.8.8/dns-query

nameserver is the list of regular DNS upstreams; adding several addresses doesn't necessarily mean they will be tried in order. With encrypted DNS addressed by hostname, consider how that hostname will be resolved in the first place. If a node server is also specified by domain, it must be resolved before connecting. Don't make the resolver for the node depend on a connection to that node that hasn't been established yet.

fallback and fallback-filter configure backup resolvers and criteria for choosing results; they don't simply switch addresses whenever any request fails. Design them around your actual resolution needs rather than piling up copied upstreams. Some LAN domains and apps don't work well with mapped addresses; you can investigate fake-ip-filter, but first confirm that the resolution mode is causing the issue and add only narrowly scoped exceptions.

After switching modes, apps may still cache old addresses and browsers may keep existing connections open. Make a new request and clear relevant caches using your system's and client's recommended procedures; don't mistake old state for the effect of a new setting. For more on how the options fit together, see nameserver, fallback, and DNS hijacking explained. Add one new resolution path at a time.

Controller and LAN Access

An external controller can read status and perform administrative actions, so keep it local by default and set access credentials before considering remote management. Never expose its port directly to the public internet. If other devices need to use a local proxy, check the listening address, authentication, and system firewall as well. Allowing LAN access isn't just a single toggle; consider which sources can actually connect.

Configurations, logs, and backups may contain sensitive data, and private repositories still need proper access controls. Before enabling automatic sync, exclude device-specific settings that shouldn't be shared, so ports, routes, and permissions from different devices don't get mixed together. Automation should report failures and preserve the last known-good version; never overwrite an active configuration just because a download returned an error page.

Choose Your Next Learning Path

Desktop users can move on to proxy groups and rule provider maintenance. Mobile users should focus on network changes and background stability. Server and router users can then study service management, forwarding, and firewalls. Those setups also require checking return paths and traffic capture scope; copying desktop settings isn't a complete deployment. Before using the core from the command line, check the current program's help and validate the configuration.

Every advanced goal should have a way to verify it: explain rule matches in connection details, trace DNS resolution, reliably start and stop TUN, and restore an old configuration after an update. Once these checks pass, add automatic routing or remote management. To revisit the fundamentals, return to the quick start guide; to switch clients, use the download center. Keep the learning path aligned with what you actually do.