Configuration Tutorials

Clash config.yaml Complete Guide

Understand every field in your Clash configuration file. Master nodes, groups, rules, and DNS to build a setup that fits your exact needs.

Est. 15 min read Difficulty: Advanced Includes Full Code Examples
Usage Tutorial config.yaml Guide

What is config.yaml?

config.yaml is the core configuration file for Clash, written in YAML. It tells the Clash core:

Which ports to listen on

Assigned ports for HTTP, SOCKS5, and transparent proxies

Available proxy nodes

Server addresses, protocols, and authentication for all nodes

Grouping & Switching logic

Categorizing nodes by strategy: manual, auto-test, or failover

Traffic routing rules

Deciding which domains are direct, proxied, or blocked

If you use an 'airport' subscription, your config.yaml is usually auto-generated. This guide is for advanced users who want to customize their setup or use self-built servers.

Default Configuration Paths

Operating SystemDefault Path
Windows %APPDATA%\clash-verge\profiles\
macOS ~/.config/clash-verge/profiles/
Linux ~/.config/clash-verge/profiles/
Mihomo (CLI) ~/.config/mihomo/config.yaml
In Clash Verge Rev, you can edit your current config directly in the 'Subscription' page using the built-in editor without searching for file paths.

YAML Syntax Quickref

Before writing your config, follow these core YAML rules to avoid syntax errors that prevent Clash from starting:

Use spaces for indentation, NOT Tabs
# Correct: use 2-space indentation
proxies:
  - name: "Node-A"
    type: ss

# Wrong: do not use Tab
proxies:
	- name: "Node-A"   # ← Tab character, will cause error
Start lists with a dash -
# String list
nameserver:
  - 223.5.5.5
  - 119.29.29.29

# Object list (each item has multiple fields)
proxies:
  - name: "Node-A"
    type: ss
  - name: "Node-B"
    type: vmess
When to quote strings
# Quotes required when value contains special characters
password: "p@ss:word#123"

# Plain alphanumeric values do not need quotes
log-level: info

# Booleans do not need quotes
allow-lan: true
udp: false
Use # for comments
# Full-line comment
port: 7890  # End-of-line comment

# Comments help document the purpose of each setting
mode: rule  # rule/global/direct

Core Configuration Parameters

Port Settings

Clash provides proxy services through local ports. Your apps should point their proxy settings to these addresses.

config.yaml — Port Settings
# Option 1: separate ports (best compatibility)
port: 7890        # HTTP proxy port
socks-port: 7891  # SOCKS5 proxy port
redir-port: 7892  # Transparent proxy port (Linux/macOS, used with TUN)

# Option 2: mixed port (recommended, HTTP+SOCKS5 combined)
mixed-port: 7890

# Mutually exclusive with Option 1, pick one
FieldTypeDescription
portIntegerHTTP proxy port for browser use
socks-portIntegerSOCKS5 port for games and CLI tools
mixed-portIntegerMixed HTTP+SOCKS5 port (recommended)
redir-portIntegerTransparent proxy port for TUN/iptables
allow-lanBooleanAllow other devices on your LAN to use this proxy (default: false)

Proxy Modes & Logging

config.yaml — Modes & Logging
mode: rule        # rule | global | direct
log-level: info  # silent | error | warning | info | debug
ipv6: false        # Whether to accept IPv6 traffic
mode ValueMeaningUse Cases
ruleRule ModeBest for daily use; routes traffic via rules
globalGlobal ProxyRoutes ALL traffic via proxy (debugging only)
directGlobal DirectBypasses all proxies (equivalent to off)

External Controller Interface (RESTful API)

Clash offers a RESTful API for external control. Web panels like Metacubexd use this to display traffic and switch nodes.

config.yaml — External Control
external-controller: 127.0.0.1:9090  # API listen address
secret: ""                              # API access token (recommended)
external-ui: ui                         # Web panel files directory (optional)
external-ui-url: "https://github.com/MetaCubeX/metacubexd/archive/gh-pages.zip"
Set external-controller to 0.0.0.0:9090 to allow remote Web Panel access from your LAN, but always set a secret to prevent unauthorized access.

