V2Ray Installation and Configuration Across Platforms

01 · BEFORE INSTALLATION

General Preparation: Installers, Subscriptions, and System State

Choose the Client by Platform and Processor

For desktop platforms, v2rayN is the preferred choice. It supports Windows, macOS, and Linux, with full access to subscription groups, system proxy, TUN, routing, and logs. On Android, use v2rayNG; choose v2flyNG when you need the V2Fly kernel line. The three clients do not serve exactly the same role: v2rayN is designed for desktop environments and keeps more settings in one place, while v2rayNG and v2flyNG are better suited to touchscreens and use the system VPN interface to handle selected traffic. Do not compare screenshots from different clients item by item, since names, menu levels, and defaults may differ. Judge them by function instead.

Before downloading, confirm the processor architecture. Most Windows devices use x64; macOS requires a choice between Apple Silicon and Intel; most Android devices use arm64, with the universal build reserved for uncertain architectures or installation failures. On Linux, choose both x64 or arm64 and the matching deb or rpm package. deb is commonly used by Debian, Ubuntu, and derivatives, while rpm is common on Fedora, Rocky Linux, AlmaLinux, and related distributions. A wrong architecture often causes the installer not to launch, an incompatible-package warning, or an immediate exit after installation. Repeatedly changing the subscription will not fix these problems.

Identify Which Layer Your Subscription Data Belongs To

The client only reads configuration and calls the kernel to establish a connection; it does not generate usable servers automatically. Prepare an accessible subscription URL, a single share link, or a complete configuration file before starting. A subscription URL usually contains multiple configurations maintained by a provider; a single share link represents one configuration; a JSON file may include complete inbound, outbound, DNS, and routing rules. Each type has a different import path and troubleshooting method. For a failed subscription update, check the URL and network reachability. For a single-node failure, check protocol parameters. If a complete configuration will not start, inspect the JSON structure and field errors in the logs.

Treat subscription URLs as sensitive information. Do not paste them into public discussions, screenshots, or browser-synced notes, since they may contain account identifiers. When using the same subscription on multiple devices, enter it directly on trusted devices and use subscription groups to distinguish sources. If one client manages multiple subscriptions, name each group after its purpose or provider rather than using hard-to-track labels such as “Subscription 1” and “Subscription 2.” Clear group names significantly shorten diagnosis when updates fail, nodes are duplicated, or rules differ.

Create a Recoverable Starting State

Before installation, make sure the system time and time zone are correct. TLS handshakes depend on accurate time, and a large clock offset can make every node appear to fail at once. Then record the current system proxy state, VPN state, DNS settings, and running network tools. For the first test, keep only one proxy client running to prevent multiple programs from changing the system proxy or virtual adapter at the same time. Corporate networks, campus networks, and public hotspots may require a sign-in page; complete that login in a browser before diagnosing client connectivity.

Start with the client's default settings and complete one connection before adding TUN, split routing, or custom DNS. Introducing too many variables at once makes symptoms harder to interpret. Initial verification should cover three levels: the client log shows no startup errors; the browser reaches the expected websites; and the network returns to its original state when the proxy is disabled. The third check is especially important because it can reveal an uncleared system proxy, a leftover virtual adapter, or a forced DNS change.

After preparing, read the v2rayN first-connection guide for latency testing and verification. To manage multiple sources, see practical subscription group management. Those articles focus on individual tasks; this chapter provides the baseline used by every platform that follows.

02 · TRAFFIC CONTROL

Connection Modes and Configuration Boundaries: System Proxy, TUN, and In-App Proxy

System Proxy Works Well for Browsers and System-Aware Applications

A system proxy writes the local HTTP or SOCKS port listened to by the client into the operating system's proxy settings. Browsers, some office software, and most applications that follow the system networking framework send requests to that local port, after which the V2Ray kernel selects a direct or proxied outbound according to routing rules. The benefits are clear behavior, quick enable/disable controls, and relatively few permission requirements, so it should be the first choice for initial setup. Its limits are equally clear: applications that ignore system proxy settings, some command-line tools, certain games, and software using a custom network stack may bypass it completely.

