# mihomo Core · Clients for Every Platform

Clash MetaDownloads

Download Clash View Guides

Choose a client for your platform and use the mihomo core for rule-based routing. Follow each step from subscription import to system proxy and TUN, checking your settings and traffic flow along the way.

  • Open Source
  • Clash YAML
  • mode: rule
  • Chinese Documentation

# Config Entry → Rule Match → Policy Exit

  • mihomo
  • Clash YAML
  • Rule Providers
  • Fake-IP
  • TUN

# proxy-groups

Rule-Based Routingand Traffic Capture

A config that parses successfully has only passed the first check. Next, find out where traffic enters, which rule it matches, and which proxy group handles it. These five topics follow the order of a typical config. The settings shown illustrate how fields relate; not every client has the same interface.

01

Rule Mode and Match Order

For everyday use, start with Rule mode. mihomo evaluates the rules in your config from top to bottom; the first matching rule determines the policy. An earlier domain rule can prevent later region-based rules from being considered. Add custom rules before the fallback MATCH rule, and make sure every referenced proxy group exists. Unlike Global mode, Rule mode lets you route workplace intranet traffic, commonly used direct services, and proxy requests through different routes. After making changes, check the matched rule and policy chain in the Connections panel rather than judging routing by whether a page loads.

config.yaml · rules
mode: rule
rules:
  - DOMAIN-SUFFIX,github.com,PROXY
  - GEOIP,CN,DIRECT
  - MATCH,PROXY
02

What System Proxy and TUN Capture

System proxy is a good starting point for your first connection: once enabled, browsers and apps that follow system proxy settings send requests to the local port. Some command-line tools, games, and apps with their own network stack ignore this setting; consider TUN for those. TUN captures traffic through a virtual network interface and routing, and desktop clients usually require service mode or additional permissions. These options control where traffic enters; they do not replace nodes or routing rules. Establish a working baseline with the system proxy, then test TUN separately to pinpoint permission, routing, or DNS conflicts.

config.yaml · tun
mixed-port: 7890
allow-lan: false
tun:
  enable: true
  stack: mixed
  auto-route: true
  auto-detect-interface: true
03

Fake-IP and DNS Mapping

Fake-IP mode returns virtual addresses for domains. The core uses its mapping to recover domain information before routing traffic and making connections. It does not send every domain to a single node, nor does enabling it alone capture all DNS requests. Check the upstream resolvers, TUN DNS capture, and your browser's Secure DNS settings together. If you run into issues with LAN device discovery, corporate domains, or a particular app, add the affected domains to fake-ip-filter and check the results. Avoid replacing the entire DNS resolution chain first, or you may obscure the actual cause.

config.yaml · dns
dns:
  enable: true
  enhanced-mode: fake-ip
  fake-ip-range: 198.18.0.1/16
  fake-ip-filter:
    - "*.lan"
    - "localhost"
04

Choosing Proxy Groups and Testing Nodes

A node test measures the client's connection to a specific test URL; it does not reflect the speed of every website. The select policy group lets you choose a node manually, while url-test automatically picks a candidate based on test results. The exact behavior also depends on interval, tolerance, and health-check settings. For your first connection, choose a node in a manual group and verify that the service you need works before enabling automatic selection. If a test times out, check the subscription, node protocol, and local network separately. Avoid changing every setting repeatedly, and don't assume one failed test means the core is broken.

config.yaml · proxy-groups
proxy-groups:
  - name: PROXY
    type: select
    proxies:
      - AUTO
      - DIRECT
  - name: AUTO
    type: url-test
    use:
      - subscription
05

Subscription Updates and Local Overrides

A subscription may provide a complete config or just a list of nodes; these are not interchangeable files. When you update a subscription, the client may download and replace the current config. For custom rules you want to keep, use the client's supported overrides, merge options, or separate rule sets. After updating, check which config is active, verify proxy group references, and review the parsing logs to confirm the new content loaded. Subscription URLs often contain credentials; don't post them in public repositories or online conversion tools. Remove links, node passwords, and other identifying details before sharing troubleshooting data.

Subscription Manager · Checklist
Config type       Full Clash YAML
Subscription refresh  Set in client
Active config    Confirm selected
Local rules     Use a separate override
After update    Check load logs
Browse installation and setup guides for every platform →

# clients

Choose a Client for Your Platform

Browse All Clients →

The download center lists clients by platform, along with supported architectures and installation instructions. Start by choosing a graphical client, then check your device's processor and system requirements. The mihomo command-line core is mainly for servers, routers, and users who manage processes themselves. Clients can differ in their interfaces and core integration, so don't assume they have identical features based on the name alone.

Windows

Start with a graphical client such as Clash Plus or Clash Verge Rev. After installation, import a subscription, select Rule mode, and enable the system proxy. If you need TUN, configure service permissions as described by the client. Running multiple proxy tools at once can cause port conflicts or competing system proxy settings.

If a browser works but the terminal doesn't, check whether the terminal has proxy environment variables set before reinstalling the client. Before quitting the app, make sure the system proxy has been restored.

Go to Downloads →

macOS

First check About This Mac to see whether your device has Apple silicon or an Intel processor, then choose the matching installer. Authorization for the system proxy, network extensions, and helper services may be managed in different places. Read the system prompts after installation and grant any permissions the client requires.

If the connection stops working after switching networks, waking from sleep, or changing VPNs, first check the proxy settings for the active network service. Archived clients can be useful for compatibility reference; for everyday use, prefer a maintained option.

Go to Downloads →

Android

Choose a client such as Clash Plus or Clash Meta for Android, and install the build that matches your device architecture. On first connection, Android asks for VpnService permission. This allows the app to create a local VPN interface; it does not provide access to a remote proxy node.

