Complete Guide to Clash YAML Configuration

The Clash YAML configuration file is the heart of the entire proxy system. Understanding its structure and field conventions is an essential step for advanced usage. Subscription-provided configs are usually generic templates and are not optimized for specific scenarios. This is the official Clash configuration file reference, systematically explaining every core field and the officially recommended best-practice syntax.

Overall Config File Structure

A complete Clash configuration file consists of six major sections: global parameters, DNS configuration, proxy nodes (proxies), proxy groups (proxy-groups), rules (rules), and an optional TUN configuration. Together, these six sections determine how Clash handles every network request you make.

port: 7890
socks-port: 7891
allow-lan: false
mode: rule
log-level: info
external-controller: 127.0.0.1:9090

dns:
  enable: true
  enhanced-mode: fake-ip
  nameserver: [1.1.1.1, 8.8.8.8]

proxies: [ ... ]
proxy-groups: [ ... ]
rules: [ ... ]

Global Parameters Explained

Global parameters control Clash's fundamental runtime behavior. The following are the most commonly used fields:

port and socks-port: The listening ports for the HTTP proxy and SOCKS5 proxy respectively, defaulting to 7890/7891. You can also use mixed-port: 7890 to merge them into a single port that supports both protocols.
allow-lan: When set to true, other devices on the local network can also use Clash as a proxy server — useful for router-level shared proxy setups.
mode: Global proxy mode. Options are rule (intelligent split-routing), global (route all traffic through proxy), and direct (all traffic connects directly).
external-controller: The address and port for the RESTful API. Dashboards such as Yacd and MetaCubeXD use this interface to communicate with Clash for graphical control.

proxies: Proxy Node Configuration

Each object in the proxies array represents a proxy server node. Required fields vary by protocol, but name, type, server, and port are mandatory for all protocols.

Clash (Mihomo core) supports more than twenty protocols including Shadowsocks, VMess, VLESS, Trojan, Hysteria2, and TUIC. Below are example configurations for the three most common protocols:

proxies:
  - name: "🇭🇰 HK-01"
    type: ss
    server: hk.example.com
    port: 8388
    cipher: chacha20-ietf-poly1305
    password: "your-password"
    udp: true

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

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

proxy-groups: Proxy Groups

Proxy groups are one of Clash's core advantages over other proxy tools. They combine multiple nodes into a single logical proxy unit, supporting manual selection, auto speed testing, failover, and load balancing — and proxy groups can reference each other in nested compositions, building a flexible layered proxy architecture.

proxy-groups:
  - name: "🚀 Node Select"
    type: select
    proxies: ["♻️ Auto Select", "🇭🇰 HK-01", "🇺🇸 US-01", DIRECT]

  - name: "♻️ Auto Select"
    type: url-test
    url: http://www.gstatic.com/generate_204
    interval: 300
    tolerance: 50
    proxies: ["🇭🇰 HK-01", "🇯🇵 JP-01", "🇺🇸 US-01"]

  - name: "🎬 Streaming"
    type: select
    proxies: ["🇺🇸 US-01", "🇯🇵 JP-01"]

The configuration above creates a two-layer structure: the "Node Select" group serves as the externally exposed entry point, where users can manually choose a specific node or select the "Auto Select" group; the "Auto Select" group continuously speed-tests nodes in the background and automatically switches to the lowest-latency one.

rules: Split-Routing Rules

The rule list is matched top-to-bottom. As soon as a rule matches, the corresponding action is executed and matching stops. Rule format is TYPE,VALUE,POLICY. The last rule must be a MATCH catch-all.

rules:
  - DOMAIN,google.com,🚀 Node Select
  - DOMAIN-SUFFIX,youtube.com,🎬 Streaming
  - DOMAIN-KEYWORD,facebook,🚀 Node Select
  - GEOIP,US,DIRECT
  - IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
  - MATCH,🚀 Node Select

Maintaining rule lists manually is tedious. It is recommended to use RULE-SET to reference community rule sets for split routing, such as Loyalsoldier/clash-rules, which include carefully curated direct-connect and proxied domain lists that are ready to use out of the box and updated regularly.

Configuration Best Practices

In practice, a few configuration recommendations can significantly improve the experience: first, set up dedicated proxy groups for popular streaming platforms (Netflix, Disney+, YouTube) so you can easily unlock content from different regions as needed; second, configure a reasonable tolerance value for url-test groups to prevent frequent node switching when latency differences are small; third, use external-controller together with a dashboard such as Yacd or MetaCubeXD to monitor connection status and traffic in real time from a browser, which greatly simplifies troubleshooting.

Ready to use Clash?

Free download — supports Windows, macOS, Linux, and Android.

Download Now

YAML proxies proxy-groups Rule Config