V2Ray Client Complete Setup Guide

Core concepts and client selection

Separate the client, core, node, and subscription

V2Ray can be understood as four layers. The client provides the interface, menus, subscription management, and system-level capture. The core parses protocols, creates outbound connections, and applies routing rules. A node is a set of server connection parameters. A subscription is a URL that distributes nodes in bulk and delivers updates. v2rayN, v2rayNG, and v2flyNG are clients, not protocols. Xray and V2Fly are common core families; the client calls the appropriate core to establish the actual connection.

Once the layers are clear, many problems become easier to locate. An open client window only confirms that the interface layer works. Nodes appearing in a subscription list only confirms that the subscription was parsed. Marking a node as active does not mean application traffic is already being sent through the client. The core must start successfully, local listening ports must be free, and the system proxy or TUN must capture the target application. Any break in this chain may look like “the webpage will not open,” but the fix can be completely different.

How to choose among the three clients

For Windows, macOS, and Linux desktops, v2rayN is the default choice. It manages subscriptions, servers, routing rules, the system proxy, and TUN in one place, making it suitable for both first-time setup and advanced routing. On Windows, choose between the desktop edition and the classic WPF edition. The desktop edition uses a cross-platform interface for a similar workflow across desktop systems; the WPF edition targets Windows with a more traditional interface and dependency stack. Choose the appropriate installer from the Windows download section for your environment.

On Android, v2rayNG is the primary choice. It uses the Xray core as its main execution layer and brings common protocols and routing options together in one interface. Choose v2flyNG when you need the V2Fly core family. Their subscription import, node selection, and connection startup flows are similar, but their core capabilities and some configuration fields differ. Do not assume that every advanced setting exported by one client can be read identically by the other. When migrating, verify protocol fields and routing rules first.

A protocol name is not a client name

VMess, VLESS, Trojan, and similar names describe connection protocols or authentication methods. REALITY and TLS describe transport security and handshake characteristics, while TCP, WebSocket, and gRPC are transport-layer settings. The client organizes these fields into a configuration the core can execute. When importing a node, the address, port, user identifier, transport, encryption, and security settings must remain compatible. Two nodes are not equivalent simply because they use the same protocol name.

Beginners do not need to hand-write every field. A reliable approach is to import a subscription first, letting the provider maintain the complete parameter set, then learn to inspect node details and logs. Before making manual changes, duplicate the node so the original configuration remains intact. For field definitions, consult the glossary alongside the concepts of protocols, cores, subscriptions, and routing. The model “the interface manages, the core executes, the node supplies parameters, and the subscription distributes them” is the foundation for installation and troubleshooting.

Installation and first launch

Confirm the operating system and processor architecture before downloading

The installer must match the operating system, processor architecture, and client edition. Most Windows devices use the x64 package. On macOS, first identify Apple Silicon or Intel. On Linux, distinguish x64 from arm64 in addition to the distribution package format. Most Android devices use arm64; choose a universal package only when the architecture is unclear or installation is rejected. All entry points are listed on the download page. Do not rename a file for another platform and try to install it.

Windows users also need to choose between the desktop and WPF editions. Choose the desktop edition for a workflow closer to macOS and Linux, or the WPF edition if your existing setup follows the classic Windows interface. Both are v2rayN, but their runtime environments, interface components, and some menu locations differ. If a tutorial screenshot does not match your interface, verify the edition first instead of assuming the feature is missing.

Startup essentials for Windows, macOS, and Linux

After installing on Windows, launch the client from a normal user directory with write access to its configuration directory. If no window appears after a double-click, check that the required runtime is installed, the path is not excessively deep, the directory is writable, and security software is not blocking configuration or log creation. Do not run the program from an archive preview; extract it fully or complete the installation first. For layered checks on startup crashes, see runtime and permission troubleshooting.

When first opened on macOS, the system may ask you to confirm the app's source and grant network-related permissions. Complete the authorization explicitly in Privacy & Security settings, then restart the client. Enabling the system proxy or TUN may also require administrator approval because it changes network configuration. See macOS installation and network permission steps for the full process. If the program opens but cannot change network settings, check permissions before importing the subscription again.

On Linux, choose a deb or rpm package for your distribution, then confirm that the current desktop session provides a system proxy interface. A successful installation only means the program files are in place; the tray icon, autostart, and system proxy integration also depend on the desktop environment. With a minimal window manager, you may need to configure the proxy separately in the browser or terminal. The current user should own the client log and configuration directories so startup does not require elevated permissions.

