Complete Clash Configuration Guide

Core Concepts: How a Connection Flows

Clash accepts connections from apps and uses your configuration to decide how to route them. A typical setup includes a graphical client, a proxy core, a configuration file, and remote proxy servers. Installing a client gives you a local tool; it does not provide remote nodes to connect to. Understanding these roles helps you pinpoint whether a problem lies with installation, the subscription, routing rules, or the network—instead of blaming every connection failure on the client.

The Client Provides the Interface; the Core Handles Connections

A graphical client handles subscription management, mode selection, logs, and system integration. The core parses the configuration, handles DNS, applies rules, and makes connections. mihomo is an actively developed core in the Clash ecosystem; the name Clash Meta is associated with its development. Clients may use different cores and package them differently, so similar-looking settings do not guarantee support for the same configuration fields. When troubleshooting, note both the client name and core details.

The configuration file defines local listening ports, nodes, proxy groups, rules, and DNS behavior. A subscription usually provides a URL for retrieving configuration or node information, but the returned content varies by provider: some supply a complete YAML file, while others provide only a list of nodes. A client that can import one format may not recognize every format. If parsing fails, first check the format specified by the subscription provider rather than repeatedly changing local network settings.

How Traffic Flows from an App to an Outbound

For example, when a browser opens a webpage, the connection enters the core through the system proxy or TUN. A rule then determines whether to connect directly or send it to a proxy group. That group selects a node, which connects to the destination. DNS may be involved at several points, depending on the interception method and configuration. Once you understand this flow, you can read the logs in order: confirm the connection entered the core, check the matched rule, then inspect the selected outbound.

Direct means the device accesses the destination through its current network; it does not mean local rules were bypassed. Proxy means the connection is sent through a specified outbound; it does not guarantee the destination will be reachable. A remote server outage, account restrictions, destination-side blocking, or a local DNS issue can all break a connection that has entered the proxy chain. A successful latency test only confirms that a specific test request completed—it does not replace testing the app you actually use.

Set Up a Minimal Verification Test

While learning, use one client, one active configuration, and one manual proxy group. Record the network state before enabling the proxy, then enable the system proxy, visit a page you can test consistently, and look for its domain in the connection list. Seeing the connection and its outbound confirms that local traffic interception is working. Avoid running multiple proxy tools at once: they may compete for ports, system proxy settings, or default routes, making results harder to interpret.

The following sections use this same verification flow. If the connection does not appear, check the entry point. If it appears but uses the wrong policy, check the mode and rules. If the policy is right but the request fails, check the node and destination network. This is more reliable than trying every switch in turn, preserves useful evidence, and reduces the chance of changing a working configuration by mistake.

Choose a Client: Start with Your Platform and Configuration Needs

If you're new to Clash, start with Clash Plus. Get installation, subscription import, and connection checks working before trying other interfaces or management setups. The best choice depends less on the client name and more on your operating system, processor architecture, configuration format, and required system integration. Check the downloads page for packages and options by platform. For a side-by-side comparison, see the client comparison.

Narrow Down Your Options by Device

On Windows, consider Clash Plus, Clash Verge Rev, FlClash, Clash Nyanpasu, or Clash for Windows for legacy setups. On macOS, options include Clash Plus, Clash Verge Rev, FlClash, and the archived ClashX Meta. On Android, consider Clash Plus, Clash Meta for Android, FlClash, or Surfboard. On iOS, start with the Clash Plus App Store listing. On Linux, choose a package for your distribution from Clash Verge Rev or FlClash.

Clash for Windows and ClashX Meta are no longer maintained. They may be useful for understanding older configurations or supporting an existing setup, but they are not recommended for new devices. Archived clients may lack support for newer protocols, compatibility fixes, or configuration extensions. Before migrating, back up your subscription source and custom rules, then import them into the new client separately for testing. Don't overwrite the old directory. Remove the old program only after confirming the new setup connects successfully.

Match the Package to Your Architecture

