Clash Configuration Reference

YAML Structure and Configuration Basics

A config file defines listening endpoints, DNS resolution, available outbound connections, and routing order. A YAML parser accepting the file only confirms that its syntax is valid; it does not mean nodes can connect or that the current core supports every field. Troubleshoot syntax errors, field semantics, and runtime issues separately. This avoids blaming a network timeout on indentation or mistaking a proxy group name error for a broken subscription.

Top-Level Keys and Nesting

Common top-level keys include mixed-port, mode, dns, proxies, proxy-groups, and rules. Top-level keys start at the beginning of a line; nested fields use consistent indentation. Two spaces is the usual convention. Do not use tabs. List items start with a hyphen and a space; a node's name, protocol, address, and port must all belong to the same item.

mixed-port: 7890
allow-lan: false
mode: rule
log-level: info

proxies: []

proxy-groups:
  - name: Default outbound
    type: select
    proxies:
      - DIRECT

rules:
  - MATCH,Default outbound

This minimal config is for testing direct connections and does not include remote proxy services. Use it to check that listeners, group references, and rule loading work as expected; it cannot tell you whether a remote node is reachable. proxies: [] defines an empty proxy list. The group references the built-in outbound DIRECT, and the final rule points to the group defined above. To add a node, define it first, then add its name to the group.

Strings, Lists, and Booleans

Values such as ports and intervals usually do not need quotes. Use true or false for switches. Quoting passwords, names with special characters, rule strings, and URLs can prevent ambiguity caused by colons, hash characters, or parser differences. A hash mark starts a comment in the right context, so quote passwords that contain one. In single-quoted strings, escape a single quote by doubling it; backslashes in double-quoted strings may trigger escapes.

Both block and inline lists are valid YAML, but block lists are easier to review line by line in a long config. Nodes can also use brace notation, though expanded fields are easier to maintain. Avoid mixing styles just to save lines. Never insert full-width punctuation or nonbreaking spaces copied from a webpage between keys and separators.

File Location and Active Configuration

The original subscription shown in the client, the local file in an editor, and the config ultimately loaded by the core may be three different things. After a subscription update, the client may also inject listening ports, a control interface, and overrides. Before inspecting a file, check which config is active, when it was last updated, and whether a merge script is in use. Then use the client's runtime config view to verify the final result.

Do not define the same key more than once at the same level. Some parsers reject duplicate keys; others keep the last value, making the result unpredictable. To add rules, edit the existing list or use a merge mechanism explicitly supported by your client instead of adding another rules block at the end of the file. Copying and pasting configs does not automatically merge their meaning.

Save the file as UTF-8 and make sure its extension is actually .yaml or another format accepted by your client—not a text file with a hidden extra extension. If parsing fails, check the line identified in the log and the list immediately above it. The cause is often a missing quote, changed indentation, or an improperly closed list item on the preceding line.

Ports, Modes, and Traffic Capture

Listening ports determine where apps send connections; the operating mode determines how the core selects an outbound; and the system proxy and TUN determine how traffic reaches the core. These are related, but they are not interchangeable. Changing only mode will not route every app through the proxy. Enabling the system proxy does not guarantee that apps which ignore system proxy settings will use the core.

HTTP, SOCKS, and Mixed Ports

port listens for HTTP proxy connections, socks-port listens for SOCKS connections, and mixed-port accepts both HTTP and SOCKS on one port. A mixed port is usually sufficient for everyday desktop use; add separate listeners only when an app requires them. Multiple listeners cannot bind to the same address and port, or they will conflict.

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

If a port is already in use, first identify whether the process belongs to an old client, another proxy tool, or a system service. Do not terminate an unfamiliar process. After changing the port, update the system proxy, browser extensions, terminal environment variables, and any proxy addresses entered manually in apps. See how to troubleshoot a 7890 conflict and change mixed-port.

Rule Mode vs. Global Mode