After enabling the system proxy, the client may offer options such as “Clear,” “Auto Configure,” “Global,” or “Leave Unchanged.” Wording varies by version, but the principles are the same: auto configuration writes the local listening address into the system; clear restores the system state; leave unchanged runs the kernel without modifying the system. During troubleshooting, do not rely only on a checked menu item. Open the system network settings to confirm that the proxy still points to the local machine, and verify that its port matches the client's current inbound port. If another program has taken the port, the log will usually report a listening failure or address conflict.

TUN Is Suited to Broader Traffic Coverage

TUN mode receives IP traffic through a virtual network adapter and passes it to the kernel, so it can cover more applications that ignore system proxy settings. It usually requires administrator privileges and involves routing tables, DNS interception, or automatic routes. TUN is not a “more advanced is always better” switch: system proxy is easier to maintain when you only need browser traffic. Consider TUN when command-line tools, desktop applications, or multiple network stacks need to follow the same rules. Before enabling it, save the current configuration, close other virtual networking tools, and confirm that the system firewall will not block interface creation.

A TUN connection that cannot reach the internet does not necessarily indicate a node problem. Common causes include insufficient virtual-adapter permissions, a missing default route, a local subnet captured incorrectly, unanswered DNS requests, or an interface that failed to recover after sleep. First disable TUN and test the same node with the system proxy. If the system proxy works but TUN does not, the issue is limited to the virtual adapter, routing, or DNS; repeatedly updating the subscription is not useful. If both modes fail, then inspect the node, kernel logs, and current network.

In-App Proxy Is Precise but Easy to Miss

Command-line tools and developer software often allow a separate proxy to be specified. Some programs read the HTTP_PROXY, HTTPS_PROXY, and ALL_PROXY environment variables, while others accept an HTTP or SOCKS address in their own settings. An in-app proxy does not automatically follow the system proxy switch. Its advantage is a narrow scope; its drawback is that a dead address may remain after the client is closed. Use the local listening port shown by the client, not the remote server address. The kernel manages remote nodes; the application only needs to connect to the local entry point.

export HTTP_PROXY=http://127.0.0.1:10809
export HTTPS_PROXY=http://127.0.0.1:10809
export ALL_PROXY=socks5://127.0.0.1:10808

curl -I https://example.com

The port in the example only illustrates the format of local proxy variables; always use the actual value shown in the client settings. After testing, run unset HTTP_PROXY HTTPS_PROXY ALL_PROXY in the current terminal. If the terminal works but graphical applications do not, the kernel and node are probably fine; check whether the graphical application reads system proxy settings. Conversely, if the browser works but the terminal does not, the terminal program probably does not read the system settings.

Routing Mode Determines How Connections Are Split

The system proxy or TUN sends traffic into the kernel; routing rules decide which outbound carries it away. These concepts are often confused. “Global proxy” usually means that requests entering the kernel prefer the proxy outbound. Rule mode matches domain, IP, port, or process conditions; direct mode is useful for temporary recovery. When rules are matched in order, a broad rule near the top can hide a precise rule below it. After editing, check the order, not merely whether the rule exists.

Local network addresses, printers, network storage, and router administration pages should usually remain direct. This is especially important in TUN mode, where private address ranges may otherwise become unreachable. Common private ranges include 10.0.0.0/8, 172.16.0.0/12, and 192.168.0.0/16. If public sites work but the local network disappears, first check whether these ranges are set to direct, then look for overlapping routes from a corporate network or container network.

Do not rely on the client icon alone to verify that the proxy works. Check the logs, target-site results, and outbound network changes together. Also distinguish TCP latency from a real connection test: the former only indicates basic handshake response, while the latter is closer to actual usability. For the recommended evaluation order, see choosing nodes by latency, region, and protocol.

03 · WINDOWS

Windows: v2rayN Installation, Subscription Import, and System Integration

Choosing Between the Desktop and Classic WPF Builds

The Windows download page offers the v2rayN desktop build and the classic WPF build. The desktop build uses a newer cross-platform interface and suits users who want a consistent workflow across desktop systems. The classic WPF build is more closely integrated with the Windows desktop environment and follows a more traditional interface and tray workflow. Both support subscriptions, node selection, system proxy, routing, and logs, so there is no need to install both. For a first installation, start with the desktop build. Choose the classic build when you already rely on a WPF workflow or need to preserve an existing process.

