01 · OVERVIEW
What This Doc Can Do for You
The tutorial covers how to install and connect; the docs cover what each config field means and how to change it. Use both together for best results.
Who This Is For
Anyone who's already imported a subscription and wants to edit rules, tune DNS, enable TUN, or debug a proxy group that isn't working.
Where's the Config File
GUI clients usually let you edit it under Config / Profiles; the CLI core reads config.yaml from its working directory by default.
About the Core
This documentation is based on mihomo (Clash Meta) syntax, which is compatible with common Clash config formats.
Back Up Before You Edit
After manually editing the YAML, double-check indentation and the space after colons — syntax errors will prevent the core from starting.
New to importing a subscription? Read the tutorial first, then come back for the field reference below.
02 · CONFIG
Config Structure Overview
A complete config is usually made up of a few blocks: ports → proxies → proxy groups → rules → DNS. Here's a minimal, readable skeleton:
# config.yaml — minimal skeleton
port: 7890
socks-port: 7891
allow-lan: false
mode: rule
log-level: info
external-controller: 127.0.0.1:9090
proxies:
- name: "Example Node"
type: ss
server: example.com
port: 8388
cipher: aes-128-gcm
password: "password"
proxy-groups:
- name: "PROXY"
type: select
proxies:
- "Example Node"
- DIRECT
rules:
- DOMAIN-SUFFIX,us,DIRECT
- MATCH,PROXY
Common Base Fields
| Field | Type | Description |
|---|
| port | number | HTTP proxy port, commonly used by browsers / system proxy |
| socks-port | number | SOCKS5 Port |
| mixed-port | number | Mixed HTTP/SOCKS port (use this or the ports above) |
| allow-lan | bool | Whether to allow LAN devices to use this proxy |
| mode | string | rule / global / direct |
| log-level | string | silent / error / warning / info / debug |
| ipv6 | bool | Whether to enable IPv6 |
When enabling allow-lan: true, also set a secret to protect the external controller — otherwise anyone on your LAN could change your config.
03 · PROXIES
Proxies (proxies)
Each node is an outbound channel. This section is usually generated automatically after importing a subscription; if adding nodes manually, make sure each name is unique in the config.
ss
ssr
vmess
vless
trojan
hysteria2
tuic
wireguard
http
socks5
Common Fields
| Field | Type | Description |
|---|
| name | string | Display name, referenced by proxy groups and rules |
| type | string | Protocol type, e.g. ss, vmess |
| server | string | Server domain or IP |
| port | number | Server port |
| udp | bool | Whether to allow UDP relay (depends on the protocol by default) |
Shadowsocks Example
- name: "HK-SS"
type: ss
server: hk.example.com
port: 8388
cipher: aes-128-gcm
password: "your-password"
udp: true
Different protocols have their own extra fields (e.g. VMess's uuid and alterId, Trojan's password and sni). Always follow what your provider gives you — don't edit these fields arbitrarily.
04 · PROXY-GROUPS
Proxy Groups (proxy-groups)
A proxy group bundles multiple nodes together and decides how one gets picked. Rules usually reference a group name, not an individual node.
select
Manual selection. Great for region groups like Hong Kong / Japan / US.
url-test
Automatically picks the fastest node by latency; configurable with interval and tolerance.
fallback
Tries nodes in list order, switching to the next one if the current one fails.
load-balance
Load-balances traffic across available nodes — good for splitting traffic across multiple lines.
url-test Example
- name: "Auto Select"
type: url-test
proxies:
- "HK-01"
- "JP-01"
- "US-01"
url: http://www.gstatic.com/generate_204
interval: 300
tolerance: 50
05 · RULES
Rule Syntax (rules)
Rules are matched top-down and stop at the first match. Add a MATCH fallback rule at the end to catch anything not covered.
Common Match Types
| Type | Example | Description |
|---|
| DOMAIN | DOMAIN,api.example.com,PROXY | Exact Domain |
| DOMAIN-SUFFIX | DOMAIN-SUFFIX,google.com,PROXY | Suffix Match |
| DOMAIN-KEYWORD | DOMAIN-KEYWORD,ads,REJECT | Keyword Match |
| IP-CIDR | IP-CIDR,192.168.0.0/16,DIRECT | IPv4 Range |
| GEOIP | GEOIP,US,DIRECT | By Country/Region |
| MATCH | MATCH,PROXY | Final Fallback Rule |
Example Syntax
rules:
- DOMAIN-SUFFIX,local,DIRECT
- IP-CIDR,127.0.0.0/8,DIRECT
- DOMAIN-KEYWORD,ad,REJECT
- GEOIP,US,DIRECT
- MATCH,PROXY
Put custom rules near the top; placing them after GEOIP,US or other broad rules may mean they never get matched.
06 · DNS
DNS Configuration
DNS determines how domain names are resolved. A good DNS setup reduces pollution, works better with your routing rules, and is a key step when troubleshooting "nodes connect but sites won't load" issues.
dns:
enable: true
listen: 0.0.0.0:53
enhanced-mode: fake-ip
nameserver:
- https://cloudflare-dns.com/dns-query
- https://dns.google/dns-query
fallback:
- tls://1.1.1.1
- tls://8.8.8.8
fallback-filter:
geoip: true
geoip-code: US
Mode Overview
- redir-host: Resolves the real IP. Good compatibility, useful for apps that need a real address.
- fake-ip: Returns a virtual IP. Faster resolution and more commonly paired with rule-based routing; some games or LAN apps may need to be added to
fake-ip-filter.
07 · TUN
TUN Mode
System proxy only covers apps that respect system proxy settings; TUN takes over traffic via a virtual network adapter, so more apps (including ones without proxy support) can follow your rules.
tun:
enable: true
stack: system # system / gvisor / mixed
dns-hijack:
- any:53
auto-route: true
auto-detect-interface: true
- Windows: Usually requires launching the client as administrator.
- macOS: The first time you enable it, you'll be asked to install a network extension — allow it in System Settings.
- vs. System Proxy: Normally use just one at a time; running both together can cause double-proxying or odd behavior.
For servers or headless environments, prefer the CLI core with environment-variable proxies; on desktop, enable TUN only when you need full system-wide takeover.
08 · API
External Controller API
Once you expose a REST API via external-controller, dashboards and scripts can switch nodes, view connections, and hot-reload the config.
| Field | Type | Description |
|---|
| external-controller | string | Listen address, e.g. 127.0.0.1:9090 |
| secret | string | Access secret, sent via the Authorization: Bearer <secret> header |
| external-ui | string | Optional, static asset folder for an external dashboard |
Common Endpoints (illustrative)
# View current config version / status
GET http://127.0.0.1:9090/version
# Switch the selected node in a proxy group
PUT http://127.0.0.1:9090/proxies/{group}
Body { "name": "HK-01" }
# Reload the config
PUT http://127.0.0.1:9090/configs?force=true
In production or public-facing environments, always set a secret, and bind to 127.0.0.1 only — never expose the controller port to the public internet.
Installed? Now Fine-Tune Your Config
Once you've downloaded a client and connected following the tutorial, come back here to customize your rules and DNS — it'll go much more smoothly.