Tutorial

Clash Meta Config Tutorial 2026: The Complete Guide to mihomo YAML Configuration

📅 2026-02-28 15 min read

What Is a Clash Meta Config File and Why Should You Learn It?

Clash Meta (now officially rebranded as mihomo) is one of the most widely used proxy kernels today, powering popular clients like ClashX, Clash Verge, and Clash Nyanpasu. Its core functionality — proxy node management, DNS resolution, and traffic routing — is entirely defined through a single YAML configuration file.

While most users can simply import a subscription link to get a working config, understanding the file structure and its underlying mechanics offers significant advantages:

  • Precise routing: Write custom rules to route domestic traffic directly and overseas traffic through proxies, avoiding unnecessary detours.
  • Effective troubleshooting: When connections fail, quickly identify whether the issue lies with a node, DNS resolution, or a routing rule.
  • Performance tuning: Proper DNS configuration and TUN mode can noticeably improve your network experience.
  • Security awareness: Understand every setting in your config to avoid blindly using untrusted configurations that could leak your privacy.
💡
Who Is This Tutorial For?

Users who have already installed a Clash-based client (ClashX, Clash Verge, etc.) and want to deeply understand and customize their configuration files. Whether you are a beginner getting started with proxy tools or an advanced user looking to optimize your setup, this guide has you covered.

Config File Basic Structure

A complete Clash Meta config file consists of several top-level fields. Here is the essential skeleton — we will explain each field in detail:

# Clash Meta (mihomo) Basic Configuration

# Mixed proxy port (HTTP + SOCKS5 share one port)
mixed-port: 7890

# Allow LAN devices to connect through this proxy
allow-lan: true

# Bind address; '*' means all network interfaces
bind-address: '*'

# Operating mode: rule / global / direct
mode: rule

# Log level: silent / error / warning / info / debug
log-level: info

# External controller API for dashboards
external-controller: 127.0.0.1:9090

# API access secret (optional but recommended)
secret: "your-secret-here"

# Process name lookup for process-based rules
find-process-mode: strict

# GeoIP data file format
geodata-mode: true
geox-url:
  geoip: "https://cdn.jsdelivr.net/gh/MetaCubeX/meta-rules-dat@release/geoip.dat"
  geosite: "https://cdn.jsdelivr.net/gh/MetaCubeX/meta-rules-dat@release/geosite.dat"
  mmdb: "https://cdn.jsdelivr.net/gh/MetaCubeX/meta-rules-dat@release/country.mmdb"

Key Fields Explained

  • mixed-port: The most important port setting. With this set to 7890, both HTTP and SOCKS5 proxy traffic flows through a single port. If you need them separated, use port (HTTP) and socks-port (SOCKS5) instead.
  • allow-lan: When set to true, other devices on your local network (phones, tablets) can use your computer as a proxy gateway.
  • mode: Controls the global traffic behavior. rule is the most common mode, letting Clash decide per-connection whether to proxy or direct based on routing rules. global proxies everything; direct bypasses the proxy entirely.
  • external-controller: Exposes a RESTful API that dashboards like yacd or Clash Verge's built-in panel use to monitor and control the proxy.
  • find-process-mode: Enables process-based rule matching (e.g., routing Telegram through a specific node). The strict mode is the most accurate but uses slightly more resources.

DNS Configuration In Depth

DNS settings are among the most impactful parts of a Clash Meta config. Incorrect DNS configuration can cause slow resolution, inaccessible websites, or even DNS leaks.

