Clash User Guide:
From Installation to Rules & TUN

1. Core Concepts and the Connection Path

Understand the Client, Core, and Service

In the Clash ecosystem, the client provides the interface, the core parses configuration, handles connections, and applies rules, while the remote service provides the actual exit. These are separate components. Installing a client does not create working proxies, and a subscription is not a client account. When something goes wrong, first identify whether the issue is in the interface, core configuration, or remote service. This is more useful than assuming every problem is an installation failure.

Many clients use the mihomo core, but actual support depends on the bundled core build, system permissions, and client implementation. Being able to import a file does not mean every field in it takes effect. Likewise, the core may support a feature that the client interface does not yet expose. The YAML examples in this guide use common mihomo syntax; check where your client expects configuration before applying them.

Break a Request into Four Stages

A browser typically resolves a domain, establishes a connection, completes an encrypted handshake, and then exchanges application data. A proxy can affect several stages: the system proxy tells an application to send requests to a local port, rules choose a policy, and a remote node connects to the destination. A failure at any stage can make a site appear unreachable, so the browser's final error message alone is rarely enough to identify the cause.

A local listener is commonly bound to a loopback address, which accepts connections only from the same device. Its port is the entry point to the core. This is different from a remote node's server address and service port. If you change the local port, update any proxy address entered manually in a browser or terminal as well. Remote node details usually come from the subscription. Changing them to resolve a local port conflict mixes up two separate issues.

A proxy group selects where a connection goes; it is not a node itself. A manual selection group lets you choose a member, a URL-test group selects one based on configured tests, and a fallback group prioritizes availability. Rules can target a proxy group or built-in actions such as DIRECT. Don't infer a group's behavior from its name alone—check its type, members, and current selection.

Know the Boundaries Between Routing, DNS, and Traffic Capture

System proxy settings, TUN, and rule modes solve different problems. The system proxy and TUN determine how traffic reaches the core; the rule mode determines how traffic is routed once it arrives; DNS settings control name resolution and how the resulting information is used for matching. These settings can work together but are not interchangeable. Rules still apply with TUN enabled, and turning off the system proxy does not necessarily stop all traffic from reaching the core.

The DNS configured in Clash may coexist with the DNS supplied by the device's current network. Apps using encrypted DNS, built-in browser resolution, or local network names can make the path more complicated. You don't need to change your DNS setup right away, but treat name resolution as a separate troubleshooting step. If testing an IP address works but testing the domain does not, investigate the DNS path.

For an initial check, choose an ordinary website and watch the client's connection log. You should see the destination domain or address, the policy used, and the connection status. If there is no entry, check the traffic capture path first. If an entry appears but the outbound connection fails, check the node, DNS, and remote-side errors. This approach—find the boundary, then narrow down the cause—works throughout this guide and preserves more useful evidence than repeated reinstalls.

2. Choose a Client for Your Platform and Needs

Choose an Interface First, Then Compare Features

For everyday use with a graphical interface, start with Clash Plus, then compare other clients based on your platform and feature needs. Focus on whether subscription updates, policy selection, connection logs, and permission prompts are easy to understand—not on the number of toggles. Before installing, check the download center for your platform and confirm your system architecture and installer type. This helps avoid downloading several apps and repeatedly moving configuration between similar interfaces.

On desktop, Clash Verge Rev, FlClash, and Clash Nyanpasu are options to compare for their interfaces and workflows. Don't assume their settings map one-to-one: subscription enhancements, service modes, core updates, and log locations can differ. If you plan to maintain a device long term, knowing where configuration is stored and how to restore it matters more than the first-launch screen.

Architecture and system integration matter more than the name

Check your system information for the processor architecture; don't rely on the computer's brand. macOS installers differ for Apple Silicon and Intel, and Windows devices can also use different architectures. Android packages may support different sets of devices depending on their target architecture. Choose from the options listed on the download page rather than guessing an installer URL based on a filename pattern.