Your processor architecture determines whether an installer can run. On Windows, check System Information for the system type; on macOS, check About This Mac for the chip or processor; on Android, choose a package that matches a supported ABI. On Linux, confirm both the architecture (AMD64 or ARM64) and package format. A single operating system may have several package options, so don't guess based on file size. If the downloads page does not list your architecture, don't try to force-install a package for a different one.

Compatibility with Clash configurations does not mean every field works everywhere. Rule providers, certain DNS options, and protocol parameters all require support from the core; graphical clients may also rewrite some fields. Surfboard follows a different configuration workflow. Before importing, check which formats it supports rather than assuming it can use a complete Clash YAML file unchanged. If a configuration fails to parse in a new client, compare the format and supported features before assuming the subscription is corrupted.

Compare Clients Under the Same Conditions

When comparing two clients, keep the device, network, subscription, node, and test destination the same, and run only one traffic-intercepting instance at a time. First check whether the same node connects, then see whether the features you need work. Don't judge clients by a single latency reading: the test URL, timeout, connection reuse, and current network conditions may all differ. What matters in daily use is connection stability, understandable routing rules, and the effort required to maintain the setup.

For servers, routers, or setups that need you to manage processes yourself, consider running the Mihomo core directly. This also means taking responsibility for service management, permissions, and protecting the control interface. For most desktop users, a graphical client makes it easier to monitor what's happening. On iOS, check the downloads page for Clash Plus and visit its official website, clashplus.io, for product information. You'll still need to import a configuration and authorize the connection after installation.

Install and Verify: Get the Local Entry Point Working

The goal of installation is to confirm that the client launches, the core runs, and a local port is listening—not to enable every network feature right away. Choose the correct OS and architecture on the downloads page. After installing, leave the default settings in place and close other proxy tools for now. On first launch, note the app's data directory, mixed port, and log location. You'll need these when importing a configuration, resolving port conflicts, or restoring a backup.

Desktop Installation Steps

On Windows, install and launch the app normally. Confirm the main window does not report a core startup failure before importing a subscription. If Windows asks for network access, choose the network types that match your needs. If you don't need to share the proxy with devices on your local network, don't expose it to them. For a portable installation, make sure your account can write to the configuration and log directories. A read-only location can prevent settings from saving, make subscriptions disappear after a restart, or break updates.

On macOS, move the app to an appropriate location based on the installer, then open it for the first time. If macOS blocks it, check the download source and system prompt rather than disabling security controls wholesale. Wait until basic connectivity is verified before granting extra permissions for TUN or a background service. On Linux, use a package suited to your distribution and check for dependency errors during installation. If the interface starts but the core exits immediately, inspect the logs for permission or configuration errors.

On Mobile, Authorize the Connection First

The first time Android creates a local VPN interface, the system asks you to authorize it. The app can intercept connections through that interface only after you grant permission. Android typically allows only one active VPN service at a time, so other VPNs, firewalls, or VPN-based filtering apps may conflict. On iOS, install Clash Plus, then follow the system prompts to add and authorize its VPN configuration. On both platforms, verify that it works while the app is in the foreground before checking whether the lock screen, network changes, or background operation affect the connection.

A VPN icon on a mobile device does not mean a remote node is connected; it only shows that the system network extension or interface is active. The icon may remain even if a node is unreachable, a subscription is inactive, or rules are misconfigured. Check real requests and the client's connection log. If Android disconnects frequently when the screen locks, check battery optimization, background activity limits, and app auto-start settings. Avoid changing several system permissions at once.

Check for Port Conflicts and Startup Failures

A mixed port usually accepts both HTTP and SOCKS proxy requests; the actual port depends on your client settings. The example port 7890 is not a universal default. If the logs say the listening address is already in use, close other proxy apps first, then check for a leftover core process. You can also switch to a free port, but update any browsers, terminals, and developer tools configured to use the old one. Changing the port in the client alone is not enough.

# Windows PowerShell: Check listening local ports
Get-NetTCPConnection -LocalPort 7890 -State Listen

