mihomo Core Features: Clash Configuration Differences and Migration Guide

In a Clash client, the graphical interface handles configuration imports, policy switching, and status display. The core is what actually processes connections, DNS, rule matching, and proxy protocols. mihomo is the compatible core that continues the development of Clash.Meta. Many clients now use it as the default core, while their interfaces may still use names such as Clash, Meta, or Premium. To determine the available capabilities, check the loaded core type, core version, and startup logs rather than relying only on the client name.

An older Clash configuration is usually a valid starting point for migration, but being able to load it does not guarantee identical runtime behavior. mihomo expands support for proxy protocols, rule types, DNS controls, traffic sniffing, TUN routing, and rule-set formats, while handling some fields more explicitly. The goal is not to enable every new feature at once, but to preserve existing routing results first and then activate enhancements one by one.

Core Role and Compatibility Limits

How Original Clash, Clash.Meta, and mihomo Relate

Original Clash established the basic structure of YAML configuration, proxy groups, rule-based routing, and external control interfaces. Clash.Meta extended that structure with additional protocol, DNS, TUN, rule-expression, and traffic-identification capabilities. The project later continued under the name mihomo, so configuration docs, logs, and client settings may still contain the term Meta. For migration purposes, mihomo is best understood as a core that continues the Clash configuration model while adding more network-processing capabilities, not as a completely separate configuration system.

Compatibility is mainly shaped by three layers. The first is the core itself: whether the current mihomo version supports a field. The second is the client: whether its interface can write the field into the effective configuration and whether it merges or overwrites settings before startup. The third is the subscription source: whether the remote configuration contains protocols or rules unknown to the target core. Keep these layers separate during troubleshooting; interface toggles alone do not reveal the final configuration.

Why the Same YAML Can Produce Different Results

A configuration that starts successfully on an older core may produce different DNS results, rule matches, or routing scope after being moved to mihomo. Common causes include client-injected DNS settings, different network-interface selection, different GeoData database versions, and changes in TUN stacks or system-route implementation. Conversely, mihomo-specific fields may be rejected, ignored, or cause configuration loading to fail when returned to an older Clash version.

Before migrating, check whether the client provides a “view effective configuration” or “export final configuration” feature. The original subscription, the configuration after client overrides, and the configuration actually loaded by the core may be different files. Only the final configuration can explain why ports, DNS, and routes behave as they do.

Inspection Layer	Key Items	Common Symptoms
Client	Core selection, override scripts, runtime permissions	Settings appear saved, but core parameters remain unchanged
Core	Version, supported fields, startup logs	Unknown fields, rule-set parsing failures
Configuration	YAML indentation, policy references, ports	Configuration fails to load or policy groups are empty
System Network	Routes, DNS, network interfaces, firewall	TUN is running, but some applications cannot connect

mihomo Key Capabilities

Proxy Protocols and Outbound Capabilities

Original Clash centers on organizing multiple proxy nodes into policy groups and then selecting a policy through rules. mihomo retains this model while expanding the available protocols and transport options. The actual range still depends on the specific version and how the client packages the core. When migrating a subscription, first confirm that the mihomo version bundled with the client can parse the fields used by newer protocols, then verify that all server-side parameters are present.

Protocol support does not guarantee that a node will connect. Certificate names, transport parameters, user identifiers, encryption methods, UDP support, and system time can all affect the handshake. When one node fails, check the connection stage in the core log instead of repeatedly switching global modes. If every node fails, check whether the client transformed the subscription, whether the network restricts the target port, and whether DNS can resolve the server address.

Rule System and Rule Sets

mihomo continues to match rules from top to bottom. Once a connection matches the first applicable rule, it is sent to the specified policy. Common rules cover domains, domain suffixes, IP ranges, processes, GeoIP, GeoSite, and remote rule sets. The final rule is typically MATCH, which catches traffic that has not matched earlier.

rules:
  - DOMAIN-SUFFIX,example.net,Proxy
  - GEOSITE,cn,DIRECT
  - GEOIP,cn,DIRECT,no-resolve
  - MATCH,Proxy

During migration, verify that every policy name referenced by a rule actually exists. Policy names are character-sensitive. If a subscription changes Proxy to another name, the rules may be syntactically valid but still fail to work as expected. GeoSite and GeoIP also depend on local data files; missing, failed, or mismatched database updates can cause the same domain to be classified differently.

Rule sets are useful for moving large collections of domains or networks out of the main configuration. mihomo supports several rule-set behaviors and formats, but older clients may not recognize newer formats. At the start of a migration, keep YAML or text rule sets that have already been tested, and consider a more compact format only after the setup is stable. Do not change the core, rule data sources, and all policy names in the same migration; otherwise, it becomes difficult to identify the cause of a difference.