Android installation and system connection confirmation

After installing v2rayNG or v2flyNG on Android, the first connection attempt will trigger a system-level connection confirmation. Once approved, the status bar will usually show the system's connection indicator. This only means Android permits the client to create a local network interface; it does not prove that the selected node works. If the connection stops immediately after you tap the start button, open the app log and check node fields, DNS resolution, port reachability, and core startup.

The system's battery policy may restrict background activity when the screen is off. For a long-lived connection, allow the client to run in the background as needed in system app settings, then observe how it recovers after network changes. Battery-management labels vary by device. The key question is whether the client process is being suspended, not whether every permission has been enabled. If you only use it in the foreground, the default battery policy is usually more resource-efficient.

Baseline checks after the first launch

After reaching the main interface, do not enable several advanced features at once. Verify in order that the client can save settings, the core can be invoked, local ports are not occupied, and the log window records startup events. On desktop, keep the default local listening address at first rather than exposing it to the LAN. Then import one configuration or subscription, select an active node, and enable the system proxy last. Change one variable at a time so any problem can be traced to its source.

Windows:
netstat -ano | findstr LISTENING

macOS / Linux:
lsof -nP -iTCP -sTCP:LISTEN

The commands above display listening ports on the local machine. If the client reports that a port is already in use, check the HTTP, SOCKS, and API ports in settings, then use the process list to identify the conflicting program. Do not terminate unfamiliar system processes. A safer approach is to assign the client an unused port and update the port in browsers, terminals, and other manually configured proxy applications.

Subscription import and node management

What subscriptions do and the correct import order

A subscription URL retrieves node configurations in bulk and typically also delivers name changes, parameter updates, and removals of expired nodes. It is neither a client installer nor a single fixed node. Copy the complete URL, add an entry under the client's subscription group or subscription settings, give it a recognizable label, and run one manual update. When it finishes, return to the server list, confirm that new nodes are in the expected group, and check the update log for parsing errors.

In v2rayN, create the subscription entry first and then update it. v2rayNG and v2flyNG may use slightly different menu names, but the logic is the same. URLs containing query parameters or long encoded strings must be copied in full, including the final characters. Do not reuse truncated text displayed after forwarding through a chat app. Subscriptions are sensitive configuration; keep them only in clients that need them, not in screenshots, public logs, or shared documents.

A successful update, successful parsing, and a usable node are three different things

A “download complete” message only means the subscription content was retrieved. Nodes appearing in the list means the content was recognized. A node that establishes a connection proves that the current network, node parameters, and core capabilities work together. Check three outcomes during troubleshooting: whether the request returned valid content, whether parsing produced nodes, and whether the active node produced a clear success or error in the startup log. Conflating these outcomes often leads to repeatedly changing the subscription URL when the actual problem is a node.

When a subscription update fails, first confirm that the device's network works independently. Then check for an obviously incorrect system date or time and verify that the URL is complete. If the client is using an expired proxy to perform the update, temporarily disable the system proxy or change the update proxy policy in subscription settings. An unchanged node count does not necessarily indicate failure: if the server content has not changed, the list may remain identical. Use the timestamp and log conclusion as evidence.

Groups, names, and the active node

With multiple subscriptions, give each source a clear name instead of placing every node in one unnamed list. Groups serve three purposes: identifying the source during updates, switching quickly during troubleshooting, and avoiding accidental deletion of unrelated configurations. Keep region or purpose details supplied by the server in node names; do not label everything “Node 1” or “Backup 2.” Store manual configurations separately so subscription updates cannot overwrite or confuse them.

The active node is the entry the client currently uses for its primary outbound connection. After selecting a node, confirm that it is actually set as the active server rather than merely highlighted in the list. Depending on the interface, this may require a double-click, a context-menu command, or a separate action. After switching, watch the status bar and core log to confirm that the outbound configuration was reloaded. Highlighting a row without reloading the core may leave traffic on the previous node.

Update policy and configuration retention

Automatic updates suit subscriptions that change frequently, but the interval should not be too short. Refreshing more often does not improve node quality; it adds unnecessary requests and makes manual troubleshooting harder because list changes become difficult to track. Keep a sensible update interval for routine use, and run a manual update before connecting if needed. When a connection fails, test the current configuration first instead of changing both the node list and client settings at once.

