Clash YAML
Configuration Reference

General fields: ports, mode, and the control interface

How listening ports are assigned

port provides an HTTP proxy listener, socks-port provides a SOCKS5 listener, and mixed-port accepts both HTTP and SOCKS5 on one port. Desktop graphical clients usually need only one mixed-port, which the system proxy can target automatically. If another application specifically requires a SOCKS5 endpoint, configure socks-port separately. Listening ports must not share a port number or conflict with other services on the system.

redir-port and tproxy-port are mainly for Linux gateways, routers, and transparent-proxy rules. Desktop users should not enable them casually just to “cover more traffic.” TUN mode uses a separate virtual network interface and routing path; it is not simply another listening port. To compare the two interception mechanisms, read TUN Mode vs. the System Proxy, identify where traffic enters the core, and then choose the relevant fields.

mixed-port: 7890
allow-lan: false
bind-address: "*"
mode: rule
log-level: info
ipv6: false

external-controller: 127.0.0.1:9090
secret: "your-controller-secret"

profile:
  store-selected: true
  store-fake-ip: true

LAN access and bind addresses

allow-lan determines whether other devices can connect through this device’s proxy ports. Set it to false for single-device use; after setting it to true, also check the operating-system firewall, listening address, and LAN isolation settings. Allowing LAN access does not automatically configure a phone or TV to use the proxy: enter the LAN address of the device running Clash and its listening port on the target device. Address changes will break connections, so assign the host a stable LAN address for long-term sharing.

bind-address limits the interfaces on which the service listens. Some clients generate this field from an “allow LAN connections” switch, so the file value may be overridden at startup by the UI. During troubleshooting, inspect the actual listening address: if it listens only on 127.0.0.1, other devices cannot connect; if it listens on all interfaces, ensure the control interface and proxy ports are not exposed to untrusted networks. Proxy listeners and the external control interface are separate services and should not be confused.

Mode, logging, and state persistence

mode: rule matches rules from top to bottom and is the basis of everyday configurations. global sends traffic to the global policy and is useful for temporarily checking whether a proxy works; direct connects without a proxy and helps determine whether the proxy path is the cause. Graphical clients usually switch modes at runtime, without necessarily writing the state back to the original subscription. Do not inspect only the file’s mode; check the current client UI as well.

log-level is commonly set to info. Temporarily raise it to debug while troubleshooting, then restore it to avoid excessive logs obscuring the diagnosis. ipv6 controls whether the core handles IPv6 capabilities, but it cannot fix a local network that lacks an IPv6 route. If connections hang after enabling it, check whether DNS returns IPv6 addresses, whether the system has usable IPv6 egress, and whether rules cover those addresses.

external-controller provides the control address used by the UI to communicate with the core and is normally bound to the local loopback address. secret authenticates access to the control interface; replace the example value. It is not a proxy-node password and is not used for remote connections. profile.store-selected saves proxy-group selections, while profile.store-fake-ip saves Fake-IP mappings. If selections reset after a subscription update, also check the client’s own persistence settings instead of editing YAML alone.

Proxy fields and proxy providers

The common structure of a proxy object

proxies is a static list of nodes. Each item needs at least a name, type, server address, and port, followed by protocol-specific authentication and transport fields. name is the reference identifier used throughout the configuration, and proxy groups use it to locate a node. Duplicate names make selection and override results unpredictable, so check uniqueness after merging a subscription. server may be a hostname or IP address, while port must match the service’s actual listening port.

The protocol type determines which fields are valid; do not mechanically copy parameters from one protocol to another. Encryption, user identifiers, transport, TLS, and the server name must match the server configuration. A client loading the YAML only means the syntax and basic field structure are valid, not that remote authentication will succeed. Handshake failures, authentication failures, connection refusals, and timeouts point to different stages and should be handled accordingly.

proxies:
  - name: "SS Demo Proxy"
    type: ss
    server: ss.example.com
    port: 443
    cipher: aes-128-gcm
    password: "your-password"
    udp: true

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

  - name: "Hysteria2 Demo Proxy"
    type: hysteria2
    server: hy2.example.com
    port: 443
    password: "your-password"
    sni: service.example.com
    skip-cert-verify: false