dns:
  enable: true
  listen: 0.0.0.0:53
  ipv6: false

  # enhanced-mode determines how DNS works
  # fake-ip: returns virtual IPs for faster connections (recommended)
  # redir-host: returns real IPs for better compatibility
  enhanced-mode: fake-ip
  fake-ip-range: 198.18.0.1/16

  # Domains excluded from fake-ip
  fake-ip-filter:
    - '*.lan'
    - '*.local'
    - 'localhost.ptlogin2.qq.com'
    - '+.stun.*.*'
    - '+.stun.*.*.*'
    - 'lens.l.google.com'
    - 'stun.l.google.com'

  # Primary DNS servers (for domestic domains)
  nameserver:
    - https://doh.pub/dns-query
    - https://dns.alidns.com/dns-query
    - 223.5.5.5
    - 119.29.29.29

  # Fallback DNS (for potentially poisoned domains)
  fallback:
    - https://dns.cloudflare.com/dns-query
    - https://dns.google/dns-query
    - tls://8.8.4.4:853

  # Fallback filter policy
  fallback-filter:
    geoip: true
    geoip-code: CN
    geosite:
      - gfw
    ipcidr:
      - 240.0.0.0/4
    domain:
      - '+.google.com'
      - '+.facebook.com'
      - '+.youtube.com'

fake-ip vs redir-host

fake-ip mode is the recommended choice. When an application requests DNS resolution, Clash immediately returns a virtual IP (allocated from the fake-ip-range) and resolves the real address asynchronously in the background. This makes connection establishment extremely fast since there is no need to wait for DNS results.

redir-host mode waits for real DNS resolution to complete before returning results. While slightly slower, it is more reliable in scenarios that depend on actual IP addresses, such as local device discovery or certain gaming services.

How nameserver and fallback Work Together

nameserver contains your primary DNS servers — typically domestic public DNS services (like Alibaba DNS or Tencent DNS) that resolve local domains fastest. fallback contains backup DNS servers — typically overseas services (like Cloudflare or Google). When Clash detects that the primary DNS returned a potentially poisoned IP (determined by fallback-filter), it automatically uses the fallback result instead.

⚠️
DNS Leak Warning

If using fake-ip mode together with TUN mode, make sure dns.listen is correctly configured. Otherwise, system DNS queries may bypass Clash and go directly to your ISP's DNS, causing a privacy leak.

Proxy Node Configuration

The proxies section is the heart of your config, defining every proxy server available to you. Clash Meta supports a wide range of protocols. Here are examples for each major protocol:

Shadowsocks (SS)

proxies:
  - name: "SS-HK"
    type: ss
    server: hk.example.com
    port: 8388
    cipher: aes-256-gcm
    password: "your-password"
    udp: true

VMess

  - name: "VMess-JP"
    type: vmess
    server: jp.example.com
    port: 443
    uuid: a1b2c3d4-e5f6-7890-abcd-ef1234567890
    alterId: 0
    cipher: auto
    tls: true
    network: ws
    ws-opts:
      path: /ws-path
      headers:
        Host: jp.example.com

Trojan

  - name: "Trojan-US"
    type: trojan
    server: us.example.com
    port: 443
    password: "your-password"
    udp: true
    sni: us.example.com
    skip-cert-verify: false

VLESS (Clash Meta Exclusive)

  - name: "VLESS-SG"
    type: vless
    server: sg.example.com
    port: 443
    uuid: a1b2c3d4-e5f6-7890-abcd-ef1234567890
    network: ws
    tls: true
    udp: true
    flow: xtls-rprx-vision
    ws-opts:
      path: /vless-ws
      headers:
        Host: sg.example.com
    reality-opts:
      public-key: "your-public-key"
      short-id: "your-short-id"

Hysteria2 (Clash Meta Exclusive)

  - name: "Hy2-TW"
    type: hysteria2
    server: tw.example.com
    port: 8443
    password: "your-password"
    obfs: salamander
    obfs-password: "obfs-password"
    sni: tw.example.com
    skip-cert-verify: false
    up: "30 Mbps"
    down: "200 Mbps"
💡
Protocol Selection Tips

If your provider supports Hysteria2, prioritize it — built on the QUIC protocol, it dramatically outperforms TCP-based protocols in high packet-loss network environments. VLESS + Reality is one of the hardest combinations to detect. Traditional SS and VMess remain stable and reliable as the most universally supported options.

Proxy Group Strategy Configuration

