Complete Clash Guide

Stage 01 / Core Concepts

Clash Basics: Clients, Kernels, and Traffic Flow

Understand the difference between the interface and the traffic engine

In the Clash ecosystem, a client usually means an app with a window, tray menu, and configuration management. The kernel reads configuration, establishes proxy connections, matches rules, and handles DNS. mihomo is an actively developed kernel in this ecosystem. A toggle in the interface does not represent every kernel capability, and different clients may use different labels for the same kernel feature. If a tutorial screenshot does not match your app, look for what the setting does rather than its exact location.

Break the connection into steps: an app makes a request; system or app settings determine whether it goes through the local proxy; the kernel selects a route based on its current mode; and the proxy policy determines the actual egress. A subscription provides configuration or node information, but does not replace any of these steps. A successful import only means the client accepted the configuration. An enabled proxy only means the entry point is set. A loaded webpage shows that the relevant path is working. These are different states and should not be treated as interchangeable.

Know the difference between nodes, proxy groups, and rules

A node contains a server address, protocol, and authentication parameters—it describes how to connect to a remote service. A proxy group combines nodes or other groups and can offer manual selection, health checks, or failover. Rules determine which policy handles a connection. Selecting a node in a manual group does not mean every connection will use it; only traffic routed to that group is affected. When troubleshooting, check both the matched rule and the final egress.

A complete configuration typically includes local listening ports, proxy nodes, proxy groups, rules, and DNS settings. A node list may contain only server details. Both can be retrieved through a link, but they are not interchangeable. A client that can parse a particular node list will not necessarily create the routing rules you need. Before choosing an import format, check whether the provider supplies a complete Clash configuration or just a list of nodes that needs further setup.

Distinguish the local proxy from the remote server

The local mixed port is the entry point between apps and the kernel—not the remote server's port. A common example is mixed-port: 7890, but the actual value depends on your configuration and client settings. Do not overwrite an active port just because a tutorial uses this number. Remote services also depend on account status, protocol support, and network reachability. A running local app does not prove the remote service is working.

System proxy settings primarily affect apps that honor them. TUN uses a virtual network interface to capture traffic that matches its routing conditions. Neither replaces rule-based routing; they are different ways for traffic to enter the kernel. Think of entry and routing as two separate dimensions: first check whether the request reaches the kernel, then check where it goes. This order helps distinguish an entry-point problem from a rule issue and avoids unnecessary DNS changes.

Before you begin, note your operating system, client, configuration source, and the access behavior you want to change. For example, “proxy the browser while keeping LAN devices on a direct connection” is easier to verify than “turn everything on.” Proxy software is not an anonymity tool: remote services, destination sites, and local apps may all process relevant data. Use configurations from trusted sources and follow local laws and network policies. Do not expose a network entry point to devices that do not need it.

Stage 02 / Choose Your Tools

Choose a Clash Client: Start with Your Platform and Configuration Needs

Start with how you use your device

For a fresh install, start with Clash Plus and choose your platform from the download page. Check system architecture, supported OS versions, subscription formats, and required permissions—not just the app name. Desktop clients are well suited to managing configurations and inspecting connections; mobile clients rely more heavily on system network extensions or VPN interfaces. For a server or router that needs to run continuously, consider deploying the kernel directly, but plan to manage the service and configuration yourself.

Windows users can compare Clash Plus, Clash Verge Rev, FlClash, and Clash Nyanpasu. Clash for Windows is an archived option that is no longer maintained. If you need a Clash for Windows replacement, save your subscription sources and custom rules first, then check whether the new client supports them. Old app directories and UI settings usually cannot be copied over as-is. Focus on migrating configuration—not copying every application file.

On macOS, consider Clash Plus, Clash Verge Rev, or FlClash. ClashX Meta is an archived option that is no longer maintained. Choose the right installer for Apple Silicon or Intel; check your chip in System Information first. When switching clients, make sure the old app is no longer set to launch at login, so two tray apps do not keep changing system proxy settings. Keeping one app in charge of the proxy makes settings consistent and makes it easier to confirm that they are restored when the app quits.

Know what differs on mobile and Linux