Authentication, TLS, and transport fields

Common Shadowsocks fields include cipher, password, and udp. The cipher must exactly match the server; similar names are not interchangeable. Trojan-style nodes rely on TLS and often require sni in addition to a password. SNI is the server name used during the handshake. It may match the connection address or be specified separately by the provider. With an incorrect value, the TCP connection may succeed while the TLS handshake fails.

skip-cert-verify controls certificate verification. A normal configuration should keep it at false; fix the server name, system clock, and certificate chain first. Setting it to true is useful only to determine whether certificate verification is the failure point, not as a general fix. Clock drift, interception on restricted networks, and an incorrect SNI can all cause certificate errors. “Connection failed” alone is not enough; use the handshake stage shown in the logs.

VMess, VLESS, TUIC, Hysteria2, and other types may also include user identifiers, network types, WebSocket paths, HTTP headers, flow control, or congestion-control fields. The available set changes with core capabilities and server deployment. When migrating a node manually, use the original subscription and current core documentation rather than copying fields based on another node’s appearance. For naming and compatibility across the original Clash, Meta, and mihomo, read Choosing a Core Version.

On-demand loading with proxy-providers

For many nodes or remote updates, use proxy-providers. A provider is a collection of nodes, and a proxy group references it through use. Common types are HTTP and local files. Remote providers include a URL, update interval, save path, and health check. The save path must be writable by the client; container and service deployments also require the directory permissions to be checked. Query parameters in remote URLs may contain credentials and should not appear in public logs or examples.

proxy-providers:
  provider-main:
    type: http
    url: "https://subscription.example/config?token=xxxx"
    path: ./providers/provider-main.yaml
    interval: 3600
    health-check:
      enable: true
      interval: 600
      url: https://www.gstatic.com/generate_204

proxy-groups:
  - name: "Subscription Proxies"
    type: select
    use:
      - provider-main
    proxies:
      - DIRECT

interval sets the refresh interval; it does not mean the client will always download immediately at startup. The client may also have its own update button and caching policy. health-check tests reachability through a fixed URL and uses the result for display or automatic policy selection, but one test URL cannot represent access to every website. When a test fails, first confirm that the test URL is reachable from the current network before blaming the node.

proxies and use can appear together in one proxy group: the former lists fixed nodes or built-in actions, while the latter imports provider collections. Override tools may handle these fields differently, and adding a static node does not necessarily add it to a provider. If nodes disappear after an update, check whether the remote provider refreshed successfully, whether its save path is writable, and whether the group still references the correct provider name.

Rule syntax, match order, and rule sets

Rules are matched from top to bottom

rules is an ordered list. Once a request matches the first applicable rule, matching stops, so specific rules must come before broad ones and MATCH should handle the remainder at the end. If MATCH is placed at the top, later rules never take effect. If a broad domain suffix comes before a special rule for one of its subdomains, that subdomain will be captured by the earlier rule.

A rule usually consists of a type, a match value, and a policy target; some rules accept additional parameters. Commas separate fields. The policy name must exist in proxy-groups, or be a built-in action such as DIRECT or REJECT. Extra spaces in a rule line may become part of a value, so keep formatting consistent when editing manually.

rules:
  - DOMAIN,api.example.com,Proxy Selection
  - DOMAIN-SUFFIX,example.com,Proxy Selection
  - DOMAIN-KEYWORD,example,Proxy Selection
  - IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
  - IP-CIDR6,fc00::/7,DIRECT,no-resolve
  - PROCESS-NAME,example-app.exe,DIRECT
  - GEOIP,CN,DIRECT
  - RULE-SET,private-domain,DIRECT
  - RULE-SET,service-domain,Proxy Selection
  - MATCH,Proxy Selection

Domain, address, and process rules