In-depth DNS Config

Clash's built-in DNS module intercepts system DNS for more precise routing and to prevent leaks. We strongly recommend enabling it, especially for Rule and TUN modes.

enhanced-mode: Core DNS Logic

config.yaml — DNS Basics
dns:
  enable: true                   # Enable built-in DNS module
  listen: 0.0.0.0:53            # DNS listen address
  ipv6: false                    # Enable IPv6 DNS resolution
  enhanced-mode: fake-ip        # fake-ip (recommended) or redir-host
  fake-ip-range: 198.18.0.1/16 # Fake-IP address pool range
enhanced-modeHow it WorksRecommendation
fake-ipReturns a fake IP; connects instantly while Clash resolves the real targetRecommended
redir-hostPerforms normal DNS lookups before matching IP-CIDR rulesBetter Compatibility

Upstream DNS Server Settings

config.yaml — DNS Servers
dns:
  # Primary DNS (for local/domestic domain resolution)
  nameserver:
    - 1.1.1.1             # Cloudflare DNS
    - 8.8.8.8             # Google DNS
    - system              # Follow system DNS

  # Fallback DNS (for international domains, prevents poisoning)
  # Use encrypted DNS (DoT/DoH) to prevent ISP hijacking
  fallback:
    - tls://8.8.8.8:853   # Google DNS over TLS
    - tls://1.1.1.1:853   # Cloudflare DNS over TLS
    - https://dns.google/dns-query  # Google DoH

  # fallback trigger: use fallback DNS for non-domestic IPs
  fallback-filter:
    geoip: true
    geoip-code: CN       # non-CN IPs trigger fallback DNS
    ipcidr:
      - 240.0.0.0/4       # Reserved ranges also trigger fallback
Why two DNS sets? Local ISPs often 'poison' international DNS queries (returning wrong IPs). You must use encrypted DNS (DoT/DoH) for international domains to get accurate results.

fake-ip-filter: Excluding Domains

Certain local services (NAS discovery, mDNS, login auth) need real IPs and must be excluded from Fake-IP range:

config.yaml — fake-ip-filter
dns:
  fake-ip-filter:
    - '*.lan'                        # LAN domains (bypass fake-ip)
    - '*.local'                      # Local mDNS
    - +.msftncsi.com                 # Windows network check
    - +.stun.*.*                     # STUN services (WebRTC)
    - +.stun.*.*.*
    - time.*.com                     # NTP time sync
    - time.*.gov
    - ntp.*.com

proxies — Node Configuration

The proxies list contains each individual node. Here are the formats for the four major protocols:

Shadowsocks

Shadowsocks Format
proxies:
  - name: "🇭🇰 HK-SS"          # Node name (customizable)
    type: ss
    server: hk.example.com   # Server domain or IP
    port: 443
    cipher: aes-256-gcm       # Cipher (common: aes-256-gcm / chacha20-ietf-poly1305)
    password: "your-password"
    udp: true                 # Enable UDP forwarding (required for gaming)

  # SS with obfs plugin (improves obfuscation and anti-blocking)
  - name: "🇯🇵 JP-SS-obfs"
    type: ss
    server: jp.example.com
    port: 80
    cipher: chacha20-ietf-poly1305
    password: "your-password"
    plugin: obfs
    plugin-opts:
      mode: http             # http or tls
      host: bing.com         # Camouflage target domain

VMess

