Browse the complete guide

V2Ray from Beginner to Advanced: Subscriptions, Routing, and TUN

Follow the practical order of use, from core concepts and client selection to installation, subscription management, system proxy settings, routing, TUN mode, maintenance, and advanced troubleshooting. Read it cover to cover or use the contents to find a specific setting.

v2rayN desktop v2rayNG for Android Routing and TUN Log diagnostics

How this guide complements the quick tutorial

The quick guide provides a short path for readers who already have a subscription URL and want to make their first connection quickly. This page explains why each setting matters, which traffic different modes affect, and where to start when something goes wrong. New users can complete the quick guide first, then return here for routing, TUN, and maintenance. If you manage multiple subscriptions or adjust rules manually, read the chapters in order.

This guide covers only the three clients listed on the site’s download page: v2rayN on desktop, plus v2rayNG or v2flyNG on Android. Installation links are consolidated on the download page; package links are not duplicated here so the setup, configuration, and troubleshooting guidance stays clear.

01 · Foundations

Core concepts: distinguish clients, cores, protocols, and subscriptions

The client handles controls; the core handles connections

The four concepts most often confused in V2Ray are the client, core, protocol, and subscription. The client is the graphical interface you use directly. It stores subscriptions, selects nodes, switches proxy modes, generates runtime configuration, and displays logs. v2rayN, v2rayNG, and v2flyNG are all clients. The core runs in the background, reading configuration to establish connections, forward traffic, resolve domains, and match routes. Common core families include V2Fly and Xray. They share similar configuration ideas, but their supported protocols and field details may differ.

So, “the client can import this link” does not mean “the current core can run it correctly.” The client must identify the share link or subscription content, convert its parameters into core configuration, and rely on a core that supports the required protocol, transport, and security settings. When troubleshooting, first determine whether the failure occurs during import, configuration generation, or the actual connection—not by repeatedly reinstalling the client. No nodes after import usually points to subscription content or parsing; nodes that exist but fail at startup usually point to field compatibility; a successful startup with inaccessible destinations calls for checks of the proxy, routing, and network path.

The protocol defines communication; transport parameters must match as a set

Names such as VMess, VLESS, and Trojan describe how the client and server authenticate and organize data. They are not speed tiers and cannot determine connection quality on their own. The same protocol may use TCP, WebSocket, or gRPC, together with security settings such as TLS or REALITY. The address, port, user identifier, transport, hostname, path, and security options must match the server configuration field by field. Changing one field rarely produces a “close enough” working result; it usually causes the handshake to fail.

A share link encodes these parameters into portable text. A subscription groups multiple share links or structured node details behind an address that can be updated. The subscription URL is not the network node itself; it is more like a remote configuration list. When the client updates it, the client requests the list, parses the nodes, and writes them into a local group. A successful update only means the list was retrieved and parsed—not that every node can connect. Conversely, if an update temporarily fails, existing local nodes may continue to work because the client retains the last successfully synchronized configuration.

System proxy, routing, and DNS operate at different layers

The system proxy determines whether proxy-aware applications hand requests to the client. Routing rules determine whether the client sends those requests through a proxy, directly, or to a block. DNS converts domain names into addresses and may also participate in domain-rule matching. Inspect these layers separately. If a browser works but one program does not, that program may ignore the system proxy. If every application reaches the client but some destinations use the wrong exit, the routing rules are the likely cause. If a domain fails while its address responds directly, inspect the DNS path.

Layer Primary responsibility Typical symptoms Check first
Subscription Fetch and organize node configuration Empty group or format error during update URL integrity, subscription response, group settings
Core Establish connections and forward traffic Startup, handshake, or protocol errors Protocol fields, transport parameters, system time
System proxy Send application requests to the client Browser and other applications behave differently Application proxy support, system proxy status
Routing and DNS Choose an exit and resolve domains Some domains fail or use an unexpected exit Rule order, DNS results, stale connection cache
02 · Tool selection

Choose a client: platform, core, and management style

Use v2rayN as the primary desktop client

v2rayN supports Windows, macOS, and Linux, making it a practical primary desktop client. It brings subscription groups, node selection, system proxy settings, routing rules, TUN, and logs into one interface for long-term management. Windows users can choose between the newer cross-platform desktop interface and the classic WPF interface. Both handle the same core tasks; the main differences are their UI technology and operating style. On macOS, choose the package for your processor architecture. On Linux, choose the package format used by your distribution.

