mihomo Config and Troubleshooting Terms
Clash Glossary
Look up field names in config.yaml and find the resulting outbound in the logs.
Check unfamiliar options before changing them. For connection issues, trace the path in order: capture, DNS resolution, rule matching, and outbound selection. Link each card title directly to its term.
Core and Protocols
Know which layer is responsible—the app, the core, or the remote server—so you know where to look when something fails.
- mihomo
- mihomo is a proxy core in the Clash ecosystem. It reads configuration, accepts connections, matches rules, and selects an outbound. The GUI client handles imports and toggles; the core processes connections. If you see an “unsupported field” error, check the version of the core the client actually loaded, not just the version shown in the interface.
- Proxy Protocols
- A proxy protocol defines how a client connects to a remote server, authenticates, and transfers data. In a node definition, start with
type, then check which fields that protocol requires. An app using an HTTP proxy locally doesn’t mean the core also uses HTTP to connect to the remote server.
- Mixed Port (mixed-port)
- A mixed port lets the core accept HTTP and SOCKS proxy connections on the same local port. For example, set it to
7890, then point apps on the same machine to127.0.0.1:7890and choose a supported proxy type. This is the port apps connect to—not a subscription URL or a remote server port.
- UDP Forwarding
- UDP forwarding sends UDP datagrams through the proxy connection. It’s used for voice calls and some games. The entry point must accept UDP, and the selected outbound and remote server must support it too. A working webpage only confirms that the relevant connection works. To troubleshoot call issues, check separately where the app’s UDP traffic is going.
Config File Structure
Know the difference between the source file and the effective config. See Config Fields for the full structure.
- YAML
- YAML is the data format used for mihomo configuration. Indentation defines nesting, and hyphens mark list items. Use spaces, not tabs, and keep items at the same level aligned. If a parse error points to a line, check the colon and indentation on the line above too—the core may not detect the broken structure until it reaches the next line.
- Main Config (config.yaml)
- The main config is read when the core starts or reloads. A common filename is
config.yaml. It can contain general settings, proxy definitions, proxy groups, and rules, and may also reference external resources. A GUI client may save a separate runtime config after importing a file, so editing a file with the same name doesn’t necessarily change the one the core reads.
- Proxy Definitions (proxies)
proxiesis a list of proxy nodes defined one by one in the main config. Each entry has anameand protocol-specific fields such as the server and port; proxy groups can reference it by name. If a renamed node disappears from a group, first check that its reference was updated before troubleshooting the network.
- Overrides and Merging
- Overrides and merging create an effective config based on the original. Changing a scalar field is different from adding a list item: a client might replace the whole list, or support prepending or appending items. After adding rules, check the effective list to make sure the original rules are still there and the new ones haven’t ended up after the catch-all rule.
Proxy Groups and Rules
Rules decide where a connection is sent; proxy groups decide which outbound is actually used.
- Rule Routing
- In rule mode, routing rules select an outbound for each connection based on its conditions. Standard rules are checked from top to bottom; the first match wins. Put domain-specific rules before broader rules that would override them. When troubleshooting a custom rule, first confirm
mode: rule, then check which rule the connection details show as matched.
- Proxy Groups (proxy-groups)
- A proxy group collects multiple outbound options under one name for rules to reference. It can contain nodes, other proxy groups, or built-in outbounds; the selection method depends on the group type. A rule matching a group is only the first step. To confirm where a connection goes, check which group member is currently selected.
- Domain Suffix Rule (DOMAIN-SUFFIX)
- A domain suffix rule matches both the specified domain and its subdomains. For example,
DOMAIN-SUFFIX,example.com,DIRECTmatchesexample.comandapi.example.com, but notnotexample.com. To match one exact domain only, useDOMAIN.
- GeoIP
- GeoIP is a rule type that classifies traffic by IP address ranges.
GEOIP,CN,DIRECTchecks whether the destination IP is classified as CN in the data; it doesn’t check whether the domain ends in.cn. The same domain may resolve to different addresses, which can change the match result.
- Catch-All Rule (MATCH)
MATCHhas no conditions; it handles connections that reach the end of the rule list.MATCH,DIRECTsends connections directly if no earlier rule matches. You can also point the final rule to a proxy group. Ordinary rules placed afterMATCHwon’t get a chance to handle connections already caught by it.
- URL Test Group (url-test)
- A
url-testgroup probes a specified URL and selects an outbound based on the results. Common fields includeurl,interval, andtolerance; tolerance can prevent switches caused by small latency fluctuations. A fast response from the test URL doesn’t guarantee fast access to a particular service, and it doesn’t mean higher download speeds.
Traffic Capture
Check separately whether packets reach the core and which resolver handles domain lookups.
- System Proxy
- System proxy settings are provided by the operating system for apps to use; they don’t mean all system traffic is captured. Apps that read these settings connect to the local proxy port, while apps with their own settings may bypass it. If a browser works but the terminal doesn’t, first check which proxy settings the command-line tool uses.
- TUN Mode
- TUN mode receives IP packets routed through a virtual network interface and passes them to the core for processing. Apps don’t need to understand HTTP or SOCKS proxies, but the traffic captured still depends on routes, permissions, and exclusions. If no relevant connections appear after enabling TUN, check whether the virtual interface and routes are actually active.
- Fake-IP
- Fake-IP is a DNS mode in which the core returns a temporary address to an app and keeps a mapping between that address and the domain. When a connection later targets that address, the core can use the mapping to recover the domain for rule matching. For services that depend on real DNS results, consider whether the relevant domains should be added to
fake-ip-filter.
- DNS Hijacking (dns-hijack)
- In mihomo’s TUN config,
dns-hijacksends matching DNS queries to the core’s DNS module. It isn’t an upstream resolver address, and it doesn’t automatically capture DNS queries apps send over HTTPS. After changing this setting, check separately whether queries are being captured and which upstream resolver handles them.
- DNS Leaks
- A DNS leak occurs when queries that should use a specified DNS route leave through an unexpected path. Using a proxy to load a webpage doesn’t prove that the domain lookup beforehand used the same route. To troubleshoot, check DNS settings in both the operating system and the app, then compare them with the core logs to confirm whether queries went through the expected resolver.
- DNS Routing (nameserver-policy)
- DNS routing selects an upstream resolver based on the queried domain. For example, send internal domains to an organization’s resolver that can resolve them, while other domains use the usual upstream. This determines which resolver answers the query, not whether a connection to the resulting address goes direct or through a proxy—that depends on the connection rules.
Subscriptions and Nodes
Fetching, parsing, and connecting are three separate checks.
- Subscription
- A subscription lets a client periodically fetch configuration or a node list, usually from a URL. A full config can include rules and proxy groups, while a node list may need to be used with an existing config. Before importing, check which format the client accepts. Don’t include your subscription URL in screenshots shared for troubleshooting.
- Node
- A node is a remote proxy entry the core can select to forward a connection. Its name is mainly for display and config references; connecting requires the server address, port, and protocol settings. Seeing a name in the list only means the entry loaded. Whether it works depends on remote connectivity and authentication.
- Node Latency
- The latency shown for a node is usually the response time measured when accessing a test URL through that node. It isn’t just a connectivity check to the node’s address, and it doesn’t translate directly to download speed. For a fair comparison, use the same test URL and network. A single timeout only means that probe didn’t finish in time.
- Subscription Update
- A subscription update fetches remote content again, then has the client parse and replace or update the subscription data. If a request times out, first check network access to the subscription URL. If the response can’t be imported, check its format. If old entries still appear in proxy groups after a successful update, check whether the active config references this subscription.