Install to a location that a standard user can read and write reliably. If the installer requests system authorization, verify its source and follow the system prompt. After the first launch, do not enable startup or TUN immediately. First confirm that the main window opens normally and that the log area loads the kernel successfully. When security software asks about network access, allow the client to create local listeners and outbound connections on the current network type. Refusing this can leave the interface working while every test fails.

Subscription Groups and the First Update

Open subscription group settings, create a group, and enter the subscription URL. The group name identifies the source and does not change remote content. Save it, then choose “Update Current Subscription” or the equivalent action and wait for the server list to refresh. If the list is empty, check the update log first. An address-access error points to the URL or current network; a parsing error means the copied value may contain a line break, spaces, or missing characters; a successful update with hidden entries calls for checking server filters and the active group label.

Do not put every subscription into one group. Separate groups make updating, disabling, and filtering easier and prevent duplicate node names from becoming difficult to trace. Avoid very short update intervals; repeatedly requesting subscriptions at startup will not improve node quality. Follow the provider's recommended schedule and refresh manually when many nodes fail or the configuration changes. Changes in server names before and after an update reflect subscription content, not necessarily damaged local configuration.

Selecting a Configuration, Real Connection Tests, and System Proxy

After updating a subscription, select one configuration as the active server. Do not judge it by name alone; run a real connection test or visit an actual target first. A TCP timeout usually indicates that the configuration is unusable, but low latency does not guarantee application-layer success. TLS, authentication, transport parameters, or the remote state can still cause failure. For the first test, choose a standard route and avoid complex custom routing or DNS so you can establish a working baseline.

After confirming the active configuration, enable the system proxy. In Windows proxy settings, the proxy server should point to 127.0.0.1 and the port used by the client. If the browser still shows its previous state, fully close and reopen it, or check whether an independent proxy extension is active. Before closing v2rayN, clear the system proxy if possible. If the program exits unexpectedly, open Windows “Network & Internet” proxy settings, disable any leftover manual proxy, and restart the client.

TUN, Permissions, and Sleep Recovery

Enable TUN only after confirming that ordinary proxying works and you need applications that ignore system proxy settings to enter rule processing. Creating a virtual adapter for the first time usually requires administrator privileges. If startup fails, exit the client normally, then launch it with system authorization once to initialize the component. Whether administrator privileges are required every time depends on the installation method and system policy. Do not keep TUN mode enabled in another virtual networking program at the same time; the programs may compete over the default route and DNS.

After Windows sleep, a Wi-Fi change, or a switch from wired to wireless networking, the virtual interface may retain an old route. The client may still appear active while new connections fail. The recovery order is: disable the system proxy or TUN, wait a few seconds, and enable it again; if that fails, restart the kernel; restart the client only as a last resort. Directly deleting the system adapter is not the preferred action, since the route usually just needs to be refreshed.

The server list, subscription groups, logs, and settings in the v2rayN main window are covered in a detailed guide to the v2rayN main interface. Installers and current download links are listed in the Windows downloads section. Do not infer the installer type from the version appearance in a screenshot.

04 · MACOS

macOS: Chip Selection, Permissions, and Proxy Recovery

Confirm the Chip Type and Complete Installation

The macOS version of v2rayN provides separate DMGs for Apple Silicon and Intel. Open “About This Mac” to identify the chip: an Apple chip name means you should choose the arm64 installer, while an Intel processor requires the x64 build. Choosing the wrong installer may prevent the application from opening or force it through a compatibility layer with additional issues. Drag the app into the “Applications” folder before launching it. Avoid running it long-term from a mounted disk image, since path changes can affect permissions, startup behavior, and future updates.

On the first launch, macOS may ask you to confirm a downloaded application, network access, or the addition of an auxiliary network configuration. Handle explicit prompts through Privacy & Security in System Settings instead of repeatedly clicking the app icon. If the system is still verifying the application, wait for verification to finish before deciding that startup failed. If the window does not appear after installation, check the menu bar and Dock. Some desktop clients continue running in the background after the main window closes; use the menu's Quit command to exit completely.

Import the Subscription and Confirm Local Listening

