Clash Proxy Groups, Rule Providers, and Network Stack Configuration

Proxy Group Types and Maintainable Routing

A proxy group is not just a folder for nodes. It is a stable interface between rules and the actual egress. Rules only need to target durable group names such as “Proxy,” “Streaming,” or “Downloads,” while node changes, subscription replacements, and regional adjustments stay inside the groups. This reduces configuration coupling: replacing a subscription does not require rewriting rules, and changing the egress for a service does not require searching through every domain. Plan the traffic hierarchy first, then choose group types instead of putting every subscription node into one giant selector.

How to Choose Among the Four Common Group Types

select is a manual selection group, suitable for the main entry point, a specific region, or services that need a stable egress. It does not change the current choice on its own, so its behavior is easy to predict. url-test checks availability at the configured URL and interval, then selects a faster candidate, making it suitable for everyday web browsing. fallback uses the first available node in list order, prioritizing continuity and failover for primary and backup links. load-balance distributes connections across multiple nodes, which suits workloads with many parallel requests, but different connections to the same site may use different egresses. That can be problematic for login sessions and sites with strict risk controls.

Latency tests only show how quickly the test target responded under the current network conditions. They do not measure download speed or replace real-world availability checks. Choose a stable, very small HTTPS resource that responds quickly. A short interval generates constant probe traffic; a long one delays updates after a node fails. Home networks usually work better with an interval measured in minutes. Mobile networks also require consideration of background restrictions and network changes, so a test group alone cannot provide reliable recovery.

Build regional groups first, then service groups

A more reliable structure usually has three layers. The bottom layer contains nodes or proxy providers; the middle layer contains regional groups such as “Hong Kong Auto,” “Japan Backup,” and “US Manual”; the top layer contains service groups such as “Proxy,” “Streaming,” and “Developer Services.” Service groups reference regional groups, and rules reference service groups. Do not put dozens of raw nodes directly into every service group, or subscription renames, retired nodes, and duplicates will make the entire setup difficult to maintain.

proxy-groups:
  - name: Hong Kong Auto
    type: url-test
    use:
      - provider-main
    filter: "(?i)港|HK|Hong Kong"
    url: https://www.gstatic.com/generate_204
    interval: 600
    tolerance: 80

  - name: Japan Backup
    type: fallback
    use:
      - provider-main
    filter: "(?i)日|JP|Japan"
    url: https://www.gstatic.com/generate_204
    interval: 600

  - name: Proxy
    type: select
    proxies:
      - Hong Kong Auto
      - Japan Backup
      - DIRECT

  - name: Developer Services
    type: select
    proxies:
      - Proxy
      - Hong Kong Auto
      - Japan Backup
      - DIRECT

use refers to the names of proxy-providers, while proxies refers to specific nodes, built-in policies, or other proxy groups. They are not interchangeable. Keep filters tolerant of naming differences between providers by covering local names, English abbreviations, and full English names where appropriate. Do not make expressions too broad: “US” may match unrelated words, so test against separators and the provider’s actual naming format.

Avoid circular references between proxy groups. For example, if “Proxy” contains “Auto Select” while “Auto Select” also lists “Proxy” as a candidate, the core cannot resolve a final egress. If a group becomes empty, a policy cannot be selected, or the configuration fails to load after an edit, first check that names match exactly, then check the reference direction. Punctuation, surrounding spaces, and letter case can make names that look identical behave as different values.

Keep one clearly defined main entry group to simplify temporary troubleshooting. When a site behaves unexpectedly, manually switch the main entry to another region or DIRECT, then determine whether the issue is the node, the rules, or the destination. If switching the entry point restores access immediately, inspect the current node and regional group first. If direct access always occurs, check rule order and mode. If no policy can reach the site, move on to DNS, TUN, and the system network stack. A clear group design makes every later section easier to verify.

Subscription-Based Rule Management and Match Order

Writing thousands of domain or IP rules directly into the main configuration makes it hard to read and turns updates into full-file replacements. rule-providers separates rule content into collections that can be downloaded, cached, and updated independently, leaving only provider definitions and a few RULE-SET references in the main configuration. Updating a rule set does not require changing proxy groups, and the structure is easier to version. Advertising domains, LAN addresses, service-specific domains, and regional IP ranges are good candidates for providers; one-off rules for a couple of domains are clearer near the top of the main configuration.

