Clash Setup Guide for All Platforms
Installation & Configuration

Before You Start: Choose a Platform, Config, and Routing Mode

Know the Difference Between the Client, Core, and Subscription

The client provides the configuration list, proxy controls, and logs. The core parses configuration, matches rules, and establishes connections. A subscription is how a service provider supplies configuration or proxy-node details. Installing a client does not give you usable nodes. Before you begin, get a subscription URL you are authorized to use or a local config file, and confirm it works with your chosen client. Do not mistake an account login or payment page, or a dashboard URL copied from your browser, for a subscription link.

mihomo is a proxy core, not a specific graphical client. Clients built around it may differ in how they merge configuration, manage permissions, and handle updates. This guide recommends Clash Plus for Windows, macOS, Android, and iOS; for Linux desktops, start with Clash Verge Rev. Choose a client for your platform, then check the config format to avoid mixing formats just because product names look similar.

Check Your OS and Processor Architecture

On Windows, check Settings → System → About for the system type. On a Mac, open About This Mac to see the chip or processor. On Android, check your device information and the architecture notes on the download page. On Linux, run uname -m to check the architecture: x86_64 is typically AMD64, and aarch64 is ARM64. An architecture mismatch can prevent an app from starting; reinstalling the config repeatedly will not fix it.

Also check the installer's minimum OS requirements, available disk space, and account permissions. Graphical clients, helper services, and cores may each have different compatibility requirements; prefer the download page and project documentation over general assumptions. On a managed device, confirm that you are allowed to change proxy settings, install services, or create virtual network adapters. Do not remove system profiles to bypass management policies or disable security software from unknown sources.

Subscriptions and Local YAML Files

A subscription URL is an address the client requests periodically. YAML is a common structured text format that uses indentation to show field hierarchy. Base64 is a text encoding, not a complete Clash config by itself. Some URLs return a full YAML config; others return only a list of nodes. If an import fails, check the format before switching cores. For details, see Subscription URLs and Import Formats.

Subscription URLs often contain access credentials, so treat them like passwords. Copy the full URL, including all query parameters, without adding quotes, spaces, or line breaks. When asking for help, redact sensitive path segments and parameters; check screenshots for QR codes, node passwords, and control API details too. Do not paste a real URL into an unfamiliar converter site. If conversion is necessary, first find out what configuration data the service can access.

Start with a System Proxy; Consider TUN if Needed

A system proxy directs requests from apps that honor the OS proxy settings to a local listening port. It is a good first step for testing browser traffic. TUN uses a virtual network interface to route more traffic at the network layer, but routing rules, app scope, and firewall settings still apply; it does not automatically proxy everything. TUN usually requires additional permissions and is more likely to conflict with another VPN or virtual network adapter.

Before you begin, quit other proxy tools, note the current proxy and DNS settings, then establish the simplest working connection. Do not change rules, nodes, DNS, and routing mode all at once; otherwise, it's hard to identify the cause of a problem. The snippets below describe local listening settings only. Add them to an existing working config; they include no remote nodes and cannot provide a proxy connection on their own.

mixed-port: 7890
allow-lan: false
bind-address: "127.0.0.1"
mode: rule
log-level: info

Windows: Install a Client and Check the Local Proxy

Download and Launch the Client for the First Time

Open the Windows client downloads and start with Clash Plus. Other options include Clash Verge Rev, FlClash, Clash Nyanpasu, and the discontinued Clash for Windows. For a new setup, avoid archived clients: older interfaces, core capabilities, and newer config fields may not line up. If migrating, keep a copy of the old config and don't remove a working setup before the new one is ready.

Choose the installer for your system type, install it locally, then launch it from the Start menu. If Windows warns you about security, verify the download source, publisher, and package before proceeding; do not disable your security protections wholesale. Start with standard permissions. Elevate through the system prompt only when an operation, such as installing a helper service or configuring a virtual adapter, requires it. If a work device blocks the install, contact your administrator.

Import a Subscription and Select It