On Linux, package formats also vary by distribution. A package for a Debian-based distribution cannot be installed as an RPM package. Graphical clients are designed for desktop sessions, while a command-line core requires you to manage configuration directories, service startup, and logs yourself. On a headless server, there's no need to install a full desktop just to use a proxy; using the core with a service manager is usually simpler.

Mobile clients generally use the system VPN interface to capture traffic, and that interface can usually be occupied by only one relevant service at a time. Another security tool, work profile, or network accelerator may conflict. On desktop, virtual adapters and competing routes can cause similar issues. If you need a corporate VPN or access to specific local network resources, prioritize a client that lets you control the capture scope instead of assuming all network tools will work together.

Check Subscription Compatibility and Maintenance Separately

Clients that all advertise subscription import may accept different formats. A full Clash YAML configuration, a standalone node list, and another client's profile are not interchangeable. If you choose Surfboard, confirm that your provider supports its format rather than treating the file extension as proof of compatibility. Converting a profile can omit rules, proxy groups, or protocol settings; even a successful conversion needs a connection-path check.

Clash for Windows and ClashX Meta are discontinued, archived options. If an existing setup depends on them, they may be useful as a migration reference, but for a new device prioritize actively maintained alternatives. An older app launching successfully doesn't mean it understands protocols and fields in a new subscription. If you see unknown fields, skipped nodes, or core errors, check for feature gaps before deciding the subscription is invalid.

For Clash Plus on iOS, open the download center to go to the App Store, and see the product information on the official clashplus.io site. Even with the same client name across platforms, don't assume desktop and mobile permissions are identical. After choosing a client, note its name, system architecture, configuration source, and primary use. These details make a useful environment summary when troubleshooting later.

3. Installation, Permissions, and Environment Checks

Make Minimal Changes on First Launch

Before installing, quit other proxy tools and note the system's current proxy settings and VPN status. If two apps both modify the system proxy, the one launched last may overwrite the other; the order in which they quit can also affect restoration. Back up existing work configurations before migrating. Don't make uninstalling the old app your first migration step. It's easier to roll back if you keep the old setup until the new app can import a profile and run reliably.

After opening the client, check that the main window, settings, and logs display correctly. Leave launch at startup, TUN, and complex overrides disabled for now. Having no subscription or nodes at this point is normal, not an installation problem. If the app exits immediately, check system compatibility, architecture, access to the install directory, and security software logs rather than repeatedly downloading the same file.

Match Permission Requests to Their Purpose

Desktop clients may request extra permissions for a system service, virtual network adapter, or network extension. Understand what each permission is for before approving it; running the entire graphical app with elevated privileges is not a general-purpose fix. System proxy settings typically apply to the current user session, while TUN may require a service component and route changes. If a feature lacks permission, check the client's installation instructions and distinguish a missing service from one that isn't running.

On macOS, follow the system prompts for network permissions and confirm the relevant status in System Settings. Android and iOS show a VPN permission prompt the first time traffic capture is enabled. The interface may still open if you deny it, but traffic won't reach the core as expected. On managed devices, policy may restrict these permissions; follow your organization's requirements rather than trying to bypass them by reinstalling.

After installation, find the configuration directory and log location. Check whether the client uses a portable directory, user data directory, or separate service directory. The profile shown in the interface may not be the same file the core actually runs. Note the directory location for reference, but don't edit its contents yet. The client may overwrite generated files the next time it saves settings or starts up.

Local Ports and Listening Scope

A local port is the entry point apps use to connect to the core. If another process occupies the port, the logs may report a bind failure or that the address is already in use. Close the other process or change the listener port in the client, if supported, and update any manually configured proxy address. Don't change the remote service port in your subscription to work around a local conflict; they belong to entirely different parts of the connection.

# For understanding the local entry point only; not a complete working configuration
mixed-port: 7890
allow-lan: false
mode: rule
log-level: info

The example's mixed port accepts common HTTP and SOCKS proxy requests, but use the actual port shown by the running client. Disabling LAN access helps keep initial troubleshooting focused on the local device. If you later need to share the proxy with other devices, also consider the listening address, firewall, and access controls. Enabling LAN access alone doesn't create a properly secured sharing setup.