VMess Format
  # VMess + WebSocket + TLS (most common setup)
  - name: "🇺🇸 US-VMess-WS"
    type: vmess
    server: us.example.com
    port: 443
    uuid: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
    alterId: 0                  # Always 0 for newer protocol versions
    cipher: auto
    network: ws                # Transport: ws / grpc / tcp / h2
    tls: true
    servername: us.example.com # SNI, same as server or CDN domain
    ws-opts:
      path: /vmess            # Must match server-side path
      headers:
        Host: us.example.com

  # VMess + gRPC (low latency, strong firewall penetration)
  - name: "🇸🇬 SG-VMess-gRPC"
    type: vmess
    server: sg.example.com
    port: 443
    uuid: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
    alterId: 0
    cipher: auto
    network: grpc
    tls: true
    grpc-opts:
      grpc-service-name: "vmess-grpc"

Trojan

Trojan Format
  - name: "🇯🇵 JP-Trojan"
    type: trojan
    server: jp.example.com
    port: 443
    password: "your-password"
    sni: jp.example.com     # TLS SNI (usually same as server)
    udp: true
    skip-cert-verify: false # Keep false in production, never skip cert verification

  # Trojan + WebSocket (for CDN relay)
  - name: "🇰🇷 KR-Trojan-WS"
    type: trojan
    server: kr.example.com
    port: 443
    password: "your-password"
    network: ws
    ws-opts:
      path: /trojan
      headers:
        Host: kr.example.com

Hysteria 2

A next-gen protocol based on QUIC, optimized for high loss environments to boost international speeds.

Hysteria 2 Format
  - name: "⚡ US-Hysteria2"
    type: hysteria2
    server: us.example.com
    port: 443
    password: "your-password"
    sni: us.example.com
    skip-cert-verify: false
    # Set your actual local bandwidth in Mbps (upload/download)
    up: "50 Mbps"
    down: "200 Mbps"
up / down should reflect your local upload/download bandwidth, not the node's. Accurate values help QUIC perform optimally; setting them too high can cause congestion.

proxy-groups — In-depth Guide

Proxy groups are one of Clash's most powerful features. They group multiple nodes under a Strategy, allowing your rules to point to a group instead of a static node.

select — Manual Choice

The most basic type, where you manually select the active node via your client's interface.

select Proxy Group
proxy-groups:
  - name: "🚀 Proxy Select"
    type: select
    proxies:
      - "⚡ Auto Select"   # Reference another proxy group
      - "🛡️ Fallback"
      - "🇭🇰 HK-SS"        # Reference a single node (name must match proxies list)
      - "🇺🇸 US-VMess-WS"
      - "🇯🇵 JP-Trojan"
      - DIRECT            # Special: direct connection, no proxy
      - REJECT            # Special: reject connection (ad blocking)

url-test — Auto Switching

Periodically tests latency for all nodes and automatically switches to the fastest one.

url-test Proxy Group
  - name: "⚡ Auto Select"
    type: url-test
    proxies:
      - "🇭🇰 HK-SS"
      - "🇺🇸 US-VMess-WS"
      - "🇯🇵 JP-Trojan"
      - "⚡ US-Hysteria2"
    url: 'http://www.gstatic.com/generate_204'  # Speed test target URL
    interval: 300                               # Test interval (seconds)
    tolerance: 50                               # Switch tolerance (ms); only switches if gap exceeds this
    lazy: true                                  # Lazy: only tests when there is active traffic

fallback — Auto Failover

Uses the first node in the 'proxies' list by priority. If the current node fails, it automatically switches to the next one to maintain connectivity.

fallback Proxy Group
  - name: "🛡️ Fallback"
    type: fallback
    proxies:
      - "🇭🇰 HK-SS"         # Primary node
      - "🇯🇵 JP-Trojan"     # Backup 1
      - "🇺🇸 US-VMess-WS"   # Backup 2
    url: 'http://www.gstatic.com/generate_204'
    interval: 60   # Check interval (shorter than url-test for faster failure detection)

load-balance — Load Balancing

Distributes different requests across multiple nodes. Best for concurrent connection scenarios like downloads to improve overall throughput.