The subscription process is similar to Windows: create a subscription group, enter the URL, save and update it, then select an active configuration. When copying the URL, check that the clipboard did not add leading or trailing spaces. If no server list is generated, open the log and inspect the HTTP status and parsing details. Being able to open an ordinary webpage in the browser does not prove that the subscription URL is reachable, since it may have separate access restrictions. Likewise, a successful subscription update only means that the configuration was downloaded, not that every node in it can connect.

After selecting a configuration, start the kernel and confirm that the local HTTP and SOCKS listeners have been created. In system proxy settings, enter the address and port currently shown by the client; the address is usually the loopback address. Do not arbitrarily enter a LAN address as the system proxy, and do not enable “Allow LAN Connections” by default. This option broadens the local listening scope and should be used only when other devices on the same network genuinely need the proxy and you understand the network boundary.

System Proxy and Per-Service Settings

macOS stores proxy settings per network service, so Wi-Fi and wired connections can have different configurations. After v2rayN changes the system proxy, switching network services may leave the new service without the same settings. Similarly, manually changing the proxy in System Settings can make it disagree with the client menu. If the browser bypasses the proxy, first confirm which network service is active, then check that the web proxy and secure web proxy server and port both point to the local machine.

If the network becomes completely unreachable after closing the client, the system proxy usually remains enabled while the local listener has stopped. Open the proxy details for the current network service, disable the relevant proxy entries, save, and test a direct connection. If the client is still running, use its “Clear System Proxy” function first. Repeatedly restarting the router will not remove a proxy address stored on the Mac.

TUN, Network Extensions, and DNS

TUN mode on macOS may require system authorization to create a virtual network interface. When enabling it for the first time, watch for system prompts and check Privacy & Security in System Settings. Restart the mode after authorization. If the switch immediately turns itself off, inspect the log for permission, interface-creation, or route-writing errors. If TUN starts but domains fail while a known IP responds, check DNS first. If both domains and IPs are unreachable, inspect the default route and active node.

When the network changes from home Wi-Fi to a corporate network, hotspot, or wired interface, macOS may change DNS and the default route. Rebuild TUN after a network change rather than reusing the old interface. If local services cannot be reached, check that private addresses remain direct and that “Bypass simple hostnames” or similar system options have not been overridden incorrectly. For local domains in development environments, also confirm that hosts files, LAN DNS, or container networking have not been replaced by remote DNS rules.

scutil --proxy
networksetup -listallnetworkservices
route -n get default

The commands above display the current system proxy, network-service list, and default route without changing configuration. If a proxy is enabled, compare its server address and port with the client. The default route should point to the active network interface or be correctly captured by TUN. After troubleshooting, return to the graphical interface to change switches so command-line state and client state do not diverge.

The installer for your chip is available in the macOS downloads section. If the same node works with the system proxy but not with TUN, keep the subscription and node unchanged and focus on permissions, DNS, and routing. This provides more diagnostic value than reinstalling.

05 · LINUX

Linux: Package Installation, Desktop Proxy, and Service Boundaries

Choose Correctly Between deb and rpm

The Linux version of v2rayN must match both the distribution's package format and the processor architecture. Debian, Ubuntu, and Linux Mint typically use deb; Fedora, Rocky Linux, and AlmaLinux typically use rpm. x64 is used by common Intel and AMD desktop processors, while arm64 is used by corresponding ARM devices. Run uname -m to check the architecture: x86_64 commonly maps to x64 and aarch64 to arm64. A mismatch in either package format or architecture may cause the package manager to reject the installation.

uname -m

sudo apt install ./v2rayN*.deb
sudo dnf install ./v2rayN*.rpm

Run the installation command matching your distribution from the directory containing the downloaded file. Installing through the package manager is easier for managing desktop entries and dependencies than extracting an archive directly. If dependencies cannot be satisfied, update the package index for the current distribution and check whether the system version is still supported. Do not mix base libraries from another distribution casually. If the application installs but will not launch from the menu, start it once from a terminal and inspect standard output for missing graphical dependencies, display services, or permission issues.

The Desktop Environment Determines Whether the System Proxy Can Be Written Automatically

Linux has no single standardized desktop proxy interface. GNOME, KDE Plasma, and other desktop environments store proxy settings differently, and v2rayN's automatic configuration may vary with the desktop session. Even after the client says “System Proxy Enabled,” open the desktop network settings and confirm the HTTP, HTTPS, and SOCKS entries. Some applications follow the desktop proxy, some read only environment variables, and others use their own settings. On Linux, it is especially important to distinguish “the kernel is running” from “the application is sending traffic to the kernel.”