DNS, Fake IP, and Domain Mapping

mihomo’s DNS module can define upstream servers, dedicated resolvers for proxy-node domains, fallback policies, and domain-based resolver selection. In fake-ip mode, the core returns reserved addresses to applications and stores a mapping between each address and its original domain. When the connection reaches the core, it can still be routed by domain rules. This is especially useful for applications that expose only a destination IP, but it requires DNS requests to actually pass through the core.

If the system still sends DNS requests to another local service, or the browser uses its own encrypted DNS, the core may not see the original domain. The result can be missed domain rules, mixed detection results, or some applications bypassing routing. In TUN setups, DNS hijacking can help, but port conflicts, LAN DNS behavior, and enterprise network policies must still be evaluated separately.

TUN, Sniffing, and Application Traffic Capture

The system proxy generally affects only applications that follow the operating system’s proxy settings. Command-line tools, games, some app-store applications, and programs that establish UDP connections directly may bypass it. TUN mode uses a virtual network interface and system routes to receive a wider range of traffic, then lets the core make the routing decision. mihomo provides multiple TUN stacks and auto-route options, but permissions and routing implementations differ across operating systems.

Traffic sniffing identifies domain information from established connections to improve rule matching when only a destination IP is available. It does not work for every protocol and should not replace a correct DNS configuration. During migration, verify standard DNS and rules first, then enable sniffing for selected applications to avoid conflating routing errors with sniffing-based destination rewriting.

Key Configuration and Syntax Migration Points

Keep Basic Ports and the Control Interface First

Basic fields are relatively similar between the two core families. During migration, you can initially retain the mixed port, LAN access, operating mode, log level, and external control interface. Port numbers must match the client interface and system proxy settings. The control interface should be protected with an access key and a sensible listening scope.

mixed-port: 7890
allow-lan: false
mode: rule
log-level: info
external-controller: 127.0.0.1:9090
secret: "local-control-key"

mixed-port accepts both HTTP and SOCKS proxy requests, making it suitable for most desktop clients. If the old configuration uses separate port and socks-port values, keep that structure temporarily and merge them only after confirming that all applications using those ports have been migrated. Do not let multiple clients listen on the same port; the core started later will report an address-in-use error.

Rule Provider Behavior Types

The important parts of rule-providers are not limited to the download URL; they also include behavior, format, the local path, and the update interval. domain suits domain collections, ipcidr suits IP ranges, and classical can contain classic rules with types and policy targets. If the behavior type does not match the file contents, the rule set may download successfully but still fail to parse.

rule-providers:
  private-domains:
    type: http
    behavior: domain
    format: yaml
    path: ./ruleset/private-domains.yaml
    url: https://example.invalid/rules/private-domains.yaml
    interval: 86400

rules:
  - RULE-SET,private-domains,DIRECT
  - MATCH,Proxy

A rule provider URL is only the data source. The provider must still be added to the ordered rule list through RULE-SET. Defining a provider without referencing it does not affect routing. After migration, check matched rules in the connection log or the client’s connection view to confirm that traffic is actually entering the intended rule set.

A Minimal, Verifiable DNS Configuration

Add DNS settings in stages. First enable the core DNS service, set its listening address, and specify stable upstreams. Next enable enhanced mode. Only then add domain-based resolver policies, dedicated resolvers for proxy nodes, and filtering lists. The structure below shows how the fields relate; choose specific upstreams based on your network and requirements.

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

proxy-server-nameserver is mainly used to resolve proxy server domains, avoiding a DNS dependency before the proxy connection is established. If a node uses an IP address directly, this setting has less impact. Before enabling IPv6, confirm that the local network, proxy nodes, and rules handle IPv6 correctly. Enabling IPv6 responses in DNS alone does not guarantee a usable path for subsequent connections.

TUN Fields Depend on the System Environment

tun:
  enable: true
  stack: mixed
  auto-route: true
  auto-detect-interface: true
  strict-route: true
  dns-hijack:
    - any:53

These fields describe common directions, not values that every system should share. Virtual machines, containers, VPNs, enterprise security software, and multiple network adapters can change the default route. Windows usually requires permission to create a virtual interface and modify routes; macOS may require network-extension and system authorization; Linux needs the appropriate network-management capabilities. If LAN devices become unreachable after enabling TUN, inspect the routing table and excluded networks instead of immediately changing proxy rules.

Migration Steps from Older Clash Versions to mihomo