In the client's Config or Subscription page, choose import from URL, paste the full address, and save. After a successful import, check that a new entry appears in the config list and select it as the active config. A saved subscription isn't necessarily in use: some clients store multiple configs, but only the selected one is loaded at startup. Then open the proxy groups page and confirm that the groups defined in the config appear.

To import a local YAML file, use the file import option and keep the original as a backup. Make sure the filename doesn't have an extra extension added by a text editor, and use spaces rather than tabs for indentation. Subscription updates may overwrite manual edits; keep local rules in the client's supported override or merge section. After each update, check the error log before deciding whether to restore the previous config.

Turn On the System Proxy and Test in Stages

Make sure the core is running before enabling the system proxy in the client. Open Windows Settings → Network & Internet → Proxy and check the local address and port set by the client. Use the port shown in the client now; don't copy 7890 just because a guide uses it. If another program has taken the port, close the conflicting app or change the listening port, then update any apps where you configured a proxy manually.

First visit a site that normally works without a proxy, then visit a destination that needs one, and watch the client's connection log. The first test checks your basic network; the second checks your rules and proxy exit. Browser access does not mean PowerShell, the Microsoft Store, or other apps are routed too. You can use this one-off request in a terminal to test the local HTTP proxy. Match the port to your current config; this test does not change global environment variables.

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

TUN, UWP, and Firewall Considerations

Consider TUN only if an app does not honor the system proxy. Install or start the helper service as prompted, complete system authorization, then enable routing through the virtual adapter. During testing, turn off other VPNs and check for duplicate routing; remote-work tunnels, VM adapters, and game boosters can all change routes. If the whole network stops working, turn off TUN and return to the verified system-proxy setup instead of layering on more DNS changes.

Some UWP apps are restricted from accessing a local proxy by loopback isolation. First check whether the problem affects only a particular app, then see if the client offers loopback management and grant an exception to that app if appropriate. Don't disable isolation for every app. If the firewall asks about network access, distinguish local connections from LAN sharing: a proxy used only on this PC usually doesn't need to expose its port to other devices on the same Wi-Fi network.

Recover After Sleep, Exit, or Client Migration

If connections fail after waking from sleep or switching networks, first check whether the core is still running, then toggle the system proxy off and on. Management policies or other software may rewrite proxy settings, so the toggle can be on even if the system address has changed. If the log reports a listening failure, check for a port conflict. If a connection is established but the destination times out, check the node and rules instead of assuming it's a Windows permissions issue.

Before quitting normally, turn off the system proxy and TUN. If the app crashes and your browser loses connectivity, return to the system proxy settings, clear any manual proxy values it left behind, and test a direct connection. When moving to a new client, turn off routing and auto-start in the old one, import only the configs you need, and verify the new setup before uninstalling the old app. Don't let two clients compete for the same port and system proxy settings at sign-in.

macOS: Move the App to Applications and Set Up Routing

Choose the Right Build for Your Mac and Install It

Open Apple menu → About This Mac. If it shows an Apple chip, choose the Apple Silicon or ARM64 build; if it shows an Intel processor, choose the Intel or x64 build. Visit the macOS downloads and start with Clash Plus. Clash Verge Rev and FlClash are also options. ClashX Meta is no longer maintained; it's archived, so check config compatibility and supported macOS versions before using it.

Open the DMG, drag the app icon into the Applications folder, and wait for the copy to finish. Launch the app from Applications rather than running it from the disk image; doing so can cause issues with updates, permissions, and path detection. Eject the disk image once copying is complete. To replace an existing app, quit the old process first, back up your config, then follow the system prompts.

If you see a security warning on first launch, verify the download source and read the warning. Only if you trust the app should you use the Open Anyway option in System Settings; don't copy terminal commands that remove quarantine attributes or disable system protections. Authorizing a helper service is separate from opening the app for the first time. If installing a service later prompts for an administrator password, check what you're authorizing each time.

Import a Subscription and Choose a Proxy Group