If the browser works but terminal commands do not, the node probably has not suddenly failed; the terminal is likely not reading the desktop proxy. Temporarily export proxy variables in the current terminal and use the client's actual port for testing. If successful, decide whether to add them to the shell configuration. Persistent environment variables affect package managers, container tools, and LAN access, so do not set them globally without understanding the scope. Clear them after closing the client, or commands will continue trying to reach a stopped local port.

Subscription Directories, Permissions, and Persistent Configuration

Import subscriptions through the v2rayN graphical interface as usual. If the client was once launched as an administrator and a standard user can no longer save configuration, ownership of the configuration directory may have changed. The graphical client should normally run as the current desktop user, with elevated privileges used only to create TUN or perform specific system operations. Running as an administrator long-term muddles ownership of downloads, logs, and configuration and expands the program's access. When saving fails, check the user's configuration-directory permissions instead of repeatedly deleting the subscription.

After a desktop session ends, the system is upgraded, or the application terminates unexpectedly, the system proxy may remain enabled. Recovery depends on the desktop environment: switch to “No Proxy” or “Automatic” in network settings, then confirm that terminal environment variables have been cleared. If an application uses its own proxy, remove the local address in that application's settings too. To troubleshoot, close v2rayN and send an ordinary network request. If it still tries to reach 127.0.0.1, some proxy setting remains active.

TUN, Routing Tables, and Container Network Conflicts

Linux TUN depends on the kernel device, network-management method, and permissions. If it fails to enable, first confirm that /dev/net/tun exists, then check the log for permission errors. If TUN starts but some addresses are unreachable, inspect ip route and ip rule. Docker, Podman, virtual machines, and corporate VPNs may create additional subnets. Overlap with the local LAN or proxy rules can send traffic through the wrong interface. Do not delete every route just because several are present; first identify which program owns each route.

ip route
ip rule
cat /etc/resolv.conf
ss -lntp

Use ip route and ip rule to inspect routing decisions, /etc/resolv.conf to view the current resolver entry point, and ss -lntp to check local listening ports. If the client says the kernel is running but the expected port does not exist, inspect the startup log first. If the port exists but an application is refused, check the address type, protocol type, and firewall. Sending HTTP requests to a SOCKS port, or entering SOCKS settings in an HTTP-only program, also appears as a local connection failure.

Installers and arm64 builds are listed in the Linux downloads section. For a desktop environment that needs long-term stability, first make sure the graphical client works normally in a standard-user session, then add startup, TUN, and custom routes one at a time.

06 · ANDROID

Android: v2rayNG, v2flyNG Import, and System VPN Integration

Choose the Client and Installer

On Android, v2rayNG is the preferred client and follows the Xray kernel line; choose v2flyNG when you need the V2Fly kernel. Both provide subscriptions, configuration lists, routing, and system VPN integration, but menu names and some protocol support may differ. Do not start connections in both clients at once, since the system permits only one active VPN session of this type at a time. Disconnect in the current client before switching to the other one.

Most recent mainstream devices can use the arm64 build. Choose the universal build only when the architecture is uncertain, the arm64 package cannot be installed, or the device has unusual compatibility requirements. Before installation, make sure the current file manager or browser is allowed to install this file, and disable that source's installation permission afterward if desired. If Android reports that the app was not installed, check for an identically named app signed differently, available storage, and package architecture before deleting network settings.

Scanning, Clipboard, and Subscription Import

Import a single configuration by scanning a QR code, importing a share link from the clipboard, or entering it manually. QR import requires camera permission; before using the clipboard, confirm that the complete link was copied; manual entry is useful for checking a small number of parameters. For subscriptions, open subscription groups or subscription settings, add the URL, and run an update. Importing a subscription URL as a single node usually will not produce the expected list, while entering a single share link as a subscription URL may only produce an error.

If the configuration list is empty after an update, check the active group, filter keywords, and update log. If entries exist but cannot connect, select one as active and run a real connection test. Mobile data and Wi-Fi use different paths, so the same configuration may behave differently on each. Record the current network type when diagnosing; do not update over Wi-Fi, test over mobile data, and immediately conclude that the node has failed.