# macOS / Linux: Find the process listening on this TCP port
lsof -nP -iTCP:7890 -sTCP:LISTEN

These commands only inspect the system; they do not fix conflicts. If no process is listening, check whether the core started and whether the configuration parsed successfully. If a port is listening, identify the owning process so you don't mistake another service for Clash. If a command is unavailable in your terminal, use the operating system's built-in network or process tools instead. You don't need to install unrelated software just to run an example.

After installation, you should be able to find the logs, confirm the core's status, and identify the local proxy port. Next, import a subscription rather than trying TUN first. For details on Windows firewall, startup, and service mode, see the complete Windows installation and setup guide. For a cross-platform first-launch check, see the first-launch checklist.

Import a Subscription: Separate Download, Parsing, and Activation

A subscription import involves three separate steps: the client downloads the content, the core can parse it, and the running setup actually uses that configuration. Seeing a subscription name in a list only confirms that an entry was created; it does not mean the configuration is active. Keep a working copy of the original subscription, then add local overrides gradually. Subscription URLs often contain account access credentials. Treat them like passwords and never include them in public screenshots or support requests.

From Import to Activation

Open the client's subscription, configuration, or profile page and choose the option to import from a URL. Paste the complete address and save it. Spaces, line breaks, or punctuation added by a chat app can cause requests to fail. Update the subscription and check the download result and parsing messages. Then select it as the active configuration. Button labels vary—such as Use, Activate, or Set as active—so check whether the active profile indicator and node list change.

Importing a local file is different from subscribing to a URL. A local file is a snapshot of the content at that point in time and usually won't fetch later node changes. A URL subscription can retrieve updated content when refreshed. If you received an archive, webpage, or login page, don't import it as YAML. File extensions are not proof that the content is valid: a webpage can load successfully but still produce missing-field or unexpected-character errors in the parser.

Find the Cause by Identifying the Failed Step

For a download failure, start with the error type. A timeout may indicate a connectivity problem between your current network and the subscription server. A certificate error calls for checking the device clock and request path. An authorization failure may mean the subscription URL has expired or the account status has changed. For parsing errors, check the expected format, indentation, and core support. Only investigate proxy groups and nodes after the content downloads and parses successfully. Not every subscription problem means a node is unavailable.

On some networks, you may need an existing proxy to reach the subscription server, creating a startup dependency on a new device that has no working proxy yet. Use an access method supported by the subscription provider, or import a valid configuration you saved earlier, before changing proxy settings for update requests. Don't send a subscription URL containing account credentials to an unfamiliar online converter. The service can access both the original URL and its contents, so the risk goes beyond a change in configuration format.

Keep Personal Changes Separate from Remote Content

A subscription update may rebuild the configuration file, overwriting rules, ports, or group names you edited directly. Prefer the client's override, merge, or extension mechanism, and confirm that it runs after subscription updates. Merge behavior varies by client, so check whether lists are appended or replaced. Test with one small change first, such as adding a clearly identifiable rule, before extending your full routing setup.

Keep proxy group names from the subscription consistent. If a local rule points to a group the provider has removed or renamed, the configuration may fail to load. After updating, check that the group still exists, your manual selection was retained, and node names have not changed. Don't rely on stale interface data to judge the result. If needed, reload the configuration and inspect what the core actually accepted—but save the working version first.

If the subscription updates normally but connections fail, continue to the proxy modes section. Find more common issues in the FAQ. When asking for help, share the error type, client name, and a redacted configuration structure; you don't need to reveal the full subscription URL.

Proxy Modes: Separate Traffic Interception from Outbound Selection

Rule, Global, and Direct modes determine how connections that enter the core are routed. The system proxy and TUN determine whether app connections enter the core at all. These are separate settings. Global mode will not automatically intercept apps that ignore the system proxy, and turning off the system proxy does not necessarily stop traffic already intercepted by TUN. If switching modes does not change an app's behavior, first check how that app connects instead of trying another node.

