ClashX Config File Deep Dive: YAML Explained

Configuration Overview

ClashX uses YAML format configuration files to define all proxy behaviors. Understanding the structure and function of each configuration item is key to mastering ClashX.

The configuration file is usually located at ~/.config/clash/config.yaml, and can also be automatically updated via subscription links. This article will provide an in-depth analysis of each part of the configuration file to help you create the most suitable configuration for your needs.

💡

YAML Format Key Points

YAML is very sensitive to indentation and must use spaces (not tabs) for indentation. It is recommended to use 2 spaces for one level of indentation.

Basic Structure

A complete ClashX configuration file mainly contains the following sections:

Basic Configuration File Structure

# General settings
port: 7890
socks-port: 7891
allow-lan: false
mode: rule
log-level: info

# Proxy Nodes
proxies:
  - name: "Node1"
    type: ss
    server: example.com
    port: 443

# Policy groups
proxy-groups:
  - name: "🚀 Proxy Select"
    type: select
    proxies:
      - "Node1"

# Rules
rules:
  - DOMAIN-SUFFIX,google.com,🚀 Proxy Select
  - GEOIP,CN,DIRECT
  - MATCH,🚀 Proxy Select

General Settings

General settings control the basic behavior and performance parameters of ClashX.

Port Configuration

# HTTP proxy port
port: 7890

# SOCKS5 proxy port
socks-port: 7891

# Mixed port (supports both HTTP and SOCKS5)
mixed-port: 7892

# RESTful API port
external-controller: 127.0.0.1:9090

# API access key (optional)
secret: "your-secret-key"

Network Settings

# AllowLocal Networkconnection
allow-lan: false

# bind address(Local Networkwhen used)
bind-address: "*"

# Mode：rule(Rules) / global(global) / direct(Direct)
mode: rule

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

# IPv6 support
ipv6: true

DNS Configuration

DNS configuration affects the speed and accuracy of domain name resolution:

dns:
  enable: true
  listen: 0.0.0.0:53
  enhanced-mode: fake-ip  # or redir-host

  # Fake-IP address pool
  fake-ip-range: 198.18.0.1/16

  # Fake-IP filter (these domains do not use Fake-IP)
  fake-ip-filter:
    - "*.lan"
    - "localhost.ptlogin2.qq.com"

  # DNS server
  nameserver:
    - 119.29.29.29
    - 223.5.5.5
    - https://doh.pub/dns-query

  # Fallback DNS(used when the primary DNS fails)
  fallback:
    - https://1.1.1.1/dns-query
    - https://dns.google/dns-query

  # Domain-based DNS selection
  nameserver-policy:
    "geosite:cn":
      - 119.29.29.29
      - 223.5.5.5
    "geosite:geolocation-!cn":
      - https://1.1.1.1/dns-query

⚠️

DNS Mode Selection

fake-ip: Better performance, but may be incompatible with some applications
redir-host: Good compatibility, but slightly slower

Proxy Configuration (Proxies)

The proxies section defines all available proxy server nodes. ClashX supports multiple proxy protocols.

Shadowsocks (SS)

proxies:
  - name: "Shadowsocks nodes"
    type: ss
    server: example.com
    port: 443
    cipher: aes-256-gcm
    password: "your-password"
    udp: true

ShadowsocksR (SSR)

  - name: "ShadowsocksR nodes"
    type: ssr
    server: example.com
    port: 443
    cipher: aes-256-cfb
    password: "your-password"
    protocol: auth_aes128_md5
    protocol-param: ""
    obfs: tls1.2_ticket_auth
    obfs-param: "cloudflare.com"

VMess

  - name: "VMess nodes"
    type: vmess
    server: example.com
    port: 443
    uuid: b831381d-6324-4d53-ad4f-8cda48b30811
    alterId: 0
    cipher: auto
    tls: true
    skip-cert-verify: false
    servername: example.com
    network: ws
    ws-opts:
      path: /path
      headers:
        Host: example.com

Trojan

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

HTTP/HTTPS Proxy

  - name: "HTTP proxy"
    type: http
    server: example.com
    port: 8080
    username: user
    password: pass
    tls: true
    skip-cert-verify: false

Proxy Groups Configuration

Proxy groups allow you to combine multiple nodes to achieve advanced features such as automatic selection and load balancing.