Connection Authorization, Per-App Proxy, and Background Limits

The first time you tap Connect, Android displays VPN connection authorization. After approval, the status bar usually shows the corresponding system indicator. If tapping Connect does nothing, check for another VPN session, a work-profile policy, or another system networking feature occupying the interface. If the client says connected but no apps can reach the network, disconnect and try another known-good configuration. If only certain apps fail, inspect per-app proxy settings.

Per-app proxy settings can select which applications are handled by the client and which are bypassed. Read the rule direction carefully: “Proxy only selected apps” and “Bypass selected apps” produce opposite results. For the first setup, disable per-app restrictions, confirm that the overall connection works, and then add applications individually. If only newly installed apps fail after enabling the feature, they may not be included in the existing list; review the selection scope.

Some systems restrict background applications, sleep-time networking, or automatic process cleanup, causing the connection to drop after the screen has been locked for a while. In battery settings, allow the client to maintain the background activity it needs and remove excessive sleep restrictions for that app. There is no need to disable every power-saving feature; adjust only the current client. Frequent reconnections may also result from automatic switching between Wi-Fi and mobile data, so test on one network type first.

Routing, Remote DNS, and LAN Access

Android clients usually capture traffic through the system VPN interface, while routing mode determines where domain and IP traffic exits. In rule mode, LAN addresses should remain direct; otherwise screen casting, printers, network storage, and router administration pages may become unreachable. If public access works but local devices disappear, check LAN bypass settings and private-address rules before changing node protocol parameters.

DNS settings must align with routing targets. When remote domains are accessed through the proxy, remote DNS can reduce mismatches between local resolution and the proxy exit. Local domains, router hostnames, and LAN services may instead depend on local DNS. An overly uniform setup may make one class of domains work while another fails. Keep the client's default DNS for the first setup and change it only for a stable, reproducible resolution problem. Disconnect and reconnect after every change.

The arm64 and universal builds for both Android clients are listed in the Android downloads section. To understand how Xray, V2Fly, and graphical clients relate to one another, read Project V, V2Fly, and the Xray ecosystem explained so client names, kernel names, and protocol names are not treated as the same layer.

07 · CONFIGURATION

Subscriptions, Routing, and DNS: The Cross-Platform Core

Subscription Updates and Node Parameters Are Separate Paths

A subscription update requests the subscription URL, reads the response, parses the configurations, and writes them into a local group. A node connection reads one configuration, starts the kernel, resolves the server domain, establishes the transport, and completes the protocol handshake. A successful update proves only that the first path completed; it does not prove that every node works. A successful node connection likewise says nothing about whether the subscription can update later. First identify which path failed. Otherwise, you may replace nodes to fix a subscription URL problem or re-import a subscription to fix a single-node parameter issue.

Before updating, record the configurations that currently work. If many entries change afterward, first confirm that the correct group is active. When multiple subscriptions create duplicate node names, do not identify the source by display name alone. Filter by group before testing, or use keywords to exclude unwanted regions and multiplier tags. A filter that is too broad hides valid nodes; one that is too narrow loses its management value. For a detailed multi-source workflow, see multi-subscription groups and server filtering.

Routing Rules Work by Match Scope and Order

Common routing conditions include domains, IP addresses, ports, protocols, and processes. Domain rules suit specific websites; IP rules suit LANs and fixed subnets; process rules help split desktop traffic but vary in cross-platform support. Rules usually match from top to bottom, then choose a proxy, direct, or blocked outbound. Put precise rules before broad ones. For example, send LAN and local domains direct first, handle specific domains next, and let the default outbound receive everything unmatched.

{
  "routing": {
    "domainStrategy": "IPIfNonMatch",
    "rules": [
      {
        "type": "field",
        "ip": [
          "geoip:private"
        ],
        "outboundTag": "direct"
      },
      {
        "type": "field",
        "domain": [
          "domain:example.com"
        ],
        "outboundTag": "proxy"
      }
    ]
  }
}

The example shows the basic relationship in a routing structure: private addresses go direct and specified domains use the proxy. A complete real-world configuration must also define outbounds corresponding to the direct and proxy tags. Graphical routing interfaces usually replace hand-written JSON, but understanding the tag relationship remains important. If a rule references an outbound tag that does not exist, the kernel may refuse to start. If a domain rule uses syntax unsupported by the current kernel, it may never match.