Behavior Determines How a Rule Set Is Interpreted

domain is for domain collections. Entries may be full domains, domain suffixes, or keyword patterns, depending on the payload format. ipcidr is for IPv4 and IPv6 networks and requires a destination IP for matching. classical supports classic rules with type prefixes and parameters, such as DOMAIN-SUFFIX, IP-CIDR, and PROCESS-NAME. If the source file contains classic rules but behavior is set to domain, the download may succeed while the entries fail to work as expected. Inspect the file before creating a provider instead of judging by its filename alone.

format is commonly yaml, text, or a binary format supported by the core. YAML payloads usually contain a top-level payload key, while text formats often contain one entry per line. path is the local cache location; every provider needs a distinct path so a later download does not overwrite an earlier one. interval controls the update frequency. When the rules rarely change, there is no reason to fetch them every few minutes. If a remote request fails, an existing cache can usually continue serving the rules, so do not mistake a temporary update failure for complete rule invalidation.

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

  service-rules:
    type: http
    behavior: classical
    format: yaml
    path: ./ruleset/service-rules.yaml
    url: https://example.com/rules/service-rules.yaml
    interval: 86400

  private-ip:
    type: http
    behavior: ipcidr
    format: yaml
    path: ./ruleset/private-ip.yaml
    url: https://example.com/rules/private-ip.yaml
    interval: 86400

rules:
  - DOMAIN,router.local,DIRECT
  - RULE-SET,private-domain,DIRECT
  - RULE-SET,service-rules,Proxy
  - RULE-SET,private-ip,DIRECT,no-resolve
  - GEOIP,CN,DIRECT
  - MATCH,Proxy

The addresses in the example only illustrate the structure. In a real configuration, replace them with rule sources that you have verified are reachable and use the expected format. If a rule file requires authentication, do not place long-lived credentials in a main configuration that may be synced publicly. Prefer a local generation process, a controlled reverse proxy, or secure storage supported by the client, and ensure diagnostic exports do not include access parameters.

Rules Run Top to Bottom; the First Match Wins

Clash rule order matters more than rule count. Put exact domains and personal overrides first, service rule sets in the middle, broad regional rules later, and use MATCH for everything else. If GEOIP,CN,DIRECT comes first, a later service rule set cannot send an already matched connection through a proxy. Likewise, placing MATCH in the middle makes every later rule ineffective.

no-resolve is useful for IP rules when you do not want the matching stage to resolve domains proactively. It still matches when the destination is already an IP; when the destination is a domain, it avoids an extra lookup just to determine its network. This can reduce unnecessary DNS activity, but if an IP rule determines the egress, verify that the destination address is available before the request enters the rule system. Do not add this parameter mechanically to every IP rule.

When a rule set does not match, verify three things first: whether the provider updated successfully, whether the file format matches behavior, and whether the request includes a domain that can be matched. A browser using encrypted DNS, an application connecting directly to an IP, or a process not captured by TUN may present a different match target than expected. Check the connection list for the actual destination, matched rule, and policy instead of repeatedly changing rule order by trial and error.

For long-term maintenance, record each rule set’s source, purpose, behavior type, and associated proxy group. Introduce new rules as individual entries near the top of the main configuration and observe them for a few days before moving them into a custom provider. Before deleting a rule, check connection logs so that “not used recently” is not mistaken for “never needed.” For a deeper look at how the main configuration is organized, read Clash YAML Configuration Sections Explained.

DNS Optimization and Leak Troubleshooting

DNS configuration involves three separate questions: who resolves the domain, which network path carries the query, and how the result reaches the rule system. Changing one public DNS address rarely solves all three. System DNS, Clash’s built-in DNS, browser secure DNS, and application-specific resolvers may coexist, so first identify the actual request path before choosing servers. A controllable setup usually sends captured applications through Clash DNS, letting rules and proxy policies determine the connection path.

nameserver, proxy-server-nameserver, and direct-nameserver