Use Rule Mode for Everyday Traffic

Rule mode applies the configuration's rules in order to select a policy for each connection. One connection may go direct while another uses a proxy group, depending on matches such as the domain, address, or process. It's suited to everyday use, provided the rules are complete and the group names exist. For an initial test, select an available node in a manual proxy group and check which rule matches the destination domain. This helps distinguish a routing mistake from a node failure.

Global mode usually sends all connections that enter the core to the global policy. You still need to select the right node or group in that policy. It can help rule out routing rules temporarily: if the same destination fails in Rule mode but works in Global mode, inspect the routing result. This comparison is only useful if the app actually enters the core and both modes ultimately use the same node. Otherwise, you've changed two variables and the result is inconclusive.

Direct mode sends connections entering the core directly to their destination. It's useful for checking the underlying network, but it does not exit the client or necessarily close the local listener or virtual interface. To fully remove the client's effect on system networking, turn off TUN, turn off the system proxy, then exit the app normally. Switching to Direct alone does not confirm that leftover system proxy settings have been cleared.

Use an Explicit Proxy for Comparison

Terminal tools do not always read the desktop system proxy, and browser extensions may override system settings. To verify the local entry point, you can explicitly direct a single command to the mixed port. This separates system proxy behavior from the core's outbound behavior. The commands below assume the mixed port is 7890; update the port if you changed it. In Windows PowerShell, using the full executable name avoids confusion with command aliases.

# Windows PowerShell
curl.exe --proxy http://127.0.0.1:7890 -I https://example.com

# macOS / Linux
curl --proxy http://127.0.0.1:7890 -I https://example.com

A response confirms that this request made it through the specified entry point, but it doesn't prove other apps use the same route. Open the connection list during the test and confirm the request domain, matched rule, and outbound. If the command immediately fails to reach the local port, return to the installation section and check the listener. If it connects locally but times out remotely, check the node. The test destination may also impose restrictions, so try another known-good destination if needed.

Reconnect After Switching Modes

A mode change usually affects new connections first. Existing long-lived connections may continue using their original outbound. Reload the page, close the relevant connections, or restart the test app before checking the result. Otherwise, a reused connection can make it look as though the setting had no effect. Video, messaging, and browser connection pools are especially likely to delay changes. Closing all connections can interrupt active transfers, so do so only when that is acceptable.

Routing Rules: Match Order and Proxy Groups

Routing rules are checked from top to bottom, and the first matching rule typically determines the outbound. Before adding a rule, answer three questions: what connection should it match, where should it go, and which rules should it run before? Rule count is not a measure of quality. A clear order and valid proxy group references matter more. Start with inline rules before adding external rule sets, so you don't introduce too many hard-to-trace conditions at once.

Start with Three Common Match Types

DOMAIN matches an exact domain, DOMAIN-SUFFIX matches a domain and its subdomains, and IP-CIDR matches an IP address range. MATCH is the catch-all rule and should not appear above rules that still need to run. Domain rules rely on the core knowing the destination domain. If an app connects directly to an IP address, some domain conditions may not match; check the connection details to see what is available.

A proxy group is not a rule; it is an outbound selector that rules can reference. A manual selection group is useful for learning or keeping a fixed exit. A URL-test group typically selects based on results from a specified test destination, while a fallback group focuses on availability and candidate order. The core determines which group types are supported. URL-test results apply only to the test destination and cannot guarantee the same node will work equally well for every site, regional service, or long transfer.

# Rule snippet: merge into an existing configuration; this is not a complete subscription
# DIRECT is the built-in direct outbound
rules:
  - DOMAIN,example.com,DIRECT
  - DOMAIN-SUFFIX,example.net,DIRECT
  - IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
  - IP-CIDR,10.0.0.0/8,DIRECT,no-resolve
  - MATCH,DIRECT