On Android, consider Clash Plus, Clash Meta for Android, FlClash, or Surfboard. Note that Surfboard uses a different configuration format from Clash YAML, so not every subscription link will work as a universal import. Check the provider's format documentation before choosing an app. The VPN icon in Android's status bar generally means the local network interface is active; it does not prove traffic is reaching the intended proxy egress. Check the results in the apps you use as well.

On iOS, check the Clash Plus App Store listing first, and visit the official site at clashplus.io for product information. Network extensions, background lifecycle, and app sandboxing affect where configurations are stored, so desktop service installation steps do not apply. For a Linux desktop, start with Clash Verge Rev or consider FlClash. Choose a package for your distribution, and distinguish desktop proxy settings from routing traffic across the entire system.

Choose based on the features you actually need

If your configuration uses newer protocols, rule providers, or DNS parameters, make sure the client's bundled kernel can parse those fields. Seeing “Clash” in an app's name does not guarantee support for every syntax extension. If an import fails with an unsupported-field error, check the kernel documentation and configuration format before removing anything. Deleting a setting may get the file to parse, but could also change security settings or routing behavior.

For most new users, clear import steps, readable errors, and reliable system proxy restoration matter more than the number of toggles. If you need to troubleshoot app routing, connection details, matched rules, and process identification matter more. For laptops and phones, test sleep and wake, network changes, and background behavior too. List your actual needs, then install one candidate and verify it. You do not need to install every client just to compare interfaces.

After choosing a client, keep the installer that currently works and export your custom settings. Note how subscriptions are updated. When migrating, first make sure the new client can parse the configuration; then disable the old client's traffic entry point and enable the new one. This handoff helps avoid losing connectivity and prevents port conflicts from looking like a broken app. Check the download page for current package options, platform links, and maintenance status rather than relying on old screenshots.

Stage 03 / Set Up the Runtime

Installation and Permissions: Check Kernel Startup and Port Ownership

Get a basic setup running before granting advanced permissions

Download the installer that matches your system architecture, close any similar clients that are still running, and follow the system prompts. On first launch, leave TUN, LAN access, and auto-start turned off. First confirm that the interface opens, the kernel runs, and you can access the configuration page. Treat installation, configuration parsing, and system traffic capture as separate steps. If something fails, you will know which layer changed instead of troubleshooting several newly enabled options at once.

On Windows, the GUI and background service may run separately. TUN and some system-level operations require the client's service mode or administrator approval, but that does not mean the GUI should always run with elevated privileges. If service installation fails, check the app logs and system prompts to see whether security software blocked the operation. Do not download repair scripts from unknown sources or disable all system protections just to get the install to work.

On macOS, move the app to a suitable location for regular use before launching it, then follow system prompts for app verification and network permissions. System proxy settings need access to network service settings; TUN may require additional permissions depending on the client. If the app will not launch, check its source, chip architecture, and OS compatibility rather than copying online commands to bypass permissions. The relevant permission settings may vary by macOS version.

Check mobile permissions and Linux services

On Android, the first connection usually asks for permission to set up a VPN connection. Verify that the request came from the client you are using before approving it. Another app using Android's VPN interface may not be able to run at the same time, so decide which one should manage network traffic. iOS also requires approval for network configuration. After granting permission, check the client's status; the system prompt alone does not mean the subscription or egress is ready.

A Linux GUI opening successfully does not mean it can change desktop proxy settings or create a virtual interface. Follow the client documentation for service permissions; avoid granting broad write access to the entire installation directory. For a kernel deployment, define the service account, configuration directory, working directory, and log ownership. Do not use the download folder as a permanent working directory: cleaning up downloads could also delete active rules or configuration files.

Check the mixed port instead of changing numbers at random

If startup logs report that an address is already in use, find out which process owns it. It could be an old client that did not exit, another instance of the same app, or an unrelated service. Keep only the instance you need or choose an available port for the current client. If you change the port, update browser extensions, command-line environment variables, and manual proxy settings too. Changing the kernel alone leaves apps pointing to the old entry point.

# Windows PowerShell: inspect listeners on the example port
Get-NetTCPConnection -LocalPort 7890 -State Listen

# Linux: inspect listeners on the example port
ss -ltnp 'sport = :7890'