rule matches requests against the rule list from top to bottom and is generally a good default for everyday use. global uses a global proxy selection and is useful for temporarily testing an outbound. direct sends traffic directly. Switching modes only changes how connections already reaching the core are handled; it does not change the operating system's routing. A mode toggle in the client may also override the config file, so check the active runtime state.

To share the proxy with devices on your local network, allow LAN connections and bind to an address that covers the relevant network interfaces—for example, bind-address: "*" if appropriate for your setup. This expands who can reach the proxy, so restrict access with firewall rules, configure proxy authentication if needed, and avoid exposing the port to the public internet. Entering the host's IP as a proxy on another device does not open the listener by itself.

System Proxy and TUN

The system proxy relies on apps honoring the operating system's proxy settings. Its scope is clear, making it a good first step when testing a connection. TUN captures traffic through a virtual network interface and may require administrator privileges, route changes, and DNS configuration. Enabling TUN while an app already has a proxy configured can result in overlapping capture. Note the current state first, then change one capture method at a time.

tun:
  enable: true
  stack: mixed
  auto-route: true
  auto-detect-interface: true
  dns-hijack:
    - any:53

This TUN snippet illustrates how the fields relate; do not enable it blindly on a remotely managed server. Automatic routing can disrupt remote sessions, container networking, and corporate VPNs. dns-hijack handles relevant DNS traffic within the capture scope; it does not mean all encrypted DNS will be intercepted. The outcome also depends on system routes, app behavior, and core support.

Top-level ipv6 and the field with the same name under DNS have different scopes. Disabling only one does not guarantee that all IPv6 traffic on the device stops. If you need IPv6, check the upstream network, node support, and capture routes together. For a comparison, see how TUN mode and the system proxy work.

DNS Resolution and Address Mapping

First make sure the DNS resolution chain can start on its own; then configure routing and enhanced modes. A timeout is not necessarily a node issue. The DNS server may be unreachable, encrypted DNS hostnames may lack bootstrap resolution, or resolving the proxy server's hostname may create a loop—all of which can prevent a connection from starting. Troubleshoot resolution for the destination domain, the proxy server, and the DNS service itself separately.

Common Fields and the Startup Chain

enable enables the built-in DNS server, while listen sets its listen address. These settings take effect only when an app sends requests to that listener or requests are redirected to the built-in DNS. default-nameserver can bootstrap resolution for encrypted DNS server hostnames. Use upstream servers in an IP format supported by the core to avoid depending on hostnames that cannot yet be resolved.

dns:
  enable: true
  listen: "127.0.0.1:1053"
  ipv6: false
  enhanced-mode: fake-ip
  fake-ip-range: 198.18.0.1/16
  default-nameserver:
    - 223.5.5.5
    - 119.29.29.29
  nameserver:
    - https://dns.alidns.com/dns-query
  proxy-server-nameserver:
    - 223.5.5.5
  fake-ip-filter:
    - "*.lan"
    - "*.local"
    - "localhost"

This example shows how local DNS listening, bootstrap resolution, and resolving proxy hostnames fit together. Test whether the listed upstream servers work on your network. 1053 is not the operating system's default DNS port; adding it to the config alone will not route all system requests there. If you switch to the standard port, also check permissions, port conflicts with existing services, and how the system's DNS server is configured.

fake-ip and Real Address Resolution

fake-ip assigns mapped addresses to domains so the core can retain the domain context and choose an outbound when a connection is made. This helps with domain-based routing, but some LAN discovery tools, address comparisons, or apps that require real IPs may need exceptions. The example range is for internal mapping—not a remote proxy server address or a gateway for other devices.

fake-ip-filter lets specific domains bypass this mapping process. Check its matching syntax in the docs for your core; do not confuse it with DOMAIN-SUFFIX in routing rules. If you run into compatibility issues, add a narrow exception for the exact domain and see whether the app works again. Excluding every domain defeats the purpose of the selected enhanced mode.

redir-host returns real resolved addresses, which can help apps that rely on real IPs. However, the domain-to-IP mapping may be affected by caches, the app's own resolver, and the request path. Neither mode is inherently faster. Choose based on your traffic capture method and app compatibility. After switching, reconnect and clear stale DNS caches in the operating system and apps as needed.