nameserver is the primary upstream for ordinary domain queries. HTTPS or TLS can reduce interference with plaintext lookups on the local network, but encryption does not mean the query uses the proxy; the egress still depends on core capabilities, rules, and bootstrap resolution. proxy-server-nameserver is mainly used to resolve the proxy server’s own hostname, avoiding the loop where the proxy must be resolved before it can be reached, while resolution itself supposedly requires that proxy. direct-nameserver is for explicitly direct queries, such as LAN device names or local services, when the client and core support the field.

default-nameserver is commonly used to resolve the addresses of encrypted DNS servers themselves, usually with resolvers reachable by IP. It is not the final upstream for every query and should not be filled with a long list of addresses. If an encrypted DNS URL uses a hostname that the default resolver cannot reach, the client may start while every domain lookup hangs, even though direct IP access still works.

dns:
  enable: true
  listen: 0.0.0.0:1053
  ipv6: false
  enhanced-mode: fake-ip
  fake-ip-range: 198.18.0.1/16
  default-nameserver:
    - 223.5.5.5
    - 1.1.1.1
  nameserver:
    - https://dns.alidns.com/dns-query
    - https://1.1.1.1/dns-query
  proxy-server-nameserver:
    - https://dns.alidns.com/dns-query
  fake-ip-filter:
    - "*.lan"
    - "*.local"
    - "time.*.com"
    - "time.*.gov"
    - "+.stun.*.*"
    - "+.stun.*.*.*"

When listen binds to all interfaces, other devices on the LAN may reach the port. For local-only use, bind it to a loopback address whenever possible. If it must serve as a LAN DNS server, also check the system firewall, access controls, and router settings. A port conflict can prevent the core from starting or stop the DNS module from listening. On Windows, use system networking tools to find the owning process; on macOS and Linux, use lsof or ss.

# Windows PowerShell
Get-NetUDPEndpoint -LocalPort 1053

# macOS
lsof -nP -iUDP:1053

# Linux
ss -lunp | grep 1053

Choosing Between Fake-IP and redir-host

fake-ip returns a mapped address from a reserved range first, then restores the original domain when the connection reaches the core. This preserves domain information for the rule system, makes domain matching more consistent, and avoids cases where a resolved IP leaves no domain context. The trade-off is that some LAN discovery, time synchronization, gaming, printer, and real-resolution-dependent applications may not work correctly and need entries in fake-ip-filter. Add filters gradually based on domains that actually fail; copying a huge list causes many domains to bypass Fake-IP and weakens consistent routing.

redir-host returns the real resolved address and is often easier to understand from a compatibility perspective, but the relationship between domains and connections depends more heavily on the DNS mapping cache. With CDNs, rotating addresses, and application-specific resolvers, rule matching may be less stable than with Fake-IP. Do not choose based on a single test site: verify common applications, LAN services, sleep/wake behavior, and network changes.

Confirm DNS Leaks by Following the Request Path

A leak generally means that a query intended for a controlled upstream or proxy path is sent independently by the system, router, network operator, or browser. Online tests only see some queries triggered by the test page and cannot prove that every application uses the same path. A more reliable process is to disable the browser’s built-in secure DNS or align it with the system setup, then inspect Clash logs, system DNS settings, and local-port traffic. The site’s Clash DNS Leak Test and Prevention Guide combines online testing with local observation.

When IP addresses work but domains do not, start with the DNS module’s startup state, listening port, and upstream reachability. When some domains resolve slowly, check whether one upstream consistently times out and whether IPv6 queries are being dropped. When traffic should use a proxy but goes direct, verify whether the application bypasses system resolution, whether the connection list retains the domain, and whether the target rule comes before broad direct rules.

If stopping and starting TUN leaves the system with incorrect DNS settings, fully exit the client, restore the adapter to automatic DNS, and start again. Do not run multiple networking tools that modify the system proxy, virtual adapters, or DNS at the same time. Each may work correctly alone yet cause intermittent failures when the last one started overwrites the earlier configuration.

TUN Mode, Fake-IP, and the System Network Stack

