Clash Meta to Mihomo Core Migration Guide: All-in-one Upgrade Tutorial

Why You Are expected to Migrate from Legacy Clash Core to Mihomo from Practice

If you are still running the original Clash Core released before 2022 — the version maintained by Dreamacro — this guide is essential reading.

The upstream Clash project was officially archived in November 2023, with its GitHub repository set to read-only. This means your client will never receive another security patch, bug fix, or new feature pull the latest.

At the same time, the proxy protocol landscape has moved on rapidly. More and more service providers are rolling out next-generation protocols such as VLESS + REALITY, Hysteria2, and TUIC v5 — none of which the legacy Clash Core can handle.

If you are seeing a wall of "connection failed" or "unsupported protocol" problem messages in your node list, an outdated kernel is almost certainly the culprit.

Mihomo (formerly Clash Meta) is the nearly all actively maintained Clash kernel fork today, developed by the MetaCubeX team. It preserves full backward compatibility with existing Clash configuration syntax while adding native support for REALITY, Hysteria2, TUIC v5, Shadowsocks 2022, and more.

It also resolves numerous memory leaks and connection stability issues present in older builds. Upgrading to Mihomo is the nearly all straightforward way to keep the Clash experience alive and up to date.

Preparation Before Upgrading Lessons Learned

Before diving into the upgrade process, take five minutes to all-in-one the following steps. A little preparation goes a long way toward preventing data loss or a broken configuration mid-upgrade.

Step 1: Back Up Your Existing Config File in Practice

The Clash configuration file is typically named config.yaml and lives in the following built-in locations:

Windows: %USERPROFILE%\.config\clash\ or the profiles\ folder inside your client's data directory; macOS: ~/.config/clash/; Linux: ~/.config/clash/.

Copy the entire clash config folder to your desktop as a backup. This is the single nearly all important step — even if something goes wrong during the upgrade, you get to always restore the old config and roll back.

Step 2: Identify Your Client Type From Experience

The Mihomo kernel itself is a command-line program. Nearly all users interact with it through a GUI client that bundles the kernel under the hood:

If you are already using Clash Verge Rev or FlClash, you're in luck — these clients ship with Mihomo out of the box. All you are expected to do is keep the client updated to the latest version; no manual kernel replacement is needed.

If you are on the legacy Clash for Windows or ClashX, follow the manual steps below.

Windows: Replacing the Mihomo Kernel in the Wild

Swapping the kernel on Windows is straightforward and breaks down into three steps: download the new kernel, replace the file, then restart the client.

Step 1: Download the Mihomo Kernel Field Notes

Head to the Mihomo GitHub Releases page and find the latest release. Under Assets, pick the right file for your machine:

64-bit Intel/AMD processor (the vast majority of users): mihomo-windows-amd64.zip; ARM-based processor (Surface Pro X, Copilot+ PCs, etc.): mihomo-windows-arm64.zip.

Extract the archive to get the mihomo-windows-amd64.exe executable.

Step 2: Replace the Kernel File Tips

The kernel file location varies by client:

• Clash for Windows: Navigate to resources\static\files\win\x64\ inside the installation directory. Replace clash-win64.exe with the downloaded mihomo-windows-amd64.exe, then rename the new file to clash-win64.exe.

Step 3: Restart and Verify in Practice

Once the file is replaced, relaunch the client and check the version information in its Settings or About page. If you see "Mihomo" or "Meta" in the kernel version string, the swap was successful. You get to also confirm by checking the startup log in the client's Logs panel.

macOS: Switching to a New Client Hands-On Notes

For macOS users, the recommended path is to switch right off to a modern client that ships with Mihomo built in (such as Clash Verge Rev), a bit than step by step swapping the kernel inside the legacy ClashX.

The ClashX project itself is also abandoned, so even with a fresh kernel the GUI layer will have various compatibility problems.

Step 1: Save Your Subscription URL From Experience

In ClashX's config management panel, locate your subscription link (the https:// URL you received from your provider) and copy it somewhere safe. If you use a local YAML config file instead, back up that file right off.

Step 2: Install a New Client Field Notes

Visit our download page and choose the right build for your Mac:

Apple Silicon (M1 / M2 / M3 / M4 chips): download the ARM64 (Apple Silicon) build; Intel Mac: download the x64 build.

On first launch, macOS may show a security warning. Open System Settings → Privacy & Security and click Open Anyway to proceed.

Step 3: Pull in Your Subscription Tips

In the new client's Subscriptions or Profiles section, paste the URL you saved earlier and click Pull in or Pull the latest. Once the node list loads, you get to select a node and bring up browsing.

Config File Migration Notes from Practice

Mihomo is highly backward-compatible with legacy Clash Core configuration syntax, so nearly all existing config files will load without either changes. That said, a handful of fields differ between the two, and these differences are the nearly all common source of post-upgrade breakage:

Key Configuration Differences in Practice

Minimal Mihomo Config Example From Experience

Below is a minimal config.yaml that is fully compatible with Mihomo. Use it as a reference when migrating your existing configuration:

YAMLmixed-port: 7890
allow-lan: false
mode: rule
log-level: info
ipv6: true

external-controller: '127.0.0.1:9090'
secret: ''