Choose Upstream DNS by Domain

nameserver-policy selects DNS servers for specific domains. Corporate domains often need corporate DNS and should not be sent to a public resolver; LAN device names may also resolve only through the router. The reserved domains below illustrate the syntax. Replace the private IP with a DNS server that exists and is reachable on your network.

dns:
  nameserver-policy:
    "+.corp.example":
      - 192.168.50.1

Merge this snippet into the existing dns mapping; do not add a second top-level DNS declaration. When respect-rules makes DNS connections follow routing rules, take care to prevent dependency loops and define how proxy server hostnames are resolved. Do not force all DNS requests through a proxy group until you have confirmed the bootstrap resolution and outbound dependencies.

If regular apps work but a browser with secure DNS enabled behaves differently, check whether the browser is using its own encrypted DNS service. That can bypass the system DNS settings you expected it to use. Verify the resolution path in one test app first, then decide whether to change the app settings or capture policy. Avoid changing several variables at once.

Proxy Nodes and Protocol Fields

proxies defines available remote outbounds; it does not determine when they are selected. At a minimum, each node needs a unique name, the correct protocol type, a server address, and the authentication and transport settings required by that protocol. A correct server address and password are not enough: mismatched transport, TLS, server name, or path can still cause the handshake to fail.

Core Fields and Name References

name is an internal identifier referenced by the config and the display name shown in groups and the interface. Keep it unique and stable. Set server to an IP or hostname, not a webpage URL with a path. port is the server's listening port, not the local mixed port. type determines how the other fields are interpreted; changing it alone cannot convert one protocol into another.

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

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

The example hostnames and passwords only illustrate the field structure and cannot be used to connect. The Shadowsocks cipher and password must match the server; the Trojan password, server name, and certificate settings must match too. Do not guess protocol options from the client name. Use the service provider's original connection details or a compatible subscription.

TLS and Transport Settings

The TLS server name may differ from the connection address, but it must match the server deployment and certificate requirements. Different protocols may use sni or servername; do not replace one with the other indiscriminately. For certificate errors, first check the device clock, hostname spelling, certificate coverage, and server configuration. Disabling certificate verification weakens authentication and should not be a routine fix.

WebSocket nodes may also require a specific path and Host header, while gRPC nodes may require a service name. These are part of the handshake, not optional optimizations. When node details specify a transport, check its corresponding nested options too. Copying a path from another node can still result in a rejection, even if the address and password are the same.

Protocol Compatibility and Layered Troubleshooting

mihomo and older Clash cores do not support exactly the same protocols and extension fields. A subscription importing successfully in one client does not mean another core can read every node. First check what the core supports, then confirm the client preserves and passes the fields correctly. To install a client, visit the client downloads page. Clash Plus is a good place to start for most users.

Troubleshoot in layers: domain resolution, TCP or UDP reachability, protocol handshake, authentication, then the destination request. For resolution failures, check DNS; for connection refusals, check the port and service status; for TLS errors, check the hostname and certificate; for authentication failures, verify the password or ID. Avoid deleting and recreating the entire node each time, as this can erase useful log clues.

udp: true allows the node to try handling UDP; it does not make UDP work automatically with every traffic capture method. Requests sent by an app through an HTTP proxy take a different path from UDP traffic captured by TUN. The server, protocol implementation, or network firewall may also restrict traffic. When testing, first identify which protocol the app actually uses rather than assuming UDP works because a webpage loads.

Proxy Group Types and Routing Logic

proxy-groups organizes nodes into selectable outbound sets. Rules usually target a stable group name, which decides the specific node. This way, you do not need to rewrite each rule when a subscription changes. When reviewing proxy groups, distinguish manual selection, health checks, and actual traffic: a successful test only confirms that one test condition was met, not that every destination is reachable.

Manual and Automatic Selection