# macOS: inspect listeners on the example port
lsof -nP -iTCP:7890 -sTCP:LISTEN

These commands can help inspect local listeners, but some process details may require additional permissions. If you see a listener, use the process name and client logs to identify it; do not terminate an unfamiliar system process. No listener does not necessarily mean the installation is broken: the kernel may be waiting for a valid configuration, or it may be using a different port. Check the settings page and current value in the logs before changing the setup.

Finally, test whether settings are restored when the client exits. At a time when a brief interruption is acceptable, quit the app and check whether the system proxy is cleared, then reopen the client. If the browser cannot connect after the app exits while system settings still point to a local proxy port, the entry point was not restored. First clear the stale proxy in system network settings, then investigate the client's exit behavior. Test this before relying on the setup so you do not mistake a later shutdown issue for a network failure.

Stage 04 / Prepare a Working Configuration

Subscriptions and Configuration: Import, Enable, and Preserve Local Changes

Check the input format before importing

Open the client's configuration or subscription page, choose import from URL, and paste the complete link from a trusted source. Before downloading, check for leading or trailing spaces, line breaks, and punctuation added by a chat app. Subscription URLs may contain account credentials. Never post one in a public forum or paste it into an untrusted online converter. Hide the full URL in screenshots—especially sensitive parameters after the domain.

To import a local file, choose a valid YAML configuration and make sure it is not a saved web page or a file with an extra extension added by the OS. Complete configurations, Base64 node lists, and individual share links have different structures; acceptance depends on the importer's capabilities. To learn how they differ, read Subscription URLs, Local YAML, and Base64 Formats. Do not try to force compatibility by repeatedly changing the file extension.

After downloading, select and enable the configuration in the list. Some clients let you save multiple subscriptions, but the kernel loads only the selected configuration or a merged result. Check the selected marker, then confirm that the expected proxy groups appear on the proxy page. A visible configuration name only means the entry exists. If the kernel reports a parse error, check the logs for a bad field, indentation, or referenced name.

Understand YAML structure and proxy references

YAML uses spaces for indentation; do not mix them arbitrarily with tabs. List items typically start with a hyphen, and field names and values need the correct syntax. Text containing special characters can be quoted, but quotes must be properly paired. When troubleshooting, start with the location in the log and the surrounding lines: the cause is often a missing character on the preceding line. Do not post your entire configuration publicly; node passwords and credentials can be buried deep in the file.

# Minimal direct-connection example: illustrates structure, with no remote proxy nodes
mixed-port: 7890
allow-lan: false
mode: rule
log-level: info

proxy-groups:
  - name: Manual selection
    type: select
    proxies:
      - DIRECT

rules:
  - MATCH,Manual selection

This example illustrates the structure, but all connections go direct. Do not use it in place of a subscription intended to reach remote services. A rule's policy name must exist in the configuration and match exactly, including capitalization. For everyday changes, use the client's override, merge, or extension feature; the name varies by app. Direct edits to a downloaded configuration may be overwritten on the next subscription refresh, making settings seem to disappear.

Schedule refreshes and handle failure cases

Automatic update intervals are a maintenance setting, not a connection speed control. Some interfaces use minutes; others use seconds, so check the unit first. For example, if the interface specifies minutes, 1440 means one day. Do not copy that value into a provider field that expects seconds. Avoid repeatedly polling the server at very short intervals: frequent refreshes will not fix an incompatible format and may trigger provider rate limits.

When an update fails, distinguish a network timeout, expired credentials, an HTML page, and a configuration parse error. A timeout calls for checking the network path; expired credentials mean checking the account and subscription URL; an HTML response may be a login or error page; a parse error calls for checking the format and kernel support. “Update through proxy” only helps if the current proxy works. If the configuration is already broken, you may need to switch temporarily to direct access or use another update method supported by the provider.

After each successful update, make sure the configuration is still enabled and that proxy group selections behave as expected. Keep a private copy of a working configuration for rollback and back up custom rules separately. For more detailed troubleshooting, see Subscription Update Errors and Auto-Update Intervals. Restoring a working connection before investigating the cause preserves more clues than repeatedly deleting and recreating the subscription.

Stage 05 / Verify the Traffic Entry Point