DNS Determines How Domains Enter Routing Decisions

When a domain is accessed, the client may match domain rules first or resolve it to an IP before continuing evaluation. domainStrategy controls when domain resolution occurs, though available options can vary slightly by kernel and client. AsIs tends to preserve the domain for rule matching; IPIfNonMatch resolves the IP when no domain rule matches. More aggressive strategies involve DNS more heavily. Choose based on what the routing rules require, not because one value is assumed to accelerate everything.

DNS problems often appear as domains that will not open, long waits on the first visit, inconsistent results for the same website across networks, or total domain failure in TUN mode. Compare domain and IP reachability first, then inspect the client's DNS log. Do not change system DNS, client DNS, browser secure DNS, and routing policy at the same time. Change one layer at a time so you can identify what took effect. Browsers may have their own DNS settings, so check whether the browser is bypassing system and client resolution when its results differ from other apps.

{
  "dns": {
    "servers": [
      "https+local://1.1.1.1/dns-query",
      "localhost"
    ],
    "queryStrategy": "UseIP"
  }
}

DNS capabilities vary with kernel versions and client implementations. The example illustrates the layers of a server list and query strategy; do not overwrite a complete configuration before confirming how the client supports it. When the graphical client offers DNS presets, start with one matched to the current kernel and adjust it based on logs. Save the original values before customizing so you can roll back quickly if resolution fails.

Combine Latency Results with Real Connection Tests

Latency shown in a node list may come from a TCP probe, a connection test, or a target-URL test, and these methods are not directly comparable. Low TCP latency means the basic connection is established quickly, but it does not include a complete application request. A real connection test is closer to actual use, yet it is also affected by the test address, DNS, and current network. Choose nodes based on success rate, actual access, region requirements, and traffic multipliers rather than simply selecting the smallest number.

Batch latency tests establish many connections at once, so weak networks or large node lists may produce temporary timeouts. Test in batches by subscription group, then verify candidates by visiting real targets. Node status naturally changes over time, while frequent switching makes problems harder to reproduce. If every node fails at the same time, check the local network, system time, subscription state, and kernel startup before editing nodes one by one.

08 · TROUBLESHOOTING

Common Configuration Problems: Build a Troubleshooting Path from Symptoms

The Client Will Not Start or Exits Immediately

First determine whether the problem is at the installation or configuration layer. An installer that will not run or an incompatible-package warning usually points to a platform, architecture, or package-format mismatch. If the window appears briefly and exits, suspect runtime dependencies, permissions, configuration parsing, or kernel loading. On desktop platforms, start the program from a terminal and observe the output; on Windows also inspect the client log directory, on macOS review system prompts, and on Linux check standard output and desktop-session information. Do not repeatedly reinstall without recording the error, since reinstallation can overwrite useful evidence without fixing architecture or permission problems.

If the client starts after its configuration is removed, the cause may be a custom route, DNS setting, or complete JSON configuration. Roll back from the most recent change instead of importing everything again. If even the default configuration will not start, check the system time, disk space, write permissions for the user directory, and security-software blocks. A read-only installation location, an administrator-owned configuration directory, or an executable kernel file being blocked can all produce similar symptoms.

Subscription Update Fails or the List Is Empty Afterwards

For a failed subscription, first determine whether the request was sent. A malformed URL, incomplete copy, unreachable network, or server error fails at the request stage. If the request succeeds but parsing fails, inspect whether the response is in a subscription format supported by the client. If parsing succeeds but the list is empty, check the active group, filter keywords, and any accidentally enabled hide conditions. With multiple groups, confirm that you updated the current group rather than another source.

A subscription URL opening in a browser does not prove that the client received exactly the same value. The browser may auto-complete the address or retain a login session, while the client requests the raw URL. Copy it again from the provider's subscription control and avoid chat software that may truncate links. Excessive update requests can trigger server-side limits; waiting a reasonable amount before trying again works better than clicking repeatedly.

The Node Appears Usable, but the Browser Cannot Open Websites