This snippet demonstrates rule order and syntax. All outbounds use the built-in direct route, making it easier to understand the rules without nodes. If you need proxying, replace the relevant outbound with a proxy group that actually exists in your configuration. Don't copy the example group name as-is. The final direct fallback is not a universal recommendation either. If unmatched connections should use a proxy by default, point the fallback to a verified working proxy group and consider how much traffic that change will affect.

How no-resolve Relates to DNS

In an address rule, no-resolve means the core will not proactively resolve a domain to an IP just to evaluate that rule. It does not disable all DNS, or prevent the rule from matching a target IP that is already known. Using it with private network ranges can avoid extra lookups made solely to check those ranges. If your routing depends on the result of resolving a destination, consider your DNS setup before deciding whether to keep resolution enabled. Don't add the same parameter to every address rule by default.

DNS responses affect address rules and the actual destination IP, while domain rules may not require the destination IP to be resolved first. In fake-ip mode, the core returns a synthetic address to preserve the mapping between a domain and its connection; it is not the real address of a remote server. A synthetic address alone does not indicate DNS pollution. Check the domain recognized by the core, the matched rule, and the final outbound before changing DNS or excluding a particular app.

Verify Rule Matches After Editing

Back up the current configuration, then add just one clearly targeted rule in a local override. Reload the configuration, visit the matching domain, and check the connection details to see which rule actually matched. If it doesn't match, look for a broader rule above it, a reused connection, or an override that was not applied to the running configuration. If the configuration fails to load, check indentation, commas, and group names. Restore the last working version before fixing errors one at a time.

Rule sets help maintain large groups of similar domains, but check the provider's format, behavior type, update interval, and local cache path. Whether a cached copy remains available after a download failure can affect whether the configuration works. Avoid stacking multiple rule sets with overlapping purposes or unclear sources; the same domain may be caught by different rules. Establish a clear routing plan first, then choose rule content that fits it.

For details on match order, suffix scope, and fallback rules, see Clash Custom Rules and Priority: A Detailed Guide. When maintaining your own rules, note the purpose of each change and how you verified it. This makes future migrations easier.

TUN Mode: Expand Traffic Interception and Handle DNS

TUN receives connections through a virtual network interface and can handle apps that ignore the system proxy, but it is not a universal fix. Confirm that the normal system proxy works before enabling it; expanding interception can turn a localized configuration error into a network-wide problem. Also distinguish between the TUN interface being present, routes being intercepted, and DNS being intercepted. These states do not always occur together.

Check Permissions and Potential Conflicts First

Desktop platforms may require service mode, a helper service, or elevated permissions to create an interface and change routes. The exact method depends on the client. Check the service status in the interface, then grant permission only if needed. Note any existing corporate VPNs, virtual machine or container networks, and other proxies. Two tools that both change the default route or DNS can create routing loops, conflicts, or partial connectivity. Keep the test environment as simple as possible.

On mobile, the system manages traffic interception through its VPN or network extension framework, and the interface may not expose the same TUN settings as a desktop client. Don't copy every networking option from a desktop YAML file to your phone. System restrictions, client implementation, and configuration overrides all differ. Even with the same subscription, test Wi-Fi, mobile data, screen lock, and network switching separately.

Know What the Common Settings Do

# mihomo TUN configuration snippet; merge it into an existing configuration
# First check whether the client already sets these options in its interface
tun:
  enable: true
  stack: mixed
  auto-route: true
  auto-detect-interface: true
  dns-hijack:
    - any:53

enable turns on the interface, stack selects the network stack, auto-route lets the core configure routes according to platform capabilities, and auto-detect-interface attempts to identify the outbound interface. This is not a complete configuration, and the same combination will not suit every setup. If the client already manages these fields, use its merge mechanism to avoid conflicts between the file and interface settings.

dns-hijack intercepts matching DNS traffic, but it does not automatically cover encrypted DNS built into every app. Browser Secure DNS, app-specific resolution, hard-coded IP addresses, and system caches can all affect the results. After enabling it, test regular websites, local network names, and the apps you rely on. One working website does not prove that every DNS path is behaving as expected.