DOMAIN matches only the complete domain and suits one host. DOMAIN-SUFFIX matches the specified domain and its subdomains, making it suitable for an entire site. DOMAIN-KEYWORD may match any domain containing the keyword, giving it the broadest scope and the highest risk of false positives. Use a complete domain whenever possible, and use a clear suffix rather than a very short fragment.

IP-CIDR and IP-CIDR6 match destination address ranges. LAN, container, and corporate networks should usually go direct, but the ranges must reflect the actual network. no-resolve prevents an extra domain lookup when trying to obtain an IP for matching. It does not block traffic that already has an IP and does not change a resolution the application has already performed.

PROCESS-NAME and process-path rules depend on platform capabilities, permissions, and the interception method. In system-proxy mode, not all traffic provides reliable process information, and mobile platforms may not support the same process rules. Cross-platform configurations should use domain and address rules as the foundation, with process rules as device-specific additions. If a rule matches on desktop but not on a phone, first check whether the rule type is portable across platforms.

GEOIP classifies addresses using an IP database, while GEOSITE and rule sets classify domain collections; availability depends on the core and its data files. Database rules conveniently cover broad targets, but their data changes on an update cycle and cannot replace explicit service rules. To force a specific domain through a policy, place its precise rule before the database rule.

Managing large rule sets with rule-providers

Large rule collections belong in rule-providers. Each provider needs a name, type, behavior, source, save path, and update interval. behavior determines the content format: domain collections, IP ranges, and classical rule lines are not interchangeable. A successful provider download does not mean it is routing traffic; you must also reference the same name with RULE-SET in rules.

rule-providers:
  private-domain:
    type: http
    behavior: domain
    format: yaml
    url: "https://rules.example/private-domain.yaml"
    path: ./rules/private-domain.yaml
    interval: 86400

  service-domain:
    type: file
    behavior: classical
    format: yaml
    path: ./rules/service-domain.yaml

rules:
  - RULE-SET,private-domain,DIRECT
  - RULE-SET,service-domain,Proxy Selection
  - MATCH,Proxy Selection

The domain behavior is for domain or domain-suffix collections, ipcidr is for address ranges, and classical accepts traditional rule expressions. The remote content must match the declared format. If the provider file already contains a complete payload structure, the core reads it in that format after saving. Treating an ordinary subscription file as a rule set causes a parsing error.

When a rule-set refresh fails, check the network request first, then the save-directory permissions and file format. An old cache may continue to work, so current access does not prove that the update succeeded. In service mode, relative paths are based on the working directory or client configuration directory, not necessarily the directory containing the YAML file. After moving to another device, path differences are a frequent cause of failed rule providers.

Verify rule matches instead of guessing from outcomes

Connection logs usually show the destination domain, matched rule, and final policy. Before testing, clear existing browser connections or make a new request; a reused connection may continue using the old policy. Reload the configuration after changing rules, then check whether a new connection matches the new rule. A page opening alone cannot tell you whether it used a direct or proxied connection.

Start custom rules with a few precise entries. Add one clear domain rule, confirm the match, and then expand to a suffix or rule set. If a new rule breaks many websites, immediately check for an overly short keyword, an overly broad address range, or an early MATCH. Effective routing depends not on rule count but on clear order, existing targets, and explainable scope.

Configuration validation, loading, and layered troubleshooting

Validate syntax before checking the network

Handle configuration problems in a fixed order: file encoding and YAML syntax, field structure and references, listening ports, DNS, node connections, proxy groups, rule matches, and application interception. Do not move to the next layer until the previous one passes. A syntax error prevents the entire configuration from loading; a node error affects one connection; a rule error may send traffic through the wrong policy. Identifying the scope prevents aimless changes to every setting.

Graphical clients usually provide a configuration check or reload button. On servers and in command-line environments, use the test options provided by the installed core, but follow the package documentation for the exact executable and arguments. The check command must point to the actual configuration directory; a wrong relative path may test another file with the same name. Even after “configuration valid,” inspect startup logs because port conflicts, directory permissions, and network connections are runtime issues.

# Example: enter the actual configuration directory, then call the current core's configuration-check option
cd /path/to/clash-config
mihomo -t -d .

