Clash Technical Docs - Core Architecture · Rules Syntax

Core Architecture

Clash (Mihomo) is a high-performance rule-based routing proxy core engine developed in Go. Understanding its architecture helps write more accurate and efficient configurations.

Architecture Overview

The Mihomo (formerly Clash.Meta) core consists of the following core subsystems working together:

Inbound Listener

Listens on local ports and receives traffic from applications. Supports HTTP / HTTPS / SOCKS5 / TUN / Transparent Proxy and other inbound types, mixed-portcan provide HTTP+SOCKS5 mixed port simultaneously.

Rule Engine

Sequentially matches the rules list in the config file, deciding whether each connection goes through proxy or direct connection. Supports 20+ match conditions like DOMAIN, IP-CIDR, GeoIP, PROCESS-NAME, etc., stopping upon a hit.

Outbound / Proxy

Forwards traffic through configured proxy nodes. Supports Shadowsocks, VMess, VLESS, Trojan, Hysteria2 and other protocols. Proxy groups implement auto speed test, failover, load balancing and other smart routing.

DNS Subsystem

Built-in high-performance DNS resolver, supports DoH (DNS over HTTPS), DoT (DNS over TLS), DoQ (DNS over QUIC). FakeIP mode can completely eliminate DNS leaks, ensuring proxy traffic cannot be sniffed.

RESTful API and Dashboard

Exposes RESTful API via external-controller, allowing real-time proxy node switching, traffic statistics viewing, and configuration refreshing. Compatible with Web control panels like Clash Dashboard, Yacd, MetaCubeXD.

Traffic Processing Flow

From the application sending a network request to its final forwarding by Clash, it goes through the following processing chain:

Application

Browser / Game / Command Line

Inbound Listening

HTTP / SOCKS5 / TUN

DNS Parsing

FakeIP / RealIP

Rules Matching

Sequential Match, Stop on Hit

Policy Outbound

PROXY / DIRECT / REJECT

FakeIP Principle:When FakeIP mode is enabled, Clash DNS assigns a fake IP (like 198.18.x.x) to each domain. When the app initiates a connection, it carries this fake IP. Clash inbound recognizes and restores the domain name, then goes through the rule engine to match, completely preventing the real IP from being exposed to local apps, fundamentally eliminating DNS leaks.

Proxy Modes

Clash supports four working modes, switched via the mode field in the config file or the client interface:

Daily Recommendation

Rule Mode

Match sequentially according to the rules list, deciding whether each connection goes through proxy or direct connection.Direct connection for domestic sites to maintain speed, automatic proxy for overseas sites, balancing speed and privacy, is the best choice for most users.

mode: rule

Global Proxy

Global Mode

All traffic (including domestic) is forwarded through the proxy server. Suitable for scenarios requiring complete exit IP consistency (like operating overseas accounts), but will cause domestic access speed to drop.

mode: global

Debugging & Testing

Direct Mode

All traffic is sent directly without passing through any proxy, equivalent to turning off the proxy function. Usually used to troubleshoot whether the proxy itself affects the connection, or temporarily close the proxy without exiting the client.

mode: direct

Advanced Users

Script Mode

Write fully customized routing logic in JavaScript, accessing all attributes like requested domain, IP, port, process name, etc., achieving flexible control far beyond rule lists.

mode: script

TUN Mode vs System Proxy

Feature	System Proxy	TUN Mode
Working Layer	Application Layer (Layer 7)	Network Layer (Layer 3)
Coverage	Only proxy-supported apps (browsers, etc.)	All traffic (games, command line, all APPs)
Required Permission	Normal user permission	Needs Admin / root permission
Config Complexity	Simple, one-click enable in client	Needs network driver installation (automatic)
Recommended Scenario	Daily browser surfing	Game acceleration, Steam, Global Proxy

DNS Mechanism

Clash has a built-in DNS resolver to prevent leaks and achieve more accurate routing through precise DNS query control:

FakeIP Mode

Assigns fake IPs (198.18.0.0/16) to domains, completely eliminating DNS leaks. Rule matching is done at the domain level (most accurate). Recommended for most users.