If you manage multiple subscriptions, keep separate groups for work and everyday use, or plan to learn custom routing, v2rayN’s desktop workflow is a better fit. Create groups by subscription source, then select nodes within each group. Updates to one source will not turn the entire list into an untraceable mix. Remember: a group is a configuration source, while a node is a connection target. Do not use constant node renaming as a substitute for group management.

Choose between v2rayNG and v2flyNG on Android

v2rayNG follows the Xray core route and is usually the first choice on Android. v2flyNG uses the V2Fly core and can suit configurations that require its capabilities or compatibility. Both support subscription imports, node switching, and traffic capture through a VPN interface, but their menu names, routing options, and core support are not identical. Advanced rules exported from desktop may not transfer unchanged to mobile; use the fields the client actually recognizes.

The package architecture must match the device. Most newer Android devices use arm64; the universal build is intended for uncertain architectures or broader compatibility. Architecture affects whether the package runs, not the subscription content or protocol parameters. If the arm64 build installs normally, switching to the universal build will not fix connection problems. Return instead to the logs, node parameters, and network conditions.

Client Supported platforms Core family Best for
v2rayN Windows、macOS、Linux Runs with the core capabilities provided by the client Desktop subscription management, system proxy, routing, and TUN
v2rayNG Android Xray Everyday mobile connections and per-app control
v2flyNG Android V2Fly An alternative when V2Fly compatibility is required

Do not use client switching to hide a configuration problem

The same configuration may behave differently across clients, but switching clients should not be the first troubleshooting step. Record the protocol, transport, security parameters, and error log first, then determine whether the issue is a core capability difference. If a configuration cannot be imported, check whether the share format is complete. If it imports but fails at startup, inspect the generated configuration or core log. If it fails only on a particular network, compare the network path and DNS before concluding that the client is incompatible.

After choosing a client, make one tool the primary workspace and learn its log entry point, configuration directory, and recovery process. Constantly moving imports between clients creates duplicate nodes, stale groups, and different routing defaults, making later diagnosis harder. A clear setup is to use v2rayN as the desktop management center and choose v2rayNG or v2flyNG on mobile according to the required core. See the client download page for platform-specific installation links and architecture details.

03 · Environment setup

Installation and initial setup: establish a recoverable baseline

Confirm the system and processor architecture before downloading

On Windows, first choose between the desktop edition and the classic WPF edition. Choose the desktop edition for a similar interface across desktop systems, or the WPF edition if you prefer the traditional Windows workflow. macOS devices require a choice between Apple Silicon and Intel packages; the wrong architecture usually results in a failure to launch or extra compatibility work. Linux users should choose a deb or rpm package for their distribution and still distinguish x64 from arm64. On Android, confirm arm64 first; consider the universal build only when the architecture is unknown.

The installation directory must allow the current user to read and write files. While running, the client typically saves subscriptions, logs, routing configuration, and interface settings. A tightly restricted directory can prevent settings from being written after an update. For portable use on Windows, avoid leaving the program in a temporary extraction folder. After first launch on macOS, confirm that the app can save settings. On Linux, verify that the program starts from the application menu or terminal rather than relying solely on successful package installation.

Configure only the essentials on first launch

When opening v2rayN for the first time, confirm the interface language, configuration location, and log entry point. Do not enable every advanced option immediately. Keep the default routing, leave TUN off, and postpone automatic startup and connection until one minimal connection test succeeds. The baseline has four parts: the client starts normally, the subscription imports, the core runs after a node is selected, and a browser can reach a target through the client with the system proxy enabled. Add automatic updates, startup launch, and custom routing only after all four are stable.

System time is an easy-to-miss prerequisite. Some secure connections are sensitive to clock skew; an incorrect device time or time zone can cause certificate validation and handshake failures. Enable automatic time synchronization before checking protocol parameters. Also avoid port conflicts with other local programs. If the log says the listen address is already in use, close the old client or identify the process holding it. Do not change several ports in succession, because browsers and other applications may still point to the old port.

Understand the configuration directory and how to exit

Closing a graphical window does not always terminate the client process. Desktop clients often remain in the system tray, so the core and system proxy may keep running after the window closes. Before changing the installation directory, replacing program files, or restoring a backup, use the tray menu to exit and confirm that related processes have ended. Closing only the window and then moving the directory can leave files locked, interrupt settings writes, or keep the system proxy pointed at the old port.