The system proxy affects only applications that actively read proxy settings. Command-line tools, games, store components, some desktop clients, and programs that open sockets directly may ignore it completely. TUN mode captures a broader range of IP traffic through a virtual adapter and sends it to Clash for rule evaluation, making it useful for applications that are not proxy-aware. It is not simply a “stronger system proxy switch”; it involves routing, DNS, a virtual interface, and permissions. Make sure ordinary system proxy mode works before enabling it.

Core Fields and Stack Selection

enable controls TUN; auto-route lets the core install required routes; auto-detect-interface identifies the current default outbound interface and reduces manual changes after switching between wired, wireless, and hotspot connections; dns-hijack sends DNS requests on specified ports to the built-in DNS. stack selects the network stack implementation, with common values including system, gvisor, and stacks that support hybrid handling. Support varies by core and platform, so follow the options exposed by the current client.

system generally uses the operating system’s networking capabilities, offering natural performance and compatibility while inheriting platform-specific behavior. gvisor uses a user-space network stack and provides clearer isolation; in some environments it avoids system-stack limitations, but it may behave differently with unusual protocols or many concurrent connections. Treat stack changes as a troubleshooting tool rather than something to change repeatedly without evidence. Change one variable at a time and test under the same network conditions.

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

dns:
  enable: true
  enhanced-mode: fake-ip
  fake-ip-range: 198.18.0.1/16

strict-route can reduce the chance of traffic bypassing the intended routes, but it may also affect existing routes in virtual machines, containers, corporate VPNs, and complex LANs. If LAN devices, remote desktops, or development containers become unreachable after enabling it, compare the route tables before and after and verify that private networks still use the correct interface. To reach a LAN, rules can send private addresses direct, but rules cannot repair a connection already diverted by an incorrect system route.

Fake-IP Addresses Are Not Real Destinations

After enabling Fake-IP, seeing addresses such as 198.18.0.0/16 in packet captures or the system connection list is normal. The application first connects to the mapped address; the core restores the domain from its mapping table, then applies rules and performs real resolution. Do not add this range to ordinary direct routes or interpret it as the address of a remote server. If the connection is not captured by TUN, the system will try to reach the reserved address as a real destination, causing immediate failure or a long wait.

Fake-IP and TUN therefore depend on a closed loop: Clash returns a mapped address for the DNS query, the application connects to that address, and routing sends the connection back to Clash. If another tool takes over any link in this chain, the mapping can break. Common conflicts include a browser’s independent DNS, another virtual adapter taking the default route, corporate security software filtering the reserved range, and a stale virtual interface retaining higher route priority after wake-up.

Understand Permissions and Conflicts by Platform

If enabling TUN on Windows cuts off all connectivity, disable TUN first and confirm that basic proxy mode works. Then check whether the virtual adapter was created successfully and whether the correct default interface was detected. On macOS, confirm that the client has network-extension permission and disable other active VPNs. On Linux servers, verify that the kernel provides a TUN device and that the running user can create interfaces and modify routes. Android relies on VpnService and normally allows only one active VPN; see Android VpnService Authorization and Battery Optimization Guide for authorization and background restrictions.

The most effective way to troubleshoot TUN is to test in layers: disable TUN and verify the node with system proxy mode; enable TUN with simple rules; test domains, direct IPs, LAN addresses, and an application that ignores system proxy settings; only then add complex DNS, sniffing, and rule providers. Enabling every advanced option at once makes any failure look like “the network is down” and obscures the actual fault.

Domain Sniffing: Uses, Configuration, and Limits

Domain-based routing works best when it receives a domain, because domains usually describe service ownership more reliably than constantly changing CDN addresses. Some applications resolve a name themselves and connect directly to an IP, while transparent capture may expose only an address when the connection starts. Domain sniffing recovers the target hostname from TLS SNI, HTTP headers, or other identifiable data, giving domain rules another chance to match. It supplements connection metadata; it is not a universal replacement for DNS.

What TLS and HTTP Sniffing Actually See

TLS sniffing generally reads the server name exposed during the handshake without decrypting subsequent content. HTTP sniffing can read the Host field in a plaintext request. Sniffing may produce no result when the protocol carries no domain, the application uses a direct IP, the connection reuses an existing channel, or the protocol hides the server name. The identifiable scope of UDP also depends on the core and the traffic, so do not assume every UDP connection can yield a domain.