RealIP Mode

Resolves real IP first before matching rules, allowing IP-CIDR rules to take effect. For CDN domains, routing might be inaccurate due to different IP affiliations. Suitable for scenarios needing precise IP routing.

                                
                                
                                
                            
config.yaml · DNS Config Example

dns:
  enable: true
  enhanced-mode: fake-ip   # fake-ip | redir-host
  fake-ip-range: 198.18.0.1/16
  listen: 0.0.0.0:1053
  nameserver:
    - https://doh.pub/dns-query    # DoH Domestic
    - https://dns.alidns.com/dns-query
  fallback:
    - https://1.1.1.1/dns-query   # DoH Overseas Backup
    - tls://8.8.8.8:853
  fallback-filter:
    geoip: true
    geoip-code: CN
                        

Rules Syntax

The Clash rule system is one of its most powerful features, precisely controlling the direction of every traffic flow via YAML format.

Rules Format

Each rule consists of three parts, separated by English commas ,:

Rules Types

DOMAIN-SUFFIX

Match Condition

google.com

Target Policy

🚀 Proxy Node Selection

Rules are matched sequentially from top to bottom. It stops upon the first hit. If no rule is matched, the last rule is used as a MATCHfallback.

Rule Types Detailed

Domain DOMAIN

Exact match for full domain, case-sensitive.

DOMAIN,www.google.com,PROXY

Domain DOMAIN-SUFFIX

Match domain suffix (including subdomains). The most commonly used domain rule type.

DOMAIN-SUFFIX,google.com,PROXY

Domain DOMAIN-KEYWORD

Matches if the keyword is contained in the domain, widest coverage.

DOMAIN-KEYWORD,googleapis,PROXY

Domain DOMAIN-REGEX

Use regular expressions to match domains, flexible and powerful.

DOMAIN-REGEX,^(www\.)?google\.com$,PROXY

IP Address IP-CIDR

Match IPv4 CIDR address segment. Add no-resolve parameter to skip DNS resolution.

IP-CIDR,192.168.0.0/16,DIRECT,no-resolve

IP Address IP-CIDR6

Match IPv6 CIDR address segment.

IP-CIDR6,2400:3200::/32,DIRECT

Geo-location GEOIP

Match based on IP affiliation country/region, using GeoIP database.

GEOIP,CN,DIRECT

Geo-location GEOSITE

Use Geosite domain database to match (v2ray-rules-dat), covering a large number of preset domain categories.

GEOSITE,cn,DIRECT

Process PROCESS-NAME

Match based on the process name initiating the connection (Windows/macOS/Linux).

PROCESS-NAME,steam.exe,DIRECT

Process PROCESS-PATH

Match by full process path, more accurate than process name.

PROCESS-PATH,/usr/bin/curl,PROXY

Network NETWORK

Match by protocol type, tcp or udp。

NETWORK,udp,REJECT

Network PORT / DST-PORT

Match target port or port range.

DST-PORT,443,PROXY

Rule Set RULE-SET

Reference external rule set files (.yaml / .list), supports remote URL subscription, can automatically update.

RULE-SET,gfw,PROXY

Fallback MATCH

Match all traffic, must be placed at the end of the rule list, as the fallback policy when no rules hit.

MATCH,🚀 Node Selection

Policy Keywords:In addition to custom proxy group names (like 🚀 Proxy Node Selection), the target policy of a rule has three built-in keywords:

DIRECT — Direct connection, no proxy
PROXY — Go through default proxy (equivalent to using the first node in proxies)
REJECT — Reject connection (commonly used for ad filtering)

Proxy Groups

Proxy groups are the core of the Clash rule system, combining multiple nodes into logical groups with different routing behaviors:

select Select

Users manually select nodes or sub-proxy groups in the client interface. Most flexible and most common proxy group type. Requires opening the client to switch.

type: select

url-test URL-Test

Regularly initiate HTTP speed test requests to all nodes, automatically select the node with the lowest latency. interval sets test interval (seconds), tolerance sets switching tolerance (ms).