The goal of the basic checks isn't simply to access a website. The client should start, the core should not produce persistent errors, the listener should be clear, and closing the client should restore network access. Once that's confirmed, import a subscription; the cause of any problem will be easier to isolate. For a command-line Linux setup, see two deployment paths: desktop client and systemd. Desktop startup and system services are separate configurations.

4. Import Subscriptions, Update Them, and Preserve Configuration

Confirm What You're Importing

A subscription is usually a configuration URL maintained by a service provider. The client uses it to retrieve nodes, proxy groups, rules, and other settings. The URL may contain a personal access token, so treat it as sensitive information. Don't include it in public screenshots, support tickets, or shared documents. Before importing, check which client and format the provider recommends. A URL opening in a browser doesn't prove its contents are compatible with your core.

Find the subscription, profile, or configuration section in the client, add a remote profile, paste in the URL, and save it. When the update finishes, set that profile as active, then check that proxy groups and nodes appear. Some clients separate downloading from activation; after downloading alone, the core may still be running an older profile. If the client lets you name profiles, choose a name that identifies their source and purpose without including the full URL.

After the first import, check the update log and core log instead of relying only on a success message. A successful download means the server returned a response; successful parsing means the structure could be read; successful core loading means the configuration is running. If some node protocols aren't supported, only part of the list may appear. Compare the node count before and after with any warnings to distinguish unsupported entries from nodes removed by the provider.

Troubleshoot Update Failures in Three Stages: Request, Content, and Load

If the request fails, first check that you copied the entire URL, including trailing parameters, and that it has no extra spaces. Then identify whether the error is a parsing failure, connection timeout, access denied, or unexpected redirect. A subscription may be unreachable even when the rest of the network works, depending on the route used for update requests. Clients differ in whether updates use the existing proxy; check the relevant setting rather than assuming they follow the currently selected policy group.

If the response arrives but import still fails, check whether it contains YAML, another format, or a web error message. An account status page, login page, or CAPTCHA page cannot be loaded as a proxy configuration. If the server returns an error temporarily, don't save the error page and try to edit it. Keep the last working profile and wait for the source to recover; that's safer than clearing local data and losing nodes and rules that still work.

If loading fails, check the field or line number named in the error. YAML uses indentation to express structure; tabs, missing colons, and incorrect list indentation can all break parsing. YAML that parses can still have semantic problems, such as rules referencing a nonexistent proxy group. Distinguish a syntax error from a core validation error: check the structure for the former, and field support and name references for the latter.

Keep Remote Content Separate from Personal Changes

Edits made directly to a subscription-generated file are often lost the next time it updates. Put persistent settings in the client's override, merge, patch, or local extension feature; names and merge order vary by client. Test persistence with a small change, such as adjusting the log level. Then update the subscription and restart the core to confirm that the running configuration retains the change.

Be especially careful when merging arrays. Some override systems replace the entire rule list instead of appending one rule; proxy groups may also be replaced by entries with the same name. Before applying changes, preview or export the final configuration and make sure the original nodes, groups, and fallback rules are still present. Avoid maintaining the same field in the interface, a local file, and a remote patch at once; it becomes difficult to tell which value actually takes effect.

If performance drops immediately after an update, you don't need to replace the entire client right away. Compare the active node, proxy group selection, and rule matches before and after the update. If a node name changed, your previous manual selection may no longer work and the client may have switched to another member. For a quick walkthrough, see the subscription steps in Getting Started. The goal here is to make updates observable and reversible, not just to schedule them.

5. Proxy Modes and Connection Checks

What Rule, Global, and Direct Modes Change

Start with Rule mode for everyday use. Connections that reach the core are routed according to the rules, so some services can connect directly while selected requests use a proxy. Global mode usually sends ordinary connections that reach the core to the global policy, making it useful for a brief comparison. Direct mode helps test what happens without a proxy exit. These modes describe choices inside the core; they don't guarantee that every app's traffic has been captured.