Proxy groups are the key to Clash's intelligent traffic routing. They let you combine multiple nodes and define a selection strategy for how traffic is assigned.

Manual Select

proxy-groups:
  - name: "🚀 Proxy"
    type: select
    proxies:
      - "♻️ Auto"
      - "🔮 Load Balance"
      - "SS-HK"
      - "VMess-JP"
      - "Trojan-US"
      - "VLESS-SG"
      - "Hy2-TW"
      - DIRECT

Auto URL Test

  - name: "♻️ Auto"
    type: url-test
    proxies:
      - "SS-HK"
      - "VMess-JP"
      - "Trojan-US"
      - "VLESS-SG"
      - "Hy2-TW"
    url: http://www.gstatic.com/generate_204
    interval: 300
    tolerance: 50

Fallback

  - name: "🔄 Fallback"
    type: fallback
    proxies:
      - "Hy2-TW"
      - "VLESS-SG"
      - "Trojan-US"
    url: http://www.gstatic.com/generate_204
    interval: 300

Load Balance

  - name: "🔮 Load Balance"
    type: load-balance
    proxies:
      - "SS-HK"
      - "VMess-JP"
      - "Trojan-US"
    strategy: consistent-hashing
    url: http://www.gstatic.com/generate_204
    interval: 300

When to use each strategy:

  • select: Most flexible — manually pick your node. Ideal when you need precise control over your exit IP (e.g., unlocking region-specific streaming content).
  • url-test: Fully automatic — always picks the fastest node. The tolerance parameter (in ms) prevents frequent switching; a new node must be faster by at least this margin before Clash will switch.
  • fallback: Priority-ordered — uses the first available node in the list. Best when you have a clear preference for which node to use.
  • load-balance: Distributes requests across multiple nodes. The consistent-hashing strategy ensures the same domain always routes through the same node, avoiding IP-change issues.

Routing Rules Configuration

Rules determine whether each network connection should be proxied, direct-connected, or blocked. Clash Meta evaluates rules top-to-bottom and executes the first match, so order matters.

rules:
  # Exact domain match
  - DOMAIN,google.com,🚀 Proxy
  
  # Domain suffix match (includes all subdomains)
  - DOMAIN-SUFFIX,googleapis.com,🚀 Proxy
  - DOMAIN-SUFFIX,github.com,🚀 Proxy
  - DOMAIN-SUFFIX,youtube.com,🚀 Proxy
  
  # Domain keyword match
  - DOMAIN-KEYWORD,google,🚀 Proxy
  - DOMAIN-KEYWORD,twitter,🚀 Proxy
  - DOMAIN-KEYWORD,facebook,🚀 Proxy
  
  # GeoSite rules (Meta's extended database)
  - GEOSITE,google,🚀 Proxy
  - GEOSITE,github,🚀 Proxy
  - GEOSITE,telegram,🚀 Proxy
  - GEOSITE,cn,DIRECT
  
  # IP CIDR matching
  - IP-CIDR,127.0.0.0/8,DIRECT,no-resolve
  - IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
  - IP-CIDR,10.0.0.0/8,DIRECT,no-resolve
  - IP-CIDR,172.16.0.0/12,DIRECT,no-resolve
  
  # GeoIP rules (match by IP geolocation)
  - GEOIP,CN,DIRECT
  - GEOIP,private,DIRECT,no-resolve
  
  # Process name matching (requires find-process-mode)
  - PROCESS-NAME,Telegram,🚀 Proxy
  - PROCESS-NAME,Steam,DIRECT
  
  # Catch-all rule (must be last)
  - MATCH,🚀 Proxy