First verify that the active node is actually selected, then confirm that the system proxy was written. The client's test checks the kernel's connection to a specified target; the browser must also send traffic to the local port. Open system proxy settings and verify the loopback address and port, then fully restart the browser. If an independent proxy extension is installed, disable it temporarily so it cannot override system settings. If only one website fails, inspect routing rules, DNS, and the target site's status instead of declaring the entire proxy unusable.

If every browser fails while a command-line tool works through an in-app proxy, focus on system proxy or browser settings. If the browser works but other applications do not, those applications probably ignore the system proxy; consider an in-app proxy or TUN. Comparing application types quickly shows which layer is not sending traffic into the client.

The Network Goes Completely Offline After Enabling TUN

Disable TUN immediately and verify that ordinary networking returns. If access still fails, check for a leftover system proxy, then inspect DNS and the default route. Once ordinary networking is restored, test the same node with the system proxy. If it works, the node and kernel are basically sound; focus on TUN permissions, the virtual interface, automatic routing, and DNS. If the system proxy also fails, fix the node or kernel first instead of continuing to adjust the virtual adapter.

TUN problems often occur when multiple VPNs, container networks, virtual machines, or corporate network clients run together. Disable one possible conflicting network tool at a time and watch how the routes change. If the LAN is unreachable while public sites work, check direct routes for private ranges; if domains fail while IPs work, check DNS; if no traffic has an exit at all, inspect the default route and interface permissions. Breaking the symptoms down is safer than resetting the entire network and is more likely to preserve valid settings.

The Connection Drops Automatically After Running for a While

On mobile devices, check background restrictions and automatic network switching first. On desktops, check sleep recovery and changes to network interfaces. If the drop occurs at a fixed interval, inspect scheduled updates, kernel restarts, and system power policies. If it happens only when Wi-Fi signal conditions change, an active connection may have been invalidated by a network switch; disconnecting and reconnecting usually restores it. Compare other nodes only after logs show that the remote side closed the connection or handshakes repeatedly failed.

Do not judge node stability from one disconnection. Record the time, network type, current mode, and key log lines, then repeat the test two or three times to find a pattern. If all nodes drop together, the local network or client state is more likely; if one node fails repeatedly, the problem is more likely on the node side. For real connection testing, see first connection and proxy verification.

The Network Is Still Abnormal After Closing the Client

The most common cause is a system proxy or environment variable still pointing to a local port. On Windows and macOS, open the proxy settings for the current network and disable manual proxying. On Linux, check HTTP_PROXY, HTTPS_PROXY, and ALL_PROXY in addition to the desktop proxy. On Android, confirm that the system VPN session has disconnected. If TUN was enabled, wait for the virtual interface and routes to be cleaned up before reconnecting to the network.

If the browser remains abnormal, fully exit and relaunch it, and check its independent proxy and DNS settings if necessary. If only one application cannot recover, open that application's network settings and remove the local proxy. Clearing browser data should not be the first step; proxy residue and web cache are different layers. Restore direct system access first, then re-enable client settings layer by layer to avoid making a simple issue larger.

How to Decide Whether to Update the Subscription, Change Nodes, or Reinstall

If subscription requests fail or the server list remains outdated, address the subscription. If one configuration fails its handshake while others work, change nodes or wait for the remote side to recover. If every node fails while the kernel is healthy, inspect the network, time, system proxy, and DNS. Reinstallation belongs to the installation layer only when the program cannot start, dependencies are damaged, or the installer architecture is wrong. It comes late in the troubleshooting path because most connection problems occur in configuration and system networking.

For complex failures, create a minimal configuration: one subscription group, one known-good configuration, default routing, default DNS, and a system-proxy test. Once the minimal setup works, restore custom settings one by one. The step that reintroduces the problem usually identifies the layer at fault. If the minimal setup still fails, collect the client log, platform, network type, and reproduction steps. Describing what appears in the log after clicking Connect, whether the system proxy is written, and how system proxy compares with TUN is far more useful than simply saying “it does not work.”

After troubleshooting, record the confirmed client type, subscription-group naming scheme, usual connection mode, and custom rules. If you need to reinstall, visit the client downloads page to confirm the platform entry first. If you only need to repeat the basic process, return to the quick-start guide. This manual is for boundaries and exceptions; the quick-start guide is for restoring the shortest working path.