A common misconception is that switching to Global mode sends all traffic from the entire device through a proxy. If an app doesn't read the system proxy settings, its connections may never reach the core, so changing modes won't affect them. Troubleshoot in order: check for a connection entry, check the matched policy, and only then decide whether the exit works. Traffic capture and routing mode are not the same setting.

Build a Short, Repeatable Test Path

Leave TUN off at first, enable the system proxy, select a node, and open a test website. At the same time, open the connections panel, filter by the destination domain, and check the policy and exit. A loaded page is only the first piece of evidence. The connection log confirms that the request reached the core; core logs can explain where it failed. If you use an IP-check site, make sure that request itself follows the expected route.

Command-line tools may not use the desktop system proxy. Specify the local proxy explicitly to compare paths. The command below assumes the client's mixed port is 7890; use the port shown in the interface when you run it. The target is a public example site, and not every destination will be equally reachable. One successful request shows that this path basically works, not that every protocol, app, and website is working.

curl --proxy http://127.0.0.1:7890 --head https://example.com
curl --socks5-hostname 127.0.0.1:7890 --head https://example.com

The second command sends the destination hostname to the SOCKS proxy for resolution, which helps compare it with a path where the local device resolves the domain first. If the results differ, check the client's DNS settings, node protocol, and logs; the difference alone doesn't prove a particular kind of leak. For a useful comparison, record the command, time, mode, and node, then repeat under the same conditions.

Latency Tests Don't Guarantee Download Performance

The test value shown by a client usually measures the round trip for a specific request, and its meaning depends on the test URL and implementation. A lower value doesn't guarantee faster downloads, smoother video or gaming, or better reliability on a particular site. A test can fail because its target is unreachable even when the node works elsewhere. Choose nodes based on your actual needs, connection success rate, and stability over time—not just their list order.

If one app fails while the browser works, check whether the app supports the system proxy, has its own proxy settings, or proxies only some traffic. Login flows may use system components or other processes, so the main window and login window can take different routes. Don't switch to Global and leave it there. Find the failing connection first, then decide whether to change the app settings, add a rule, or expand the traffic capture scope.

Existing long-lived connections may continue using the old path after you change nodes or modes. To test the new settings, reopen the destination or, if needed, close the relevant connection and start a new request. Don't clear unrelated sessions. Some apps also cache DNS results and connection pools, so they may need to be restarted. Treating an old connection as the result of a new setting can make a successful change look ineffective.

By the end of this stage, you should be able to reproduce a successful connection and explain its mode, entry point, and exit. For a more detailed first-connection checklist, see how to choose a node, test it, and verify where traffic goes. Get this shortest path working reliably before changing rules or enabling TUN, so you can identify the effect of each new setting.

6. Rule Order, Proxy Groups, and Split Routing

From the First Match to the Final Fallback

Rules are usually checked from top to bottom, and the first match determines where a connection goes. Both rule content and ordering matter. A broad domain-suffix rule near the top can prevent a more specific domain rule below it from ever being reached. Before adding a rule, find the existing match point instead of appending it blindly. Appending is especially likely to appear successful but do nothing when a catch-all action already sits at the end.

Domain rules define website or service boundaries, IP-range rules handle specific network ranges, and process rules depend on platform support, permissions, and detection capabilities. An app may contact multiple domains or use helper processes, so adding its main domain doesn't necessarily cover all of its requests. Check actual connections when maintaining rules instead of guessing which servers an app uses based on its name.

# Configuration snippet: merge into an existing profile; not a complete subscription
# Geographic labels such as mainland China or outside China are not evaluated in this example
rules:
  - DOMAIN,example.com,DIRECT
  - DOMAIN-SUFFIX,example.org,DIRECT
  - IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
  - MATCH,DIRECT

The example uses the built-in DIRECT action to illustrate rule ordering; it isn't a universal split-routing plan. An exact-domain rule matches only the specified name, while a suffix rule also covers the domain's subdomains. An option on an IP-range rule can prevent it from triggering DNS resolution just to match the address. The final fallback handles connections that didn't match earlier rules. To send traffic through a proxy, the target name must match a proxy group in your active configuration.

Check the Group Type Before Changing Its Members