load-balance Proxy Group
  - name: "⚖️ Load Balance"
    type: load-balance
    strategy: consistent-hashing  # round-robin | consistent-hashing (same domain → same node)
    proxies:
      - "🇭🇰 HK-SS"
      - "🇯🇵 JP-Trojan"
      - "🇺🇸 US-VMess-WS"
    url: 'http://www.gstatic.com/generate_204'
    interval: 300

rules — In-depth Rule Configuration

Rules determine where every network request goes: direct, to a proxy group, or blocked. Rules match top-to-bottom; once a match is found, it's executed and no further rules are checked.

Rule Types Overview

Rule TypeFormatDescription
DOMAIN DOMAIN,google.com,POLICY Exact match for a full domain
DOMAIN-SUFFIX DOMAIN-SUFFIX,google.com,POLICY Matches domain and all its subdomains
DOMAIN-KEYWORD DOMAIN-KEYWORD,google,POLICY Matches if domain contains keyword
IP-CIDR IP-CIDR,192.168.0.0/16,POLICY Matches target IP range
IP-CIDR6 IP-CIDR6,::1/128,POLICY Matches IPv6 range
GEOIP GEOIP,CN,POLICY Matches by target IP's geographic location (country)
GEOSITE GEOSITE,CN,POLICY Matches via preset domain database (Mihomo extension)
PROCESS-NAME PROCESS-NAME,steam.exe,POLICY Matches by the requesting process name (desktop only)
RULE-SET RULE-SET,rule-set-name,POLICY Refers to external rule-set files (batch rules)
MATCH MATCH,POLICY Catch-all rule for all unmatched requests (must be last)

Rule Matching Priority

Matches top-to-bottom and stops at first hit. Precise rules (e.g., DOMAIN) should be first, broader rules (e.g., GEOIP) later, and MATCH must always be the final line.
DOMAIN Exact DomainHighest
DOMAIN-SUFFIX Domain Suffix
DOMAIN-KEYWORD Domain Keyword
IP-CIDR / GEOIP IP Address Rule
MATCH Catch-all (Final)Must be last

Common Rule Examples

config.yaml — Rule Examples
rules:
  # ===== Ad & Malicious Domain Block =====
  - DOMAIN-KEYWORD,adservice,REJECT
  - DOMAIN-SUFFIX,doubleclick.net,REJECT
  - DOMAIN-SUFFIX,googlesyndication.com,REJECT

  # ===== Developer tools via proxy (precise matches first) =====
  - DOMAIN-SUFFIX,github.com,🚀 Proxy Select
  - DOMAIN-SUFFIX,githubusercontent.com,🚀 Proxy Select
  - DOMAIN-SUFFIX,npmjs.com,🚀 Proxy Select
  - DOMAIN-SUFFIX,docker.io,🚀 Proxy Select
  - DOMAIN-SUFFIX,docker.com,🚀 Proxy Select

  # ===== Process-name rules (desktop only) =====
  - PROCESS-NAME,steam.exe,🚀 Proxy Select
  - PROCESS-NAME,git,🚀 Proxy Select

  # ===== Private IP ranges: direct =====
  - IP-CIDR,127.0.0.0/8,DIRECT
  - IP-CIDR,172.16.0.0/12,DIRECT
  - IP-CIDR,192.168.0.0/16,DIRECT
  - IP-CIDR,10.0.0.0/8,DIRECT

  # ===== China mainland IPs: direct =====
  - GEOIP,CN,DIRECT

  # ===== Catch-all: remaining traffic via proxy =====
  - MATCH,🚀 Proxy Select
A longer rule list increases processing time for every request. We recommend using RULE-SET to pull in external files for hundreds of rules while keeping your config.yaml clean.

Full config.yaml Example

Here's a complete, well-commented Clash configuration. It includes three protocol types, four group strategies, and a full set of rules. Copy and modify it to fit your needs:

Complete config.yaml (Annotated)
# ============================================================
#   Clash config.yaml — Complete Example
# ============================================================

# --- Basic Configuration ---
mixed-port: 7890
allow-lan: false
mode: rule
log-level: info
ipv6: false
external-controller: 127.0.0.1:9090
secret: ""