Proxy Modes: Distinguish System Proxy, Rule, and Global Modes

First decide how requests enter the kernel

After importing a configuration, select a working policy, enable the system proxy, and make a new request in a regular browser. Open the connection list and look for the destination domain and handling policy. If the page fails and there is no connection record, check the system proxy and the browser's own proxy settings before changing rules. Browser extensions, app-specific proxy settings, and system settings can override one another. Identify which entry point the request actually uses.

System proxy settings usually direct apps that support them to a local address and port, but they do not guarantee that every program will follow. Command-line tools, games, background services, and some store apps may use their own network stack. UWP apps on Windows may also be affected by loopback access restrictions; not every related error is caused by a subscription. Check the client's loopback settings or system documentation if needed, and adjust only the apps that require it rather than granting broad access to everything.

Choose rule, global, or direct mode based on your needs

Rule mode routes connections based on configuration conditions and is suited to everyday split tunneling. Global mode generally sends connections that reach the kernel through the global policy. Direct mode sends those connections straight to their destinations. “Global” does not mean all system traffic is captured: requests that never reach the kernel will not be rerouted just because global mode is selected. Verify the entry point before choosing a mode—this is one of the guide's most important troubleshooting steps.

Global mode is useful for short comparison tests. If a destination fails in rule mode but works in global mode, check the rule or its associated policy. Other differences, such as DNS or connection reuse through a different egress, may also be involved, so do not assume one rule is the sole cause. Restore the original mode after testing, then close existing connections or restart the relevant app so new requests use the updated settings.

Set up a comparison with an explicit proxy

If the local mixed port is actually 7890, you can explicitly specify the proxy with the command below. It uses a public test site to check whether a connection can be established. On Windows PowerShell, curl.exe avoids differences caused by command aliases with the same name. If your port is different, replace the value with the one in use. A successful command only proves that this request path works; it does not prove that every app or destination is working.

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

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

If the explicit proxy works but the browser fails, check browser extensions, app-specific proxy settings, and cached connections. If both fail and the logs show a request, check the selected policy, node availability, and destination access restrictions. If there is no request in the logs, recheck the port, kernel status, and whether the request actually ran. Do not rely on a browser's generic error page: the same message can result from a resolution failure, a refused connection, or a remote disconnect.

Command-line environment variables may also preserve an old proxy entry point. During troubleshooting, check whether the current terminal has HTTP_PROXY, HTTPS_PROXY, or ALL_PROXY set, and whether the app honors these variables. Changes usually affect newly started processes; running apps may retain old values. Do not change every session globally just to proxy one terminal. Test in a single terminal first, then decide whether to make the change persistent.

By the end of this chapter, you should be able to identify which apps use the system proxy, which need an explicit setting, and what the current mode affects. If you still see “connected, but webpages won't load,” follow the System Proxy, Port Conflicts, and Routing Troubleshooting Checklist. Change one variable at a time and record the results so you can compare them; switching modes, nodes, and DNS all at once makes diagnosis harder.

Stage 06 / Control Traffic Flow

Rule-Based Routing: Match Rules in Order and Verify the Result

Understand rule order before adding conditions

Rules are typically checked from top to bottom. The first matching rule determines the handling policy, and a final fallback rule catches everything else. A “more specific” condition does not automatically take priority—position matters too. A broad condition near the top may prevent more specific rules below it from ever matching. Before editing, define the goal: which domains should go direct, which should use a proxy group, and what should happen when nothing else matches.

Domain rules and IP rules match different things. DOMAIN matches an exact domain, DOMAIN-SUFFIX matches a domain suffix, IP-CIDR matches an address range, and GEOIP relies on a geolocation database. A suffix rule is not an arbitrary substring match, nor does it automatically cover every separate host used by a website. A page may request different hosts for login, images, and APIs. Use actual connection records to identify what else needs a rule.

Start with the smallest rule set you can understand

The snippet below demonstrates a common rule order. Add it to an existing complete configuration, and make sure PROXY is a defined policy or proxy group. The example sends a domain suffix through a proxy, keeps private address ranges direct, applies a direct rule to mainland China IPs, and sends remaining traffic to the proxy as a fallback. This is a learning example, not a configuration for every network. Adapt it to your LAN routing and provider's recommendations.