select lets you choose manually and is useful for a top-level outbound or a specific purpose. url-test selects a candidate based on periodic probes, while tolerance helps prevent unnecessary switching over minor differences. fallback tries available candidates in list order rather than prioritizing the shortest probe time. If you need a fixed preferred route, account for this difference in priority.

proxy-groups:
  - name: Auto select
    type: url-test
    proxies:
      - SS example
      - Trojan example
    url: https://www.gstatic.com/generate_204
    interval: 300
    tolerance: 50
    lazy: true

  - name: Failover
    type: fallback
    proxies:
      - SS example
      - Trojan example
    url: https://www.gstatic.com/generate_204
    interval: 300

  - name: Default outbound
    type: select
    proxies:
      - Auto select
      - Failover
      - DIRECT

The example refers to node names defined in the previous section. If a node has not been imported, add it first or use an existing name. The test URL is a runtime probe target, not a page dependency; make sure it is suitable for your network and each outbound. Different targets respond differently, so results from before and after changing the test URL are not directly comparable.

Probe Interval and What Availability Means

interval is usually measured in seconds, while tolerance in the relevant automatic test groups is usually measured in milliseconds. Shorter intervals increase probe requests and network activity without necessarily making real traffic more reliable. On mobile devices, consider background activity and battery use. Start with a reasonable interval and adjust it only to address a specific recovery need; do not set every value as low as possible.

lazy can reduce active checks for unused groups when supported, so a lack of fresh probe results when you first open the interface does not necessarily mean a node is down. Group probes, provider health checks, and user-triggered node speed tests may use different mechanisms. Check which target was tested, when the test ran, and which URL it used; do not mistake one result for overall status.

Load Balancing and Nested References

load-balance distributes multiple connections, using the configured strategy to maintain some destination consistency or rotate between candidate outbounds. It does not split one download connection across multiple routes to combine their speeds. For logins, payments, or long-lived sessions that depend on the source address, frequent outbound changes may trigger extra verification. Use a more stable group or a dedicated rule for this traffic.

Proxy groups can reference other groups, but keep the structure simple and avoid circular references. For example, a default outbound can reference an automatic selection group, but that group should not reference the default outbound in return. Avoid reusing node names as group names, which makes configs and logs harder to interpret. When renaming a group, update references in rules, nested groups, and override scripts too.

If the interface still shows an earlier manual selection, check whether the client saves group selections and whether profile.store-selected is used to restore them. The first candidate in the file is not necessarily the one currently selected. For a full comparison of group types and syntax, see how to configure url-test, fallback, and load-balance.

Rule Order and Matching Syntax

rules are generally matched from top to bottom, and the first match determines the outbound. If a request takes the wrong route despite a valid config, check for broad rules above it before checking whether the target rule exists. MATCH is usually the final catch-all. It handles requests that did not match earlier rules, so ordinary rules placed after it will never run.

Domain and Address Rules

DOMAIN matches an exact domain, DOMAIN-SUFFIX matches that domain and its subdomains, and DOMAIN-KEYWORD matches a keyword in the domain. Keyword rules can match broadly, so they are not a good substitute for a known list of domains. A rule can target a built-in outbound, node name, or proxy group. In practice, group names are easier to maintain because you can change routes without changing the routing logic.

rules:
  - DOMAIN,router.lan,DIRECT
  - DOMAIN-SUFFIX,example.com,Default outbound
  - IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
  - IP-CIDR,10.0.0.0/8,DIRECT,no-resolve
  - IP-CIDR,172.16.0.0/12,DIRECT,no-resolve
  - IP-CIDR6,fc00::/7,DIRECT,no-resolve
  - MATCH,Default outbound

The example routes several common private address ranges directly and sends other requests to the default outbound. This is not a complete LAN ruleset for every device: corporate networks, virtual subnets, and special routes may need additional handling. example.com is a sample domain. Add rules for actual destinations and their dependencies as needed; avoid copying broad keyword matches without checking them.

no-resolve and Domain Context