A subscription update may replace same-named nodes or remove entries deleted by the remote source. If you have changed transport parameters locally, duplicate the node as an independent configuration and record why. Otherwise, the next update may restore the remote values. Before migrating the client, use its built-in backup or export function to save subscription groups, routing settings, and preferences. Copying a node share text alone usually does not preserve all client settings.

If every node fails immediately after an update, first inspect the subscription content, client core, and local network. If only one node fails, the issue is more likely its parameters or the server's status. Search the site for “v2rayN subscription update failed” to find detailed failure paths. By the end of this chapter, you should be able to update subscriptions manually, keep groups clear, switch the active node explicitly, and use logs to distinguish retrieval from connection results.

System proxy and proxy modes

How local listening relates to the system proxy

Once the core starts, it creates local HTTP, SOCKS, and other listening ports. Applications send requests to these ports, and the client then chooses direct, proxy, or block according to its routing rules. A system proxy is a mechanism that tells applications honoring system settings where to send requests; it does not establish the protocol connection itself. If the client closes while an old proxy address remains configured, the browser may lose network access because the local port is gone. Exit normally so the client can restore system settings.

Most desktop browsers read the system proxy, but command-line tools, some development environments, games, and standalone network components may ignore it. A working browser does not prove that every application is captured; an inactive terminal proxy does not prove that the node is broken. Choose between the system proxy, an application-level proxy, and TUN based on the application. For a focused checklist, see browser and terminal proxy troubleshooting.

Global, rule-based, and direct modes

Global mode generally sends most traffic that meets capture conditions through the proxy, making it useful for briefly testing a node and local listeners. Rule mode selects an exit according to domains, IPs, ports, processes, or rule sets and is the main choice for daily use. Direct mode sends captured traffic through the local network and is useful for comparison tests or temporarily disabling the proxy path. Mode names vary slightly between clients, so judge by actual outbound behavior.

For initial troubleshooting, switch to global mode. If global mode works but rule mode does not, the problem is likely routing matches or DNS decisions. If neither works, return to the node, core, and local-port checks. If direct mode is also abnormal, the cause may be a leftover system proxy, application settings, or the local network. This comparison narrows the scope quickly, but global mode should not replace a proper rule design for daily use.

How to configure applications that require a manual proxy

Applications that require manual proxy settings should use the address and port actually listened to by the client. Local applications usually use 127.0.0.1. The protocol must match the port; do not enter a SOCKS port in a field that accepts only an HTTP proxy. If the client changes its default port, update every manual configuration. LAN devices cannot point their own 127.0.0.1 at the desktop client. They must use the LAN address of the device running the client, with LAN sharing explicitly enabled.

HTTP proxy environment variable example:
set HTTP_PROXY=http://127.0.0.1:10809
set HTTPS_PROXY=http://127.0.0.1:10809

Current macOS / Linux terminal session:
export HTTP_PROXY=http://127.0.0.1:10809
export HTTPS_PROXY=http://127.0.0.1:10809

These variables affect only programs that read them and only within the current scope. Whether they persist after the terminal closes depends on whether they were written to a shell configuration file. During troubleshooting, start with a temporary setting, confirm that it works, and then decide whether to persist it. Remove variables using the appropriate method for the operating system so the terminal does not keep sending requests to a closed local port after the client exits. SOCKS proxying also depends on whether the application resolves domains through the proxy; check the application's specific options.

The boundaries of LAN sharing

Enabling LAN sharing makes the client's listeners accessible to other devices on the same network. Before enabling it, verify the listening address, system firewall, and current network. Use different policies on trusted home networks and public networks; do not widen the listening scope for a temporary test on a public network. Shared devices must enter the LAN address of the computer running the client as the proxy server and use the corresponding port. Sleep, network changes, or an address change will interrupt shared connections.

LAN sharing provides a local proxy entry point; it does not automatically change network settings on other devices. Each device still needs its own application or system proxy configuration. If another device on the LAN cannot reach the port, first confirm local listening on the host, then inspect inbound firewall rules and whether the network permits device-to-device access. If the port is reachable but the destination is not, continue with the client log and routing result. Port reachability is not the same as outbound success.

Use logs to confirm that traffic enters the client