type: url-test

fallback Fallback

Use the first available node in order sequentially, automatically switch to the next when the first is unreachable. Suitable for scenarios needing stable primary node + backup nodes.

type: fallback

load-balance Load-Balance

Distribute connections across multiple nodes, with consistent-hashing (fixed node for the same domain) and round-robin (round-robin) strategies.

type: load-balance

relay Relay

Forward traffic through multiple nodes in sequence (Node 1 → Node 2 → ... → Target) to achieve multi-hop proxy. Note that each hop increases latency.

type: relay

Complete Config Example

Below is a complete config.yaml example including core config, proxy nodes, proxy groups, and rule list:

                                
                                
                                
                            
config.yaml · Complete Reference Example

# ── Basic Config ──────────────────────────────────────
mixed-port: 7890        # HTTP + SOCKS5 Mixed Port
allow-lan: false
mode: rule
log-level: info
external-controller: 127.0.0.1:9090

# ── DNS ──────────────────────────────────────────
dns:
  enable: true
  enhanced-mode: fake-ip
  nameserver:
    - https://doh.pub/dns-query

# ── Proxy Nodes ────────────────────────────────────
proxies:
  - name: Hong Kong 01
    type: vmess
    server: hk1.example.com
    port: 443
    uuid: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
    alterId: 0
    cipher: auto
    tls: true
    network: ws
    ws-opts:
      path: /ws
      headers:
        Host: hk1.example.com

# ── Proxy Groups ──────────────────────────────────────
proxy-groups:
  - name: 🚀 Proxy Node Selection
    type: select
    proxies:
      - ♻️ Auto Select
      - Hong Kong 01
      - DIRECT
  - name: ♻️ Auto Select
    type: url-test
    url: https://www.gstatic.com/generate_204
    interval: 300
    tolerance: 50
    proxies:
      - Hong Kong 01

# ── Rule List ────────────────────────────────────
rules:
  - GEOSITE,cn,DIRECT          # Domestic Domain Direct
  - GEOIP,CN,DIRECT            # Domestic IP Direct
  - DOMAIN-SUFFIX,local,DIRECT  # LAN Direct
  - IP-CIDR,127.0.0.0/8,DIRECT,no-resolve
  - IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
  - MATCH,🚀 Node Selection          # Other Traffic via Proxy
                        

Protocol Support List

Clash (Mihomo) natively supports 20+ mainstream proxy protocols, compatible with the vast majority of proxy subscriptions and self-built node solutions.

Supported Protocols Overview

Shadowsocks

One of the most widely used proxy protocols, validated by years of practical use, supports AEAD encryption (AES-256-GCM / ChaCha20-Poly1305), simple configuration, and excellent compatibility.

✓ AEAD Encryption ✓ Simple Config ✓ High Compatibility

VMess

V2Ray

V2Ray core protocol, supports WebSocket, gRPC, HTTP/2, QUIC and other transport methods, can be combined with TLS for traffic camouflage, strong penetration ability.

✓ TLS Camouflage ✓ WS/gRPC ✓ HTTP/2

VLESS

V2Ray Next

The next-generation streamlined version of VMess, removing symmetric encryption overhead for higher performance. Supports Reality TLS fingerprint camouflage, currently one of the protocols with the strongest anti-blocking capabilities.

✓ Reality ✓ Extremely Low Overhead ✓ TLS Fingerprint

Trojan

Trojan-GFW

Achieves penetration by disguising proxy traffic as legitimate TLS traffic on HTTPS port 443, making it almost indistinguishable from normal HTTPS under GFW detection, extremely high stability.

✓ HTTPS Camouflage ✓ Port 443 ✓ High Stability

Hysteria2

Next Gen

High-performance proxy protocol based on QUIC/UDP, specifically optimized for high-packet-loss and high-latency network environments, speeding far beyond traditional TCP protocols on 3G/4G/transoceanic links.

✓ QUIC/UDP ✓ Weak Network Acceleration ✓ Ultra-low Latency

TUIC