no-resolve means an address-based rule will not trigger DNS resolution just to complete a match. If the connection already has a usable destination IP, it may still match the address rule. This option does not disable DNS. For domain requests, including or omitting it affects matching and DNS overhead, so do not append it to every rule by default.

GEOIP uses an address database to identify the region associated with a destination IP, while GEOSITE relies on domain category data and core support. Database categories do not necessarily reflect where a service actually operates, and a site's dependencies may not all belong to the same category. If your config uses these data sources, check that the files exist, are compatible, and have updated successfully. A field being accepted does not prove the data loaded.

Process Rules and Traffic Capture Scope

Process name and path rules require the platform and traffic capture method to provide process information. A router generally cannot identify which app on another LAN device made a request, and some mobile operating systems impose permission limits. Before using these rules, check whether connection details show a process field. Then decide whether to match a process name or full path; do not rely on the app window title.

Rules only handle requests that reach the core. If an app does not appear at all in the connection list, check the system proxy, the app's proxy settings, or TUN routing before adding more domain rules. If the request is listed, check its destination domain, destination IP, matched rule, and final outbound. Following these four details is usually more useful than repeatedly switching nodes.

Test Rules with a Narrow Scope

When validating a rule, start with one domain and a specific outbound. Once it matches, expand it to a suffix or rule set. A webpage may request static assets, APIs, and authentication domains; proxying only the main domain can leave some resources on another outbound. Use connection logs to identify required dependencies rather than adding every unknown domain to a broad match.

After changing rules, reload the config and make a new test connection. Reused HTTP connections, downloads, and real-time sessions may continue using the old outbound, so they are not reliable as the only test of a new rule. For common connection issues, see FAQ troubleshooting. For the steps to configure traffic capture, refer to the setup guide.

Providers and Update Behavior

Providers separate frequently updated nodes or rules from the main config, keeping its structure stable. proxy-providers manages proxy resources, while rule-providers manages rule resources; they use different content formats and are referenced in different places. A successful download only confirms that a file was retrieved. Check that its content is valid, that a group or rule references it, and that it is active in the current config.

Proxy Providers and Subscription Formats

YAML resources used by proxy providers typically have proxies as their main structure. A complete Clash config, a standalone proxy resource, and a Base64-encoded list of proxy links are not interchangeable. Some clients can import and convert these formats, but that does not mean the core's HTTP provider can parse the same raw content. See subscription URLs, local YAML, and Base64 formats explained to identify the resource type before importing it.

proxy-providers:
  Remote proxies:
    type: http
    url: "https://subscription.example.com/nodes.yaml"
    path: ./providers/nodes.yaml
    interval: 3600
    health-check:
      enable: true
      url: https://www.gstatic.com/generate_204
      interval: 300

proxy-groups:
  - name: Subscription selection
    type: select
    use:
      - Remote proxies

Replace the example URL with a compatible resource provided by your service. path is the local cache location. Relative paths are usually resolved from the core's working directory or the data directory specified by the client—not the webpage's directory. A non-writable directory or multiple providers using the same path can cause update and cache problems. Use a distinct filename for each resource to prevent accidental overwrites and make troubleshooting easier.

The outer interval controls how often the resource updates; health-check.interval controls how often nodes are tested. Both are usually measured in seconds, but they serve different purposes. A subscription not updating does not mean health checks have stopped, and a successful health check does not mean the subscription has refreshed. Check the update timestamp and probe results separately; one cannot confirm the other.

Rule Providers and behavior

A rule provider requires its content format, format, and behavior to match. domain is for domain lists, ipcidr for address ranges, and classical for entries that include rule types. Do not change the behavior name to force an arbitrary file to load. If the resource content differs, convert it correctly or choose the appropriate format.

rule-providers:
  Local direct rules:
    type: file
    behavior: classical
    format: yaml
    path: ./rules/local-direct.yaml

rules:
  - RULE-SET,Local direct,DIRECT
  - MATCH,Default outbound