The configuration directory usually contains client settings, the node database, subscription details, routing rules, and logs. Back up the entire directory only after the client has fully exited, rather than exporting just the current node. A share link cannot preserve groups, custom routing, or interface settings; copying only the program directory may miss user data stored elsewhere by the system. Locations vary by platform and client type, so prefer the client’s open-configuration-directory or backup function, then record the actual path.

First-install checklist
1. Confirm the system and processor architecture
2. Install or extract to a location suitable for long-term use
3. Launch the client and locate the logs
4. Keep the default routing and leave TUN disabled for now
5. Import one subscription and select one node
6. Enable the system proxy and test in a browser
7. Exit the client and confirm that the system proxy has been restored

The exit test is important. After a normal exit, requests may still be affected if the system retains a setting that points to the local proxy port. When starting the client again, check that the system proxy state matches what the interface shows. If not, use the client’s system-proxy cleanup function, then confirm the setting in the system network controls. Do not treat rebooting the device as the standard fix; once you understand the proxy toggle and process state, most cases can be corrected directly.

04 · Configuration management

Subscriptions and nodes: import, update, group, and filter

Importing a subscription is not a one-time node copy

A subscription URL continuously retrieves a node list. Pasting a single share link is useful for a temporary test; for long-term use, save the subscription in its own group. Before importing, check that the URL is complete, especially for leading or trailing spaces, line breaks, or punctuation added by a chat app. Name subscriptions by source or purpose, such as “Daily” or “Test configuration.” Do not name a subscription after its current node, because nodes change while the source relationship should remain stable.

After adding a subscription in v2rayN, save the subscription settings before running an update. Some users treat “add subscription” and “update subscription” as one action, saving the URL without generating nodes. After the update, check three things: whether the target group appears, whether it contains nodes, and whether existing manual nodes remain in their separate group. If the entire list is empty, do not overwrite it with another update immediately. Read the subscription log to determine whether the response was empty, the format could not be parsed, or a group filter hid the results.

Balance change with traceability when updating

Do not set the automatic update interval too short. Subscription content rarely needs minute-by-minute refreshes; frequent requests provide little practical benefit and make the node list change during troubleshooting. Set an interval from a few hours to a day based on the source’s update frequency, while keeping a manual update option. Before investigating a node, pause automatic updates or record its key parameters so its name, address, or position cannot change mid-test.

Updating a subscription and testing a node are separate actions. An update confirms that the configuration list can be retrieved; a connectivity test uses a specific node. Distinguish TCP reachability, real connection latency, and download speed. TCP reachability only shows that the address and port respond. Real connection latency includes the protocol handshake, while download speed depends on bandwidth, server load, and the target resource. Read Latency tests: differences and recommended order to avoid sorting nodes by one number alone.

Groups, deduplication, and expired configurations

Create separate groups for multiple subscriptions instead of copying every node into the default group. Groups answer where a node came from, which update changes it, and whether deleting a source would also remove manual configuration. Put manually added nodes in a dedicated group so subscription refreshes cannot overwrite same-named entries. If the client supports deduplication by alias, address, or full parameters, understand the rule first: two nodes with the same name may have different parameters, while differently named nodes may point to the same configuration.

Expired nodes do not need to be deleted one by one immediately. Run a subscription update first to confirm whether they have been removed from the remote list, then use the logs to determine whether the failure is persistent or caused by temporary network unreachability. If you need to keep a node for comparison, copy it to a manual group and mark its date or purpose. A large collection of expired configurations increases the chance of selecting the wrong one and slows batch tests, so periodically remove isolated nodes that no longer belong to a valid subscription.

Symptom Likely area Recommended action
No nodes after an update Subscription URL, response content, parsing format Read the update log and confirm the target group
Update succeeds but nodes cannot connect The specific node or current network path Start one node and read the core log
Nodes appear more than once Multiple subscriptions contain the same configuration Group by source and use parameter-based deduplication carefully
Manual nodes mixed into a subscription Group management Move them to a separate manual group before updating
05 · Traffic entry points

Proxy modes: system proxy, application proxy, and connection checks

The system proxy affects only applications that honor it