Enable TUN in a Reversible Order

Save the working configuration and confirm how to exit the client before enabling TUN in the interface. First check the core logs for a successfully created interface. Then visit a regular website and a local network resource, and inspect the connection logs. If a printer, router admin page, or company intranet address stops working, check the relevant routes and direct rules. Route exclusions and direct routing rules operate at different layers; adding a domain rule is not a substitute for handling every route.

If the entire device loses connectivity, turn off TUN first, leave the client running, and check whether the normal system proxy works again. Once connectivity is restored, compare the two entry points and check the service status, default interface, DNS, and other VPNs. Don't change the network stack, DNS, rules, and nodes all at once while offline; even if service returns, you won't know why. On a remotely managed server, keep a separate access path so a default route change can't lock you out.

Test UDP apps separately. A webpage loading only confirms that some TCP requests work; it does not prove that real-time communication, games, or a particular UDP protocol will work. Check node support, server-side policies, the current network, and client settings. Don't switch network stacks as a first step. Find the relevant connection and error in the logs, then decide whether to change the outbound or interception settings.

For certificate issues caused by the system clock, packet capture tools, or DNS routing, see How to Troubleshoot Certificate Errors in Your Browser After Enabling Clash. After testing, keep only the traffic interception method you actually need.

Maintenance: Updates, Backups, and Recovery

Reliable use depends on making every change traceable and reversible. Client updates, core updates, subscription updates, and custom rule edits are separate operations; don't do them all at once. Record the current working state, make one change, and repeat the same tests. If something breaks, you can return to a known starting point instead of trying to untangle multiple configurations, nodes, and interception settings.

What to Back Up

At a minimum, save the subscription source, active configuration, custom override rules, proxy group selections, and key network settings. The client data directory may contain access credentials or control interface details, so store backups securely and never upload them to a public repository. Before migrating to another device, check what the export includes: some exports contain only rules, while others include the entire runtime directory. These have different privacy and recovery implications.

Keep the original subscription content separate from your custom rules. The former can be fetched again from the remote source; the latter may exist only on your device. Record the port, LAN access setting, TUN status, and startup behavior too. The client may store these in its interface settings, not in the exported YAML. After restoring, don't just check the node names. Verify the system proxy address, listening interface, and local overrides are all active.

Use the Same Checklist Before and After Updates

Before updating, read the release notes relevant to your platform and the features you use. You don't need to install a new package on every device just because it's available. After updating, check that the app starts, the core parses the configuration, the subscription loads, rules match, and TUN is in the expected state. Then test one proxied destination and one direct destination. If the new setup is unstable, restore the saved configuration and settings. Cached data and extension fields may not be compatible across different cores or after a downgrade.

Routine latency tests can reveal nodes that are clearly unreachable, but don't refresh the entire subscription constantly to chase the lowest number. Concurrent tests consume network resources and may hit server limits. Download speed, time to first connection, and long-connection stability are different metrics. Keep one verified candidate in your regular proxy group. It's more useful to compare against it when something goes wrong than to switch repeatedly based on a single test.

Use Logs to Build a Troubleshooting Record

Use the normal log level for everyday use, and increase detail only briefly while reproducing an issue. Record when it happened, the app, destination domain, interception method, mode, matched rule, and error. A timeout, refused connection, parsing error, and authorization failure point to different stages; don't copy only the final word, "failed." Before sharing logs, check for subscription credentials, node addresses, private network addresses, or local file paths, and redact them as needed.

Record changes to the environment too. If a problem appears after joining a new Wi-Fi network, connecting to a company network, enabling security software, or starting a virtual machine, the default route, DNS, or firewall rules may have changed. Compare against the previous network before changing the client. If several devices have the same problem on one network, check the shared network and remote service first instead of reinstalling the client on every device.

Before Exiting or Uninstalling