rules:
  - DOMAIN-SUFFIX,github.com,PROXY
  - IP-CIDR,10.0.0.0/8,DIRECT,no-resolve
  - IP-CIDR,172.16.0.0/12,DIRECT,no-resolve
  - IP-CIDR,192.168.0.0/16,DIRECT,no-resolve
  - GEOIP,CN,DIRECT
  - MATCH,PROXY

no-resolve prevents an active DNS lookup solely to match that IP rule. It does not disable DNS for the entire configuration or mean the destination can never have an IP address. If a connection already has a usable address, IP matching may still occur. Whether to use it depends on how you want domain requests handled and the cost of resolution. Geolocation rules also require a usable data source; missing or outdated databases can produce unexpected results.

Preserve LAN access and service discovery

Router admin pages, printers, file servers, and corporate intranets often need direct access, but a few private address ranges may not cover everything. An internal network can use special domains, split DNS, or other address ranges, and cross-subnet access depends on routing. If an intranet domain fails, check name resolution and destination reachability separately. Do not send an entire top-level domain direct without checking; that could reroute unrelated services too.

Rule providers help manage large rule sets, but distinguish the rule behavior type from the file format. Domain lists, address lists, and classic rule lists have different syntax, and the referenced type must match the contents. Before using one, verify that the source is trusted, updates are reasonable, and local data remains available if a download fails. Do not layer on a large rule set you do not understand: duplicate conditions, overly broad ranges, and update overrides make results harder to explain.

Verify the result in connection details, not just in the config

After each rule change, confirm that the configuration has reloaded. Start a new connection to the destination and inspect its domain, target address, matched rule, and final policy in the connection details. Some apps reuse long-lived connections, which do not immediately switch egress when rule text changes. If needed, close only the relevant connection or restart the test app. There is no need to reset all system network settings. Verify with a new request, not content already loaded from cache.

If traffic still does not follow the expected route, check whether the request includes domain information, then verify rule order, policy names, and whether a subscription update overwrote the configuration. Process-based rules also depend on platform support and process identification, so do not blindly sync them across devices. Keep new rules narrowly scoped and note their purpose. Removing temporary rules once they are no longer justified is easier to maintain than piling on exceptions.

Stage 07 / Extend Traffic Capture

TUN and DNS: Capture Traffic First, Then Check Resolution

Use TUN only when you need it

Consider TUN when you need apps that ignore system proxy settings to reach the kernel. It uses a virtual network interface and routing settings to capture more traffic, but coverage still depends on system permissions, routes, protocol support, and client implementation. TUN is not a universal fix for network problems. Enable it only after the system proxy path works, so you have a clear comparison and can quickly revert if something breaks.

Before enabling TUN, note any VPNs, containers, virtual machines, and corporate networking tools in use. They may also modify routes or DNS. If you run them together, identify which one controls the default route and which handles LAN access. If you lose intranet access or remote connections loop after enabling TUN, turn it off to restore the baseline, then investigate route conflicts. Do not change adapter priority, firewall settings, and DNS services all at once—you will not know which change affected the result.

Understand common TUN options

auto-route lets the kernel configure the relevant routes automatically; auto-detect-interface helps select the egress interface; and dns-hijack captures eligible DNS requests. These options are not guaranteed to work independently of platform conditions. When a laptop switches from wired to wireless, interface detection and routing may need to be re-established. Reconnect or restart the kernel as the client requires instead of repeatedly reimporting the subscription.

# Merge into a mihomo configuration that supports these options
# Requires appropriate system permissions; keep a copy of the original configuration before enabling
tun:
  enable: true
  stack: mixed
  auto-route: true
  auto-detect-interface: true
  dns-hijack:
    - any:53

dns:
  enable: true
  enhanced-mode: fake-ip
  fake-ip-range: 198.18.0.1/16
  nameserver:
    - https://dns.alidns.com/dns-query

This snippet is not a complete subscription, and you should not bypass the client's own TUN management by pasting it directly. The configured resolver must be reachable on the current network, and the kernel must be able to resolve that service's domain initially. The example's fake IP pool is for internal mapping, not a remote proxy server address. If it conflicts with your environment, read the relevant configuration documentation before changing the range or filters.