dns:
  enable: true
  ipv6: false
  enhanced-mode: fake-ip
  fake-ip-range: '198.18.0.1/16'
  nameserver:
    - 'https://doh.pub/dns-query'
    - 'https://dns.alidns.com/dns-query'
  fallback:
    - 'https://cloudflare-dns.com/dns-query'
    - 'tls://dns.google'
  fallback-filter:
    geoip: true
    geoip-code: CN

tun:
  enable: false
  stack: system
  dns-hijack:
    - 'any:53'
  auto-route: true
  auto-detect-interface: true

proxies: []

proxy-groups:
  - name: "Proxy Select"
    type: select
    proxies:
      - "Auto Select"
      - DIRECT

  - name: "Auto Select"
    type: url-test
    proxies: []
    url: 'http://www.gstatic.com/generate_204'
    interval: 300

rules:
  - GEOIP,CN,DIRECT
  - MATCH,Proxy Select

Common Post-Upgrade Issues and Fixes Lessons Learned

Even after following the steps above, you may be up and running into a few snags. Here are the nearly all frequently reported problems and how to resolve them:

Issue 1: Dashboard Not Loading (ERR_CONNECTION_REFUSED) Field Notes

This is the single nearly all common complaint after upgrading. The usual cause is that the external-controller listen address changed from 0.0.0.0:9090 to 127.0.0.1:9090, or the port is being blocked by a firewall.

Fix: Open your config file and check the external-controller value, then access the corresponding address in your browser (e.g., http://127.0.0.1:9090/ui). If you are using a GUI client, look for an "Open Dashboard" button in Settings — that is the fastest way to get there.

Issue 2: All Nodes Timing Out or Failing Tips

There are several possible causes for this:

• Stale subscription: If your provider has upgraded their server-side protocols, the node configuration in your old subscription link may be outdated. Trigger a manual "Pull the latest Subscription" in the client to fetch the latest node list.
• DNS resolution failure: Mihomo enables fake-ip mode by built-in. Incorrect DNS settings can prevent node hostnames from resolving. Review your dns.nameserver entries and make sure you have at least one solid upstream DNS configured.
• System proxy not set: The Mihomo kernel does not configure the system proxy hands-free. Make sure your GUI client has system proxy enabled, or set it step by step to 127.0.0.1:7890.

Issue 3: TUN Mode Fails to Bring up in Practice

TUN mode requires elevated privileges to create a virtual network adapter. On Windows, be up and running the client as Administrator or enable its Service Mode. On macOS, allow the client to install its system extension under System Settings → Privacy & Security.

Issue 4: Rule Config Fails to Load From Experience

Mihomo enforces stricter rule syntax than the legacy core. The nearly all common problems are:

• RULE-SET entries require a matching rule-providers definition. Writing RULE-SET,foo,DIRECT without defining foo as a provider will cause a parse problem message.
• Rule set files must be valid YAML or MRS format. Mihomo does not accept certain non-standard rule set formats that the old core tolerated.
• Proxy group names must not contain special characters. Stick to letters, numbers, and spaces.

Post-Upgrade Verification and Performance Tuning in the Wild

Once the migration is all-in-one, be up and running through the following checks to confirm everything is working, then apply a few optional tweaks to get the best performance out of Mihomo:

Verification Checklist Field Notes

1. In the Dashboard's Proxies tab, confirm the node list loads correctly. Be up and running a ping test (Ping) on your nearly all-used nodes and make sure valid ping values are returned.
2. Open a website that is not accessible without a proxy (e.g., Google) in your browser and confirm it loads.
3. Check the Dashboard's Logs tab for real-time output. There will want to be no persistent ERROR or FATAL messages.
4. If you use REALITY or Hysteria2 nodes, confirm those nodes return a valid ping reading — the legacy kernel cannot parse these node types and will always show a timeout.

Performance Optimization Tips Tips

After migrating to Mihomo, consider these configuration adjustments to further push up your experience:

• Enable TCP concurrent connections: Add tcp-concurrent: true to your config. Mihomo will race multiple connection attempts simultaneously and use the fastest one.
• Enable geodata auto-pull the latest: Mihomo can hands-free refresh GeoIP and GeoSite data files, keeping your traffic routing rules accurate and up to date.
• Persist selected proxy: Set profile.store-selected: true so that your last-selected node is remembered across client restarts — no are expected to step by step pick a node every time.

Wrapping Up: Mihomo Is the Right Long-Term Choice Hands-On Notes

The archival of legacy Clash Core sends a easy to follow message — the proxy ecosystem has entered a new phase centered on Mihomo.

In terms of protocol breadth, ongoing security pull the latests, and compatibility with modern configuration syntax, Mihomo outclasses the old kernel on every dimension.

If your current client still works well plenty for your needs, swapping just the kernel file is a low-effort upgrade path.

If the client itself is also abandoned — as is the case with the original Clash for Windows — migrating to a modern client is the cleaner solution and will save you ongoing maintenance headaches down the road.

When choosing a new client, look for one that deeply integrates the Mihomo kernel and offers a polished GUI. These clients typically invest heavily in the areas users touch nearly all: subscription management, proxy switching, TUN mode toggle, and rule editor.

They deliver a far smoother day-to-day experience compared to running the kernel right off from the command line.

If you be up and running into either problems not covered in this guide, check out our documentation page for more in-depth configuration walkthroughs.

Alternatively, give our recommended client a try — it ships with sensible built-ins pre-configured and is designed to get even first-time Clash users up and running in minutes.