Record the current baseline.
Save the original YAML, client override rules, and subscription URL. Record the current system proxy port, control port, DNS mode, TUN status, and policy groups that work correctly. Screenshots can help with comparison, but keep recoverable configuration files as well.
Confirm the core actually in use.
Check the core name and version in the client’s core settings, About page, or startup log. Some clients require a full restart after switching cores; reloading the configuration alone may leave traffic handled by the old process.
Run a syntax check.
Start by fixing YAML indentation, duplicate keys, empty policy groups, and references to nonexistent policies. Quote strings containing colons, hash signs, or other special characters. When configuration parsing fails, inspect the area around the line reported in the log, but remember that the real error may be in the preceding indentation.
Verify the basic path with the system proxy.
Temporarily disable TUN, sniffing, and complex DNS overrides. Enable only one confirmed working proxy node and simple rules. Test whether direct, proxy, and reject policies each match as expected. If the basic path fails, fix the node and port first rather than adding advanced features.
Restore policy groups and rule sets.
Confirm that every member of groups such as select, url-test, and fallback is valid, and that rule targets match policy names. The test URL, interval, and tolerance of automatic groups affect the selected result; the lowest latency in one test is not necessarily the best long-term choice.
Migrate DNS.
First ensure that the core’s listening port is not occupied, then confirm that the system or TUN sends queries to that address. Test ordinary domains, rule-set domains, and proxy server domains separately, and review the resolver and final rule in the log.
Enable TUN and sniffing last.
After enabling them, check the default route, LAN access, wake-from-sleep behavior, and network switching. For affected applications, record the destination address, protocol, and matched rule before deciding whether to add an exclusion or adjust the sniffing scope.

Subscription migration also requires separating the remote configuration from local overrides. Remote updates may replace nodes and policy groups, while local overrides preserve ports, DNS settings, or custom rules. If the client supports configuration merging, confirm the merge order. Otherwise, check after every subscription update that custom fields still exist. Do not edit cache files managed by the client directly; the next update may regenerate them.

Common Post-Migration Issues and How to Diagnose Them

Configuration Loads, but No Traffic Passes Through the Core

First confirm that the system proxy points to the current mixed-port, then check that the client process is actually listening on that port. A browser may retain an old proxy setting, while command-line programs may read an outdated port from environment variables. With TUN, check whether the virtual interface exists, whether the default route changed, and whether the active network interface was identified correctly.

Domain Rules Do Not Match; Only IP Rules Appear

This usually means the core did not obtain the destination domain. Check whether the application uses its own DNS, whether system queries enter the core, and whether the Fake IP mapping works. If only a few protocols cannot provide domain names, evaluate sniffing next. If every application shows only IPs, fix the DNS path first. Also check rule order: an earlier IP rule or rule set may already have captured the traffic.

Rule Provider Update Fails

Check the download URL, network path, file format, and permissions for the local directory. During the first launch, a remote rule may not be cached yet. If downloading depends on a proxy policy that has not been established, the startup process can contain a circular dependency. Give the rule source a clear access path first, wait for the file to be written successfully, and then restore full routing. HTTP status codes, parse errors, and file paths in the log are more useful for diagnosis than the client’s generic “update failed” message.

LAN or Some Applications Disconnect After TUN Is Enabled

Disable TUN first to determine whether the problem is related to virtual routing, then check private networks, the gateway, LAN DNS, and other VPNs. On devices with multiple network adapters, confirm that automatic detection selected the interface currently online. If only a specific UDP application is affected, check whether the node supports UDP, whether the policy group selected the correct outbound, and whether the system firewall allows traffic from the virtual interface.

Policy Names Change After a Subscription Update

Rules, rule sets, and client shortcuts may all reference policy names. If a policy is renamed during an update, old rules point to a nonexistent target. Standardize names and inspect every reference rather than simply selecting the policy again in the interface. For long-lived custom rules, use a stable local policy group as an intermediate layer and place subscription nodes in that group.

mihomo Migration Checklist

The client shows the expected mihomo version as the active core.
The original configuration, subscription details, and client overrides have been backed up separately.
The HTTP, SOCKS, or mixed port does not conflict with another process.
Every policy group referenced by a rule exists and contains at least one usable member.
Rules are ordered from specific conditions to fallback conditions, and the final MATCH points to a clearly defined policy.
GeoIP, GeoSite, and remote rule sets load and update successfully.
DNS queries reach the expected listening address, and proxy server domains resolve successfully.
Under system proxy mode, both direct and proxied traffic match the intended rules.
After enabling TUN, the default route, LAN access, and network switching remain functional.
After subscription updates, local overrides, policy names, and custom rules remain effective.

mihomo’s value lies in its actively maintained core capabilities, more complete rule and DNS controls, and support for modern traffic-capture scenarios. Migration success should be judged by actual connection logs, rule matches, DNS paths, and system routes. By validating the basic proxy, rules, DNS, and TUN layers in order, an older Clash configuration can usually transition smoothly while retaining clear rollback points for troubleshooting.