In the Config page, import a URL or local file, save it, and select it as the active config. Wait for the core to load successfully, then open the proxy groups and choose a node. Rule mode routes traffic according to the matches in your config. Global mode typically sends traffic that isn't bypassed to the global policy group; it does not enable system-level routing by itself. If you still see no connections in global mode, first check whether app traffic is reaching the client.

Don't rely only on node test results. The test target, protocol, and actual app request may differ, so one successful test doesn't prove that every site is reachable. Pin a working node and test the same destination repeatedly before restoring automatic selection. If a subscription update fails but existing nodes still work, keep the current config and troubleshoot how the subscription is fetched; there's no need to immediately clear all nodes and policy selections.

Check the System Proxy and Network Service

After enabling the client's system proxy, open System Settings → Network, select the network service in use, and check the proxy settings under Details. The labels vary slightly across macOS versions; confirm whether the active service is Wi-Fi, Ethernet, or something else. If you switch interfaces and the client doesn't update the settings, toggle the system proxy again and check the active interface instead of relying on the menu bar icon.

A browser is usually a good way to test the system proxy, but terminal tools may need proxy options passed separately. The command below affects only one request and can confirm whether the listening port is available. If the connection is refused, check the core and port. If it reaches the local proxy but times out remotely, check the proxy group, node, and destination rules. With SOCKS, also check whether DNS resolution happens locally or through the proxy.

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

Install the Helper Service and Enable TUN

TUN typically involves a virtual interface, routing, and DNS settings, and requires client support. Follow the UI prompts to install the helper service, read the system authorization details, then enable TUN. Some clients also rely on a helper for the ordinary system proxy; installing a service does not mean TUN is enabled. Check the status and logs afterward to confirm the service is running and the config loaded—not just that the authorization dialog closed.

If enabling TUN makes local devices, a corporate network, or remote connections unreachable, turn it off to restore access, then check private-network bypass rules and routing policies. Don't delete system routes, and don't test full traffic routing for the first time in a remote management session. For more on when to use each mode, see macOS System Proxy vs. TUN: How They Work.

Handle Updates, Migration, and Leftover Settings

If permissions break after an app update, quit the app completely, relaunch it, and check whether the helper service needs updating as prompted. An Apple Silicon Mac may run an older-architecture app, but that doesn't mean you should keep using that build indefinitely. A native build can reduce reliance on compatibility layers, though features still depend on the client. For migration, back up your subscription source, local overrides, and essential settings separately; don't copy an entire cache folder whose contents you don't understand.

Before uninstalling, turn off the system proxy and TUN, then use the client's service removal option. Dragging the app to the Trash may not restore proxy settings or remove a separate service. If you can't connect afterward, check for leftover addresses on the current network service's proxy page, restore the original settings, and test a direct connection. To investigate further, note what you did and when the error appeared, then check Common Questions for matching symptoms.

Android: Authorize the VPN and Allow Background Activity

Choose an Installer and Keep Your Existing Config

Visit the Android downloads and start with Clash Plus. Other options are Clash Meta for Android, FlClash, and Surfboard. These clients don't all accept the same config content; support for proxies alone doesn't mean they can interchange full YAML files. Check which clients and formats your subscription provider supports, then choose a package for your device's architecture. If unsure, check the device manufacturer's system information.

When installing an APK, Android may ask you to allow your browser or file manager to install unknown apps. Grant permission only to the source you're using, and turn it off afterward if you wish. If the installer reports a conflict, check whether an app with the same package name is already installed and whether the signatures differ. Don't uninstall it immediately; that could delete your local config. Before migrating between sources, export anything you may need to restore and confirm you can still retrieve the subscription.

Check the Config and Startup Status After Import

Open the client's config page and import from the clipboard, a URL, or a local file. After saving, check the update result and select the config for current use. If you import through the system share menu, return to the client and confirm the new entry is actually there; “shared” doesn't mean the core loaded it. For a parse error, check the log for a field or line number. A URL that opens in a browser may return a login page instead of config content.