A modern proxy protocol also based on QUIC/UDP, with a design philosophy similar to Hysteria2. Supports 0-RTT connection multiplexing, effectively reducing handshake latency, suitable for high-frequency short-connection scenarios.

✓ QUIC/UDP ✓ 0-RTT ✓ Connection Multiplexing

WireGuard

VPN Level

Next-generation VPN protocol, kernel-level implementation, minimalist design, excellent performance, modern cryptography. Clash supports WireGuard node outbound via user-space implementation, no kernel module installation required.

✓ Kernel-level Performance ✓ Modern Cryptography ✓ Native UDP

ShadowsocksR

SSR

A branch version of Shadowsocks, adding obfuscation and protocol plugins. Less common in newly built nodes, Mihomo retains compatibility support.

✓ Obfuscation Support Backward Compatible

SOCKS5

Local Proxy

Classic proxy protocol, supports TCP and UDP (SOCKS5 UDP). Commonly used for local node relay or connecting to other proxy tools.

✓ TCP/UDP ✓ Auth Support

HTTP / HTTPS

HTTP Proxy

Standard HTTP proxy protocol (CONNECT tunnel), widest compatibility, suitable for corporate intranet proxy scenarios. Only supports TCP traffic.

✓ Wide Compatibility HTTP CONNECT

SSH

Secure Tunnel

Forward traffic through SSH tunnel, no extra server configuration needed, just a server with SSH access. Suitable for temporary use or testing scenarios.

✓ Zero-config Server OpenSSH Compatible

Hysteria

v1 / Old Version

The previous generation of Hysteria2, still available. It is recommended to use Hysteria2 for new nodes, Mihomo retains compatibility support for v1.

Backward Compatible

Transport Layer Options (Transport)

Protocols like VMess, VLESS, and Trojan support overlaying multiple transport methods on top of the underlying protocol, further enhancing traffic camouflage capabilities:

WebSocket (ws)

The most versatile transport method, can be used with CDNs (like Cloudflare), strong penetration, slightly higher latency than native TCP.

HTTP/2 (h2)

Multiplexed transport based on HTTP/2, good concurrent performance, requires TLS, suitable for high-traffic scenarios.

gRPC

Transport based on gRPC framework, also supports CDN, multiplexing, lower latency, requires TLS.

Reality

Exclusive to VLESS, disguises traffic as TLS fingerprints of real websites, works normally without a domain name, strongest anti-blocking capability.

TCP (Native)

The most basic TCP direct transport, lowest latency, no extra camouflage. Suitable for network environments without strict blocking.

Split HTTP

Splits requests into multiple HTTP segments to bypass Deep Packet Inspection (DPI), good compatibility, can be used with CDN.

Mainstream Protocols Comparison

Comprehensive comparison based on speed, anti-blocking capability, and configuration complexity to help you choose the most suitable protocol:

Protocol	Speed	Anti-blocking	Config Difficulty	Suitable Scenarios	Recommendation
VLESS + Reality	★★★★★	★★★★★	Medium	First choice for self-built	Highly Recommended
Hysteria2	★★★★★	★★★★	Simple	Weak Network / High Latency	Highly Recommended
Trojan	★★★★	★★★★	Simple	Daily Proxy Mainstay	Recommendation
VMess + WS + TLS	★★★★	★★★★	Medium	CDN Relay Scenario	Recommendation
TUIC v5	★★★★★	★★★	Medium	Low latency small packet	Recommendation
Shadowsocks	★★★★	★★★	Minimalist	Proxy Subscription / Beginner	Common
WireGuard	★★★★★	★★	Harder	Enterprise VPN / Warp	Scenario Specific

Proxy User Tip:If you are using a paid proxy subscription (VPN provider), the node protocols are determined by the provider and usually do not need manual selection. After subscribing, just import it into the Clash client, and the client will automatically identify the protocol type used by each node. For specific import steps, please refer to the Installation and Usage Tutorial。

Ready to get started?

Download the Clash client, configure the subscription according to the tutorial, and you can start using it within 5 minutes.

Download Client View Installation Tutorial

Clash Technical Docs Center