If the connection drops when the screen locks, check battery optimization, auto-start, and background restrictions. If another VPN is already connected, check whether both can run at the same time. A VPN icon alone does not confirm that traffic is reaching its destination.

Go to Downloads →

iOS

The download center links to Clash Plus on the App Store and its official site at clashplus.io. After installation, import a subscription or config using a method supported by the app, grant the system VPN permission, then choose a proxy group and test your connection.

On iOS, system network extensions manage traffic capture, so desktop instructions for toggling the system proxy do not apply. Check the current app documentation for supported config formats, background connection behavior, and available features.

Go to Downloads →

Linux

For desktop Linux, choose Clash Verge Rev or FlClash and select a package that matches your distribution. Desktop proxy settings may not carry over to terminals, containers, or background services; check how each handles network traffic separately.

When using the command-line core, manage the config directory, permissions, and service logs yourself. Before enabling TUN, check existing routes, DNS managers, and container subnets. Keep a local way to restore network access if anything goes wrong.

Go to Downloads →

# quickstart

From Subscription Importto Your First Connection Check

Get one basic connection working before adding complex rules. Client installation, proxy node service, and system traffic capture are separate steps: installing the software doesn't give you a node, and having a node doesn't mean every app is using the proxy.

  1. 01

    Import and Activate a Config

    Get a Clash-compatible subscription from your provider. Open the client's config or subscription page and choose the option to import from a URL. If you already have a local YAML file, you can import that instead. After the download completes, select the config and check that proxy groups appear on the Proxy page. If parsing fails, check the subscription format, URL, and file indentation. A regular webpage URL is not a subscription link, and a raw node link may not work as a complete config.

    How to Import a Subscription URL →
  2. 02

    Choose a Node, Then Enable Traffic Capture

    On the Proxy page, select Rule mode, open the proxy group that handles your outbound traffic, and choose a node manually. On desktop, start by enabling the system proxy; on mobile, grant VPN permission when prompted. Don't change DNS, rules, and TUN all at once during your first test. Change one setting at a time so you can compare results. If the app reports a port conflict, quit other proxy processes first, or explicitly change the local listening port and the settings of apps that use it.

    How to Set Up the System Proxy →
  3. 03

    Check Connections and Matched Rules

    Run the client's node test, then visit a service you expect to use the proxy and open the Connections panel. Check the destination domain, matched rule, and final outbound route. Next, visit a service you expect to connect to directly and compare the result with your config. A successful latency test only confirms that the test request worked; verify the apps you actually use. If the browser works but another app doesn't, check which traffic the proxy captures. If the connection reaches the core but keeps failing, check the node and remote service.

    Test a Node and Verify Your Connection →
Read the Full Guide →

# source & maintenance

Open-Source Coreand Client Responsibilities

Clash Meta is a name often encountered when exploring the project's history; the current core project is called mihomo. This download site organizes download links and configuration guides. For core source code, client release notes, and node service status, consult the relevant project or provider.

Project History: Meta and mihomo

Search for Clash Meta and you'll come across the former name, mobile client names, and documentation for the mihomo core. They're connected within the same ecosystem, but they're not the same installer. mihomo continues to support Clash-compatible configs while adding capabilities for rules, protocols, DNS, and more. When a config field causes an error, first check which core is actually running and what it supports—not just the desktop app's name.

Refer to the project documentation for protocol and field behavior. Older online guides may use outdated defaults. Before copying snippets, check that the fields still apply to your setup and keep a backup of your config so you can roll back.

Open-Source Development: Code and Issue Reports

You can browse mihomo's source code, commit history, and issues in the public MetaCubeX repository. Open source makes it possible to trace implementation and changes, but a graphical client may also have its own subscription management, service process, and config override logic. Investigate interface errors separately from core parsing errors. When reporting a problem, include the steps to reproduce it, your system environment, and a minimal sanitized config; this is usually more helpful than a screenshot of a failed connection alone.

Troubleshooting logs may include domain names, node addresses, or subscription credentials. Remove sensitive information before filing a public issue, and include only the fields and error messages needed to reproduce the problem.

The Core Handles Traffic; the Client Manages It

Graphical clients typically handle subscription imports, config switching, system proxy settings, and connection displays. The mihomo core reads the loaded config, matches rules, and establishes connections. Client toggles may generate or override config fields, so after editing a file, check whether the client preserved your changes. Platforms such as iOS use their own integration methods; Clash config compatibility alone does not mean they all use the same core implementation.

Subscription services provide nodes and related config; they are separate from the client. If a node expires, your data allowance runs out, or the provider has an outage, contact your subscription provider. Reinstalling the app usually won't fix these issues.

Updates: Check Three Things Separately

Handle client, core, and subscription updates separately. A client update may change the interface or permission requirements; a core update may affect protocol or config field behavior; a subscription update refreshes nodes and provider settings. Back up local rules and necessary settings before upgrading, and read the release notes. Afterward, repeat the first-connection checks for the system proxy, DNS, and rule matches so leftover settings aren't mistaken for a new bug.

Maintain long-term rules with an override method you can track. For complete platform installation steps, see the preparation and installation guide. For config parsing, permissions, and routing issues, see the configuration FAQ.

# MetaCubeX / mihomo

Get the Core Source Code

The command below clones the source repository; it does not install a graphical client. See the repository documentation for build instructions, usage, and license information.

Browse the mihomo Source Repository ↗ 
git clone https://github.com/MetaCubeX/mihomo.git

# technical-notes

Latest Technical Notes

Browse All Articles →