Before the first connection, pin a proxy group selection and keep rule mode enabled so you can compare results. If the client offers per-app proxying, check whether the option means “only selected apps” or “bypass selected apps”—they mean opposite things. If only some apps use the proxy, the scope selection is a likely cause. Check the connection log before concluding that the node has failed.

Understand Android's VPN Permission

Most Android proxy clients use the system VPN service to route traffic from the device, and the first launch displays a system authorization prompt. Confirm which app is requesting access, allow the connection, then check the status bar or system VPN page. Here, VPN means the system-provided routing channel; it doesn't mean the remote service necessarily uses a traditional VPN protocol. The proxy protocol, DNS, and rules inside the client depend on the actual config.

Typically, only one regular VPN app can route traffic for a user profile at a time. Ad blockers, corporate access apps, and other network tools may also occupy the VPN slot. If the connection drops immediately on startup, stop other VPN apps and test this client again. Don't keep switching between apps to seize the connection. If Always-on VPN or Block connections without VPN is enabled, check which app those settings apply to.

Handle Background Restrictions and Network Changes

If the connection drops when the screen locks, check battery optimization, background activity, and the manufacturer's auto-start controls. Use the options provided by your device to allow the client the background access it needs, and keep any persistent notification the system requires. Settings vary by manufacturer; there's no need to disable every power-saving feature at once. First test after a few minutes with the screen locked, then after a longer idle period to distinguish process cleanup, network sleep, and remote timeouts.

When switching from Wi-Fi to mobile data, existing connections may need to be re-established. Wait for the network to come online, then check the core log for reconnection attempts. If it still fails, stop and restart the client's connection. On mobile data, also check whether the system restricts data use for the app and whether subscription updates are Wi-Fi-only. Data usage is tracked and billed by your carrier or service provider; the client's connection status does not show your plan balance.

Check Private DNS, LAN Access, and Network Recovery

Android Private DNS, encrypted DNS inside apps, and DNS routing in the client can use different resolution paths. If domains fail to load while the local listener works, note the original Private DNS setting and test one change at a time, following the client's documentation. Turning off encrypted DNS is not a universal fix. Check the failing destination, resolution errors, and matching rules, then restore any settings you still need after testing.

Printers, casting, and smart-home device discovery depend on LAN access. If devices disappear when the proxy is on, check whether the relevant private IP ranges are bypassed and whether the client supports the required local traffic behavior. Before changing routes, turn off the connection and compare to confirm that routing is the cause. If the network still doesn't work after stopping the client, check whether the system is blocking connections without a VPN, then restore normal network settings.

For routine maintenance, refresh the subscription in the client first, then decide whether the app itself needs an update. Before sharing logs, remove subscription URLs, passwords, and private details about destination sites. If one app always connects directly, check its proxy scope and existing long-lived connections. Save your work, restart the app if needed, then check its new connection entries.

iOS: Install Clash Plus and Establish a System Connection

Install from the App Store and Verify the App

Clash Plus is the recommended option for iPhone and iPad. Open the Clash Plus App Store page and install it using the information shown in the store. The product website is clashplus.io. You can also open the same store listing from the iOS downloads section on this site. Check the store listing and app documentation for current system requirements and features; menus may differ from screenshots of other platforms.

Before installing, make sure you have enough free space and can access the App Store. Organization-managed devices may restrict VPN configurations or app installations; check your organization's requirements if blocked. Don't remove a work-provided configuration profile to force a connection. After installation, open the app to find the config import and connection controls. Avoid adding other network tools during the first test so you can isolate any issues.

Import a Subscription in a Supported Format

In the app, find the subscription or config import option, paste the compatible URL provided by your service, then fetch or update it. If importing from a QR code, check that it comes from a trusted source and avoid displaying credentials where others can see them. Keep every query parameter in the URL. A period, space, or line break added by a messaging app can also cause the request to fail.