# --- DNS Configuration ---
dns:
  enable: true
  listen: 0.0.0.0:53
  ipv6: false
  enhanced-mode: fake-ip
  fake-ip-range: 198.18.0.1/16
  fake-ip-filter:
    - '*.lan'
    - '*.local'
    - +.msftncsi.com
    - +.stun.*.*
    - time.*.com
    - ntp.*.com
  nameserver:
    - 1.1.1.1
    - 8.8.8.8
  fallback:
    - tls://8.8.8.8:853
    - tls://1.1.1.1:853
  fallback-filter:
    geoip: true
    geoip-code: CN

# --- Proxy Nodes ---
proxies:
  - name: "🇭🇰 HK-SS"
    type: ss
    server: hk.example.com
    port: 443
    cipher: aes-256-gcm
    password: "your-ss-password"
    udp: true

  - name: "🇺🇸 US-VMess"
    type: vmess
    server: us.example.com
    port: 443
    uuid: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
    alterId: 0
    cipher: auto
    network: ws
    tls: true
    servername: us.example.com
    ws-opts:
      path: /vmess
      headers:
        Host: us.example.com

  - name: "🇯🇵 JP-Trojan"
    type: trojan
    server: jp.example.com
    port: 443
    password: "your-trojan-password"
    sni: jp.example.com
    udp: true

# --- Proxy Groups ---
proxy-groups:
  - name: "🚀 Proxy Select"
    type: select
    proxies:
      - "⚡ Auto Select"
      - "🛡️ Fallback"
      - "🇭🇰 HK-SS"
      - "🇺🇸 US-VMess"
      - "🇯🇵 JP-Trojan"
      - DIRECT

  - name: "⚡ Auto Select"
    type: url-test
    proxies:
      - "🇭🇰 HK-SS"
      - "🇺🇸 US-VMess"
      - "🇯🇵 JP-Trojan"
    url: 'http://www.gstatic.com/generate_204'
    interval: 300
    tolerance: 50

  - name: "🛡️ Fallback"
    type: fallback
    proxies:
      - "🇭🇰 HK-SS"
      - "🇯🇵 JP-Trojan"
      - "🇺🇸 US-VMess"
    url: 'http://www.gstatic.com/generate_204'
    interval: 60

  - name: "🎬 Streaming"
    type: select
    proxies:
      - "🇺🇸 US-VMess"
      - "🇯🇵 JP-Trojan"
      - "🚀 Proxy Select"

# --- Rules ---
rules:
  # Ad blocking
  - DOMAIN-KEYWORD,adservice,REJECT
  - DOMAIN-SUFFIX,doubleclick.net,REJECT

  # Streaming
  - DOMAIN-SUFFIX,netflix.com,🎬 Streaming
  - DOMAIN-SUFFIX,nflxso.net,🎬 Streaming
  - DOMAIN-SUFFIX,disneyplus.com,🎬 Streaming
  - DOMAIN-SUFFIX,spotify.com,🎬 Streaming

  # Developer tools
  - DOMAIN-SUFFIX,github.com,🚀 Proxy Select
  - DOMAIN-SUFFIX,githubusercontent.com,🚀 Proxy Select
  - DOMAIN-SUFFIX,npmjs.com,🚀 Proxy Select
  - DOMAIN-SUFFIX,docker.io,🚀 Proxy Select

  # Private IP ranges: direct
  - IP-CIDR,127.0.0.0/8,DIRECT
  - IP-CIDR,192.168.0.0/16,DIRECT
  - IP-CIDR,10.0.0.0/8,DIRECT

  # China mainland IPs: direct
  - GEOIP,CN,DIRECT

  # Catch-all: remaining traffic via proxy
  - MATCH,🚀 Proxy Select

Done Configuring? Download a Client

Import your configuration file into a Clash client, or use the 'Subscription' feature to pull managed configs directly from your provider.