A manual group is suited to a fixed selection, a URL-test group selects based on configured probes, and a fallback group prioritizes order and availability. The test URL, interval, and tolerance affect switching behavior. Don't assume that an automatic group always picks the best node for your actual workload. For apps that need stable sessions, consider whether a switch will interrupt or re-establish existing connections.

Proxy groups can reference one another, but names must match exactly and references should not form a cycle. A subscription update that renames a group can break local rules that still reference the old name. Before changing anything, map rule targets to group members and then to the final node, and confirm each path reaches a usable exit. In complex configurations, the hardest question is often not rule syntax but which of several similarly named groups is actually selected.

Verify Rule Matches in the Connection Log

Start with one clear destination when adding split routing. Record the matched rule and exit before making a change, then add a narrowly scoped rule in the right position and establish a new connection. If nothing changes, check in order that the right profile is active, the override was actually merged, the rule appears before broader entries, and the request isn't using an old connection. Only after checking all four should you consider whether the rule type itself is unsuitable.

DNS behavior can affect whether an IP or domain rule matches. If the core can't see the original domain, it can match only on the information it has. Conversely, fake-IP mapping can preserve the association between a domain and a connection, but it depends on a complete traffic capture path. Don't assume every unexpected match is caused by an outdated ruleset. Check whether the connection log shows a domain or an IP address before deciding whether to add a domain rule, an IP rule, or fix DNS.

Rule providers are useful for reusing sets of conditions that update over time, but check the behavior type, storage location, and how each set is referenced. A successful download doesn't mean a rule reference exists, and different file types aren't interchangeable. Before adding an external ruleset, understand where it comes from and what happens if updates fail; keep the last working copy. Avoid stacking large numbers of overlapping rules just to increase coverage—the more duplication there is, the harder it is to explain a match.

After maintaining rules for a while, remove exceptions that are no longer needed, especially forced DIRECT or forced proxy rules added for temporary tests. They can override future subscription rules and be hard to spot in the interface. A good ruleset isn't the longest one; it's one where you can quickly explain why a connection took a particular route and safely undo your last change.

7. TUN Mode and DNS

Enable TUN When You Need to Capture More Traffic

TUN receives system traffic through a virtual network interface, making it useful for apps that don't follow the system proxy. It doesn't provide a new remote exit or fix a broken node. Before enabling it, confirm that the subscription and node work with the system proxy, then save your current configuration. If problems appear after turning on TUN, you can focus on permissions, routes, DNS, and the virtual interface instead of questioning the entire connection path.

Desktop clients typically need service permissions or a network component, while mobile clients are managed through the system VPN interface. If you already use a corporate VPN, security tool, or other virtual network software, check whether it also changes the default route or DNS. Several tools can work individually but compete when used together. During testing, use only one traffic-capture tool if possible, and note any local network resources you need so you can check them one by one.

# mihomo configuration snippet; merge with working nodes, rules, and DNS settings
tun:
  enable: true
  stack: mixed
  auto-route: true
  auto-detect-interface: true
  dns-hijack:
    - any:53

This example shows common field relationships, but may not work in every client or on every system. Auto-route controls whether the core sets related routes; interface detection helps select the active network exit; stack options relate to system compatibility. A client may generate these fields through its interface. If direct file edits are overwritten, use the client's supported settings instead of maintaining two conflicting configurations.

DNS Is More Than a Toggle

DNS hijacking usually applies to traditional resolution requests that pass through the traffic-capture path. It doesn't mean every app's built-in encrypted DNS is captured. Browser Secure DNS, app-specific resolution, and internal company domains can all take different paths. Test public websites, local network names, and apps that depend on a specific DNS service separately. One public domain isn't enough to represent the entire network.

In fake-IP mode, the app receives a mapped address that the core associates with the original domain during the connection. This helps with domain-based routing, but depends on the mapping and connection following the same path. redir-host returns resolved addresses more directly, but has its own matching and caching behavior. Neither mode is universally better. If a local network service breaks, first check its domain and app requirements instead of switching DNS modes across the board.