After importing, check that the config shows selectable policies or nodes, then look for any parse errors. Don't assume every YAML field supported on desktop has the same meaning on mobile; the app may use its own import and conversion logic. If a field isn't supported, request a compatible config or consult the app documentation. Don't randomly remove DNS, rules, or policy groups, leaving a config that loads but behaves differently.

If the app lets you select a config, confirm that the newly imported entry is active. When multiple subscriptions are saved, name them clearly to avoid selecting an outdated one by mistake. If an update fails, keep the existing entry and check the error and your service account status. If existing nodes still connect but the subscription won't update, the problem is with config retrieval; repeatedly removing the system VPN profile won't help.

Allow the App to Add a VPN Configuration

The first time you connect, iOS may ask to let the app add a VPN configuration and confirm with system authentication. Check the app name, authorize it, then return to the app to check its status. The VPN indicator means the network extension is running; it doesn't prove that a remote node has established every connection successfully. Check an actual destination, the app's connection log, or error details to confirm the result. A single toggle does not mean setup is complete.

On mobile, traffic is usually routed through a system network extension; don't follow desktop instructions for a local system proxy. Don't add a manual proxy to Wi-Fi “just in case” either: it may not apply on mobile data and could create a double proxy. Keep to one routing path. First verify Wi-Fi, then test mobile data. Configure a LAN proxy separately if that's what you need.

Test Wi-Fi, Mobile Data, and Local Access Separately

Start on a stable Wi-Fi connection. Open a site that normally works without a proxy, then a destination that needs one. If the first works and the second doesn't, check the policy group, node, and matching rules. If both fail, disconnect the client to verify basic network access, then troubleshoot the config and routing. Keep the destination and node fixed during testing so results remain reproducible.

Next, switch to mobile data, confirm the app is allowed to use cellular data, and check that the connection is re-established. A network switch can interrupt existing sessions, so reopen the page rather than relying on one that's already loaded. On hotel, campus, or other captive Wi-Fi, pause the proxy and complete the network sign-in first. Node or DNS errors may simply mean the upstream network hasn't granted access yet.

To reach a printer, router admin page, or other local device, check whether the client needs local network permission and whether the rules preserve a direct route. iOS privacy settings, other VPNs, and management policies can also affect access. Pause them one at a time for testing rather than disabling every privacy setting. Note the original setting each time, and change only what's needed once you identify the cause.

Manage Auto-Connect and Configuration Recovery

If the app supports on-demand connection or auto-reconnect, enable it only after manual connections are stable. Then test locking the screen, waking the device, and switching networks separately. An app being suspended in the foreground and its network extension stopping are not the same thing; check the system VPN page and actual access results. Don't follow Android background-whitelist instructions: iOS has different permissions and lifecycle behavior, and app options vary.

When you're done, disconnect in the app first. To remove the VPN configuration, use the VPN management section in Settings. Removing the system profile does not cancel your subscription or necessarily delete the subscription data stored in the app; check each separately. Before reinstalling, back up anything you can restore and confirm you can still sign in to your service account. For help, share your device OS, network type, and the steps that failed—not the full subscription QR code.

Linux: Desktop Setup and Running the Core with systemd

Choose a Desktop Client or a Standalone Core

For desktop use, start with the Linux downloads. Clash Verge Rev is recommended; FlClash is another option. Choose a DEB or RPM package for your distribution and confirm it matches your system architecture. Don't install a desktop client on a headless server expecting a tray window. For servers, routers, or scripted setups, you can use the standalone mihomo core, but you'll need to manage its config, permissions, and service lifecycle yourself.

Install desktop packages with your distribution's package manager to handle dependencies. If a runtime library is missing, read the package manager output; don't download random shared libraries and overwrite system directories. After launch, check that the tray, config storage, and system proxy work with your desktop environment. GNOME, KDE, and other environments have different proxy settings, and command-line programs may not honor the desktop proxy—so a GUI toggle won't cover every process.

Import a Config and Test the Listening Port

In a graphical client, import the subscription from the Config page, select it, then enable the system proxy. A standalone core needs a complete YAML file with working proxies and rules. The command below assumes you've installed a binary for the correct architecture at /usr/local/bin/mihomo and saved a working config at the specified path. It only validates the config; it won't fetch nodes or install a system service.

