Home/Configuration Reference
Clash Configuration Reference
config.yaml is Clash's one and only "brain." This guide breaks it down field by field, top to bottom: what type each field is, what its default value is, and when you'd need to change it — treat it like a dictionary lookup, much faster than reading the source code.
Basic Network Fields
These fields determine which ports Clash listens on and how it receives traffic on your machine — almost every configuration uses them.
The HTTP proxy listening port, e.g. 7890. When you set your system proxy, both HTTP and HTTPS traffic point to this port.
The SOCKS5 proxy listening port. Some tools (download managers, command-line programs) only support SOCKS5 and need this port configured separately.
A mixed port that accepts both HTTP and SOCKS5 connections on the same port. Modern clients generally only need this single port configured, which is more convenient than setting port and socks-port separately.
Whether to allow other devices on the LAN to connect to this proxy port via your machine's IP. Turn this on if you want to connect from your phone to Clash running on your computer — also recommended to pair it with authentication below to keep random devices on the LAN from freeloading.
The network interface address the proxy port binds to; * means listen on all interfaces. Rarely needs changing.
Run Mode & Logging
rule routes traffic according to the rules list (recommended for everyday use); global forces all traffic through a single proxy group, useful for temporary debugging; direct connects all traffic directly, equivalent to disabling the proxy while keeping the client running.
How verbose the logs are. Temporarily switch to debug when troubleshooting connection issues to see exactly how each rule matches; for everyday use, keep it at info to avoid your log files growing too fast.
Whether to enable IPv6 support — if your network and some of your nodes natively support IPv6, enabling this can improve compatibility. If you're unsure, it's usually safe to leave it off, since IPv6 support still varies a lot between networks.
External Controller & Dashboard
Opens a RESTful API listening address, which is how the companion web control panel (Dashboard) reads proxy status, connection lists, and real-time traffic. Most clients with a GUI configure this for you automatically.
The secret key required to access the external-controller interface. If allow-lan is enabled and the panel is exposed on your LAN, be sure to set a secret — otherwise anyone on the LAN can read or modify your proxy configuration.
proxies: Node Definitions
proxies is a list where each item describes a specific proxy node. Fields vary by protocol, but they all include these general-purpose fields:
| Field | Description |
|---|---|
name | The node's display name — this is what's referenced in rules and proxy groups |
type | Protocol type: ss / vmess / trojan / socks5, etc. |
server | Server address (domain or IP) |
port | Server port |
| Other fields | Varies by protocol — for example, Shadowsocks needs cipher and password, while VMess needs uuid and alterId |
proxies:
- name: HK01
type: ss
server: hk01.example.com
port: 443
cipher: aes-256-gcm
password: "your-password"
- name: JP01
type: trojan
server: jp01.example.com
port: 443
password: "your-password"
sni: jp01.example.comIf your subscription link is in a standard format, the client will parse this whole block automatically, so you usually won't need to write it by hand — but understanding the structure helps when troubleshooting "why won't this node connect" and figuring out which field is the culprit.
proxy-groups: Scheduling Groups
The behavioral differences between the four types (select / url-test / fallback / load-balance) are covered in detail in Advanced Configuration; here are a few commonly used general-purpose fields:
| Field | Applies To | Description |
|---|---|---|
proxies | A list of the specific nodes or sub-groups included in this group | A list of the specific nodes or sub-groups included in this group |
use | All | References a remote node collection from proxy-providers, replacing a hand-written node list |
url | url-test / fallback / load-balance | The URL used for health checks, usually a lightweight endpoint like generate_204 |
interval | url-test / fallback / load-balance | Health check interval (seconds) |
tolerance | url-test | Latency tolerance (milliseconds), to prevent nodes from switching frequently over similar latencies |
strategy | load-balance | consistent-hashing or round-robin — determines the distribution algorithm |
rules: Routing Rules
For the full list of rule types, see Advanced Configuration · Rule Types Explained. Here we just cover the format: each line is a comma-separated three-part type,value,action (except MATCH, which only has two parts).
rules:
- DOMAIN-SUFFIX,github.com,Auto
- GEOIP,CN,DIRECT
- MATCH,Autodns: Domain Resolution
For a detailed breakdown of the fields and the trade-offs between Fake-IP and Redir-Host modes, see Advanced Configuration · DNS & Fake-IP. Here's a quick reference for the core fields:
| Field | Type | Description |
|---|---|---|
enable | boolean | Whether to enable the built-in DNS module (required for TUN mode) |
enhanced-mode | fake-ip / redir-host | Domain resolution strategy — see the Advanced Configuration comparison |
fake-ip-range | string | The virtual address range used by Fake-IP; must not conflict with your local network range |
nameserver | string[] | The default upstream DNS servers to use |
fallback | string[] | The fallback DNS to use when a result is judged untrustworthy |
fallback-filter | object | The conditions that determine when fallback kicks in, such as checking against geoip-code |
tun: Virtual Network Adapter
For the underlying principles, see Advanced Configuration · How TUN Mode Works. Core fields:
| Field | Type | Description |
|---|---|---|
enable | boolean | Whether to enable TUN mode |
stack | system / gvisor | Which network stack implementation to use — see the Advanced Configuration comparison |
auto-route | boolean | Whether to automatically configure the system routing table to point to the virtual adapter |
auto-detect-interface | boolean | Automatically detect the physical network interface, avoiding manual specification of the outbound interface |
dns-hijack | string[] | The address range of DNS requests that should be intercepted |
profile: Caching Strategy
Once enabled, the node you manually switch to in a select-type proxy group will be remembered — the next time you launch the client or update your subscription, it will keep your last selection instead of resetting to the default node in the config file.
Whether to cache Fake-IP's domain-to-IP mappings. Enabling this reduces re-mapping overhead after a restart, but in rare cases can cause a temporary mismatch with the actual resolved result.
A Minimal Working Configuration
Putting all of this together, a minimal working configuration looks roughly like this (in real use, proxies is usually generated automatically from your subscription, so you rarely write it by hand):
mixed-port: 7890
allow-lan: false
mode: rule
log-level: info
external-controller: 127.0.0.1:9090
proxies:
- name: Node01
type: ss
server: example.com
port: 443
cipher: aes-256-gcm
password: "your-password"
proxy-groups:
- name: Auto
type: url-test
proxies: [Node01]
url: "https://www.gstatic.com/generate_204"
interval: 300
rules:
- GEOIP,CN,DIRECT
- MATCH,AutoSave this file as config.yaml and import it into your client — that's a minimal system with working routing. From there, add modules like dns, tun, and rule-providers as needed.