When v2rayN enables the system proxy, it points the operating system’s HTTP or SOCKS proxy to the client’s listening port. Browsers and most applications that follow system network settings send requests to the client, but some programs use their own network stack and may ignore the system proxy. This can make a browser work while a command-line tool or specific application connects directly. The routing rules are not failing; the traffic never entered the client.

The most direct way to determine whether an application enters the proxy is to inspect the client access log. Use the target application and check whether the log shows a new related connection. If there is no trace at all, inspect the application’s proxy settings or evaluate TUN when broader traffic capture is needed. If a connection appears but uses the wrong exit, inspect the routing rules. Do not infer system-proxy status solely from whether a webpage opens; caching, existing connections, and an application’s own proxy can all mislead the test.

PAC, automatic configuration, and global proxy modes

“Automatic configuration,” “PAC,” and “Global” in the client interface describe how the system hands requests to the local proxy. They should not be confused with core routing modes. PAC uses a rule script to decide which domains use the system proxy; a global system proxy sends all proxy-aware requests to the client. Once inside the client, the core may still route a request directly. Thus, “global system proxy” and “global proxy routing” are two different switches.

For the first test, use a clear and observable combination: enable the system proxy, keep the core’s default routing, and select a node with verified complete parameters. To check whether an application supports the system proxy, temporarily use the global system proxy and inspect the logs. Switch back to your everyday mode afterward. Changing PAC, routing rules, and nodes at the same time makes it impossible to identify which change affected the result.

Existing connections, caches, and verification

Established long-lived connections do not always migrate immediately after switching nodes or routing modes. A browser may reuse an existing connection, and DNS may retain an older result. During testing, close existing connections for the target page and restart the application if necessary before sending a new request. Refreshing alone may still reuse a connection, so compare nodes with the same target, the same application state, and similar times.

When Windows requires its local DNS cache to be cleared, use the system command, but this is not necessary after every node switch. Run it only when DNS results are clearly stale or an old address persists after changing DNS settings:

ipconfig /flushdns

DNS caching on macOS and Linux is managed by system services, and the exact command varies by OS version and distribution. Rather than running commands blindly, first confirm that the problem is actually in the resolution layer: does the client log show the domain being resolved, did it match the expected rule, and does using a known address change the behavior? If the domain and address produce different results, handle the cache through the system’s active resolver service.

Four-step connection check

  1. Check the processes: Confirm that both the client and core are running, with no port conflict or configuration-load failure in the logs.
  2. Check the entry point: Use the target application and confirm that its new request appears in the client log.
  3. Check the route: Inspect the matched rule and final exit, distinguishing proxy, direct, and blocked traffic.
  4. Check the result: Test with a new connection; do not compare using an old tab or download task.

Restore the system proxy before exiting the client, especially after a crash or forced termination. If the client is not running while the system proxy still points to a local port, applications may appear unable to reach the network at all. Turn off the proxy in the system network settings first, then restart the client and inspect its exit behavior. Once the basic proxy flow is stable, move on to routing and TUN; this greatly reduces the number of variables.

06 · Exit decisions

Routing: rule order, match conditions, and verification

Routing rules are matched from top to bottom

Routing sends different requests through different exits, commonly a proxy, direct connection, or block. Rules are usually evaluated in order: once an earlier rule matches, later rules no longer participate. Correct rule content in the wrong position can therefore produce unexpected results. For example, a broad domain rule placed first may prevent a later exception for one domain from ever running.

Put specific, narrow exceptions first and broad defaults later. Domains, IPs, ports, network types, and process names are separate matching dimensions; do not stack many conditions without understanding their logic. In some configurations, multiple fields in one rule must all match; other client interfaces expand conditions into separate rules. After importing external rules, inspect the configuration the client actually generates rather than relying only on rule names in the interface.

The boundary between domain and IP rules

Domain rules depend on the client seeing the original domain. If an application connects directly to an IP, or the domain is resolved before it reaches the client, matching can only use the IP. IP rules, in turn, depend on resolution results and address changes; the same domain may return different addresses over time. A sound approach is to use domain rules for known services, IP rules for local and reserved addresses, and a default exit for anything unmatched.

Common domain matches include an exact domain, a subdomain suffix, and a rule set. An exact domain matches only the specified host; a suffix rule covers all its subdomains and has a wider scope; a rule set helps maintain a category of domains, but you should understand its source and coverage. Do not infer a rule set’s contents from its name alone. After changing rules, use the logs to see what actually matched and whether the request left by domain, IP, or the default rule.