/usr/local/bin/mihomo -t -f /etc/mihomo/config.yaml

After validation succeeds, run it in the foreground first. Check that it can read the config, rule files, and any required databases, then send a proxy request from another terminal. The working directory must have the required read/write permissions; for configs with relative paths, check the data directory too. Don't enable full routing on a production server for the first time, especially in your only SSH session, where a config could rewrite the default route.

/usr/local/bin/mihomo -d /var/lib/mihomo -f /etc/mihomo/config.yaml
# Run this in another terminal; use the port set in your config
curl --proxy http://127.0.0.1:7890 --head https://example.com

Run a systemd Service as an Unprivileged User

For a persistent service, create a dedicated service account and data directory, then put the verified config in its config directory. The example below is for standard HTTP and SOCKS listeners and does not grant the network capabilities needed for TUN. These commands are for common systemd-based distributions and must be run by an administrator. If the account or directories already exist, check them first rather than overwriting existing settings or permissions.

sudo useradd --system --home-dir /var/lib/mihomo --shell /usr/sbin/nologin mihomo
sudo install -d -o mihomo -g mihomo -m 750 /var/lib/mihomo
sudo install -d -o root -g mihomo -m 750 /etc/mihomo
sudo chown root:mihomo /etc/mihomo/config.yaml
sudo chmod 640 /etc/mihomo/config.yaml

Save the following as /etc/systemd/system/mihomo.service. The config and binary must already be in place. The service account must be able to read any other local files referenced by the config and write to the data directory. Rather than running the core as root indefinitely, start with a local proxy service under an unprivileged account; this makes file-permission and network-permission issues easier to distinguish.

[Unit]
Description=Mihomo local proxy
Wants=network-online.target
After=network-online.target

[Service]
Type=simple
User=mihomo
Group=mihomo
WorkingDirectory=/var/lib/mihomo
ExecStart=/usr/local/bin/mihomo -d /var/lib/mihomo -f /etc/mihomo/config.yaml
Restart=on-failure
RestartSec=5
NoNewPrivileges=true
UMask=0077

[Install]
WantedBy=multi-user.target

Check the Logs Before Enabling Startup

Reload the service definition, start the service, and check its status and logs. Enable it at startup only after confirming the listener, proxy requests, and config loading all work. Stop any foreground test process first to prevent a port conflict. If the service exits, the first clear error in the log is usually more useful than the final restart message. Check the config path, permissions, port conflicts, and missing files first.

sudo systemctl daemon-reload
sudo systemctl start mihomo
systemctl status mihomo --no-pager
journalctl -u mihomo -b -n 80 --no-pager
sudo systemctl enable mihomo

The network-online target only defines startup order; it doesn't guarantee that a subscription server or remote node is reachable. Before updating the config, save the old file and validate the new one. Restart the service only after validation succeeds. If the new config doesn't work, restore the old file and restart; don't keep editing it while the service repeatedly restarts. For a more complete walkthrough, see Linux Desktop and systemd Deployment Notes.

TUN Permissions and Exposing Services

Linux TUN also involves a device node, network capabilities, routing, and DNS. The unprivileged service above doesn't configure any of these; changing tun.enable to true alone won't complete the setup. Design a least-privilege approach for your distribution and kernel environment, using the mihomo documentation. Containers also require host-level permissions. In remote environments, prepare console access or another recovery method before testing traffic routing.

For local use, bind the proxy and control interface to the loopback address. Don't listen on every network interface just to connect a dashboard. If you need LAN sharing, restrict source networks, enable authentication, and configure a firewall; protect the control interface separately. Stopping a standalone core won't remove proxy environment variables or routes you added manually. Restore the original settings on exit and verify connectivity with a direct request.

Configuration and Troubleshooting: Check One Layer at a Time

Narrow Down the Problem First