A sniffed domain should correspond to the connection’s real destination. On a shared IP hosting multiple sites, an incorrect override can send traffic through the wrong rule; some applications also connect to dedicated addresses that do not match the certificate or SNI. Start with common ports, observe connection records, and expand the scope only when needed. Do not scan every port just to improve the apparent domain display rate.

sniffer:
  enable: true
  parse-pure-ip: true
  force-dns-mapping: true
  override-destination: false
  sniff:
    TLS:
      ports:
        - 443
        - 8443
    HTTP:
      ports:
        - 80
        - 8080-8880
  skip-domain:
    - "Mijia Cloud"
    - "+.push.apple.com"

parse-pure-ip lets the core try to recover a domain for a pure IP destination, which is especially useful in transparent proxy scenarios. force-dns-mapping uses DNS mappings to help identify the target and is common with Fake-IP. override-destination controls whether the sniffed result replaces the original destination. Enabling it can make rules and connection targets better reflect the expected domain, but false positives have a more direct impact. Keep it disabled initially, confirm that the recovered names in the logs are stable, and enable it only if needed.

When to Add Skip Entries

A skip list is for destinations that should not be sniffed or overridden. LAN devices, smart-home equipment, push services, special authentication software, and some games may depend on fixed addresses or non-standard handshakes. If an application works with sniffing disabled but consistently fails when it is enabled, and the connection log shows an unrelated recovered domain, add the relevant domain or process-related target to the skip scope. First confirm that sniffing is actually responsible rather than TUN, MTU, UDP, or the node itself.

List entries must follow the domain-matching syntax supported by the current core. A full domain suits one service; a domain suffix covers a family of subdomains. The broader the suffix, the more cautiously it should be used. Skipping an entire top-level domain, for example, removes sniffing from many unrelated connections. Entries that look like application names depend on how the core interprets special markers, so recheck them when moving to another client.

How Sniffing Works with Rules and DNS

Once a connection enters the core, its domain may come from a Fake-IP mapping or be recovered through sniffing before the rules select a policy. When DNS mapping is reliable, sniffing is mainly a supplement. When an application completely bypasses Clash DNS, sniffing may be the key to making domain rules work. If the same application sometimes follows a domain rule and sometimes falls through to an IP or final rule, different connections are probably using different resolution or transport paths.

For verification, prepare three layers of rules: one exact domain rule, one corresponding IP or regional rule, and a final MATCH. Visit the destination and see which layer matches. If the exact domain rule never triggers but the connection record shows the correct domain, check rule order and spelling. If the record contains only an IP, inspect DNS mapping and sniffing. If no connection appears, check whether the application is captured by the system proxy or TUN. This comparison is more diagnostic than simply checking whether a page opens.

Graphical clients may expose these fields as separate switches for “Domain Sniffing,” “Override Destination,” and “Parse Pure IP,” or expose only some capabilities. Clash Plus, Clash Verge Rev, and FlClash place them differently, but the exported configuration and core logs remain authoritative. When moving between clients, start with the smallest sniffing setup, confirm that the current core recognizes the fields, then restore advanced options one at a time.

Local Overrides and Subscription Merging

Remote subscriptions distribute nodes; local overrides preserve personal policies over time. If DNS, rules, proxy groups, and experimental settings are written directly into a subscription file, the next update may overwrite everything. Completely disabling updates means missing node changes. A better structure treats the remote subscription as input and the local override as a repeatable transformation, with the client or a conversion process generating the final runtime configuration. This keeps nodes current while preserving custom rules and network-stack settings.

Know the Difference Between Replace, Append, and Prepend

Clients use different names for overrides, but the operations usually fall into three categories: replace a top-level field, append to the end of an array, or insert at the beginning. Complete objects such as DNS and TUN suit explicit replacement or deep merging. Rule arrays usually need personal exact rules at the front and fallback rules at the end. Proxy groups require name-based deduplication rather than blindly concatenating two arrays.

