MIHOMO / CONFIG.YAML
Clash Advanced Configuration Guide
First, distinguish traffic interception, DNS resolution, rule matching, and outbound selection; then edit the corresponding configuration section. The User Guide covers initial setup, subscription import, and connection checks. This page is for tuning and troubleshooting after your basic connection is working. If you haven’t installed a client yet, choose a package for your operating system on the client downloads page, prioritizing Clash Plus if it’s recommended for your platform and meets its system requirements. Examples below use mihomo’s native fields. Whether a client lets you edit a field in its UI depends on its core and how it merges configuration.
Proxy group types and outbound selection
A proxy group answers “which outbound should a matched rule use?”—not “which traffic should match this rule?” In Rule mode, the core checks each new connection against rules in order, then sends it to the strategy group specified by the matching rule. A group can reference proxies, built-in strategies, or other groups, but every reference must resolve and groups must not form a cycle. For example, an office group can reference a default outbound group, but the default group must not list the office group as a candidate. When troubleshooting, first check which group the rule points to, then see what that group has selected.
Choose a group type to match your needs
| Type | Selection method | Best for |
|---|---|---|
select | Use the manually selected candidate | A fixed outbound; isolating variables during troubleshooting |
url-test | Choose a candidate based on probe results | Multiple interchangeable outbounds |
fallback | Prefer the first available candidate in the list | A primary outbound with a backup |
load-balance | Distribute connections across candidates according to a strategy | Workloads where different connections can use different outbounds |
Use select for workloads that need a stable outbound. For example, if a backend treats an IP change as suspicious and flags it as a new login, don’t switch automatically just because another proxy has a faster probe result. For a primary and backup link, list candidates in order of business priority in fallback rather than ranking them by a single speed test. This lets new connections use the backup when the primary is unavailable; existing long-lived connections won’t migrate seamlessly, so an app may still need to reconnect or sign in again.
In url-test, url is the probe target, interval is measured in seconds, and tolerance in milliseconds. Tolerance helps prevent frequent switching when candidate results are close. A successful probe only shows that the outbound can reach the test URL; it doesn’t guarantee that calls, file sync, or a particular site will work. Make sure every candidate can reach the chosen target. Scheduled probes also use bandwidth and battery, so there’s no need for every group serving the same purpose to test the same proxies separately.
load-balance distributes connections, not packets within a single download. An app that opens multiple connections may use different outbounds at the same time. Even with a hashing strategy, don’t rely on it to provide a consistent public IP. First make sure all candidates are within an acceptable range, then check the distribution using two separate new connections. When troubleshooting web sessions or logins, switch to a fixed outbound first so you don’t mistake an app session issue for a proxy protocol failure.
Verify group references with a built-in strategy first
This minimal example can be loaded on its own and doesn’t need a subscription. It defaults to direct connections; switch to REJECT manually to block only example.com and its subdomains. Use it to verify that group selection works, not to create a proxy outbound. If a client is already listening on the same port, run the example in a separate test environment or choose an unused local port.
mixed-port: 7890
allow-lan: false
mode: rule
proxy-groups:
- name: ExamplePolicy
type: select
proxies:
- DIRECT
- REJECT
rules:
- DOMAIN-SUFFIX,example.com,ExamplePolicy
- MATCH,DIRECT
Test requests must go through the listener used by the example configuration. In the connection log, first confirm that the test domain matches DOMAIN-SUFFIX, then check that the strategy chain includes ExamplePolicy. After changing the selection, close the relevant app connections and make the same request again. A browser may reuse a pooled connection, so simply refreshing the page may not distinguish old results from new ones. If there’s no request in the log at all, troubleshoot traffic interception before changing group names or probe settings.
After adding a subscription, a group can use proxies to reference specific proxy names or use to reference proxy providers. The first option suits a small set of fixed candidates; the second works well for subscriptions that update regularly. If a group has a name filter, check after each update that it still returns candidates. Name groups for their purpose, not after a provider’s current proxy names. That way, switching subscriptions only requires changing the candidate source—not rewriting every rule.
If the selected option changes unexpectedly after switching back to the configuration, check whether the client saved a previous group selection and which configuration instance it’s reading. List order and runtime selection are different things; the candidate order alone doesn’t tell you which outbound is in use. Before deployment, test a domain that should match explicitly, one that should use the fallback rule, and a connection that needs a backup outbound. For more on rule order, see GEOIP, GEOSITE, and RULE-SET routing in practice.
Manage rules with providers
When a set of domains or IP ranges needs independent maintenance, put its rules in rule-providers and reference it from rules with RULE-SET. A provider fetches and parses rule entries; the rule that references it still determines the outbound. This lets maintainers update a list without changing the main configuration, but the provider name, matching order, and outbound name referenced by the main configuration must remain stable. Start with a small, clearly scoped rule set rather than moving every workload to one source at once.
Choose matching behavior and file format
Use behavior: domain for domain matches and ipcidr for IP ranges. classical expresses each match as a rule type and value, such as DOMAIN-SUFFIX,example.org. Entries in a classical rule set don’t include an outbound; specify that on the main configuration’s RULE-SET line. Changing a file extension doesn’t change its actual format. With format: yaml, the rule file carries its entries in a payload array.
Validate the match with a local file before switching to a remote source. The example sends the sample domain to DIRECT; all other connections are direct too, so use the connection log to distinguish the two rules rather than checking whether the outbound is different. Place the rule file at the corresponding relative path under mihomo’s working directory. Desktop clients may generate a runtime configuration in a different working directory from the subscription file; check the startup information to confirm the path.
# Merge into config.yaml; if rules already exists, merge the rule list only.
rule-providers:
documentation:
type: file
behavior: classical
format: yaml
path: ./rules/documentation.yaml
rules:
- RULE-SET,documentation,DIRECT
- MATCH,DIRECT
# rules/documentation.yaml
payload:
- DOMAIN-SUFFIX,example.org
- DOMAIN-SUFFIX,example.net
Remote updates and rule order
To switch to remote maintenance, set the provider’s type to http, enter the rule file url supplied by its maintainer, keep a separate local path, and set the update interval in seconds with interval. Don’t have multiple providers share a cache path, or you won’t be able to tell which source wrote the file. After an update, check the loaded entries and timestamp. A rule file opening in your browser doesn’t mean the core downloaded the expected format; the response could be a login page or an error message.
When there’s no usable cache on first launch, check that the rule source is reachable. If the rule file is accessible only through a particular outbound, and that outbound depends on the same rules or on proxies that haven’t initialized yet, startup becomes a circular dependency. Fetch and review the rules using a working configuration first, or start with a local file. Then choose a reachable path for remote updates. Shortening the refresh interval won’t fix a failure to load rules for the first time.
Rules are evaluated from top to bottom, and the first match wins. If a domain matches both a specific exception and a broader rule set, the order determines the result. Put exceptions first, followed by narrower domain sets, then broader IP ranges or geographic rules, and keep MATCH last. New entries added by a rule set update are subject to the existing order, even if the main configuration hasn’t changed. Give every remote rule set a clearly defined scope.
IP-based matches can also trigger DNS lookups. If a connection originally has a domain name, an earlier IP rule may trigger a lookup to match it, complicating troubleshooting for remote resolution or later domain rules. If you only want to match target IPs you already know, consider using no-resolve on a supported IP rule or IP-type rule set reference. It won’t automatically match a domain as an IP, and it doesn’t disable DNS throughout the core. Test once with a domain and once with a literal IP before adding the option.
When traffic takes the wrong route, record the failed connection’s destination, matched rule, rule set, and outbound. If an earlier rule matched, fix its order or scope. If no rule set matched, check its load status, entry type, and whether the domain is visible. If the right rule matched but the connection failed, check the strategy group and outbound instead. Keep the last working main configuration and its corresponding rule files for rollback; otherwise, you may restore the reference while still loading a new list.
DNS upstreams and resolution paths
To troubleshoot DNS, first find out who sent the query, then which resolver handled it. An app may use the system resolver or its own encrypted DNS. The core also sends queries when needed—for example, to resolve a proxy server’s domain or obtain a target IP for certain rules. Adding a mihomo dns section doesn’t mean every app uses it. Map out the browser, operating system, core, and upstream separately; don’t assume every query goes to the address shown in system settings.
Distinguish ordinary queries, upstream bootstrap, and proxy hostname resolution
| Field | Purpose | Common misconception |
|---|---|---|
default-nameserver | Bootstrap resolution for DNS upstreams specified by hostname | Not the default resolver list for ordinary domain queries |
nameserver | Handle general queries not covered by a specific policy | Doesn’t determine which outbound a connection ultimately uses |
nameserver-policy | Select an upstream based on domain and other match conditions | Matches DNS queries; it’s not the same as rules |
proxy-server-nameserver | Used only to resolve proxy server hostnames | Must remain reachable before a proxy outbound is established |
Start with upstreams reachable by IP to get things working and reduce the extra dependency of resolving a hostname-based upstream. Then introduce encrypted upstreams or domain-specific policies one at a time. If a node address is a hostname and resolving it requires that same node before it’s connected, the failure happens before the outbound is established. Before enabling respect-rules, configure proxy-server-nameserver as required by mihomo and make sure it doesn’t create a dependency loop with its own underlying outbound.
This example listens on a loopback address and is only for testing the core’s DNS in isolation. It uses public resolvers that can be queried directly. It doesn’t change system DNS or turn your machine into a LAN DNS server. redir-host makes it easier to inspect real IP answers during verification. Make sure your network allows access to the example upstreams. If your workplace requires internal resolvers, use the addresses provided by your administrator instead of adding an unreachable public fallback.
dns:
enable: true
listen: 127.0.0.1:1053
enhanced-mode: redir-host
nameserver:
- 223.5.5.5
proxy-server-nameserver:
- 223.5.5.5
dig @127.0.0.1 -p 1053 example.org A
Route queries by domain, then verify what’s intercepted
If internal hosts are listed only on your organization’s resolver, use nameserver-policy to send their domain suffixes to an internal upstream, and verify that traffic to the resolver uses the right interface. Putting internal and public resolvers in the same list doesn’t reliably separate internal from external lookups, and may send internal names to an unrelated upstream. Test a known internal record and a public record separately; a successful configuration load alone doesn’t prove resolution is correct.
Compare three results during diagnosis: a query sent directly to the core’s listening address, one using the operating system’s default resolver, and a new connection from the affected app. The first checks that the listener and upstream basically work. The second shows whether the system is forwarding queries to the core. Only the third reveals whether the app uses its own resolution mechanism or cache. Different results aren’t necessarily wrong if the differences match the expected paths. A browser’s built-in encrypted DNS generally can’t be redirected just by intercepting ordinary port 53 queries.
Before checking for a so-called DNS leak, define which resolution paths are allowed. For example, internal domains may use your organization’s resolver, ordinary external domains a specified public upstream, and an app’s encrypted DNS may have separate requirements. Test sites often show the exit point of the recursive resolution chain, not necessarily the server your device connects to directly. If results don’t match expectations, check system or client query logs and use a controlled request to identify the source. Don’t just repeat the test across multiple sites.
Treat query timeouts and successful queries with unexpected answers as separate problems. For timeouts, check that the listener is running, the upstream is reachable, and routing doesn’t loop back to the core itself. For unexpected answers, check specific policies, cache, address families, and whether the app uses another resolution path. If only one app fails, reproduce its specific path first. To review how the configuration sections fit together, see A guide to the config.yaml file structure and check that DNS and outbound rules aren’t reversed.
Check both address families separately with A and AAAA queries. Disabling IPv6 DNS answers won’t change existing IPv6 connections in every app or the system’s routing. Conversely, disabling IPv6 on an interface won’t fix a failed upstream lookup. After a change, send a new request through the same entry point and record the domain, query type, and result. Don’t change DNS upstreams, TUN, and browser settings at the same time; otherwise, you won’t know what made the difference—even after reverting.
TUN interception and Fake-IP mapping
TUN determines which device traffic goes to the core; Fake-IP determines how the core answers intercepted domain queries. They can work together, but solve different problems. A system proxy usually affects only apps that follow system settings, while TUN can intercept more traffic through a virtual interface. Fake-IP assigns a mapped address to a domain, then restores the domain when the connection reaches the same core instance so domain rules can be applied. If Fake-IP is enabled but connections using mapped addresses bypass the core, DNS may return an answer while the connection fails.
Enable the interface, DNS interception, and mapping in order
First, use the old configuration to confirm that the core and outbound work. Record the current default route and any existing VPNs or virtual adapters. Desktop clients usually need permission to create an interface and change routes. On mobile, traffic interception uses the system VPN mechanism, so use the client’s own options. Don’t treat desktop YAML as instructions for mobile settings. If another VPN is running, decide which one should handle the default route in your environment, then test whether they can coexist instead of relying on startup order.
This desktop starting point should be merged into a configuration that already works. mixed selects the TUN network stack; it isn’t mixed-port. auto-route installs the routes needed for interception, and auto-detect-interface selects an outbound interface. dns-hijack lists ordinary UDP and TCP DNS separately; it doesn’t turn encrypted DNS into ordinary queries the core can resolve.
tun:
enable: true
stack: mixed
auto-route: true
auto-detect-interface: true
dns-hijack:
- any:53
- tcp://any:53
dns:
enable: true
enhanced-mode: fake-ip
fake-ip-range: 198.18.0.1/16
fake-ip-filter:
- '+.lan'
nameserver:
- 223.5.5.5
The filter in this example only determines whether the corresponding domain returns a Fake-IP. For internal names that exist in your environment, return the real address and use a dedicated resolution policy to send the query to an upstream that can resolve it. The filter doesn’t add a direct rule or create a route that bypasses the virtual interface for the real address. If internal printing, file sharing, or service discovery fails, check resolution, the route to the target address, and the discovery protocol used by the app separately.
Trace the traffic path to find the break
After enabling it, test three kinds of targets: a public site whose domain rule you can check, a local resource that should be reachable, and an app that doesn’t use system proxy settings. The public site should match the expected rule, the local resource should remain reachable as required, and the independent app’s connection should appear in the core. Temporarily disable any proxy configured directly in the app, so a connection through another local port isn’t mistaken for TUN interception.
If a domain query returns an address in the mapping range but there’s no corresponding connection in the log, check the route and interface for that target address, especially for overlapping networks on the device. If the problem starts only after connecting another VPN or LAN, focus on route priority, interface selection, and address-range conflicts. If the connection reaches the core but its domain isn’t recognized, make sure the same instance created the mapping and handled the connection, and rule out a stale mapping cached by the app.
Automatic interface selection may not suit your setup after switching networks. With two network adapters, an external adapter, or a workplace VPN, record the actual outbound before and after switching and check whether the default route changed. Some apps keep old connections on the previous interface for a while, so don’t use an existing long-lived connection to verify the change. If you need to limit interception, first identify which subnets should remain on the original interface, then adjust routing based on core and platform support. Don’t broadly exclude subnets that might overlap with your target traffic.
If the whole device loses connectivity, turn off TUN in the client first and check whether the default route and DNS have recovered. If not, check for a leftover service reinstalling routes or another VPN taking over. Once basic connectivity is back, enable TUN alone to reproduce the issue. Don’t simultaneously enable the system proxy, change the network stack, and adjust subnets halfway through a test. These changes affect different layers, and stacking them makes the real failure point harder to find.
To compare against redir-host, make a fresh query and connection as well, so the app doesn’t keep using a cached Fake-IP. Record the specific difference: did the DNS answer change, did a different rule match, or did only the default route change? If interception fails on just one platform, check permissions and VPN status first, then see Common usage issues. Don’t copy system settings directly from another platform.
Domain sniffing and matching limits
Domain sniffing adds a domain hint to connections that have only a destination address. Before enabling it, confirm that the traffic reaches the core and that the missing domain is causing rules to match incorrectly. If a proxy request already has a reliable domain or a Fake-IP mapping, it can usually be matched directly. If an app connects to a bare IP and its protocol carries no recognizable hostname, sniffing won’t invent a usable domain.
Limit detection to the protocols and ports you need
For plain HTTP, the host field in the request header can provide a name. TLS may expose a name through SNI in the handshake; QUIC needs protocol-specific detection and depends on the handshake data and network behavior. A port only narrows what to inspect—it doesn’t prove the traffic uses a specific protocol. Don’t add an entire range of custom ports used by workplace apps. First check the protocol and port of a failing connection, then enable detection for a small class of traffic. TLS sniffing doesn’t reveal HTTPS page contents or require importing a certificate.
sniffer:
enable: true
parse-pure-ip: true
override-destination: false
sniff:
HTTP:
ports: [80, 8080]
TLS:
ports: [443]
QUIC:
ports: [443]
skip-domain:
- '+.lan'
Here, parse-pure-ip allows attempts to identify connections without a domain, while override-destination is disabled so a sniffed domain won’t rewrite the original dial target. This lets you see whether rules benefit before deciding whether to change how the connection is made. Don’t treat this as a universal fix: a service may be designed to use a fixed address, and even if its handshake includes a name, it may need to keep connecting to that address rather than resolving the name again.
Use skip-domain to exclude known domains that shouldn’t be sniffed; it isn’t an exclusion list for arbitrary IP ranges. With a bare-IP connection, the core may not have a name to match against this setting before processing it. For these issues, narrow the protocol or port range, or use target-address exclusions if the core supports them. Don’t add a domain that never appears and expect it to skip an entire subnet. Also, don’t confuse the domain exclusion list with DNS Fake-IP filters.
Compare connection logs before and after enabling sniffing
Add a precise rule in a clear position for the test domain, and temporarily pin the outbound to a group with a predictable result. With sniffing off, make a new connection and note the destination and matched rule. Then enable sniffing and make another connection from the same app. Check whether a domain appears, whether the matched rule changes, and whether the request succeeds. If the log merely shows a new name but traffic still takes the same route, verify the name against the rule’s match conditions. Seeing SNI alone doesn’t mean domain-based routing is working as intended.
A single IP address can host multiple sites. The domain shown for a connection should come from that connection itself, not from another domain previously seen at the same address and added to a rule. Even an outer hostname may identify only the object seen in the handshake, not the service host the user ultimately visits. For apps that need precise identification, prefer an interception method that preserves the original request domain, or use a Fake-IP mapping when both resolution and connections are under your control.
Encrypted client hellos may hide the actual server name, and some TCP or UDP apps don’t send a usable domain at all. In these cases, write a clearly scoped rule based on the actual destination address and port, or send the app’s traffic through a specific outbound. Expanding the sniffing port range won’t recover a name that was never sent and may increase false positives. Treat this as a domain that can’t be observed, not a failure to maintain the rule set.
If the issue only occurs with UDP traffic, check separately whether the browser obtains a domain when using QUIC, whether the outbound supports that traffic, and whether the app falls back to TCP after a failure. Change only one condition per comparison test, and start a new connection after each change. TCP working while UDP fails doesn’t by itself point to a sniffing problem; the outbound protocol, routing, and firewall are also part of the path. Conversely, sniffing a name doesn’t mean packets made it through the outbound successfully.
If you need to share logs, keep the rule type, protocol, port, and order of events, but remove internal domains and other information that could expose your environment. Once the configuration works, keep only the protocols and ports that testing showed were useful. If the benefit is limited to one app, record the reproduction steps and rollback settings. After a client upgrade or override change, you can use the same comparison to tell whether detection changed or the source traffic now enters differently.
Local overrides and multiple subscriptions
Keep updatable subscriptions separate from local rules that need long-term maintenance. Subscriptions provide proxies that change over time; the local main configuration controls ports, strategy groups, rule order, and logging. Adding fields directly to an imported remote subscription may be undone by the next update. Before using a client’s override feature, check whether it applies to one subscription, all configurations, or the generated runtime configuration, and find out whether it replaces, prepends, or otherwise merges lists.
Use providers to keep proxy sources separate
If a source is a proxies file that follows mihomo’s proxy provider format, use proxy-providers to combine multiple sources. Full subscriptions often include rules, dns, and their own strategy groups; don’t assume a client will automatically extract a provider-compatible proxy file. Check the top-level structure and actual response before importing. If the client only supports full configurations, use its documented merge feature and inspect the exported result. Don’t mistake client-specific override syntax for native core fields.
# Both files must exist, and each must be a proxy file containing a proxies list.
proxy-providers:
office:
type: file
path: ./providers/office.yaml
personal:
type: file
path: ./providers/personal.yaml
proxy-groups:
- name: Office
type: select
use: [office]
- name: Personal
type: select
use: [personal]
rules:
- DOMAIN-SUFFIX,example.org,Office
- DOMAIN-SUFFIX,example.net,Personal
- MATCH,DIRECT
The example puts the two sources in groups for different purposes. Replace the sample domains with authorized targets that actually suit each purpose, then test their connections separately. Don’t put every source into a single automatic-selection group just to make the list look tidy. Personal and workplace outbounds usually have different reachability and usage requirements. Mixing them can make the same site behave differently over time and make failures harder to trace. If multiple sources have proxies with the same name, use stable source prefixes and check which candidates the client actually displays.
If you already have a reachable remote provider URL, you can use type: http with a separate url and local cache path for each source, setting interval to match its update frequency. Subscription URLs may contain credentials; keep them in a controlled local configuration or client storage, never in a public repository, online conversion service, or screenshot. If one source fails, first find out which purpose-specific groups are affected. Don’t replace every group with the same outbound to hide the problem.
Check merge order and the final effective configuration
Mappings and lists are different kinds of merge targets. Overriding dns may replace the entire mapping in some implementations, discarding existing domain policies; others merge fields and may retain old upstreams. When appending to the rules list, new rules placed after the existing MATCH will never match. Before editing, decide whether the operation should replace everything, prepend entries, or insert them before a specific item. Then verify the generated file—not just that the editor saved successfully.
Use consistent names for groups and rule sets so references between sections remain stable. When renaming a group, check its rule outbounds and references in other groups. When renaming a rule provider, also check RULE-SET and any DNS policies that use that set. If two objects have the same name, decide which definition to keep rather than relying on unpredictable handling of duplicate keys by the merge tool. A YAML editor accepting the file doesn’t guarantee the core will receive the structure you intended.
With a standalone mihomo binary, you can check the configuration before loading it. The command below assumes you’ve changed into the working directory containing the configuration and relative provider paths, and that the core command is installed locally. If the client manages the core, use its own validation or log features where possible, and check the final configuration with the same core. Otherwise, you may be testing one file while running another.
mihomo -t -d . -f ./config.yaml
A successful configuration check only means the core accepts the current configuration. It doesn’t prove that remote files are reachable, every group has candidates, or traffic is routed correctly. After loading, test office, personal, and fallback connections separately, checking provider status, matched rules, and outbounds. Simulate a subscription refresh and repeat the same tests. Only when local changes and references still work after the refresh can you confirm that the override is in the right place. Keep test inputs and expected results in your local operations notes.
If only one group fails after an update, check whether its source was renamed, emptied, or changed format before looking at the merge logic. If all groups fail, first check whether the wrong base subscription was loaded or a client update changed the override’s scope. For rollback, restore the last working main configuration and its provider files, verify that rule targets still exist, and then restore sources one at a time. Good long-term maintenance makes it possible to identify which input changed, rather than fixing the issue once and losing the conditions needed to reproduce it.
External controller and runtime status
The external controller is the core’s management API, not a proxy traffic listener. A panel uses it to read connections, rules, and group status, and may change group selections, close connections, or modify configuration. It serves a different purpose from mixed-port and the DNS listener. If the client’s built-in panel meets your needs, there’s no reason to enable another listener. If you need a separate one, bind it to a loopback address by default and use a strong, unique secret stored locally only.
Use loopback binding and separate authentication
Merge the controller settings into the top level. If the client already manages a controller port, check its current listening address to avoid multiple core instances competing for the same port. The key below is an obviously non-reusable example; replace it with a unique random value generated on your machine before running. allow-lan: false can restrict LAN access to ordinary proxy listeners, but it doesn’t replace loopback binding and authentication for the controller itself.
external-controller: 127.0.0.1:9090
secret: "replace-with-local-random-value"
allow-lan: false
For a standalone panel served from local static files, set external-ui as supported by your core and point it to a trusted panel directory maintained on your machine. If the controller serves the panel, it’s usually available at /ui/ on the same control service, which can avoid browser cross-origin issues. A working control API doesn’t mean the panel path is available if the files haven’t been deployed; likewise, an open panel page doesn’t prove API authentication works. Test both separately.
The command below makes an authenticated read-only request from the same machine running the core, in an environment with Bash and curl. It prompts for the secret instead of putting it in the command or a script. Before running it, make sure shell tracing is off, and don’t share a terminal recording or request headers with anyone. If you use the client’s built-in panel, its connection diagnostics can replace the command.
read -rsp 'Controller secret: ' controller_secret
printf '\n'
printf 'header = "Authorization: Bearer %s"\n' "$controller_secret" |
curl --fail --silent --show-error --config - \
http://127.0.0.1:9090/version
unset controller_secret
Distinguish the panel, listener, and active configuration
| Symptom | Check first | Don’t change first |
|---|---|---|
| Connection refused | Whether the service is running and the address and port match the current instance | Rule order and DNS |
| Unauthorized response | Whether the current secret matches the panel’s connection settings | Listener scope |
| API works but the panel is blank | Panel assets, browser security restrictions, and the API address configured in the panel | Core outbound policies |
| Panel shows data, but from the wrong instance | The actual connection address, configuration file, and service owning the process | Unrelated settings for other groups |
If a request from the local machine returns unauthorized, first check whether you’re connected to the wrong core instance, then re-enter the secret. Don’t remove authentication for troubleshooting. If the command works but the browser reports a cross-origin or mixed-content error, test again with a local panel served from the same origin. Browser security restrictions protect users; disabling them or allowing requests from any site isn’t a fix. In particular, don’t submit local management credentials to a panel from an untrusted source.
Don’t bind the controller to every interface or forward its port to the public internet. If remote management is necessary, use an existing, access-controlled remote desktop or management channel, and open the panel from a local session on the device. Keep controller authentication enabled even when network access is restricted. On shared devices, limit access to configuration files and don’t store the secret alongside ordinary proxy ports in a shared directory readable by other processes or accounts.
When troubleshooting a workload, use the panel to observe before changing settings. Record a new connection’s destination, protocol, matched rule, and actual strategy chain, then adjust one variable in the relevant section. After changing a group selection, start a new test connection; existing sessions may keep using the old outbound. If a change only takes effect in the UI and disappears after a restart, check whether it’s a runtime selection, a client-saved preference, or a persistent change written to the local main configuration. These are not the same thing.
Enable detailed logging only as needed. Temporarily increase the log level to investigate load failures or domain detection, then restore it after reproducing the issue to avoid accumulating connection targets and personal activity. When asking for help, share the error type and relevant redacted configuration sections; there’s no need to hand over the full runtime configuration. Seeing proxies and rules in the panel only proves that the management API can read their status. Verify proxy access with actual connection logs and repeatable requests.
Run final checks in a fixed order: confirm the app’s traffic reaches the core, the required domain can be resolved or identified, the expected rule matches, and the selected group has a working outbound. Finally, refresh the subscription and reload, then verify that at least one key scenario still works. If the basic connection isn’t working, return to the User Guide and check the import and connection again. For system proxy, permission, or port issues, start with Frequently asked questions; there’s no need to change the whole configuration at once.