{
  "routing": {
    "domainStrategy": "AsIs",
    "rules": [
      {
        "type": "field",
        "ip": [
          "geoip:private"
        ],
        "outboundTag": "direct"
      },
      {
        "type": "field",
        "domain": [
          "domain:example.com",
          "full:service.example.net"
        ],
        "outboundTag": "proxy"
      },
      {
        "type": "field",
        "network": "tcp,udp",
        "outboundTag": "proxy"
      }
    ]
  }
}

This example sends local and reserved addresses directly first, routes a specified domain through the proxy next, and finally sends unmatched TCP and UDP traffic to the proxy exit. The client may generate different exit labels, so do not copy the example’s labels over an existing configuration. First inspect the tags of the client’s current outbounds, then reference values that already exist. A tag mismatch may prevent the core from loading or send requests to the default exit.

Add exceptions gradually from the default rules

Build a stable routing configuration from a simple structure. Start with the client’s default “bypass LAN and mainland China” preset, or an equivalent, and use it for basic verification. Add only a few clear rules at a time. Test the relevant destination and record the match after each addition. Importing a large rule set and troubleshooting afterward makes it difficult to identify whether the conflict comes from order, the dataset, DNS resolution, or an exit tag.

Process-based routing suits desktop applications that ignore the system proxy but expose process information the client can identify. It solves a different problem from domain routing: process rules choose an exit based on the application source, while domain rules choose one based on the destination. If one application needs different policies for different destinations, prefer domain or IP rules. If all traffic from an application should use one fixed exit, a process rule is more direct. With TUN, process identification also depends on platform permissions and the client implementation.

Verify routing by checking the destination, inbound, matched rule, and outbound in the logs. The final page result alone cannot confirm the traffic path. After a change, create a new connection and test one destination that should be direct, one that should use the proxy, and one local-network destination. All three must behave as expected before concluding that the rules are not being overridden by a broad match. For the structure of each configuration section, see a section-by-section guide to inbounds, outbounds, and routing.

07 · Full traffic capture

TUN mode: coverage, DNS, and compatibility

TUN handles traffic outside system-proxy coverage

TUN mode uses a virtual network interface to receive a broader range of system traffic. It is useful for applications that ignore the system proxy, programs that need UDP, or setups that apply routing rules consistently. It is not a “faster mode” and will not repair a dead node. TUN adds variables across the network stack, DNS, and routing table, so enable it only after ordinary system-proxy operation has been verified. If the baseline node connection already fails, TUN usually makes the symptoms harder to isolate.

When TUN is enabled, the client may need elevated privileges to create a virtual interface and modify system routes. Insufficient permission can appear as a failed interface creation, failed route installation, or no traffic after startup. Use the client log to identify the exact stage rather than relying on the toggle state. Windows, macOS, and Linux handle virtual interfaces and system permissions differently; after an OS or security-policy update, authorization may need to be granted again.

Strict routing and bypassing the local network

As TUN coverage expands, define how local-network traffic should be handled. Printers, network storage, router administration addresses, and local development services usually need direct access. Put LAN and reserved-address exceptions first so they do not enter the remote proxy. If local devices become unreachable after enabling TUN, check that private-address rules exist before broad proxy rules, then inspect whether the virtual interface changed the route to the local subnet.

Strict routing reduces the chance of traffic bypassing TUN, but it can conflict with virtualization software, enterprise network clients, container networks, and other traffic filters. When a conflict appears, do not immediately disable every safety option. First identify the overlapping route or virtual adapter. Record the routing-table differences before and after enabling TUN, then adjust bypass networks or interface priority one item at a time. With multiple virtual-network tools running, the last one started may rewrite the default route, making behavior depend on startup order.

The DNS path inside TUN

In TUN mode, DNS requests may also be captured by the client. Resolution results affect both the connection target and IP-route matching. With FakeDNS, the client first returns a reserved address to the application, then restores the original domain internally and selects the actual exit. This preserves domain information, but some applications that require a real IP may not handle it well. If a domain resolves but the application still cannot connect, check whether FakeDNS behavior is involved before changing nodes.