The core's upstream DNS, DNS resolution for proxy servers, and resolution for direct connections may serve different purposes. A seemingly sensible encrypted upstream can create a startup dependency loop if it can only be reached through a proxy that isn't available yet. If a node server uses a domain name, make sure the path used to resolve it works too. For more on how these fields fit together, see a breakdown of nameserver, fallback, and fake-IP settings.

Check Each Area After Enabling TUN, and Roll Back if Needed

Test the browser first, then apps that normally ignore the system proxy, and finally local network services such as printers, network storage, and remote desktops. Check connection logs and route-related logs at each step. If local network access breaks, check whether the destination address belongs to a range that should bypass the proxy and whether it still resolves correctly. Don't disable the system firewall as a first response; that broadens the change and can hide the actual cause.

Switching from Wi-Fi to Ethernet, a hotspot, or waking from sleep can change the active interface and default route. If TUN worked before a network change but fails afterward, check interface detection and service status before reconnecting. Some environments may require recreating the virtual interface, but that doesn't mean you need to reinstall the client every time. Keep logs from before and after the change to distinguish interface, node reconnection, and DNS cache issues.

An IP-check site and DNS tests can help, but one webpage cannot prove that every app on a device follows the same route. Limit your conclusions to the apps and request types you actually tested. A good TUN setup captures the apps you need, preserves local network access, and recovers after network changes—not one where every advanced toggle is enabled just to make the configuration look complete.

8. Maintenance, Backups, and Troubleshooting

Save a Known-Good Baseline

Once the connection is stable, record the client name, core version, active profile, subscription source, traffic-capture method, and any local exceptions you need. Back up personal overrides and important proxy group selections, but don't share URLs containing access tokens. A screenshot of the main window is rarely enough to restore a setup; settings that affect operation may be in service options, DNS, or local extension files.

Store backups somewhere only you or authorized people can access. Before moving to another device, export the configuration supported by your client and check whether the export includes subscription credentials or local paths. Desktop paths may not work on mobile, and some interface preferences can't be restored across platforms. A successful migration means the new device can recreate the intended connection, not merely that the import completed without an error.

Update One Layer at a Time, with Time to Observe

The client, core, subscription, and rulesets are separate update layers. Don't change them all at once, or it will be hard to identify the cause of a problem. Update the subscription and verify it first, then update the client or core, and deal with personal rules last. Keep a rollback point after each change. Avoid major changes to permissions, network extensions, or routing just before important work.

Read capability changes in release notes in the context of your actual configuration. If a new protocol has nothing to do with your setup, there's no need to migrate immediately. If an old field changes behavior, test a copy first. A client update can also change merge order or default settings. After upgrading, check the final running configuration rather than just confirming that the same toggles still appear enabled.

Choose a Troubleshooting Path Based on the Scope

First ask whether the problem affects one destination, one app, or every connection. For a single website, check the service and the matching rule first. If all nodes fail, investigate the local entry point, DNS, and current network restrictions. If only one node is affected, focus on its connection errors. Scope isn't a final diagnosis, but it can substantially reduce guesswork and repeated changes.

Start reading logs around the time the error occurred. Find the first relevant failure, then check for downstream errors. A DNS failure can make every later connection time out; a local port bind failure can cause interface connection errors. Don't capture only the last line. If you temporarily increase log verbosity, restore the normal level after troubleshooting to avoid large log files, unnecessary storage use, and exposure of extra connection details.

Test Startup and Wake-from-Sleep Separately

Starting the client at boot, starting the core service, and automatically enabling the system proxy may be three separate options. After changing them, do a real reboot and check service status before and after login, including how subscription updates behave before the network is ready. The app appearing in the startup list doesn't prove that the proxy is working. Environments that require a password or user confirmation may also delay automatic connections.

Include waking from sleep and switching networks in maintenance checks. If only old sessions fail after resume, opening new connections may be enough. If no requests appear in the logs, check the traffic-capture entry point and service. If requests appear but DNS continues to fail, inspect DNS and the exit. Troubleshooting by layer preserves what's still working and avoids clearing useful evidence by rebooting the whole device every time.