Rule Type Quick Reference

  • DOMAIN: Exact match on the full domain. google.com will NOT match www.google.com.
  • DOMAIN-SUFFIX: Matches the domain suffix. google.com matches both www.google.com and mail.google.com. This is the most commonly used rule type.
  • DOMAIN-KEYWORD: Matches if the domain contains the keyword. Broadest scope but also most prone to false positives.
  • GEOSITE: Clash Meta exclusive — matches against a curated domain database by category. Far more efficient than maintaining domain lists manually.
  • IP-CIDR: Matches a destination IP range. Add no-resolve to skip DNS resolution, which avoids unnecessary lookups in fake-ip mode.
  • GEOIP: Matches by IP geolocation. CN matches mainland China IPs.
  • PROCESS-NAME: Matches by application process name, enabling per-app routing control.
  • MATCH: Catch-all rule placed at the very end to handle any traffic not matched by previous rules.
💡
Rule Writing Best Practices

Place precise rules (DOMAIN) first, broader rules (DOMAIN-KEYWORD, GEOSITE) in the middle, and IP-based plus catch-all rules at the end. This ordering ensures the best balance of accuracy and performance.

TUN Mode Configuration

TUN (network tunnel) mode captures all system traffic, including applications that don't natively support proxy settings. In Clash Meta, TUN mode is mature and stable — it is the best approach for achieving true system-wide proxying.

tun:
  enable: true
  stack: system    # system / gvisor / mixed
  dns-hijack:
    - any:53
    - tcp://any:53
  auto-route: true
  auto-detect-interface: true
  # MTU setting for macOS
  mtu: 9000

TUN Stack Options

  • system: Uses the system network stack. Best performance and highest compatibility. Recommended on macOS.
  • gvisor: User-space network stack independent of the system implementation. More stable in certain Linux environments.
  • mixed: Hybrid mode — TCP uses system, UDP uses gvisor. Useful on systems where UDP performance is poor with the system stack.

dns-hijack intercepts all DNS queries to ensure they pass through Clash's DNS module instead of going directly to your ISP — this is the core mechanism for preventing DNS leaks. auto-route automatically creates routing table entries without manual configuration. auto-detect-interface automatically identifies the outbound network interface.

⚠️
TUN Permission Notice

TUN mode requires administrator privileges (on macOS, you need to grant VPN permissions in System Settings). The first time you enable it, the system will display an authorization prompt — simply click Allow. If you are using ClashX Pro, TUN functionality is built in.

Advanced: Script Rules and Sub-Rules

Clash Meta provides more powerful traffic control mechanisms beyond traditional rule lists, designed for advanced users with complex routing needs.

Sub-Rules

Sub-rules allow you to apply a secondary rule set after a primary rule matches, enabling finer-grained control over the same category of traffic.

# Reference sub-rules in your main rules
rules:
  - SUB-RULE,(AND,((GEOSITE,geolocation-!cn),(NOT,((GEOSITE,cn))))),overseas-rules
  - SUB-RULE,(GEOSITE,cn),china-rules
  - MATCH,🚀 Proxy

# Sub-rule definitions
sub-rules:
  overseas-rules:
    - GEOSITE,youtube,📹 YouTube
    - GEOSITE,netflix,🎬 Netflix
    - GEOSITE,openai,🤖 AI Services
    - GEOSITE,telegram,📱 Telegram
    - MATCH,🚀 Proxy
  china-rules:
    - GEOSITE,bilibili,📺 Bilibili
    - GEOSITE,zhihu,DIRECT
    - MATCH,DIRECT

Rule Providers (External Rule Sets)

When your rule list grows large, you can store rules in external files or remote URLs and reference them via rule-providers:

rule-providers:
  reject:
    type: http
    behavior: domain
    url: "https://cdn.jsdelivr.net/gh/Loyalsoldier/clash-rules@release/reject.txt"
    path: ./ruleset/reject.yaml
    interval: 86400
  proxy:
    type: http
    behavior: domain
    url: "https://cdn.jsdelivr.net/gh/Loyalsoldier/clash-rules@release/proxy.txt"
    path: ./ruleset/proxy.yaml
    interval: 86400
  direct:
    type: http
    behavior: domain
    url: "https://cdn.jsdelivr.net/gh/Loyalsoldier/clash-rules@release/direct.txt"
    path: ./ruleset/direct.yaml
    interval: 86400