Distinguish DNS failures from connection failures

DNS maps domain names to destinations; changing resolvers alone will not fix node authentication or port conflicts. In fake-IP mode, requests receive mapped addresses so the kernel can preserve the domain association. Redir-host typically returns the resolved address. The two modes differ in compatibility and processing paths; there is no setting that works best for every device. Some LAN apps, specialized detection tools, or direct-connect services may need exceptions.

nameserver, fallback, and related filters each have their own roles. A fallback resolver does not simply mean “query this only if the main server is down.” The final result depends on selection and filtering rules, so understand the current kernel's behavior before configuring it. Do not pile up resolver addresses assuming more means greater reliability. For a field-by-field explanation, read mihomo DNS Configuration and fake-ip Explained, then limit changes to a clearly identified problem.

Encrypted DNS in a browser or app may bypass the usual port 53 request path, so DNS hijacking does not control every lookup. When troubleshooting, note whether the app has its own resolver enabled and compare it with the system DNS path. Do not leave app security features disabled just to inspect logs. Compare behavior in a controlled test, then decide whether to use a consistent resolver or keep the app's own policy.

Verify in three steps: first, check whether regular webpages load; next, see whether an app that previously ignored the system proxy appears in the connection list; finally, test LAN access and wake from sleep. On mobile, check background behavior and battery impact too. For the trade-offs, see Mobile Background Operation and Persistent TUN. If problems occur only with TUN enabled, return to the verified entry point and continue troubleshooting with route and log evidence.

Stage 08 / Keep Your Setup Recoverable

Maintenance: Backups, Updates, and a Troubleshooting Workflow

Keep a rollback point for every working setup

Track four separate components: the app, kernel, subscription, and local overrides. App updates may change the interface or system integration; kernel updates can change supported fields or defaults; subscription refreshes replace remote content; and local overrides preserve your routing preferences. Record each separately and avoid updating everything at once. When something breaks, knowing which component changed last is often more useful than an unorganized block of logs.

A backup should include more than the subscription URL. Record the current proxy group selections, custom rules, DNS exceptions, mixed port, and client system integration settings. Some export features omit system services, login items, or local rule files, so check the app documentation for anything else you need. Backups may contain credentials; store them securely, do not share them publicly, and avoid using public cloud links for ongoing configuration distribution.

Make each update a change you can verify

Save your current configuration before updating, and choose a time when a brief loss of connectivity is acceptable. After the update, check that the kernel starts, the configuration loads, a regular browser works, key apps connect, and LAN services remain available. Then decide whether to remove old files. If a field was deprecated or parsing behavior changed, read the release notes and locate the affected configuration section. Do not enable every new option just because it is available; a stable baseline is more useful than a long feature list.

Verify the order of operations at startup too. An app launching at login does not mean the network is ready. A subscription or rule provider failing to refresh while offline does not necessarily mean the configuration is broken. Check whether it updates after connectivity returns, and use the client's delayed start or retry options if available. If things fail after a laptop wakes from sleep, compare the egress interface, system proxy, and kernel status before deleting subscriptions.

Troubleshoot in order: entry point, kernel, egress, destination

First check the entry point: is the kernel running, is the port listening, and is the app actually using that entry? Second, check the configuration: which file is active, are there parsing errors, and do proxy group references resolve? Third, check egress: is the remote service reachable through the selected policy, or is there an authentication or protocol error? Finally, check the destination: do other sites and apps work, and is the issue limited to a specific domain or network?

Collect logs for one reproducible failure. Note the time and actions, make the request, and keep the relevant lines before and after it. Temporarily increasing the log level can help, but detailed logs may increase disk writes and include visited domains. Restore a suitable everyday log level when finished. Before sharing, hide subscription URLs, credentials, and domains you do not want public. Do not share only the final generic error line and omit the cause above it.

Handle network changes and leftover settings

Switching from home to work may change DNS, captive portal requirements, and access restrictions. Complete the network's own sign-in first. If needed, temporarily disable the proxy entry point and verify direct access before restoring your configuration. Corporate networks may explicitly prohibit proxies or VPNs; follow their policies rather than trying to evade them by changing ports or hiding processes. Client testing is meaningful only when the network path you are using is permitted.