# To check whether a local port is already in use, use the appropriate tool for the operating system
# Linux
ss -lntup

# Windows PowerShell
Get-NetTCPConnection -State Listen

Common locations for parsing errors

When an error includes a line number, inspect that line and the several lines above it. YAML parsers often report the error only when they can no longer continue; the real problem may be a missing quote on the previous line, a missing space after a colon, or broken list indentation. If a duplicate mapping key is reported, search for the same field at that level. If the type is wrong, check whether a list is missing a hyphen or an integer was accidentally written as an object.

Content copied from chat apps or rich text may contain full-width colons, curly quotes, non-breaking spaces, and invisible characters. The safest fix is to retype the problematic line in a plain-text editor. Chinese proxy-group names work normally, but punctuation should use standard half-width YAML separators. Comments must begin with a hash and be separated appropriately from the value.

If the configuration parses but reports a missing target, check the proxy name, provider name, proxy-group name, and rule-set name. Common causes include a group referencing a node renamed by a subscription update, a rule pointing to a group removed by an override, or a RULE-SET name that differs from the provider key. Search for the complete text inside the quotes and watch for trailing spaces or look-alike characters.

Branches for ports, the system proxy, and TUN

If the client appears to be running but an application cannot connect, first confirm that the listening port exists, then verify the system-proxy address. If mixed-port has been changed to a new value while the system proxy still points to the old one, the browser will fail immediately. If only applications that ignore the system proxy cannot be intercepted, the basic proxy path may be working; evaluate TUN instead of continuing to change the node protocol.

If enabling TUN cuts off all network access, check permissions, the virtual interface, routes, DNS interception, and conflicts with other network software. Disable TUN first and confirm that the system-proxy path works, then handle TUN separately. If access remains unavailable after closing the client, check whether the system proxy is still enabled and whether virtual-interface routes were restored. Do not enable multiple proxy clients during one test; they may compete for the system proxy, ports, and routes.

Verifying node availability and rule matches

When a node test fails, distinguish DNS resolution failure, TCP timeout, connection refusal, TLS handshake failure, and authentication failure. For resolution failures, check the node hostname and proxy-server-nameserver; for timeouts, check the network and remote address; a refusal usually means the destination port is not accepting connections; for handshake failures, check the system clock, SNI, and certificate; for authentication failures, check the password, user identifier, and protocol fields. Different errors require different fixes.

If the node test succeeds but the target website fails, inspect the matched rule and policy in the connection log. If it matched DIRECT, investigate rule order or mode. If it matched the expected node, continue with target-domain resolution, the node’s egress, and site-side restrictions. Temporarily switching to global mode can separate a rule problem from a connectivity problem, but restore rule mode afterward. Global mode working proves only that one proxy path is available, not that the original rules are correct.

Build the smallest working configuration

When a complex configuration is hard to diagnose, start with one port, one node, one manual proxy group, and two rules. Confirm that it loads and connects, then add DNS, automatic policies, rule providers, and TUN in sequence. Save a working copy after each layer. This is faster than guessing inside a subscription thousands of lines long and makes the fields actually supported by the client and core clear.

The node used for minimal-configuration testing must have complete, verified details, and the test domain should be stable. If the minimal configuration still fails, the issue is probably with the node, system network, permissions, or client installation rather than the rule set. Return to the User Guide to review initialization, or read Ten Questions About Subscriptions, Modes, and Connection Status. If you need to reinstall, choose the platform from the Download Center; Clash Plus is the first desktop and mobile option to check.

After troubleshooting, restore temporary debug logging, broad test rules, and certificate-verification changes to normal settings. Remove unused ports, duplicate groups, and inactive providers, and add short comments to custom sections. Long-term maintainability depends on each module having a clear responsibility, not on the number of fields. A configuration remains sustainable when you can explain why each rule exists, what each group references, and what each DNS resolver handles.

Continue from a working configuration

If the client is not installed yet, get the installer for your platform first. If installation is complete but the interface is unfamiliar, follow the quick-start flow to import a subscription, choose a policy, and verify the connection.

Go to Download Center View the User Guide