The most direct way to verify a working proxy is not merely checking the webpage result, but watching the client's connection log. Trigger a request that is not cached; the log should show the domain, destination address, inbound type, and final outbound. No record means the application traffic never entered the client. A record routed directly means the rules selected direct. A failure after entering the proxy path means you should inspect the node or remote handshake. Logs separate “not captured” from “captured but failed” into two distinct paths.

Traffic routing and rule design

What routing rules solve

Traffic routing decides which exit to use after traffic has entered the client, based on its destination characteristics. Common exits are proxy, direct, and block. Rules can match domains, IPs, ports, network types, processes, or predefined rule sets. The goal is not to write as many rules as possible, but to make common traffic behave consistently and explainably. Excessive overlap increases maintenance costs and makes match order harder to understand.

A basic rule set usually starts with clear boundaries: send local and LAN addresses direct, route domains or rule sets that genuinely require a proxy through the proxy, and send everything else to a predictable final rule. The final rule matters because every request that misses earlier conditions lands there. If the default exit is unclear, the same rules may behave differently across clients or versions.

Rule order and first match

Most routing systems check rules in order and use the result of the first match. Put more specific rules before broader ones. For example, if a subdomain needs the proxy while the parent domain usually goes direct, the subdomain rule must come first. When combining port, process, and domain conditions, confirm whether all conditions or any one condition must match. Do not rely on the rule text alone; check how the client implements field relationships.

After changing rules, reload the configuration and use the log to inspect the matched rule. If a request takes the wrong exit, record its actual domain and resolved address, then identify the rule it matched. Do not immediately add more broad rules, which may hide existing conditions. Validate the direction with one precise rule first, then decide whether to expand it to a domain suffix, IP range, or rule set.

Domain matching versus IP matching

Domain rules depend on the client seeing the destination domain during routing. If an application resolves the domain locally and passes only an IP to the proxy, a domain condition may not apply. IP rules, in turn, depend on resolution results and address ownership; services with dynamic addresses may change frequently. Domain strategy, DNS settings, and inbound protocols together determine what information is visible, so when a domain rule fails, do not check spelling alone.

Domain-suffix rules are suitable for stable groups of subdomains, while full-domain rules are better for precise exceptions. IP-range rules should use the correct CIDR notation; the prefix length determines the range, and an overly broad range may capture unrelated traffic. Private LAN addresses should usually go direct so internal services do not take an external path. Port rules work well when a service has a clear protocol boundary, but modern applications may use several ports, so one port cannot represent all their traffic.

{
  "routing": {
    "domainStrategy": "AsIs",
    "rules": [
      {
        "type": "field",
        "ip": [
          "geoip:private"
        ],
        "outboundTag": "direct"
      },
      {
        "type": "field",
        "domain": [
          "domain:docs.example.test",
          "domain-suffix:example.test"
        ],
        "outboundTag": "proxy"
      }
    ]
  }
}

This example shows a common field structure: private addresses go direct, while a specified test domain goes through the proxy. Actual clients may generate configuration through a graphical interface, and outbound tags must match the names already defined in the client. The reserved test domain is included only to explain the syntax. Before merging the snippet into a complete configuration, export or back up the current rules and verify the JSON commas, brackets, and array nesting.

Why DNS and routing must be considered together

DNS determines how a domain becomes an address; routing determines which exit the request uses. If DNS queries and subsequent connections take different paths, the result may suit one network while the actual connection leaves through another. When rule mode fails but global mode works, inspect the domain strategy, DNS server selection, cached results, and whether resolution is performed through the proxy. Old cache entries may continue affecting results briefly after a configuration change.

Do not make major changes to DNS, routing rules, and proxy mode at the same time. A safer approach is to keep the default DNS and validate routing with a precise domain rule first, then adjust DNS for resolution requirements. When a problem occurs, record four items: the original domain, the resolved address, the matched rule, and the final outbound. Together, these usually show whether the error is in resolution, matching, or connection.

Build a maintainable rule hierarchy

Long-term rules can use four layers: put high-priority exceptions first, followed by local and LAN services, then primary domains or rule sets, and finally a default exit. Every custom rule should have a clear name and purpose. Delete temporary test rules after resolving the issue so they do not affect traffic months later. For teams or multiple devices, record why a rule changed instead of keeping only the final configuration file.

As the rule set grows, periodically check for duplicate conditions, later rules that can never match, and domains that no longer exist. When one application behaves oddly, create the smallest rule targeting that application instead of rearranging the entire set. Mastery is not measured by a long rule table, but by being able to explain from logs why a request went direct, through the proxy, or was blocked—and to verify the expected result after a change.