select - Manual Selection

Users manually select which node to use:

proxy-groups:
  - name: "🚀 Proxy Select"
    type: select
    proxies:
      - "🇭🇰 Hong Kong Node"
      - "🇯🇵 Japan Node"
      - "🇺🇸 US Node"
      - DIRECT

url-test - Auto Speed Test

Automatically select the node with the lowest latency:

  - name: "♻️ Auto Select"
    type: url-test
    proxies:
      - "Node1"
      - "Node2"
      - "Node3"
    url: "http://www.gstatic.com/generate_204"
    interval: 300    # test interval(s)
    tolerance: 50    # tolerance(ms)

fallback - Failover

Automatically switch to backup nodes when primary node fails:

  - name: "🔰 Failover"
    type: fallback
    proxies:
      - "primary node"
      - "backup node1"
      - "backup node2"
    url: "http://www.gstatic.com/generate_204"
    interval: 300

load-balance - Load Balancing

Distribute traffic among multiple nodes:

  - name: "⚖️ Load Balance"
    type: load-balance
    proxies:
      - "Node1"
      - "Node2"
      - "Node3"
    url: "http://www.gstatic.com/generate_204"
    interval: 300
    strategy: consistent-hashing  # or round-robin

relay - Chain Proxy

Traffic passes through multiple proxy nodes:

  - name: "🔗 chained proxy"
    type: relay
    proxies:
      - "Node1"
      - "Node2"

💡

Proxy Group Best Practices

• Create different proxy groups for different purposes (e.g., streaming, gaming, downloads)
• Use url-test for automatic optimization
• Include url-test groups as options in select groups

Rules Configuration

Rules determine which traffic goes through proxy and which goes direct. Rules are matched from top to bottom, and stop matching once matched.

Complete Rule Example

rules:
  # Local NetworkDirect
  - DOMAIN-SUFFIX,local,DIRECT
  - IP-CIDR,127.0.0.0/8,DIRECT
  - IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
  - IP-CIDR,10.0.0.0/8,DIRECT,no-resolve

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

  # Streaming
  - DOMAIN-SUFFIX,youtube.com,🎬 Streaming
  - DOMAIN-SUFFIX,netflix.com,🎬 Streaming
  - DOMAIN-KEYWORD,spotify,🎬 Streaming

  # Apple Services
  - DOMAIN-SUFFIX,apple.com,🍎 Apple Services
  - DOMAIN-SUFFIX,icloud.com,🍎 Apple Services

  # Google Services
  - DOMAIN-SUFFIX,google.com,🚀 Proxy
  - DOMAIN-SUFFIX,googleapis.com,🚀 Proxy
  - DOMAIN-SUFFIX,gstatic.com,🚀 Proxy

  # CN websitesDirect
  - GEOIP,CN,DIRECT

  # FinalRules
  - MATCH,🚀 Proxy

Rule Priority Recommendations

1. LAN

Highest Priority

2. Block Rules

REJECT

3. Special Services

Streaming, Gaming, etc.

4. Geolocation

GEOIP Rules

5. Default Policy

MATCH

Advanced Configuration Options

Rule Providers

Load rules from external files for easier maintenance and updates:

rule-providers:
  reject:
    type: http
    behavior: domain
    url: "https://cdn.example.com/reject.yaml"
    path: ./ruleset/reject.yaml
    interval: 86400

  proxy:
    type: http
    behavior: domain
    url: "https://cdn.example.com/proxy.yaml"
    path: ./ruleset/proxy.yaml
    interval: 86400

rules:
  - RULE-SET,reject,REJECT
  - RULE-SET,proxy,🚀 Proxy

TUN Mode

System-level proxy, no need to configure applications:

tun:
  enable: true
  stack: system  # or gVisor
  dns-hijack:
    - any:53
  auto-route: true
  auto-detect-interface: true

Experimental Features

experimental:
  # Ignore failed DNS resolutions
  ignore-resolve-fail: true

  # Detect interface name
  interface-name: en0

⚠️

Important Notes

• TUN mode requires administrator privileges
• Configuration changes need to be reloaded to take effect
• Recommended to validate configuration in test environment first

Was this article helpful?

✓ ✓ Thank you for your feedback!

Tags: ClashX Config File YAML Tutorial Advanced