Without FakeDNS, decide whether DNS requests should go direct or through the proxy, and avoid a loop: DNS could be sent through the proxy while establishing that proxy connection itself requires the same DNS result. Client defaults usually avoid basic loops. Custom configurations should retain a bootstrap DNS that can resolve the node server’s address. This is especially important when the node address is a domain name.

Symptoms after enabling TUN Check first How to investigate
No network access at all Permissions, virtual interface, default route Check the TUN startup log and system routes
Local-network devices are unreachable Direct rules for private addresses Test the gateway and devices on the same subnet
Domains fail but addresses work DNS capture and bootstrap resolution Check DNS logs and the resolution exit
Some applications behave abnormally FakeDNS, UDP, and other virtual adapters Disable advanced features one at a time for comparison

Safe enablement and recovery steps

Save the current configuration before enabling TUN. Exit other network tools that modify routes, and record a node that works with the ordinary system proxy. Then enable TUN, confirm that the virtual interface is created, and test the local network, domain resolution, TCP, and UDP applications. If it fails, disable TUN first and confirm that basic networking returns. If problems remain, exit the client and inspect leftover virtual interfaces, the system proxy, and the default route. Do not repeatedly reinstall the client before the network is restored; leftover routes are rarely fixed by reinstalling.

08 · Long-term use

Routine maintenance: updates, backups, logs, and speed checks

Keep client updates separate from subscription updates

A client update changes the interface, configuration-conversion logic, and core management. A subscription update changes only the node list. Schedule them separately and keep a recovery path for both. Before updating the client, exit it, back up the configuration directory, and record the currently working mode. Afterward, test the original node and routing first; do not refresh the subscription at the same time. If something breaks, you can then tell whether the cause was the program update or a remote configuration change.

Subscription updates should preserve the group structure while you watch for additions, removals, and renames. If a frequently used node disappears, first check whether the source changed its list instead of repeatedly copying it from an old cache into the main group. If an old configuration is needed briefly for comparison, copy it to a manual group and mark its purpose. Remove it when finished so expired parameters are not selected later.

What to back up and how to rehearse recovery

A useful backup should include subscription settings, manual nodes, routing rules, client preferences, and essential local configuration. Logs rarely need to be kept in full long term, but for a reproducible issue retain the section covering startup and the error moment. Store backups somewhere separate from the program directory and create them after the client exits to reduce inconsistency from active writes.

A backup that has never been restored cannot be assumed complete. Before an update, record the configuration-directory location and check that the backup contains recently modified groups and routing files. To restore, install a runnable client, replace the configuration while the program is exited, and validate from the default routing. Do not repeatedly merge old and new configuration directories; it becomes difficult to know which files the client finally read.

Read logs from the first error

Core logs often produce several cascading messages after one underlying error. An invalid configuration field may cause the core to exit, after which the client reports repeated failures to connect to the local port. The first configuration error is the one to fix, not the final “connection refused” message. Start at core initialization and follow configuration loading, listen ports, DNS initialization, outbound connections, and the protocol handshake in order.

Before sharing logs, remove subscription URLs, user identifiers, server addresses, and other configuration details. Keep only the error type, timeline, and necessary context. Full configuration is not needed for troubleshooting. For recurring errors, record the trigger—for example, “after updating the subscription,” “after enabling TUN,” or “with one node only.” The trigger is more useful than a screenshot of the final line alone.

Diagnose slow speeds by local setup, node, and path

Do not begin by running repeated speed tests. First inspect local settings: whether global proxy mode was enabled by mistake, whether routing sends heavy traffic through an unsuitable exit, whether TUN conflicts with another virtual adapter, and whether the device is handling background downloads. Next compare nodes at the same time, against the same target, and in the same proxy mode. Finally observe the path across different times and network connections to determine whether fluctuations correlate with congestion.

Low latency does not guarantee high download speed. Latency reflects the wait for a connection or request, while throughput is shaped by bandwidth, congestion control, packet loss, and server load. Video buffering may also involve DNS, segmentation, and long-lived connection stability. See A layered approach to troubleshooting slow V2Ray speeds for a complete method. Change one condition at a time and record the node, mode, target, and time for comparable results.

Weekly check

Update subscriptions, remove confirmed-expired standalone nodes, verify that automatic updates work, and watch for recurring log errors.

Before making changes

Exit the client and back up the configuration. Record the current node, routing mode, system proxy, and TUN state so multiple variables do not change at once.

