Find settings by concept, from subscription imports to network routing. Each card explains a term, clears up common misconceptions, and highlights related settings to check.
The interface, background process, and controller each have different roles. When troubleshooting, first identify the running core, then check where your changes were saved.
The program core that handles proxy connections, rule matching, DNS resolution, and TUN traffic. Derived from the Clash Meta project, mihomo can be launched by a GUI client, but the client and core may have different names. If a field is unsupported or a configuration fails to load, check the actual core and its version—not just the client version.
Core and Client
An app that provides a graphical interface for managing subscriptions, choosing proxy policies, viewing logs, and changing system settings, such as Clash Verge Rev. How overrides, service mode, and configuration storage work varies by client. After importing the same subscription into another client, recheck the system proxy, TUN settings, and local changes—don't rely only on the import confirmation.
Core and Client
An API that lets a dashboard or management tool inspect connections, switch policies, and reload configuration. The external-controller setting specifies its listening address. This is not a proxy port for browser settings, and it should not be used in place of mixed-port. Protect it with the secret access key and restrict its reach to trusted addresses.
Core and Client
A management interface connected to the external controller, typically used to inspect rules, active connections, and proxy groups. external-ui can specify the directory for dashboard files, but the dashboard itself does not forward proxy traffic. Closing the dashboard page in a browser does not necessarily stop the core; if the dashboard won't open, proxy connections may still be working.
Core and Client
A node provides connection parameters; a protocol defines how communication works. First check that the parameters match the server, then interpret the test results.
A set of server parameters for establishing a proxy connection, usually including a server address, port, protocol, and authentication details. In a configuration file, nodes can be listed directly under proxies or supplied by a proxy provider. A node is not a complete configuration, and its display name does not prove where traffic exits. When troubleshooting, check the logs and try accessing the destination site.
Proxy Protocols
The communication method used to exchange data between a client and a proxy server. A node's type field declares its protocol. Protocol, underlying transport, and TLS settings are separate layers; one field alone is not enough to infer the others. Core support for a protocol also does not mean the subscription includes all the details required to use it.
Proxy Protocols
An encrypted proxy protocol configured in mihomo with type: ss. The server address, port, encryption method cipher, and password must match the server; don't infer them from the node name. If the server requires a plugin or specific parameters, check core compatibility too. A configuration that parses successfully does not guarantee the remote server is reachable.
Proxy Protocols
A check that connects to a specified test address and measures round-trip time. Results depend on the test address, connection reuse, and network conditions. Success only means that this particular request completed; it does not prove every site or protocol works. Latency is not download speed. If a test times out, first determine whether the node is unreachable, DNS resolution failed, or the test address itself cannot be reached.
Proxy Protocols
Rules determine what matches; policies determine how matching traffic is handled. Read the matched rule and the resulting policy together in the logs.
Choose a handling policy for each connection based on its domain, IP address, or other conditions. Enable rule mode with mode: rule. Rules are generally checked from top to bottom; the first match applies its specified policy. A final MATCH rule commonly handles everything else. If a rule references a policy named PROXY, that policy must be defined in the configuration—copying the rule alone is not enough.
Rules and Routing
A set of proxy choices defined under proxy-groups and referenced by rules. select lets you choose manually; url-test selects based on test results; fallback switches according to availability and order. These types serve different purposes. Group names, node names, and rule references must match. A node picked by automatic testing may not be the best choice for the site you're using.
Rules and Routing
A collection of matching conditions stored in a separate file and managed by rule-providers. Main rules reference the collection with RULE-SET and specify a handling policy. The collection's behavior must match the file format. A successful update only confirms the file was retrieved; also check where it is referenced and whether an earlier rule already matches the connection.
Rules and Routing
Data and matching based on the geographic region associated with an IP address. For example, GEOIP,CN,DIRECT matches an address in the corresponding region and sends it direct. With MMDB mode, the database file is commonly named Country.mmdb; a missing database or failed update can affect rule matching. IP geolocation does not necessarily reflect the server's physical location and does not replace specific domain rules.
Rules and Routing
Domain resolution and preserving domain information for connections are related, but separate, concerns. Check the actual query path before making changes.
The system that resolves domain names to IP addresses and other records. In mihomo, related behavior is controlled by the dns settings. The operating system, browser, and core may each have their own DNS settings; apps using encrypted DNS may also take a separate path. If a page won't load, distinguish a resolution failure from a connection failure—changing nameserver alone does not prove the problem is fixed.
DNS and Network Stack
A DNS mode that returns a synthetic IP for a domain, then restores its domain association when the connection reaches the core. Enable it with enhanced-mode: fake-ip. This helps preserve domain information for rule matching; the synthetic address is not the website's real server IP. Some LAN services or apps may need to be added to fake-ip-filter. After making changes, check for stale DNS caches in the app and operating system.
DNS and Network Stack
When DNS queries reach a resolver outside the expected path—for example, queries go to a local network resolver instead of through the proxy. Check system DNS, encrypted DNS in the browser, TUN traffic interception, and the core's upstream query path. A test page showing a resolver in a particular region does not, by itself, prove a leak. First define the expected path, then compare it with actual requests.
DNS and Network Stack
A feature controlled by the sniffer settings that infers domain names from identifiable connection handshake data. It can help handle connections that include only a destination IP. It does not decrypt HTTPS content and cannot recover every domain; some handshake data may not be visible. If domains are misidentified or an app behaves unexpectedly, check the sniffing scope and exclusions rather than forcing it on every connection.
DNS and Network Stack
Keep the complete configuration, proxy sources, and local changes separate. Settings that disappear after a subscription update often need to be saved as overrides.
Configuration or proxy data supplied through an updateable remote link. Common formats include Clash YAML configurations, encoded node lists, and collections of protocol links. A link opening successfully does not mean its format suits the import method; an HTML login page is not a valid configuration. Treat authentication details in subscription URLs like passwords—don't share them in screenshots, support tickets, or with untrusted conversion services.
Subscriptions and Configuration Files
A structured text format commonly used for mihomo configuration, with indentation to represent hierarchy and hyphens to mark list items. Use spaces, not tabs, for indentation; quote strings containing special characters according to YAML syntax. The error yaml: unmarshal errors may indicate a field type or structure mismatch. A file that parses successfully may still have invalid nodes, proxy groups, or rule references.
Subscriptions and Configuration Files
A source of proxy nodes defined under proxy-providers, loaded from a remote or local file and commonly referenced with a proxy group's use field. It provides nodes; it is not a complete configuration with DNS, rules, and listening ports. Importing a proxy provider link as a full subscription may leave out required configuration. Check the file contents and the import methods supported by your client.
Subscriptions and Configuration Files
A way to save changes separately from the original subscription and apply them when the client generates the active configuration. Useful for custom rules, DNS, or listening settings. Direct edits to a downloaded subscription file may be overwritten at the next update. Clients differ in how they handle array replacement, appended rules, and script execution order. Check the final applied configuration after saving, not just the snippet in the editor.
Subscriptions and Configuration Files
Proxy listeners, system settings, and route interception are separate controls. After enabling a setting, test it in the apps you use; after disabling it, check that system settings have been restored.
A proxy endpoint provided by the operating system to apps that support the setting, usually pointing to the client's local listening address and port. Some apps use their own proxy settings or connect directly, so enabling the system proxy does not route all device traffic through the core. If your browser reports a failed proxy connection after you quit the client, check whether the system proxy setting is still enabled and whether its listening process is running.
System and Platform
Uses a virtual network device and routing settings to send eligible IP traffic to the core, often for apps that ignore the system proxy. Enabling it usually requires administrator permissions, a system service, or platform authorization. An enabled toggle does not guarantee that routes are set up correctly. If the network stops working, check DNS interception, route exclusions, and conflicts with other VPNs before changing the network stack.
System and Platform
Allows other devices to connect through this device's proxy listening port. This commonly involves allow-lan, the listen address, and the system firewall. Other devices should use this device's LAN address—not their own 127.0.0.1. Sharing a proxy endpoint does not automatically change the network's default gateway. Restrict access and avoid exposing the proxy port to public networks.
System and Platform
Service mode typically runs the background core as a system service; startup settings launch the app at boot or user sign-in. They are not the same. Closing the window may minimize the app to the tray or leave the core running, depending on the client. After changing these settings, check separately whether the interface starts, the core is running, and the system proxy or TUN is restored as expected.
System and Platform