TUN mode and full-traffic capture

The fundamental difference between TUN and the system proxy

The system proxy depends on applications actively reading operating-system settings. TUN receives a broader range of IP traffic through a virtual network interface. It generally covers more complete traffic from applications that ignore the system proxy, standalone network components, or desktop flows that need unified handling. Greater coverage also means greater complexity: DNS, routing tables, virtual network permissions, and other network tools can all affect the result. Do not enable TUN by default when the system proxy is sufficient.

TUN is not a “faster” switch; it changes how traffic enters the client. Node quality, protocol handshakes, and remote paths do not improve automatically when TUN is enabled. If the node already fails in system-proxy mode, switching directly to TUN usually adds variables rather than solving the cause. First validate the node and core with the system proxy, then enable TUN only when an application cannot otherwise be captured.

Preparation before enabling TUN

Before enabling TUN, close other network tools that may modify routing tables or create virtual interfaces, record the current DNS and system proxy state, and ensure the client has permission to create a virtual interface. On Windows, check the virtual network adapter driver and administrator approval. On macOS, expect network-extension or related system confirmation. On Linux, ensure access to the TUN device and permission to write routes. Permission failures usually appear clearly in the startup log as interface-creation or route-setup errors.

For the first test, keep the rules simple and use an active node already verified to work. After startup, check three outcomes: whether the virtual interface was created, whether default or policy routes were written as expected, and whether DNS queries follow the configured path. If the client says TUN is enabled but no interface exists, check permissions and drivers. If the interface exists but carries no traffic, inspect the routing table. If traffic enters but domains fail, investigate DNS.

Strict routing, auto-routing, and bypass scope

Auto-routing usually generates the system routes required for capture, reducing manual setup. Strict routing lowers the chance of traffic bypassing the virtual interface, but it can conflict with LAN services, virtual machines, containers, or enterprise network policies. Before enabling a strict policy, determine whether printers, file shares, development services, and local admin pages need direct access, then add explicit bypass or direct rules for private addresses.

When LAN access fails, do not immediately disable every TUN setting. First check whether private addresses were incorrectly sent through the proxy, whether LAN domains are resolved by an unsuitable DNS path, and whether the firewall treats the virtual interface as a different network. For virtual machines and containers, also confirm whether they use host NAT, bridged networking, or an independent interface. Traffic paths differ across network topologies, so passage through the host's TUN is not guaranteed.

How to locate common conflicts

If the network goes completely offline after enabling TUN, stop TUN and confirm that basic connectivity returns, then inspect the last successful step in the startup log. If the problem remains after stopping it, check whether the client restored system DNS, the default route, and the system proxy. If IP addresses work but domains do not, focus on DNS. If only LAN access fails, inspect private-address routing. If only one application fails, check its network stack, IPv4/IPv6 preference, and whether it is bound to a specific interface.

Sleep, network changes, and an abnormal client exit can leave the virtual interface out of sync with the actual connection. After recovery, stop the connection, wait for the interface and routes to be cleaned up, and then restart it. Do not toggle repeatedly at high speed; system network services need time to apply changes. If the issue returns after every reboot, keep the routing tables and logs from before and after startup and look for the fixed failure step instead of relying on random retries.

Windows route inspection:
route print

macOS default-route inspection:
route -n get default

Linux route inspection:
ip route

These commands display system routes without modifying the network. When comparing before and after TUN is enabled, focus on the default route, routes associated with the virtual interface, and private-network paths. Record only necessary interface and subnet information, and remove subscription URLs, node credentials, and local device identifiers before sharing logs. By the end of this chapter, you should be able to tell whether the issue is a missing interface, uncaptured routing, inconsistent DNS, or an incorrect rule exit.

Routine maintenance, backups, and troubleshooting

Establish a stable update routine

The client, core, and subscription are three separate update tracks. A client update may change the interface, configuration migration, or system integration. A core update may affect protocol implementation and routing behavior. A subscription update mainly changes node content. Track them separately and do not update every component at once during an incident. Change one layer at a time, validating startup, connection, and routing before continuing so regressions can be traced.

Before updating the client, read the in-app change notes and confirm that the operating system and installation edition still match. After updating, keep the old configuration backup until you have verified the subscription list, active node, routing rules, local ports, system proxy, and TUN. If the new interface regenerates defaults, pay particular attention to ports and outbound tags because manual proxy applications and custom rules may still reference old values.