After a problem appears

Restore the system proxy and basic networking first, then read the earliest error. Once the minimal baseline works, restore advanced settings step by step.

09 · Advanced skills

Advanced path: from using the client to understanding configuration

Start by understanding inbound, outbound, and routing

Advanced learning does not begin with memorizing every JSON field. Start with a three-part model: inbounds receive application traffic, outbounds determine how it leaves, and routing chooses between them. The system proxy usually connects to a local HTTP or SOCKS inbound; TUN corresponds to a virtual-interface inbound; proxy nodes, direct access, and blocking correspond to different outbounds. Routing rules use domain, IP, port, network, or process information to send a request to a particular outbound.

Once this model is clear, interface options map naturally to configuration structures. Changing the local listen port adjusts an inbound; switching nodes changes proxy-outbound parameters; bypassing the local network adjusts routing rules; enabling TUN adds or enables another type of inbound. When an error occurs, use the logs to identify which section failed to establish instead of treating every issue as an unavailable node.

{
  "inbounds": [
    {
      "tag": "local-socks",
      "listen": "127.0.0.1",
      "port": 10808,
      "protocol": "socks",
      "settings": {
        "udp": true
      }
    }
  ],
  "outbounds": [
    {
      "tag": "direct",
      "protocol": "freedom"
    },
    {
      "tag": "block",
      "protocol": "blackhole"
    }
  ]
}

This example shows a SOCKS inbound listening only on the local machine, plus direct and block outbounds. It is not a complete proxy configuration and cannot replace the node outbound generated from a subscription, but it is useful for observing field relationships. The address 127.0.0.1 accepts connections only from the local machine. Changing it to another address may widen access and requires consideration of the local firewall and network boundary. Before editing a client-generated file, confirm whether it will be overwritten at the next startup or node switch.

Learn to create a minimal reproduction

The most effective way to handle a complex failure is to reduce the configuration. Keep one node, one local inbound, the simplest default routing, and explicit DNS settings, then check whether the problem remains. If the minimal setup works, restore subscription groups, custom rules, TUN, process routing, and automatic updates one by one. Focus on the layer where the problem returns. A minimal reproduction does not mean deleting the original configuration; back it up and work on a copy.

Validate protocol problems by parameter groups. First check the address, port, and user identifier; then check the transport; finally check combinations such as TLS, REALITY, hostname, and path. Do not try random values when unsure, because these fields are determined by the server configuration. If the log mentions a handshake, certificate name, or transport-path error, return to the corresponding parameter group rather than changing routing rules.

Keep your own change log

As a default preset evolves into custom rules, keep a simple change log. Record the date, purpose, affected rules, test target, and rollback method. For example: “Added a direct rule for local development domains; tested a local service and a regular website” or “Added a process rule for one application; remove it if testing fails.” This explains why an exception exists and prevents necessary rules from being deleted as redundant months later.

When editing configuration files manually, use a formatter or validator to confirm valid JSON syntax, then check tag references. JSON does not allow comments, and the final array item cannot have a trailing comma. Valid syntax still does not guarantee valid semantics: a route referencing a nonexistent outbound tag, an occupied port, or protocol fields at the wrong level can all prevent the core from starting. The configuration path and error location in the client log are the primary evidence.

Complete troubleshooting tree

  1. Client will not start: Check the system architecture, directory permissions, dependencies, and old processes holding resources.
  2. Subscription will not update: Check URL integrity, the subscription response, parsing format, and target group.
  3. Core will not run: Start with the first configuration error and check ports, fields, and core support.
  4. Application produces no log entries: Check the system proxy and application proxy support; evaluate TUN only if needed.
  5. Logs appear but the exit is wrong: Check rule order, domain and IP conditions, and outbound tags.
  6. Only domains fail: Check DNS capture, caching, bootstrap resolution, and FakeDNS compatibility.
  7. Connection works but speed is low: Compare local settings, node load, and path fluctuations separately.

After completing this advanced path, you should be able to answer four questions independently: Which inbound received the traffic? Which rule matched? Which outbound handled it? At what stage did it fail? The client interface remains the daily control center, while configuration files and logs explain its behavior; there is no need to abandon the graphical client to go further. To review the first-install items, see the v2rayN first-run setup checklist. To follow the shortest workflow again, return to the quick guide.

Download v2rayN