rules:
  - RULE-SET,reject,REJECT
  - RULE-SET,proxy,🚀 Proxy
  - RULE-SET,direct,DIRECT
  - GEOIP,CN,DIRECT
  - MATCH,🚀 Proxy

Rule providers keep your main config clean and allow rules to auto-update (via the interval setting in seconds). The behavior field supports three types: domain (domain lists), ipcidr (IP range lists), and classical (mixed format).

Common Mistakes and Troubleshooting Guide

Even experienced users frequently encounter configuration issues. Here are the most common errors and their solutions:

1. YAML Formatting Errors

This is the single most common problem. YAML is extremely sensitive to indentation:

  • Always use spaces for indentation — never use the Tab key.
  • Indentation at the same level must be consistent (2 spaces is the recommended standard).
  • A space is required after colons: key: value (correct) vs key:value (wrong).
  • Strings containing special characters must be wrapped in quotes.

2. Port Conflicts

If Clash reports a port conflict on startup, the port specified in mixed-port is already in use. On macOS, run lsof -i :7890 in Terminal to identify the conflicting process, then either stop it or change your port number.

3. Node Connection Failures

  • Verify the server address and port are correct.
  • Double-check authentication details (password, UUID, etc.).
  • Ensure the cipher (encryption method) matches the server configuration.
  • If TLS is enabled, confirm the sni field is correctly set.

4. DNS Resolution Issues

  • Confirm dns.enable is set to true.
  • Use DoH (DNS over HTTPS) format servers to prevent ISP DNS hijacking.
  • If certain apps malfunction under fake-ip mode, add their domains to fake-ip-filter.

5. Rules Not Taking Effect

  • Check whether a higher-priority rule is matching first. Rules are evaluated top-to-bottom.
  • Ensure proxy group names referenced in rules exactly match their definitions (case-sensitive, including emoji).
  • Use your client's "Connections" panel to see which rule each request matched — this is invaluable for debugging.
🛠️
Debugging Tip

Temporarily set log-level to debug to see the complete matching process for every connection in the logs. Remember to switch back to info after troubleshooting to prevent excessive log file growth.

Frequently Asked Questions (FAQ)

1. What is the difference between Clash Meta and original Clash config files?

Clash Meta (mihomo) significantly extends the original Clash configuration format. Key differences include: support for newer protocols like VLESS, Hysteria2, and TUIC; more granular TUN mode configuration; sub-rules for complex routing logic; and enhanced DNS resolution modes. Original Clash configs work in Clash Meta, but Meta-specific configs may not be backward compatible with the original Clash core.

2. Where is the Clash Meta config file stored?

The config file location depends on your client application. ClashX on macOS stores configs in ~/.config/clash/ by default. Clash Verge uses its own application data directory. You can also manually specify a config path in your client's settings. Config files typically use the .yaml or .yml extension.

3. Should I use fake-ip or redir-host mode?

fake-ip mode is recommended for the majority of users. It returns virtual IPs to dramatically speed up DNS resolution, reducing the initial connection latency — ideal for everyday browsing and streaming. redir-host mode returns real IP addresses and is better suited for scenarios that require actual IPs, like LAN device discovery or certain game servers. Start with fake-ip and only switch to redir-host if you encounter specific compatibility issues.

4. Why won't my Clash Meta config file load?

Common causes include: 1) YAML formatting errors, with inconsistent indentation being the most frequent culprit (always use spaces, never tabs); 2) Port conflicts where the mixed-port is already occupied by another application; 3) Incorrect proxy node information such as wrong server address, password, or encryption method; 4) Rule syntax errors. Use a YAML validator to check formatting and review Clash Meta's log output to pinpoint the exact error.

Tags: Clash Meta Config mihomo YAML Tutorial Proxy Rules TUN Mode

Related Articles

Related Resources

📥 Download ClashX ⚙️ Clash Meta Overview 🛡️ Mac VPN Recommendations 📝 Blog & Tutorials