Note the platform, client, routing mode, and time of the error. Then identify the layer involved: basic connectivity, subscription retrieval, config parsing, core startup, traffic routing, rule selection, or remote connection. If even ordinary sites fail after you close the client, restore network access, gateway, or system proxy settings before changing nodes. If only subscription updates fail while the old config still works, investigate the subscription URL and service account first.

Change one variable at a time, and retest on the same network, destination, and node. Keep the most recent working config and record changes and results in a local note. Make sure log and system timestamps match; otherwise, an old error can look like the current cause. If you temporarily increase log detail, restore the usual level when troubleshooting is done to avoid collecting excessive records of destination sites.

Troubleshoot Subscription Failures Separately from YAML Errors

If an update fails, check that the URL is complete, credentials haven't expired, and the provider doesn't require a particular subscription format. A login page, access-denied page, or raw node list can all cause a parse error. A page loading in your browser doesn't prove the response is in the right format. Some clients let you choose a direct or proxied route for subscription updates; test this only after confirming the existing proxy works, so you don't use a broken config to update itself.

For a YAML error with a line number, check indentation, colons, and quotes on that line and around it. The parser may report the next line even when the problem is in the field above. Don't append an example snippet to the end of a complete config and create duplicate top-level keys. In the rule example below, PROXY must refer to an actual proxy or policy group defined in the full config. Copying the name alone does not define a target.

rules:
  - DOMAIN-SUFFIX,apple.com,DIRECT
  - DOMAIN-SUFFIX,example.com,PROXY
  - MATCH,PROXY

Rules are usually matched in order, and the first match determines the policy, so specific conditions should come before fallback rules. Check whether a local override changed the order or a subscription update overwrote your edits. A config that parses is only structurally readable; it doesn't prove that every node works or that the rules behave as intended.

Use Connection Logs to Choose Your Next Step

If no connection appears after an app makes a request, check the system proxy, TUN, or the app's own proxy settings. If an entry appears but uses the wrong exit, check matching rules and policy groups. If the match is right but the connection fails, check the node, protocol support, and remote reachability. Don't treat rule mode and the system proxy as the same switch: rule mode decides how traffic is routed once it reaches the core; the system proxy controls how some apps send traffic to the core.

“Connection refused” usually means no service is listening on the target port, or the connection was actively rejected. A timeout only means the operation didn't finish in time; it doesn't prove the node is blocked. Check whether the error occurred at the local listener, during the remote handshake, or while waiting for the destination response—this is more useful than the error label alone. When sharing an error, keep necessary context but remove credentials and private destinations.

Test DNS, IPv6, and UDP Separately

DNS resolves domain names to addresses. Browser encrypted DNS, the system resolver, and the core's DNS may follow different paths, so changing one server won't affect every request. Fake-IP maps a domain to a synthetic address that the core tracks and handles. If traffic bypasses the core while using a synthetic address, access may fail. Before enabling Fake-IP, confirm the routing path is complete and configure exceptions for incompatible apps.

IPv6 availability depends on your network, node, and config. Disabling it should be a documented comparison test, not a permanent default. UDP also depends on the app, routing mode, node, and protocol support; successful browser access doesn't prove that games or real-time calls will work. Don't use an HTTPS test to a raw IP as a substitute for testing the domain: certificate checks and site selection may depend on the hostname.

Update, Roll Back, and Restore Network Access

Before updating, back up the subscription source, local overrides, and current settings separately. Update the app, core, and config one at a time, verifying each before moving on. Archived clients may not recognize newer fields; for migration, choose a maintained client and restore only the settings you need. Don't copy old caches and helper services into a new client and then guess which one caused the problem.

To restore network access, reverse the setup in order: stop TUN or the system VPN, turn off the system proxy, restore any manually changed DNS settings, app proxy settings, and terminal environment variables, then test a direct connection. If uninstalling, first run the client's service cleanup process. If the problem persists, compare your redacted logs with the symptoms on the Common Questions page. If you just need to reconnect, follow the Quick Start Guide to establish a minimal working connection.