Before exiting, turn off TUN and the system proxy, then close the app normally. If the app crashes and your browser can no longer connect, check whether the system proxy still points to a local port that is no longer listening. Remove leftover settings only after confirming the port is inactive and considering your current network needs. Don't run a network reset script from an unknown source; a full reset may also remove a corporate proxy, static IP settings, or other working network configuration.

Next Steps: From Using Configurations to Maintaining Them

Going further is not about turning on more options. It's about predicting how a configuration change will affect your setup and using evidence to confirm the result. After completing the first eight stages, study configuration structure, rule providers, DNS, and runtime management in that order. Introduce one capability at a time, test it in a recoverable configuration, then merge it into your everyday setup. For settings without a clear purpose, keeping the default is usually safer than copying an entire "optimized" configuration.

Map Configuration Dependencies First

Think of a configuration as a dependency graph made up of entry points, outbounds, proxy groups, rules, and DNS. Rules reference proxy groups, groups reference nodes or other groups, providers fetch external content, and system integration sends app traffic into the entry point. When renaming something, follow its references. Before deleting a node source, check whether any groups still use it. Successful parsing is only the first step; verify that the final outbound still does what you intended.

When learning rule providers, start with a small, known set of rules and check its format, behavior type, and update results. Don't connect a long list of external sources and hand routing decisions to a combination you can't explain. Set a reasonable update interval: rule content doesn't need to be fetched every few seconds, and excessive refreshes only add network dependencies. Understand the difference between a first launch with no cache and a routine update failure when a cached copy is available.

Then Explore DNS and Connection Metadata

Start by understanding the difference between system DNS, core DNS, and DNS built into apps. Then compare fake-ip with returning real addresses. For each test, record the requested domain, resolution result, matched rule, and outbound path. A mode that fixes one app may also affect local network discovery or apps with unusual resolution behavior. Keep regression checks for common scenarios when making changes instead of testing just one website.

Traffic sniffing can provide domain information in certain situations, but it cannot reveal all app content or guarantee that every connection will have its destination identified correctly. Results depend on the protocol, encryption, and app behavior. First learn what connection details look like without sniffing, then decide whether you need it. Sniffing is not a substitute for correct DNS interception or rule design. For sensitive work, follow the policies of the network you're using.

Protect the Boundaries When Running the Core from the Command Line

Running the core directly can suit servers and routers, but you'll also need to manage configuration paths, working directories, process restarts, log retention, and permissions. Check the configuration in the foreground before handing it off to a system service. These commands assume mihomo is installed and executable and that the current directory contains a configuration file. They validate the configuration; they don't install anything or prove that every remote node is reachable.

# Check the current configuration syntax and whether it can be loaded
mihomo -t -f ./config.yaml

# Run the specified configuration in the foreground
mihomo -f ./config.yaml

After the configuration passes validation, test rules and connections during actual operation too. A service may have a different working directory, environment variables, or user permissions from an interactive terminal, so a successful foreground run does not guarantee the service can find the same file. Absolute paths and an explicit data directory can reduce ambiguity, but use the actual deployment locations rather than copying paths from another device.

Allowing LAN connections expands access to the local proxy, while an external control interface may provide more powerful configuration management. Neither should be exposed to the public internet. Enable them only when you have a specific sharing or management need, restrict the listening address and network access, and use authentication supported by the client. Don't open a router port just to access the dashboard from your phone. First define the access boundary and how to revoke it.

Turn Troubleshooting into a Personal Runbook

Keep a fixed set of tests for common situations: a direct-connect destination, a service that requires a proxy, a local network resource, an explicit proxy request from a terminal, and any UDP app you rely on. Repeat each test after a change and record the results instead of relying on memory. When something breaks, trace the issue through five stages: entry point, DNS resolution, rules, outbound, and remote destination. These records will help with future migrations and make it easier to describe a reproducible issue to others.

If you can explain why you made each change, verify the result, and restore the previous state, you have the foundation for maintaining your own configuration. Keep the same principle in mind when choosing features: identify the stage causing the problem, then use the feature designed for it. Don't add unnecessary complexity just to increase the number of settings.