What to back up—not just the node

A complete backup should cover subscription groups, manual nodes, custom routing, DNS settings, port preferences, and general client options. A single node share text usually excludes the system proxy mode, window settings, automatic update schedule, and complete routing rules. Prefer the client's built-in backup or export function and store the backup in a controlled location. Before restoring, stop the running core so configuration files are not being written concurrently.

Judge a backup by whether it can be restored, not merely whether a file exists. After creating one, inspect its structure in an environment that does not affect the main configuration and confirm that subscription and routing files are included. When migrating across platforms, do not overwrite every file tied to system paths, permissions, or client editions. A safer approach is to import the portable configuration, then rebuild the system proxy, startup behavior, and TUN permissions separately.

How to read logs

Start with the first clear error in the log rather than only reading the final line. When the core fails to start, later messages commonly report unavailable ports, refused connections, or stopped status as consequences. Find the first failure among configuration loading, port listening, DNS initialization, and outbound establishment, then determine whether it is a syntax, port, permission, or network issue. The article Use logs to locate configuration errors covers common error entries and fixes.

Configuration syntax errors often include a field name or line and column position. Port conflicts identify the listening address. Permission problems usually occur while writing a directory, creating an interface, or changing system network settings. Node handshake failures generally appear during outbound connection setup. When the log reports domain-resolution failure, distinguish client-side, proxy-side, and system resolution. Do not capture a single error line without the initialization context around it.

Build a symptom-based troubleshooting tree

Client will not start: check the runtime, installation path, directory permissions, and damaged configuration. Client starts but the core fails: check port conflicts, configuration fields, and the core log. Core starts but the browser shows no requests: check the system proxy, application settings, or TUN capture. Logs show requests using the wrong exit: check the routing match and DNS. Requests enter the proxy but the connection fails: compare another node in the same group and inspect node parameters and the current network.

When only one application fails, do not reset the entire client. First determine whether it follows the system proxy, caches DNS, uses an independent network component, or has its own proxy setting. When only one node fails, do not delete the whole subscription. Comparing another node in the same group can separate a single-node issue from a client issue. If every node fails, then inspect subscription changes, core status, local networking, and system time.

Exit, sleep, and network switching

Before exiting the client, stop the core normally and restore system network settings. Force-ending the process may leave a system proxy address, virtual interface, or temporary route behind. If the network stops working after exit, first check whether the system proxy still points to a local port, then inspect the TUN interface and DNS. Do not reset multiple network components before confirming their state, or it will be difficult to know which change restored connectivity.

After waking from sleep or switching between wired and wireless networks, the old node connection, DNS cache, and LAN address may no longer work. First see whether the client reconnects automatically, then send a new request and check the log. If the status remains on the old connection, stop and restart the core. If recovery repeatedly fails, record interface and route differences before and after the network change and reduce the number of automatic network features enabled at once.

A sound maintenance baseline includes a restorable configuration backup, clear subscription sources and groups, separate client and core updates, an easy-to-find log entry point, and a clear recovery method for the system proxy and TUN. With these in place, most issues can be located in the existing installation instead of making reinstallation the first response.

Advanced configuration and long-term learning

Move from working to explainable

The goal of advanced use is not to enable more switches, but to explain the complete path of a request from the application to the outbound connection. The application enters through the system proxy, a manual proxy, or TUN. The inbound side preserves the domain or obtains the destination IP. DNS resolves it along the configured path. Routing selects direct, proxy, or block. The core establishes the outbound connection using the node protocol, and logs record each stage. Once this path is clear, complex problems can be reduced to a finite set of steps.

Choose one everyday application as an observation target. In system-proxy mode, record its inbound type, domain, matched rule, and outbound. Then switch to TUN and compare the path. Keep the node unchanged during the experiment so network fluctuations are not mistaken for mode differences. One complete comparison builds more reliable understanding than importing a large rule set all at once.

Understand inbounds, outbounds, and tags

An inbound defines how the client receives traffic, such as local HTTP, SOCKS, or TUN. An outbound defines how traffic ultimately leaves, such as through a proxy node, direct, or block. Tags let routing rules refer to these objects. A common error in custom configurations is a rule whose outbound tag does not match an actual configured outbound, or multiple inbounds listening on the same port. When reading generated configuration, locate the inbound list and outbound list first, then see how routing connects them.