The most dangerous operation is replacing the entire rules or proxy-groups field without bringing the subscription’s original content back in. The result may contain nodes with no group references, or leave only a few personal rules. Before editing, export the active configuration, confirm whether the override runs before or after subscription updates, and check the client’s merge order. The same script may run at different stages in different clients and produce different results.

# Local prepended rules example
rules:
  - DOMAIN,router.local,DIRECT
  - DOMAIN-SUFFIX,example.internal,DIRECT
  - DOMAIN-SUFFIX,developer.example,Developer Services

# Local DNS override example
dns:
  enable: true
  enhanced-mode: fake-ip
  fake-ip-range: 198.18.0.1/16
  nameserver:
    - https://dns.alidns.com/dns-query
    - https://1.1.1.1/dns-query

YAML merging also involves anchors, null values, and type changes. A field that is an array in the source but an object in the override usually cannot be merged as intended. Writing null may delete the field or simply produce an empty value, depending on the tool. For portability, prefer ordinary mappings and arrays instead of a graphical client’s proprietary scripting API. When scripting is required, record the input structure, processing order, and expected output.

Isolate Names Before Merging Subscriptions

The most common problem when merging subscriptions is not the node protocol but duplicate names. Both sources may include groups called “Auto Select,” “Failover,” or “Proxy,” and node names may also overlap. Blind concatenation can cause later objects to overwrite earlier ones or make a group reference the wrong node. A safer approach is to add fixed prefixes to each source, such as “Primary / Hong Kong 01” and “Backup / Hong Kong 01,” then have local groups reference them consistently.

If the client supports proxy-providers, keep each source as a separate provider and use use and filter to assemble regional groups instead of expanding every node into the main file. This keeps update boundaries clear, and a failure in one source does not directly destroy another source’s cache. Provider names, cache paths, and health-check URLs should all be independent.

proxy-providers:
  provider-main:
    type: http
    url: https://example.com/subscriptions/main.yaml
    path: ./providers/main.yaml
    interval: 21600
    health-check:
      enable: true
      url: https://www.gstatic.com/generate_204
      interval: 600

  provider-backup:
    type: http
    url: https://example.com/subscriptions/backup.yaml
    path: ./providers/backup.yaml
    interval: 21600
    health-check:
      enable: true
      url: https://www.gstatic.com/generate_204
      interval: 600

proxy-groups:
  - name: All Sources
    type: select
    use:
      - provider-main
      - provider-backup
    proxies:
      - DIRECT

The example address only illustrates the relationship between fields. Real subscription URLs often contain access credentials and must not be pasted into screenshots, issue posts, public repositories, or diagnostic files. Before sharing a configuration, remove the proxy-providers URL, node server addresses, usernames, and authentication fields, leaving only the smallest fragment that reproduces the structural problem.

Build a Configuration Workflow You Can Roll Back

Before every major change, keep three artifacts: the unprocessed subscription input, the local override file, and the final generated runtime configuration. When something breaks, first compare the final configuration with the expected result, then determine whether the cause is a subscription change, merge logic, or core behavior. Saving only the final file makes it impossible to tell where the error began and difficult to reproduce the build after the next subscription update.

Follow a fixed sequence: update one subscription and confirm that its nodes work; apply name filters and provider health checks; add proxy groups; prepend personal rules; then enable DNS, TUN, and sniffing. Reload and inspect the logs after every stage. Even if the final configuration fails, this identifies the first stage where behavior changed.

If nodes are visible but cannot be selected after merging, a proxy group usually references a missing object. If personal rules disappear after an update, the override usually ran at the wrong stage. If same-named nodes change unpredictably, the sources were not name-isolated. Check the input, transformation, and output layers instead of repeatedly deleting and re-importing items in the client.

External Controller and Secure Remote Management

The external controller lets graphical panels read proxy groups, connections, rules, logs, and provider status, and can also switch policies, update providers, and close connections. It is useful for separating core operation from the management interface, especially on servers, routers, and standalone core deployments. Because it has real control authority, do not expose it to the public internet like an ordinary status page.

Listen Address, Secret, and Panel Directory

