DOCS // TUTORIALS

Clash Tutorials

A comprehensive guide from installation to advanced configuration. Whether you are a beginner or a power user needing custom rule routing, this page provides step-by-step instructions and configuration examples.

Supported Versions:Clash v3.0.0+ Last Updated:2025-03-15

3 Steps to Get Started [QUICKSTART]

Clash is a rule-based network proxy client driven by YAML configuration files. Follow these three steps to finish basic setup in 5 minutes and start using the proxy.

01
Download Client

Go to the download page and choose the appropriate Clash client for your OS. Windows recommends Clash for Windows or Clash Verge Rev, macOS recommends ClashX Meta, and Android recommends Clash Meta.

02
Import Subscription

In the Profiles/Config panel, paste the YAML subscription link from your service provider and click Download. The client will automatically parse nodes, rulesets, and policy groups.

03
Enable System Proxy

Turn on the 'System Proxy' switch to enjoy low-latency routing. To intercept all traffic (including games and CLI), refer to the TUN Mode configuration chapter.

Note If you don't have proxy resources, you need to purchase a subscription from a proxy service provider to get an https://... link. Clash itself is a free open-source client and does not provide any proxy nodes or services.

Installation Guide [PLATFORM]

Select your OS to view the full installation and initial setup steps.

Windows Clash Client Tutorial

For Windows, we recommend the classic Clash for Windows or the modern Clash Verge Rev. Both support Windows 10/11 and are compatible with all YAML subscription formats.

  1. Download and Install
    Go to the Download Page and get the .exe installer for Clash for Windows or Clash Verge Rev. Run the installer; if SmartScreen blocks it, click "More info" → "Run anyway".
  2. Import Subscription
    Clash for Windows: Click Profiles, paste your URL at the top, and click Download. Click the profile name to activate it.
    Clash Verge Rev: Go to Subscription, paste the link, save, and then click the profile entry to activate.
  3. Enable Proxy
    Clash for Windows: Enable System Proxy on the General page.
    Clash Verge Rev: Toggle System Proxy in Settings. The tray icon will change color when active.
  4. (Advanced) Enable TUN Mode
    To proxy games or CLI traffic, enable TUN Mode. Clash for Windows requires installing "Service Mode" first via General → Service Mode → Install. Clash Verge Rev can enable TUN directly in settings after granting admin permission.
System Requirements Supports Windows 10 / 11 (64-bit). Version 1903 or later is recommended with WebView2 Runtime installed.

macOS Clash Client Tutorial

For macOS, we recommend Clash Verge Rev or ClashX Meta. Both support the Mihomo core and are optimized for both Apple Silicon (M1/M2/M3) and Intel Macs.

  1. Download and Install
    Go to the Download Page. Choose Clash Verge Rev (.dmg) or ClashX Meta (.zip) based on your chip type. Drag the app into your Applications folder.
  2. Import Subscription
    Clash Verge Rev: In the "Subscription" tab, click the "+" icon, paste your URL, and save.
    ClashX Meta: Click the menu bar icon → Config → Remote config → Manage, then click Add to paste your link.
  3. Enable System Proxy
    Click the menu bar icon and select Set as System Proxy. The icon will change color to indicate it is active.
  4. (Advanced) Enable Enhanced Mode
    Click the menu bar icon → Enhanced Mode. This is equivalent to TUN mode and allows global traffic interception.
Note If you see a "developer cannot be verified" warning, go to System Settings → Privacy & Security and click "Open Anyway" at the bottom.

Clash Meta for Android Guide

For Android, we recommend Clash Meta for Android. It is based on the open-source Mihomo core and offers more features and better protocol support than the original version.

  1. Download and Install APK
    Go to the Download Page. We recommend the Universal APK. Once downloaded, run the APK to install (you may need to allow "Install unknown apps" in system settings).
  2. Import Subscription
    Open Clash Meta for Android, tap Profiles → + icon → select "File from URL". Paste your link and tap the save icon. Then, tap the profile to activate it.
  3. Start Proxy
    Return to the home screen and tap the grey Stopped button. Accept the system VPN request; the button will change to Running.
  4. (Advanced) Enable TUN Mode
    In Settings → Network, enable Auto Route. This activates TUN mode, allowing the app to intercept traffic from all applications seamlessly.
Note If you encounter a "Problem parsing the package" error, ensure you have downloaded the correct architecture (Universal is safest) and that your Android version is 5.0 or higher.

Clash-compatible Clients for iOS / iPadOS

Important Note Due to Apple's policies, there is no official app named "Clash" on iOS. You must use third-party clients compatible with the Clash configuration format. This guide uses Stash and Shadowrocket as examples. Both must be purchased from a non-mainland China App Store.

