FLCLASH / CONFIGURATION REFERENCE
Clash Advanced Configuration Guide
Proxy Groups · Rule Providers · DNS · TUN · Local Overrides
Use this guide to understand configuration dependencies, plan for long-term maintenance, and troubleshoot network issues after making changes. For installation, importing subscriptions, and choosing a mode, start with the quick-start guide. Once your connection is working, adjust settings chapter by chapter. For client recommendations, start with Clash Plus. In FlClash, you can use the mihomo configuration principles here, but follow the app’s actual interface for imports, overrides, and permission requests.
The Clash Meta core is also known as mihomo. The examples below target that core; other forks may not support the same fields. Each YAML snippet is a partial example, not a complete configuration to combine with the others. Before applying changes, back up your working subscription and configuration, and confirm which section each field belongs in. Example domains are illustrative; replace remote rule URLs with resources you actually maintain.
Proxy Group Types and Traffic Routing
Separate Rule Targets from Proxy Selection
Proxy groups sit between rules and outbound connections. Rules decide which group handles a connection; the group then selects an outbound. Binding business rules directly to a proxy name means that renaming a proxy, replacing a subscription, or changing providers can all break your rules. Use stable group names and maintain the members inside each group, so rules can keep pointing to the same target with less ongoing maintenance.
proxies defines individual outbounds, proxy-groups defines selectable or automatically scheduled groups, and rules references them in order. Names must match exactly across all three sections, including spaces and capitalization. Groups can reference other groups, but circular dependencies are not allowed. For example, if a service group points to an automatic group that points back to the service group, the configuration cannot establish a valid selection path.
Choose a Group Type Based on How It Selects
Use select for manual selection when you need a clearly specified outbound. url-test selects an outbound based on probe results, making it suitable for similar routes. fallback checks members in order and prefers the first available outbound. load-balance distributes connections according to a policy; it does not combine multiple proxies’ bandwidth into one download, nor does it guarantee that every connection from an account will use the same IP address.
| Type | Selection method | Key limitation |
|---|---|---|
select | User selection | Check the current selection after changing members |
url-test | Probe results | Probe targets don’t reflect every real-world use case |
fallback | Order and availability | A successful connection doesn’t guarantee the app will work |
load-balance | Connection distribution algorithm | Consider whether the outbound IP may change |
Build a Two-Layer Structure with Service and Automatic Groups
The example below uses the core’s built-in direct outbound to show how groups reference each other, but it does not route traffic through a proxy. For real use, replace the direct member in the automatic group with an existing proxy name, or use use to reference a defined proxy provider. Keep a manual option so you can quickly switch to a fixed outbound if automatic selection doesn’t suit your needs.
proxy-groups:
- name: Auto Egress
type: url-test
proxies:
- DIRECT
url: https://www.gstatic.com/generate_204
interval: 300
tolerance: 50
lazy: true
- name: Everyday
type: select
proxies:
- Auto Egress
- DIRECT
rules:
- DOMAIN-SUFFIX,example.com,Everyday
- MATCH,Everyday
The interval is in seconds and sets how often to run checks; tolerance is in milliseconds and helps prevent frequent switches over small differences. lazy controls checks when a group is unused. Choose a probe URL that is reliably accessible and relevant to the route’s intended use. A lightweight webpage probe can’t tell you how a route will perform for large downloads, video streaming, or region-specific services.
For services that require a logged-in session, use a dedicated manual group and keep its outbound as stable as possible. Putting shopping, payment, or account-management traffic on a rotating set of outbounds may trigger risk checks. Before switching, stop related tasks, select the target proxy, and establish a new connection. Existing connections generally won’t migrate when you change the group selection.
Trace the Group Chain from the Actual Match
When troubleshooting, check the rule target in the connection details, expand the proxy group to see its current selection, then confirm the specific proxy. Seeing a proxy selected in the interface doesn’t mean a site is using that group: an earlier rule may have sent the connection direct, or the app may not have routed through the core at all. Verify the path before comparing proxies to avoid mistaking a rules issue for a proxy issue.
If a group is empty, check that its member names exist, proxy providers loaded successfully, and filter expressions haven’t excluded every proxy. Don’t mask reference errors by repeatedly switching global modes. For mode definitions, see the traffic mode guide. To understand how the YAML sections fit together, read the section-by-section configuration walkthrough.
Manage Rule Sets with Providers
Set Rule Order Before Splitting Rule Sources
Rules are checked from top to bottom, and the outbound is usually determined by the first matching entry. Put specific domain rules before broad region-based rules, and keep the final catch-all at the end. Moving rules into external files changes how they’re maintained, not the order in which they’re evaluated. A well-maintained rule set placed in the wrong position may never match.
Use rule-providers to define rule resources and RULE-SET to add them to the matching chain. A provider name is just a reference; it doesn’t automatically determine whether traffic uses a proxy or goes direct. Set the policy target after RULE-SET. The same rule set can use different policy groups in different configurations, keeping classification data separate from your own outbound preferences.
Understand the Difference Between behavior and format
behavior specifies how to interpret the content. Use domain for a domain list, ipcidr for IP ranges, and classical for full rule types such as DOMAIN-SUFFIX or IP-CIDR. format specifies the file format, commonly YAML, plain text, or MRS. A file extension is just a naming convention; check the actual content format instead of relying on it.
The example below uses an inline provider to show the full integration path. It requires no remote download and is useful for checking names, behavior types, and rule order. In classical content, each rule omits the policy target because the RULE-SET that references it already specifies one. Repeating the policy name inside each rule can cause format compatibility issues.
rule-providers:
Local exceptions:
type: inline
behavior: classical
payload:
- DOMAIN-SUFFIX,example.com
- IP-CIDR,192.168.50.0/24,no-resolve
rules:
- RULE-SET,Local Exceptions,DIRECT
- MATCH,DIRECT
Once you’ve confirmed the local structure loads, switch the parts that need centralized updates to remote providers. The URL below is for demonstration only. Replace it with a real, reachable rule file in the corresponding format; it isn’t a ready-to-use rule service. The core resolves relative path values from its working directory, which may not be the subscription directory shown by the client.
rule-providers:
Service domains:
type: http
behavior: domain
format: yaml
url: https://example.com/rules/business.yaml
path: ./rules/business.yaml
interval: 86400
rules:
- RULE-SET,Service Domains,DIRECT
- MATCH,DIRECT
Plan Updates and Offline Recovery
Plan for both first launch and later refreshes when setting up remote updates. On first launch, there is no local cache. If the resource URL also depends on a proxy route that hasn’t been established yet, startup may get stuck waiting on itself. Prefer a rule source reachable on the current network. If you need to specify a download proxy, first check which provider fields the current core supports and make sure that proxy doesn’t depend on the same rule set.
Avoid overly frequent update intervals. Rule classifications rarely change by the second, and frequent downloads increase network requests and can spread a bad update faster. Keep a recoverable copy of the previous configuration and check the logs to confirm providers loaded. Whether an existing cache remains usable depends on its state, the client’s directories, and the type of failure; don’t treat it as a permanent fallback.
Give each rule provider its own path; don’t let multiple providers write to the same file. When moving to another computer or reinstalling the client, back up local rule files as well as the main YAML. Mobile app sandboxes differ from desktop file systems, so absolute paths are rarely portable. Prefer clear relative directories for long-term configurations, and note which files are managed by the client.
Handle False Matches and DNS Side Effects
When a site is routed incorrectly, check the name of the rule that actually matched, then determine whether the issue is bad classification data or rule order. Put personal exceptions before public rule sets and include only the necessary domains or IP ranges. Don’t route an entire category direct to fix one domain; that would change the path for every other service in the same rule set.
no-resolve prevents certain IP-based rules from triggering extra domain lookups just to make a decision; it doesn’t disable DNS for the entire connection. If the app provides a destination IP, IP rules can still check it. When mixing domain and IP rules, be clear about which step may trigger a lookup, or you may mistake a rule-generated query for a duplicate DNS request.
Optimize DNS Configuration and Resolution Paths
Trace the Query Path to Find Where Resolution Happens
Before optimizing DNS, understand the query path: which resolver the app sends the domain to, whether the system intercepts it, whether the core receives it, and which upstream returns the result. Changing DNS addresses in the main YAML doesn’t guarantee that browsers, system services, and standalone apps will all use the same path. Browser-encrypted DNS, in-app resolution, and caches can all make test results differ from expectations.
A system proxy generally handles traffic from apps that honor proxy settings; it doesn’t automatically handle all system DNS. TUN can capture more traffic, but routing, hijack rules, and app behavior still matter. Test with one app, clear relevant caches, and check domain details in the core logs. Don’t change upstreams, enhanced mode, and routing settings all at once, or it will be hard to tell which change helped.
Distinguish Bootstrap, General, and Proxy-Server DNS
default-nameserver primarily handles bootstrap lookups for the DNS upstream’s own hostname. nameserver lists upstreams for regular queries. proxy-server-nameserver resolves proxy server hostnames, helping avoid a loop where resolving a proxy requires the proxy itself. These fields aren’t simply primary and backup servers; don’t assume they’re tried one after another only when the previous one fails.
Use nameserver-policy to send specified domains to a particular upstream, such as for local network services or internal corporate domains. Check the current core documentation for supported match syntax; for ordinary suffix matching, you can use a pattern like +.example.com. Send internal domains to an internal DNS server that can resolve them, rather than asking a public resolver for private service addresses.
dns:
enable: true
ipv6: false
enhanced-mode: fake-ip
fake-ip-range: 198.18.0.1/16
default-nameserver:
- 223.5.5.5
nameserver:
- https://dns.alidns.com/dns-query
proxy-server-nameserver:
- 223.5.5.5
nameserver-policy:
"+.example.com":
- 192.168.50.1
fake-ip-filter:
- "*.lan"
- "*.local"
Replace the private DNS address in the example with a resolver provided by your router or organization. If you don’t need internal domain resolution, remove the policy instead of keeping an unreachable address. Encrypted DNS changes how queries are transported; it doesn’t automatically route them through a proxy. Determine the connection’s egress by checking the core’s DNS options, routing, and rules.
Use Rule-Aware DNS and Fallbacks with Care
respect-rules makes DNS upstream connections follow routing rules, but it also adds dependencies. Before enabling it, set up a working DNS path for proxy hostnames and make sure no rule sends the resolver’s connection back through an outbound that hasn’t been established. If the network is already stable, don’t enable this field just because it makes the configuration look more complete.
Before using fallback and fallback-filter, understand how the core decides which results to accept. A fallback upstream isn’t necessarily used only after the regular upstream times out; filtering conditions may determine which set of results is returned. Copying extensive regional and IP filtering into a configuration without knowing the actual network conditions can lead to extra queries and inconsistent address selection.
Assess IPv6 by considering DNS responses, system routing, proxy capabilities, and connectivity to the destination together. dns.ipv6: false primarily affects DNS responses from the core; it doesn’t fully disable IPv6 at the system level or stop apps from using cached addresses. If only some sites stall, check connection details to see whether an unreachable IPv6 route was tried first.
Narrow Down Troubleshooting by Symptom
If no domains resolve, first check whether the upstream is reachable and whether its own hostname can be resolved through bootstrap DNS. If only proxy connections fail, focus on proxy hostname resolution. If only local network services are affected, check whether their queries are being sent to a public upstream by mistake. If several unrelated sites stall, compare system and core DNS to determine whether DNS is actually the cause.
A successful lookup doesn’t mean the destination is reachable. If the logs show an IP address but the connection later times out, check the routing rule, firewall, and proxy route instead of endlessly changing DNS servers. Browser, system, and core caches are separate; clear the relevant ones and close existing connections when testing. For help distinguishing stale caches from throughput bottlenecks, see the layered guide to slow speeds.
TUN Virtual Network Interface and Fake-IP
Separate the Traffic Entry Point from the DNS Mode
TUN creates a virtual network interface and sends traffic that matches its routing conditions into the core. Fake-IP is a DNS enhancement mode: the core returns a virtual address for a domain, then uses its mapping to recover the domain and process the connection. They’re often used together, but they’re separate settings. Enabling TUN doesn’t mean DNS is being intercepted, and enabling Fake-IP doesn’t mean every app uses the virtual interface.
A system proxy works well for browsers and apps that honor proxy settings. TUN is better suited to traffic that falls outside the system proxy. Before switching, confirm the existing system proxy works, then test TUN on its own. If you also use another VPN, virtual network software, or endpoint security product, check the default route and interface priority; don’t assume multiple traffic interception tools will coordinate automatically.
Start with Minimal Routing Settings
tun:
enable: true
stack: mixed
auto-route: true
auto-detect-interface: true
dns-hijack:
- any:53
dns:
enable: true
enhanced-mode: fake-ip
fake-ip-range: 198.18.0.1/16
fake-ip-filter:
- "*.lan"
- "*.local"
auto-route configures relevant routes automatically, while auto-detect-interface detects the outbound interface. stack selects the traffic processing stack; it isn’t a performance setting. Compatibility varies across operating systems, protocols, and apps. Start with the defaults supported by your client. Compare other available stacks only after reproducing an issue and recording the results.
The standard port hijacking configured by dns-hijack primarily targets ordinary DNS traffic; it doesn’t mean encrypted DNS is also converted into core queries. The actual behavior depends on the operating system and routing. Apps that connect directly to encrypted DNS services may bypass the expected domain mapping. Check the app’s own DNS settings rather than continually adding port rules.
Handle Permission and Platform Differences
| Platform | Permission requirements | Where to troubleshoot |
|---|---|---|
| Windows | Administrator rights or client service permissions | Service status, virtual interface, routing table |
| macOS | Network permissions requested by the client | Permission prompts, existing VPNs, outbound interface |
| Linux | TUN device and network management permissions | Device availability, service permissions, policy routing |
| Android | System VPN permission | VPN conflicts, background restrictions, per-app routing |
On desktop, enable TUN through the client’s service installation and authorization flow. Avoid running the entire desktop session with elevated privileges long-term. Android VPN permission is managed by the system; in normal use, two apps can’t occupy the same VPN tunnel simultaneously. On iOS, use the relevant client option rather than assuming desktop TUN fields work the same way on every platform.
When a device connects to a corporate network, internal subnets, private DNS, and security software may have additional requirements. Confirm the approved connection method with your organization before setting up route exclusions. Don’t blindly copy an exclusion list that covers every private address; some traffic may need to go through the core. Match exclusions to actual subnets and make sure remote services don’t accidentally use a local network route.
Maintain Fake-IP Mappings and Compatibility Exceptions
A Fake-IP address is neither a proxy address nor the destination server’s real address. When an app connects to it, the core uses its mapping to recover the domain. After a configuration change or core restart, the system may still cache an old virtual address while the core’s mappings have changed, causing brief failures. Clear the relevant cache and establish a new connection before considering whether mappings need to be persisted.
fake-ip-filter makes matching domains resolve to real addresses. It’s useful for local network discovery or apps that genuinely require real IPs. Don’t add broad filters covering a large part of the internet just to troubleshoot one issue; you would lose Fake-IP’s ability to associate connections with domains. After filtering, check that the real address is correct and the routing rules make sense. Filtering can’t fix an unreachable server.
To confirm traffic interception, look for a new connection from the test app on the connections page and verify its matched rule and outbound. An enabled TUN switch alone isn’t proof. After disabling TUN, also check that networking recovers and no manual system proxy remains. For installation and permissions, start with the guide. To switch clients, choose your platform in the download center. Don’t run multiple proxy entry points at once for comparison.
Domain Sniffing and Rule Matching
Understand What Sniffing Can Identify
Some connections reach the core with only a destination IP and no domain information that can be used directly by domain rules. Domain sniffing attempts to extract a hostname from a protocol handshake or request, such as the HTTP Host header, a server name visible in a TLS handshake, or supported QUIC handshake data. It adds routing clues; it doesn’t decrypt encrypted webpage content, and it can’t identify a domain for every connection.
When Fake-IP mappings are complete, the core usually already knows the corresponding domain, so sniffing may add little. Sniffing is more likely to help domain rules when an app resolves domains itself, connects directly to real IPs, or sends DNS queries outside the core. First find out where the information is missing before enabling it. There’s no need to add extra processing just to make a stable configuration look complete.
Limit Protocols and Port Ranges
sniffer:
enable: true
force-dns-mapping: true
parse-pure-ip: true
override-destination: false
sniff:
HTTP:
ports:
- 80
- 8080-8880
TLS:
ports:
- 443
- 8443
QUIC:
ports:
- 443
skip-domain:
- "+.example.com"
The example limits sniffing to common web ports. parse-pure-ip allows sniffing attempts for plain IP destinations, while force-dns-mapping extends sniffing to some DNS mapping scenarios. Neither can invent a hostname the app didn’t send. The wider the port range, the more traffic needs inspection and the greater the chance that a non-web protocol will be treated as a candidate.
override-destination determines whether sniffing results rewrite the connection destination, not just supplement matching information. Rewriting may trigger a new domain lookup and connect to a different address than the one originally selected by the app. Evaluate this carefully for services that depend on a specific entry point, address affinity, or local DNS. For an initial test, leave it off and check whether the routing information is already sufficient.
Create Precise Exceptions for Compatibility Issues
Use skip-domain to exclude known domains that don’t work well with sniffing. The suffix in the example illustrates the format; use the actual service causing the issue. Before adding an exception, compare connection logs, destination addresses, and matched rules with sniffing on and off. Keep an exception only for a repeatable difference; otherwise, you may turn a temporary routing issue into unnecessary permanent configuration.
If an app uses a fixed IP and its handshake contains no domain, domain rules have no reliable information to match. Consider an explicit IP rule or, where supported by the client and platform, a process rule. Don’t invent mappings just to make a domain rule match. One IP may host multiple services, and a name obtained by reverse lookup doesn’t necessarily match the hostname the app actually accessed.
Encrypted Client Hello and similar technologies can hide handshake information, and non-standard protocols may not be recognizable. Whether QUIC can be parsed correctly also depends on core support and the actual handshake. No hostname from sniffing doesn’t necessarily mean the configuration is wrong. Revisit the traffic entry point and DNS path to see whether the app’s queries should go through the core, rather than continually widening the sniffing port range.
Use the Same Connection to Verify Rule Changes
For a controlled comparison, close the test app’s existing connections, then open a single target page. In the connection details, note the original destination, detected domain, matched rule, and final outbound. Change only the sniffing switch or one parameter, then repeat the same steps. Existing long-lived connections won’t perform a new handshake automatically, and simply refreshing a page may reuse the old connection, making it look as if nothing changed.
Domain sniffing and rule priority are separate issues. Even when the correct domain is detected, an earlier IP or process rule may already have determined the outbound. If the result isn’t what you expected, check the matched rule before changing the order. Seeing a proxy connection in global mode doesn’t prove that a domain rule is working.
If only a few apps have a slower first response after enabling sniffing, check whether the sniffing scope is too broad, the protocol is supported, and destination rewriting is enabled unnecessarily. Don’t immediately blame the proxy. Narrow testing to one protocol and port, preserve a minimal reproduction, then check common log errors to distinguish handshake failures, DNS failures, and connection timeouts.
Local Overrides and Merging Multiple Subscriptions
Keep the Original Subscription Separate from the Final Configuration
A subscription is external input, the Profile saved by the client is a configuration container, and the core reads the final effective configuration. These may not be identical: the client may add port settings, TUN options, and local overrides, or regenerate files during reloads. Direct edits to a cached subscription are usually lost on the next update, so they’re not a good long-term maintenance strategy.
First, check the configuration page to see which Profile is active, then see whether the client supports overrides, extensions, or configuration editing. Clients differ in how they name these features and merge settings. In FlClash, rely on the current interface and the generated configuration. If the interface has no such feature, maintain a separate complete local configuration; don’t assume any YAML snippet will merge automatically.
Local overrides are useful for personal rules, DNS preferences, and controller restrictions, while subscription providers continue to manage proxy details. Keeping them separate means you can update routes without rewriting personal rules, and see which settings belong to your environment when moving to another device. For the basics, see Profiles and managing multiple configurations. For your first subscription import, follow the main setup guide.
Handle Maps, Lists, and References Separately
YAML maps and lists require different approaches. Maps may merge key by key or be replaced as a whole. Lists may be appended, prepended, or overwritten, depending on the client’s override mechanism. This is especially important for rules: rules appended after an existing MATCH usually won’t match. Check the order in the final configuration after editing, rather than only confirming that the editor saved successfully.
The core fields below can retain selection and mapping state, but verify whether the client manages them and whether they persist after switching configurations. They aren’t instructions for merging multiple subscriptions, and they won’t fix duplicate proxy names. For environments that differ significantly, such as work and home networks, separate Profiles are often easier to maintain than increasingly complex conditions.
profile:
store-selected: true
store-fake-ip: true
To put proxies from different sources into the same set of groups, use proxy-providers, but each source must provide content in a proxy-provider format supported by the core. A complete Clash configuration, a plain list of proxy links, or another subscription format may not work as a provider file. Check the structure first and confirm that it contains a valid proxy list under proxies.
Combine Multiple Sources with Proxy Providers
proxy-providers:
Route A:
type: http
url: https://example.com/provider-a.yaml
path: ./providers/a.yaml
interval: 3600
health-check:
enable: true
url: https://www.gstatic.com/generate_204
interval: 600
Route B:
type: http
url: https://example.com/provider-b.yaml
path: ./providers/b.yaml
interval: 3600
health-check:
enable: true
url: https://www.gstatic.com/generate_204
interval: 600
proxy-groups:
- name: Combined Selection
type: select
use:
- Route A
- Route B
rules:
- MATCH,Combined Selection
Replace the example URLs with real provider URLs, and give the two providers distinct cache paths. Never include subscription credentials in public screenshots, blog posts, or shared repositories. Treat configuration backups as sensitive files too; they may contain proxy passwords, subscription links, and controller credentials. When sharing troubleshooting materials, include only the structure and sanitized example values.
Multiple sources often contain proxies with the same name. Names are used in the interface and may also be used for persistent selection and rule references, so duplicates make it hard to tell which proxy you’re using. If the current core supports provider name prefixes, configure one as documented. Otherwise, rename proxies in a controlled preprocessing step or keep the sources separate. Don’t use simple text replacement across the whole YAML; it could also alter rule targets and group names.
Set Up Updates You Can Roll Back
Before updating, keep the last working configuration and local overrides. Afterward, verify that providers loaded, group members are present, rule order is correct, and DNS settings are intact. If needed, use the core’s configuration test—for example, run mihomo -t -f ./config.yaml from the relevant binary directory. This confirms that the configuration parses; it doesn’t prove that proxies are reachable or rules behave as intended.
After reloading, establish a new connection and confirm the outbound before resuming other app activity. If something fails, roll back the most recent override layer instead of deleting every Profile. Record the original configuration, the changed snippet, the final generated result, and the error logs. Rolling back layer by layer makes issues easier to find than repeatedly reimporting subscriptions, while preserving settings you’ve already verified.
External Controller and Maintenance Workflow
Separate Proxy Entry Points from Management Interfaces
Proxy ports such as mixed-port accept traffic connections; external-controller exposes the management API. A dashboard uses that API to view connections, switch proxy groups, or change runtime settings. It isn’t another proxy. Allowing proxy connections from your local network doesn’t mean the management API should also be exposed; assess the two separately.
Desktop clients usually manage the core through an internal controller. Manually changing its listen address, port, or password may stop the client interface from connecting to its own core. First check whether the client allows these fields to be customized and whether it regenerates them at startup. If the interface shows disconnected while traffic still works, check the controller connection before concluding that the proxy core has stopped.
Listen on localhost by default
external-controller: 127.0.0.1:9090
secret: "your-password"
external-ui: ./ui
The password here is for illustration only; replace it with a unique, strong password before use. external-ui points to a prepared directory of static dashboard files; setting the path won’t create a dashboard. Relative paths are resolved from the core’s working directory, and client sandboxes, the service account, and file permissions may affect access. After configuring it, first confirm the local API is reachable, then check the dashboard files.
If you don’t need a web dashboard, omit external-ui and keep using the client’s built-in management. If you do need one, use static assets compatible with the current core API and obtain them from a trusted source. Don’t expose the controller on more addresses just because some dashboard fields are missing. First determine whether the issue is dashboard compatibility, API authentication, or the content returned by the core.
Check Browser Connections and Authentication
A dashboard opening only shows that its static page is accessible; it doesn’t mean the page has connected to the controller. Check the API URL, password, and event connection separately. In the browser console, a refused connection usually points to the port or listening address; an authentication failure points to the password. If the page is hosted on a different origin, cross-origin restrictions may also apply. Each error needs to be fixed at a different layer.
Browsers may block an HTTPS page from requesting an HTTP controller API as mixed content, even when both are reachable over the network. Don’t set cross-origin permissions to allow any website to send credentials. First identify where the dashboard is hosted, then grant the minimum permissions supported by the core. Never put the password in the query string of a public URL, where it may appear in browser history, screenshots, or access logs.
For remote management, prefer a controlled local tunnel or a trusted network connection to the local API. If it must listen on the local network, use a firewall to restrict source addresses and verify that the network is trusted. Never forward the controller port directly to the public internet. The API can change policies and affect existing connections, so its access controls matter more than those of a read-only status page; don’t treat it as an ordinary display port.
Start Troubleshooting with Read-Only Information
After connecting to the dashboard for the first time, check the running mode, proxy groups, and connection logs before changing global settings. Confirm that the dashboard and client are managing the same core instance. If standalone mihomo and a desktop client are both running, they may use separate configurations on different ports. A successful group switch in the dashboard that doesn’t affect traffic often means it’s connected to the wrong instance.
Use a consistent troubleshooting order: confirm the core is running, check that the controller is listening, verify authentication, read the configuration through the dashboard, then observe a new connection. Fix one layer at a time. If traffic works but the dashboard is blank, check the static assets and browser. If the dashboard works but traffic fails, revisit the proxy entry point, rules, DNS, and proxies; don’t mistake the management interface for a real connection test.
Maintain a Long-Term Recovery Checklist
For every major change, record what fields changed, what symptoms prompted the change, how you verified it, and how to roll it back. When backing up the main configuration, also note the local rule directory, provider cache paths, and overrides managed by the client. After migration, restore the minimum working connection first, then re-enable TUN, DNS policies, and the controller one at a time. This avoids carrying over old paths and permission issues along with the configuration.
Client and core updates don’t always happen at the same time. If you encounter an unknown field, a failed configuration test, or inconsistent dashboard behavior, check the capabilities of the core actually running instead of inferring support from the interface. To choose another client, see the platform options in the download center. To restore a connection from scratch, return to the subscription import and connection guide, complete the main setup, then restore this guide’s advanced settings chapter by chapter.