Where is the config.yaml file located?

On macOS, ClashX stores the configuration file at ~/.config/clash/config.yaml. You can also access it via the ClashX menu bar icon > Config > Open Config Folder.

Do I need to restart ClashX after editing config.yaml?

No full restart needed. After saving changes, click Config > Reload Config in the ClashX menu bar. For TUN mode or DNS changes, a restart is recommended.

What happens if YAML indentation is wrong?

YAML is indentation-sensitive and requires spaces (not tabs). Incorrect indentation causes parsing failures, and ClashX will fail to start or fall back to the last valid config.

What is the difference between proxy-groups and rules?

proxy-groups define proxy strategy groups (auto-select, load-balance, etc.), while rules define traffic routing (which domains/IPs use which group). They work together for smart routing.

ClashX Configuration File Complete Guide 2026【YAML Tutorial】| Proxies/Rules/DNS

1. What Is config.yaml?

config.yaml is the core configuration file for the Clash kernel. Written in YAML format, it defines all runtime parameters including proxy nodes, policy groups, routing rules, and DNS settings. When ClashX launches on macOS, it automatically reads this file, typically located at ~/.config/clash/config.yaml.

Mastering config.yaml means you have full control over your network traffic — what goes through the proxy, what connects directly, and what gets blocked.

Highly flexible: More advanced options than the GUI can provide
Portable: A single config can be shared across multiple devices
Version-controlled: Track changes with Git for easy rollback

2. YAML Basics

YAML (YAML Ain't Markup Language) is a human-friendly data serialization format. Before writing config.yaml, here are the essential rules:

Indentation: Use spaces (never tabs), typically 2 spaces per level
Key-value pairs: key: value — a space after the colon is required
Lists: Start with - to denote an array element
Comments: Start with #

# Basic configuration example
port: 7890          # HTTP proxy port
socks-port: 7891    # SOCKS5 proxy port
allow-lan: false    # Allow LAN connections
mode: rule          # Mode: rule/global/direct
log-level: info     # Log level: silent/error/warning/info/debug
external-controller: 127.0.0.1:9090  # RESTful API address

Note: YAML is extremely sensitive to indentation. A single indentation error will cause the entire config to fail. Use an editor with YAML syntax highlighting (such as VS Code) for editing.

3. Proxies Configuration

The proxies section is where you define all your proxy servers. Clash supports multiple protocols including Shadowsocks (SS), VMess, and Trojan. Each node requires a name, type, server address, and port.

Shadowsocks (SS) Node

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

VMess Node

  - name: "JP-Node-VMess"
    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: /path
      headers:
        Host: jp.example.com

Trojan Node

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

4. Proxy Groups Configuration

Proxy groups are one of Clash's most powerful features, allowing you to combine multiple nodes with intelligent selection strategies. Common types include:

select: Manual selection for precise control
url-test: Auto speed-test, periodically checks latency and picks the fastest node
fallback: Failover, tries nodes in order and auto-switches on failure
load-balance: Distributes traffic across multiple nodes

proxy-groups:
  - name: "🚀 Proxy Select"
    type: select
    proxies:
      - "♻️ Auto Best"
      - "HK-Node-SS"
      - "JP-Node-VMess"
      - "US-Node-Trojan"
      - DIRECT

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

  - name: "🛡️ Failover"
    type: fallback
    proxies:
      - "HK-Node-SS"
      - "JP-Node-VMess"
      - "US-Node-Trojan"
    url: http://www.gstatic.com/generate_204
    interval: 300

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

5. Routing Rules

Routing rules determine where each network request goes. Clash matches rules from top to bottom and executes immediately on a hit. Common rule types include:

DOMAIN-SUFFIX: Matches domain suffixes like google.com
DOMAIN-KEYWORD: Matches keywords within domain names
IP-CIDR: Matches destination IP ranges
GEOIP: Matches by IP geolocation country/region
MATCH: Catch-all rule for unmatched requests

rules:
  # Direct connection rules
  - DOMAIN-SUFFIX,cn,DIRECT
  - DOMAIN-SUFFIX,local,DIRECT
  - DOMAIN-KEYWORD,baidu,DIRECT

  # Proxy rules
  - DOMAIN-SUFFIX,google.com,🚀 Proxy Select
  - DOMAIN-SUFFIX,youtube.com,🚀 Proxy Select
  - DOMAIN-SUFFIX,github.com,🚀 Proxy Select
  - DOMAIN-KEYWORD,telegram,🚀 Proxy Select

  # IP rules
  - IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
  - IP-CIDR,10.0.0.0/8,DIRECT,no-resolve
  - IP-CIDR,127.0.0.0/8,DIRECT,no-resolve
  - GEOIP,CN,DIRECT

  # Catch-all rule (must be last)
  - MATCH,🚀 Proxy Select

Tip: Rule order matters. More specific rules should come first, and the MATCH catch-all rule must be last. While more rules can slow matching slightly, Clash uses efficient algorithms so a few thousand rules are generally fine.

6. DNS Configuration

DNS configuration directly affects browsing speed and security. Clash provides rich DNS options including nameserver, fallback, and fake-ip mode.

dns:
  enable: true
  listen: 0.0.0.0:53
  enhanced-mode: fake-ip    # redir-host or fake-ip
  fake-ip-range: 198.18.0.1/16
  fake-ip-filter:
    - "*.lan"
    - "*.local"
    - "localhost.ptlogin2.qq.com"

  nameserver:
    - https://doh.pub/dns-query          # Tencent DoH
    - https://dns.alidns.com/dns-query   # Alibaba DoH
    - 114.114.114.114

  fallback:
    - https://dns.google/dns-query       # Google DoH
    - https://cloudflare-dns.com/dns-query
    - tls://8.8.4.4:853

  fallback-filter:
    geoip: true
    geoip-code: CN
    ipcidr:
      - 240.0.0.0/4

fake-ip mode: Returns fake IPs, reduces DNS leaks, faster — recommended for most users
redir-host mode: Returns real IPs, better compatibility — use when apps need actual IPs
fallback: When nameserver results are polluted, fallback DNS servers re-resolve the request

7. Frequently Asked Questions

Q1: Config changes don't take effect after saving?

Ensure the YAML format is correct (no tab indentation, space after colons), then click "Config" → "Reload Config" in the ClashX menu bar. Use an online YAML validator to check syntax.

Q2: How to use subscriptions and custom rules together?

Use the proxy-providers feature to import subscription nodes, then write custom policy groups and rules in your local config. Both coexist seamlessly.

Q3: Do too many rules affect performance?

Generally, a few thousand rules have minimal impact. Clash uses efficient matching algorithms, but avoid duplicate rules and place frequently-hit rules near the top.

Q4: fake-ip vs redir-host — which to choose?

Recommend fake-ip mode: faster and prevents DNS leaks. Only switch to redir-host when specific apps have compatibility issues. Use fake-ip-filter to whitelist domains that need real IPs.

Q5: How to find the current config file path?

Click "Config" → "Open Config Folder" in the ClashX menu bar to see the current config.yaml file location.