Stash Tutorial

  1. Purchase and Download Stash
    Using a US/HK Apple ID, search for Stash in the App Store and purchase it (approx. $4.99).
  2. Add Subscription Configuration
    Open Stash → Config tab → + in the top-right → select "Download from URL". Paste your subscription link, name it, and tap "Done".
  3. Start Proxy
    Switch to the Home tab and tap "Connect". Accept the iOS VPN request to start the proxy.
  4. Select Nodes
    In the Proxy tab, you can view policy groups and select nodes manually, or tap the lightning icon for a latency test to auto-select the best node.

Shadowrocket Tutorial

  1. Purchase and Download Shadowrocket
    Using a US Apple ID, search for Shadowrocket in the App Store and purchase it ($2.99).
  2. Import Subscription Link
    Open Shadowrocket → tap + in the top-right → set Type to "Subscribe" → paste subscription URL → tap "Done". Nodes will be parsed and displayed in the list.
  3. Start Connection
    Select a node from the list and toggle the Connected switch at the top. Tap "Allow" to authorize the VPN and start proxying.

Surge 5 Tutorial

  1. Download Surge 5
    Search for Surge 5 in the App Store. The app offers a 14-day free trial, after which a license is required.
  2. Import Configuration
    On the home screen, tap the current profile → "Download from URL", paste your subscription link, and download.
  3. Start Proxy
    Tap "Start" in the top-right and authorize the VPN. Surge 5 automatically recognizes most Clash subscription formats.

Linux Clash Client Tutorial (GUI)

For Linux desktop users, we recommend Clash Verge Rev. It provides a modern graphical interface and full TUN mode support, compatible with Ubuntu, Debian, Fedora, and more.

  1. Download and Install
    Go to the Download Page and get the package for your distribution (.deb for Ubuntu/Debian, .rpm for Fedora/CentOS). Install it using your package manager.
  2. Import Subscription
    Launch Clash Verge, go to the Subscription tab, click "+", paste your URL, and save.
  3. Enable Proxy
    Enable "System Proxy" on the home screen. For global interception, activate TUN Mode in settings (may require sudo permissions).

Clash Core for Linux (Advanced/Server)

Suitable for headless server environments or advanced users preferring manual deployment.

  1. Download and Extract Core
    Download the .gz archive for your architecture, extract it, and grant executable permissions:
    $wget https://clashconf.com/assets/clients/core/mihomo-linux-amd64.gz
    $gunzip mihomo-linux-amd64.gz
    $chmod +x mihomo-linux-amd64
    $sudo mv mihomo-linux-amd64 /usr/local/bin/clash
  2. Place Configuration File
    Place your config.yaml into the Clash configuration directory:
    $mkdir -p ~/.config/clash
    $cp config.yaml ~/.config/clash/config.yaml
  3. Start Clash
    Start Clash; it will listen on 127.0.0.1:9090 for the RESTful API by default:
    $clash -d ~/.config/clash
  4. Configure Proxy
    Configure your environment variables to use the Clash ports (default 7890/7891):
    $export http_proxy=http://127.0.0.1:7890
    $export https_proxy=http://127.0.0.1:7890
Note To enable auto-start, refer to the Wiki for instructions on registering Clash as a systemd service.

Import Subscription [SUBSCRIPTION]