external-controller defines the API listen address. For local-only use, binding to a loopback address is safest. For LAN access, bind to a LAN interface or all interfaces only with firewall restrictions on the source. secret is the controller credential; use a separate, sufficiently long value and never reuse a subscription credential, system password, or another service’s secret. external-ui points to a local static panel directory. The core serves the files and API but does not automatically make the directory trustworthy.

external-controller: 127.0.0.1:9090
secret: "your-password"
external-ui: ./dashboard
external-ui-name: metacubexd
external-ui-url: https://example.com/dashboard.zip

The password and panel address in the example only show the syntax. Replace the password in real deployments and obtain panel files from a source you trust. If the graphical client already includes a control panel, a remote download URL is usually unnecessary. Multiple instances cannot listen on the same IP and port. When a port conflict occurs, the later core reports a bind failure while the panel may continue showing data from the old instance, creating the impression that the configuration was ignored.

When accessing a local panel from a browser, distinguish the page address from the API address. A web server may serve the panel files while the Clash core listens for the API. Different protocols, hosts, or ports create a cross-origin request, and whether it is allowed depends on the core and browser policies. If the panel opens but continually reports that it cannot connect, first verify locally that the API port is listening, then check the controller address and secret entered in the panel instead of reinstalling the core.

Expose the Smallest LAN Access Scope

If management from a phone or another computer is genuinely needed, bind the controller to a LAN address and configure the system firewall to allow only trusted private ranges. Do not forward the control port to the public internet through a router, and do not use a weak secret. Devices on public networks actively scan common management ports; once the controller is reachable, an attacker may inspect destinations, change policies, or interrupt traffic.

A safer remote approach is to enter the local network through an existing controlled private network, a secure device-to-device tunnel, or the operating system’s remote-management capability, then access the loopback or LAN interface. The controller never needs to face the internet directly. If you reverse-proxy the controller, enable authentication, restrict sources, and handle WebSocket traffic correctly. An extra proxy layer also adds complexity, so it is unnecessary for a single home machine.

# Linux: confirm the controller port listens only on loopback
ss -lntp | grep 9090

# macOS: inspect the listening process
lsof -nP -iTCP:9090 -sTCP:LISTEN

# Windows PowerShell: inspect port status
Get-NetTCPConnection -LocalPort 9090 -State Listen

Use the Control Panel to Locate Connection Problems

The panel’s greatest value is not one-click switching but the ability to inspect connections, rules, and policies together. When troubleshooting a site, filter connections by domain or process and record the matched rule, policy chain, and final node. Then close the connection and let the application create a new one so it does not continue using the policy from before the change. Switching a group without rebuilding the connection can make the interface look updated while requests still use the old egress.

The provider page can confirm whether a subscription or rule set updated successfully, but “success” alone does not prove that its content is correct. Check whether the provider entry count is abnormal, whether filtering leaves a group empty, and whether the rule-set behavior matches the payload. The log page is useful for resolution failures, controller bind errors, rule-file read errors, and node handshake errors. Keeping verbose logs enabled indefinitely increases disk writes and privacy exposure, so return to the normal level after troubleshooting.

Validate the Complete Configuration

After advanced configuration is complete, fixed test cases are more reliable than casual browsing. Verify a direct site, a proxied site, and a LAN device first. Then test a browser, a command-line tool, and an application that ignores system proxy settings. Next check DNS queries, Fake-IP mappings, and domain rules. Finally test sleep/wake, Wi-Fi changes, and subscription updates. Record the expected and actual policy for each case and return to the relevant section when something differs.

When the configuration fails to load, check YAML indentation, spaces after colons, array nesting, and duplicate keys first. If it loads but carries no traffic, check system proxy or TUN capture. If traffic exists but uses the wrong policy, check domain information, rule order, and proxy-group references. If the policy is correct but the connection fails, then inspect the node, protocol, and destination. This order prevents every problem from being blamed on the node.

If you still cannot identify the affected layer, see the installation, configuration, and troubleshooting categories in Troubleshooting. To switch graphical clients or reproduce the setup on another system, visit the client downloads page and choose Windows, macOS, Android, iOS, or Linux. A graphical interface is convenient for everyday switching and observation, but final conclusions should come from the active configuration, connection records, and core logs.