If the client says it's connected but access still fails, repeat the shortest validation path in this guide and follow the relevant branch based on the result. If you can't explain a change, restore the last known-good state and reintroduce one change at a time. The goal isn't to memorize every error message; it's to keep consistent records so the next similar issue is quicker to diagnose and temporary fixes don't become long-term problems.

9. From a Working Setup to Maintainable Advanced Configuration

Learn to Read the Final Configuration First

The first step toward advanced setup isn't adding more fields; it's understanding how the active configuration is generated. Subscriptions, client defaults, interface toggles, and local overrides may all be merged together. Find the preview, export, or running configuration, then check the listener port, mode, DNS, proxy groups, and rule order. If the file doesn't match the interface, understand the precedence before deciding which layer to change.

Create a configuration copy for experiments and keep your daily setup as a baseline. Change one thing per experiment and write down the expected result and how you'll verify it. For example, when adding a ruleset, first check that it updates, then that the rules are referenced, and finally that a test connection matches them. If the experiment fails, you'll know which step broke instead of concluding that everything is unusable.

Expand Features in Dependency Order

You can start with rulesets, then learn about proxy providers, followed by DNS routing and more complex proxy groups. Rulesets reuse conditions; proxy providers manage where nodes come from. They're not the same thing. Before using either, check the content format, behavior type, update location, and reference method. A source downloading successfully doesn't mean its contents are automatically added to existing rules or groups; the references must be configured.

Understand scheduled updates, health checks, and automatic policy selection as parts of the same dependency chain. Updating the node list can change its members, health checks report availability, and a proxy group selects a member based on its type. If one layer fails to update, the interface may still show old results. When automatic selection behaves unexpectedly, first check whether the members are current and probes are succeeding, then inspect the selection logic instead of simply shortening the test interval.

Protocol support requires all three: a compatible core, client configuration support, and correct server parameters. A protocol appearing in the documentation doesn't prove that your installed core can use it. When migrating an older profile, see how mihomo differs from the original Clash core. Check fields and protocols directly instead of assuming compatibility based on the app's name.

Manage Terminal and Service Environments Separately

Terminal environment variables usually affect only the current session and its child processes; they don't automatically configure every desktop app to use a proxy. Tools also vary in their support for these variables. For a quick test, use the command's own proxy option when possible; use environment variables when you actually need a session-wide setting. Don't write a local address into several startup files and forget where it came from, or the terminal may keep pointing to a dead port after the client exits.

# POSIX shell: set for the current session and its child processes only
# Use the port the client is actually listening on
export http_proxy="http://127.0.0.1:7890"
export https_proxy="http://127.0.0.1:7890"

# Clear these example settings after testing
unset http_proxy https_proxy

Processes launched by a service manager usually don't inherit all environment variables from an interactive terminal. For a server deployment, specify the configuration path, working directory, run-as user, and log location before setting up startup. A command working in a terminal doesn't mean the system service is configured correctly. If you use a client API or control panel, restrict its listening scope and configure access controls so the management interface isn't exposed to networks that don't need it.

Use an Acceptance Checklist, Not More Complexity

An advanced setup should pass at least these checks: ordinary websites load, apps that need a proxy show connection entries, local network services remain reachable, updates don't overwrite personal rules, the connection recovers after network changes, and closing the client restores the expected system network state. These outcomes don't depend on a particular interface. If a new feature breaks one of them, fix the boundaries before adding more capabilities.

A gateway, router, or shared connection expands the impact beyond one device. You'll also need to understand gateways, forwarding, firewalls, and return routes; a desktop TUN example can't simply be copied over. Test on a separate device or isolated network first, and keep a way to restore the original gateway and DNS. If the setup is beyond your current experience, sticking with a stable single-device configuration is responsible risk management, not a lack of features.

To repeat the main setup steps, return to Getting Started. To switch devices or clients, choose a platform in the download center. For specific configuration questions, browse the topic-based technical notes. The value of this reference isn't reading every field in one sitting; it's knowing the goal, conditions, evidence, and rollback path before each change.