Graphical clients maintain some tags and ports automatically. After manually editing a complete configuration, saving it in the interface may regenerate those fields, so distinguish client-managed settings from user-defined fragments. Prefer the interface for routine settings it supports. Edit custom configuration only when you need more precise conditions, and keep the pre-edit version. If the core fails to start, see how to locate configuration errors in logs.

A minimal experimental configuration

When testing a new rule, keep the conditions minimal: one verified node, one capture method, one precise rule, and one clear target. Confirm that the request matches as expected, then expand gradually to a domain suffix, rule set, or process condition. If the minimal setup does not work, adding more DNS and routing options only broadens the investigation. For every experiment, record the change, expected result, actual log, and rollback method.

{
  "type": "field",
  "domain": [
    "full:api.example.test"
  ],
  "network": "tcp",
  "outboundTag": "proxy"
}

This rule matches only TCP traffic for the specified test domain and sends it to the outbound named proxy. Before using it, confirm that the outbound tag exists, the client core supports the fields, and the rule comes before broader rules. Once validated, change it explicitly to a suffix rule if subdomains also need coverage. Do not begin with conditions that are broader than necessary.

Judge performance through repeatable comparisons

Connection quality is shaped by the local network, node path, protocol settings, DNS, concurrent connections, and application behavior. To determine whether a setting improves performance, keep the node and target fixed, test before and after the change, and observe connection establishment and sustained transfer several times. A single page-load time is easily affected by cache and cannot support a stable conclusion. Instant status shown in the client reflects only current conditions and is not a long-term score.

If connection establishment is slow, distinguish DNS wait, TCP connection setup, TLS, and protocol handshake. If transfer becomes unstable after establishment, inspect packet loss, network changes, and the node path. If only rule mode is slow, check DNS and rule sets. If only TUN is slow, inspect the virtual interface, MTU, and possible duplicate capture. Different symptoms belong to different layers; attributing everything to the client usually misses the real cause.

Keeping configurations consistent across devices

Desktop and Android clients can use the same subscription source, but do not assume that all client preferences synchronize automatically. Subscriptions distribute nodes; routing rules, DNS, the system proxy, and TUN may still need separate configuration. For multiple devices, define a shared policy first—such as direct private addresses, proxy selected domains, and a default exit for everything else—then implement it according to each client's capabilities. Do not copy rules that depend on platform-specific paths or process names to another platform.

v2rayN, v2rayNG, and v2flyNG differ in menu structure and core family. During migration, first compare whether protocol fields are complete, then rebuild routing and DNS. Desktop LAN sharing, terminal environment variables, and startup settings are not Android configuration; Android's system connection authorization and background battery policy cannot be replaced by desktop settings. Keeping the policy consistent is more practical than forcing configuration files to match character for character.

Recommended learning order

First master subscriptions, the active node, the system proxy, and logs. Next, learn to compare global and rule modes. Then write precise domain rules and explain first-match behavior. After that, understand the relationship between DNS and routing. Enable TUN only later, analyzing the virtual interface and system routes. Finally, learn complete configuration structure, tag references, and cross-device policies. Keep one working baseline configuration at every stage.

Check the glossary when you encounter a new term. Return to the Quick Start Guide when you need to repeat the first-connection process, and see client comparison when comparing the three clients. Read the article for the relevant platform when investigating system issues; startup crashes, an inactive system proxy, and core configuration errors each have their own troubleshooting path. Organizing knowledge by layer prevents every incident from becoming another search for scattered answers.

Skills checklist after completing the guide

After completing every chapter, you should be able to choose the right client and installer for each platform, import and update subscriptions independently, set the active node explicitly, distinguish the system proxy from TUN, use logs to determine whether traffic enters the client, design a routing hierarchy with exceptions, private addresses, primary rules, and a default exit, and back up the configuration before updating. More importantly, you should be able to assign a problem to the appropriate layer: runtime, core, node, capture, DNS, routing, or system networking.

The next time a connection fails, preserve the evidence and answer five questions: Is the client running reliably? Is the core listening successfully? Did application traffic enter? Which exit did routing select? At what step did the outbound connection fail? These answers usually determine the next action. If you need to reinstall, go to the download page and choose the current platform. If installation is complete but the workflow is unfamiliar, return to the Quick Start Guide and build a minimal working configuration.