The corresponding local-direct.yaml contains only match conditions; it does not repeat the outbound for every item. The main config's RULE-SET line specifies the outbound. The file below shows the basic structure of classical YAML and must be saved at the declared path. Keep the order within the rule set and its position in the main config clear.

payload:
  - DOMAIN,router.lan
  - IP-CIDR,192.168.0.0/16,no-resolve

Update Dependencies and Offline Cache

Remote resource updates also need a working DNS and network path. On first launch, a resource download that depends on a node not yet available can create a startup dependency loop. Keep an accessible update route or a valid cache, and configure the download outbound according to client and core support. Do not remove the only working local node or cache file before confirming that remote resources are reachable.

If an update fails, check the HTTP status, response content type, parsing errors, and local write permissions separately. A server may return a login page or error page that downloads successfully but is not a valid proxy or rule resource. Subscription URLs can contain access credentials. Use them only in trusted clients or controlled environments, not in online conversion services of unknown origin.

Overrides, Merging, and Verifying Changes

Subscriptions provide remote content; overrides preserve local settings. Keep them separate where possible. Editing a generated subscription file directly often means losing your changes at the next update. Copying it into a fully independent local config, however, means you must maintain it as nodes change. A reliable workflow is to decide which fields are managed by the subscription and which are controlled locally, then check that the final runtime config matches your expectations.

Field Ownership and Merge Order

A client may load a subscription, merge interface settings, then apply rule patches or scripts; the exact order varies. Do not assume every client supports the same override file or paste another client's script syntax into YAML. Use the actual interface to find override settings in clients such as Clash Plus and Clash Verge Rev. The core itself does not interpret every client-specific merge extension.

Scalars, mappings, and lists need different handling. A scalar such as a port is usually replaced by the later value. A DNS mapping may merge by key or be replaced as a whole. Rules and proxy group lists may be replaced, appended, or prepended. Unless the merge tool explicitly guarantees otherwise, do not assume arrays are deduplicated automatically or same-named nodes are safely merged by name.

Prepending Rules and Using Stable References

Custom rules usually need to go before the subscription's catch-all, not simply at the end of the file. If your client provides a prepend-rules setting, the two lines below express an intent to route LAN traffic directly. They are rule list items, not a universal override file format. Use the outer structure supported by your client's merge mechanism.

- DOMAIN,router.lan,DIRECT
- IP-CIDR,192.168.0.0/16,DIRECT,no-resolve

Whenever possible, have local rules reference stable group names. If a subscription update removes or renames a group, the rule may no longer load. Hard-coding a rule to a node name that can change is even harder to maintain. If you need a local entry point, create your own group in a supported override layer and reference the subscription provider—but make sure the provider name is stable too.

Save, Validate, and Reload

Before applying changes, save a copy of the current working config and override settings. Change one area at a time—for example, update the port and verify it before changing DNS. If you have access to the core's command line, use test mode to validate the config; desktop clients may also include a built-in checker. Set the working directory in the command below to match the base path used by relative resource paths.

mihomo -t -d ./profile -f ./profile/config.yaml

A passing test only means the current test environment accepts the config. It does not prove that remote services can connect or that the client will not override fields at runtime. If the config uses external resources, confirm their paths and availability. Then reload the config in the client, review startup logs for errors with listeners, DNS initialization, or provider loading, and make a new connection.

Rollback and Issue Reports

If reloading a config fails, the client may keep running with the old one. Internet access in the interface does not prove the new file is active; check the error notification and active config. If you cannot identify the cause, restore the most recent working copy and reapply changes one at a time. For TUN, the system proxy, or DNS, also check whether system-level settings were restored during rollback. The file may be reverted while traffic capture remains in its new state.

A useful issue report includes the client and core names, traffic capture method, relevant config fields, the first related error in the logs, and what changed before and after the issue appeared. Do not just say that you cannot connect, and never post a full subscription containing sensitive data. For common issues, start with the FAQ. To repeat the installation and import steps, return to the quick start guide; there is no need to reinstall the entire environment just to troubleshoot.