If connectivity fails after quitting the client, first check for stale system proxy settings. If it fails after a system restart, also check auto-start apps and persistent environment variables. Keep a clear recovery action ready, such as disabling the system proxy or turning off TUN, instead of immediately resetting every network component. For general questions, see the FAQ. When reporting an issue, include your OS, client, entry point, steps to reproduce, and tests already performed—there is no need to publish your full configuration.

Stage 09 / Expand One Step at a Time

Advanced Topics: Providers, Automatic Policies, and Deployment Limits

Understand the configuration layers before adding automation

A stable setup does not need more features just for the sake of it. Build advanced knowledge around specific needs: learn proxy providers when you have many nodes, rule providers when rules change often, and service management when remote devices need to stay online. Keep a minimal working configuration and a separate test for each step. Avoid copying a configuration full of unknown fields and then relying on random toggles to explain its behavior.

Proxy providers separate node sources from the main configuration, making them easier to update and reuse. Make sure you understand the source format, storage path, update interval, and which proxy group references the provider. A successful provider download does not mean its nodes are being used; a group must reference them by name. Health checks also need a reachable test target, and only tell you about that test path. A successful test does not guarantee that every real request will work, or indicate actual browsing speed.

Understand what automatic selection measures

Manual groups are easiest to observe. URL-test, fallback, and load-balance groups each serve different purposes: automatic selection relies on test conditions, failover on availability checks, and load balancing on how connections are distributed. Do not stack groups just because their names sound useful. First check whether your apps need a stable egress, as with services that maintain sessions. Then decide whether automatic switching might cause extra sign-ins or dropped connections.

Test interval, timeout, and tolerance all affect automatic policies. Very short intervals may increase network requests and drain mobile batteries; long intervals may delay detection of a route change. If a test URL is unreachable on the current network, results for the whole group will be misleading. Confirm basic connectivity with manual selection first, then enable automatic checks. If problems appear, compare the test target with the actual service instead of blaming every failure on node quality.

Treat command-line kernel deployment as a separate project

Deploying to a server or router requires additional work: managing the service account, startup behavior, configuration permissions, log rotation, and traffic forwarding. Desktop system proxy experience is not a substitute. Running the kernel only provides the features enabled in its configuration; it does not automatically turn the entire LAN into a proxy network. Transparent proxy or gateway setups also involve the default gateway, forwarding, firewall, and return routes. Design them for the device topology rather than experimenting on a production network.

# Check configuration syntax in an environment with mihomo installed
mihomo -t -f ./config.yaml

# Run with a specified working directory; prepare the required resources there according to the configuration
mihomo -d ./profile

Passing a syntax check only shows that the kernel accepts the configuration. It does not prove that remote services, DNS, or rule downloads will work in the runtime environment. Use the same kernel and working directory as production where possible, and check relative file paths. A service may have different environment variables, permissions, and working directory from an interactive terminal. If manual execution works but the service fails, compare those environment differences first.

Control the management API and LAN exposure

A management API can power dashboards and automation, but it can also change proxy behavior. Enable it only when needed, bind it to the local loopback address where possible, and configure authentication if the kernel supports it. The mixed proxy port, management API, and DNS listener are separate entry points. A need for LAN access on one does not mean you should bind the others to every interface. Restrict allowed sources with the host firewall before exposing any service.

Before letting other devices use the proxy, verify the listening address, LAN access setting, authentication, and firewall rules individually. Do not assume every device on a shared network is trusted, and never forward the port directly to the public internet. Persistent router deployments also need a plan for reboots, storage limits, and failed rule resource updates. Test in an isolated environment before making the setup a permanent network gateway; one configuration error could affect the whole network.

A practical learning order is: understand the current configuration, edit rules independently, learn DNS and TUN, then move on to providers and service deployment. At each step, answer three questions: what problem does this solve, how can you verify it works, and how can you undo it? Return to Getting Started to review the basics, or visit the client download page to choose another app. Being able to explain a connection's entry point, matched rule, and final egress is the key to moving from “it works” to a setup you can maintain.