A Subscription URL is an online address (usually starting with https://) provided by your service provider that points to a YAML configuration file. Clash clients use this link to automatically download nodes, rulesets, and policy groups.

What is a Subscription Link?

A subscription link is essentially a URL pointing to a YAML config file. Every time you update the subscription in your client, Clash requests this URL to fetch the latest node info and rules.

Recommended Update Frequency

Best Practice We recommend setting the auto-update interval to 24h (once per day) to keep node info current. If nodes fail or time out, you can manually click "Update" to force a refresh.

Import Comparison Table

Platform / Client Import Path Activation Method
Clash for Windows Profiles → Top URL input → Enter Click Profile Name
ClashX Pro (macOS) Menu Bar → Config → Remote config → Manage Click Select
Clash for Android Profiles → + → Import from URL Tap the circle next to Profile
Stash (iOS) Profiles → + → Import from URL Auto-activates after completion
Clash Core (Linux) wget <URL> -O ~/.config/clash/config.yaml Restart Clash process

YAML Config Deep Dive [CONFIG.YAML]

All Clash behaviors are driven by config.yaml. Understanding core fields helps you fine-tune proxy behavior, add custom nodes, and write advanced routing rules.

Basic Ports and Run Modes

~/.config/clash/config.yaml
# HTTP proxy port
port: 7890
# SOCKS5 proxy port
socks-port: 7891
# Allow LAN devices to use proxy (true/false)
allow-lan: false
# Proxy mode: rule | global | direct
mode: rule
# Log level: info | warning | error | debug | silent
log-level: info
# RESTful API port
external-controller: 127.0.0.1:9090

Proxy Nodes (proxies)

The proxies field defines all available outbound nodes, supporting protocols like Shadowsocks, VMess, Trojan, VLESS, Hysteria2, WireGuard, and more:

proxies section
proxies:
  - name: "🇭🇰 Hong Kong-01" # node display name
    type: ss # protocol: ss / vmess / trojan / vless / hy2 / wireguard
    server: hk01.example.com
    port: 8388
    cipher: aes-256-gcm
    password: "your_password"
  - name: "🇯🇵 Japan-VMess"
    type: vmess
    server: jp01.example.com
    port: 443
    uuid: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
    alterId: 0
    cipher: auto
    tls: true

Supported Protocol Types

Shadowsocks (ss) ShadowsocksR (ssr) VMess VLESS Trojan Hysteria2 (hy2) TUIC WireGuard SOCKS5 / HTTP(S) Snell

Policy Groups (proxy-groups)

Policy groups organize multiple nodes according to specific selection strategies. Supported modes: select (manual), url-test (auto latency), fallback (failover), and load-balance (load balancing):

proxy-groups section
proxy-groups:
  - name: "PROXY" # main outbound group
    type: select # manual selection
    proxies:
      - Auto-Select
      - 🇭🇰 Hong Kong-01
      - 🇯🇵 Japan-VMess
  - name: "Auto-Select"
    type: url-test # auto select lowest latency
    proxies:
      - 🇭🇰 Hong Kong-01
      - 🇯🇵 Japan-VMess
    url: "http://www.gstatic.com/generate_204"
    interval: 300 # test every 300 seconds

TUN Mode Configuration [TUN MODE]

TUN mode creates a virtual network interface (TUN/TAP) in the OS to intercept all TCP/UDP traffic at the kernel level. This includes apps that don't follow system proxy settings (e.g., games, CLI tools, UWP apps), achieving true transparent proxying.

When to Enable TUN Mode

Scenario TUN Needed? Description
Game Acceleration (International Servers - UDP) ✅ Required Games use UDP protocol, which bypasses the system HTTP proxy
Terminal / curl / git Proxy ⚠️ Optional Can be replaced by the http_proxy environment variable
Windows UWP App Proxy ✅ Required UWP apps use sandboxing that isolates them from the system proxy
Standard Web Browsing ❌ Not Required Browsers automatically follow system HTTP proxy settings
Router / NAS Global Transparent Proxy ✅ Required Needed to intercept traffic from all connected devices

Enable TUN in YAML Configuration

tun config block
tun:
  enable: true
  stack: system # system | gvisor | mixed
  auto-route: true # auto add routes for TUN
  auto-detect-interface: true # auto detect outbound interface
  dns-hijack:
    - any:53 # hijack all DNS queries
dns:
  enable: true
  enhanced-mode: fake-ip # fake-ip prevents DNS leaks
  nameserver:
    - 223.5.5.5 # Alibaba DNS (domestic)
    - 119.29.29.29 # DNSPod (domestic)
  fallback:
    - tls://8.8.8.8:853 # Google DoT (for overseas)
    - https://1.1.1.1/dns-query # Cloudflare DoH
Note To enable TUN mode on Windows, you must first install Service Mode in the client (run Clash for Windows as administrator, then click Install on the General page). On macOS, you need to allow network extensions (kernel extensions) in System Settings.

Advanced Rules [RULES]

Clash's rule engine is its core strength. By listing rules from highest to lowest priority in the rules field, you can precisely decide whether each request goes through PROXY, DIRECT, or is REJECTed.

Rule Type Quick Reference

Rule Type Example Description
DOMAIN DOMAIN,google.com,PROXY Exact match of the full domain
DOMAIN-SUFFIX DOMAIN-SUFFIX,youtube.com,PROXY Match domain and all subdomains
DOMAIN-KEYWORD DOMAIN-KEYWORD,openai,PROXY Domain contains the specified keyword
IP-CIDR IP-CIDR,192.168.0.0/16,DIRECT Match by IP address range (CIDR)
GEOIP GEOIP,CN,DIRECT Match by GeoIP location (CN for Mainland China IP)
PROCESS-NAME PROCESS-NAME,steam.exe,PROXY Match by process name (Desktop only)
RULE-SET RULE-SET,gfw,PROXY Reference external rule sets (rule-providers)
MATCH MATCH,DIRECT Fallback rule for all unmatched requests (must be last)

Recommended Rule Structure Example

rules section (recommended order)
rules:
  # 1. LAN addresses - direct
  - IP-CIDR,192.168.0.0/16,DIRECT
  - IP-CIDR,10.0.0.0/8,DIRECT
  - IP-CIDR,127.0.0.0/8,DIRECT
  # 2. Block ad domains
  - RULE-SET,reject,REJECT
  # 3. Domestic sites - direct
  - RULE-SET,direct,DIRECT
  - GEOIP,CN,DIRECT
  # 4. Overseas sites - proxy
  - RULE-SET,proxy,PROXY
  # 5. Fallback rule (must be last)
  - MATCH,DIRECT
Best Practice We recommend using community-maintained rule sets like Loyalsoldier/clash-rules. Use the rule-providers field to automatically fetch and schedule updates, avoiding the need to manually maintain thousands of rules.

Policy Groups [PROXY-GROUPS]

Policy groups (proxy-groups) determine which outbound node is actually used after a rule is matched. A well-designed policy group structure enables advanced features like automatic selection, failover, and load balancing.

Policy Group Type Explanation

Type Description Recommended Scenario
select Manually select a node or subgroup from the list Main outbound group for manual switching
url-test Periodically pings a URL and auto-selects the node with the lowest latency Automatic optimization (Recommended for daily use)
fallback Sequentially checks node availability and auto-skips failed nodes Ensuring node stability
load-balance Distributes connections across multiple nodes for load balancing High-concurrency multi-node download scenarios

DNS Leak Protection Setup [DNS]

DNS leakage occurs when DNS queries bypass the proxy and are sent directly to your ISP's DNS servers, exposing your browsing history. Clash resolves this via its built-in DNS module and fake-ip mode.

Recommended DNS Module Configuration

dns section
dns:
  enable: true
  listen: 0.0.0.0:53 # DNS listen port
  enhanced-mode: fake-ip # recommended: fake-ip or redir-host
  fake-ip-range: 198.18.0.0/16
  # Domestic DNS servers (queried for CN domains)
  nameserver:
    - 223.5.5.5 # Alibaba DNS
    - 114.114.114.114
  # Encrypted overseas DNS (for non-CN domains)
  fallback:
    - tls://8.8.8.8:853 # Google DNS over TLS
    - https://1.1.1.1/dns-query
  fallback-filter:
    geoip: true # use fallback DNS for non-CN IPs
    geoip-code: CN
How It Works In fake-ip mode, Clash immediately returns a fake IP (from the 198.18.0.0/16 range) for all DNS requests. The actual DNS resolution happens at the remote proxy node when traffic arrives, completely preventing local DNS leaks and significantly reducing connection latency.

FAQ [FAQ]

Clash is a pure proxy client and does not include any proxy nodes. Its job is to parse YAML configs, match routing rules, and forward traffic through specified nodes. Nodes are typically provided by proxy service providers via YAML subscription links. This site does not provide or sell any nodes or subscriptions.
Browsers follow system HTTP proxy settings by default. However, games use UDP and terminal tools often ignore system proxy settings. Solution: Enable TUN Mode (see the TUN section above) to intercept all TCP/UDP traffic at the kernel level via a virtual network interface.
This is usually a rule configuration issue where local traffic is incorrectly routed through a proxy, increasing latency. Solutions:

1. Add GEOIP,CN,DIRECT to your rules to ensure local IPs connect directly;
2. Use rule-providers with a community-maintained direct (local domain whitelist) ruleset;
3. Ensure your DNS config routes local domains to local DNS servers (e.g., AliDNS 223.5.5.5).
Default config paths:

macOS / Linux: ~/.config/clash/config.yaml
Windows: %USERPROFILE%\.config\clash\config.yaml

In Clash for Windows, you can click "Open Clash Home Folder" on the General page. We recommend using an editor with YAML syntax highlighting (like VS Code). Click "Reload Config" in the client after saving your changes.
fake-ip: Returns a fake IP (198.18.x.x) immediately for all DNS requests, postponing actual resolution to the remote proxy node. Pros: extremely fast connection setup, prevents DNS leaks. Recommended for TUN mode.

redir-host: Performs real DNS resolution locally before matching rules. Better compatibility but carries a risk of DNS leaks and adds latency to the first connection. Suitable for scenarios with specific IP requirements.
Troubleshooting steps:

1. Check if the subscription link is complete and try opening it in a browser to verify accessibility;
2. Confirm the subscription hasn't expired;
3. If your network requires a proxy to access the subscription URL, enable "Update via Proxy" in the client settings;
4. Check the Log page for error messages to identify the specific issue.