REFERENCE / 09 CHAPTERS
Complete V2Ray Guide
This guide covers the client setup process in nine stages. It works for a first-time setup and as a reference when you need to check what a setting does before changing it. For a basic connection, start with the Getting Started guide. For routing, DNS, or TUN issues, jump to the relevant section here. Both paths use the same concepts: first identify how an app connects to the client, then see where the core sends its requests.
The instructions focus on the v2rayN desktop client, with notes on differences in v2rayNG and v2flyNG for Android. Interface labels may change between releases, so look for settings by their purpose rather than by button location.
1. Core Concepts and the Connection Path
What the Client, Core, and Server Do
V2Ray usually refers to the proxy technology ecosystem associated with Project V, not a standalone account service that includes server access. A graphical client stores server details, manages subscriptions, builds configuration, and starts the core. The core handles inbound connections, protocol communication, and routing rules. A remote server accepts connections that match its configuration and forwards requests. Installing a client only gives you the local tools; you still need authorized server details to establish an end-to-end connection.
V2Fly and Xray are separate core projects in the related ecosystem, and their protocol extensions and configuration details do not always match. v2rayN provides a desktop interface; v2rayNG is commonly used with Xray configurations on Android, while v2flyNG offers the V2Fly option. A client being able to import a profile does not prove that its active core supports every option in it. Check compatibility across the transport, security layer, and any extensions.
Break Server Settings into Three Layers
The first layer is the proxy protocol, such as VMess, VLESS, Trojan, or Shadowsocks. It defines how the two sides identify a connection and represent requests. The second is the transport, such as TCP, WebSocket, or gRPC, which carries the protocol data. The third covers security settings, such as TLS, REALITY, and the server name. All three layers must match the server configuration. A correct address and port do not make the other fields interchangeable.
The server name, connection address, and request destination are three different things. The connection address locates the remote service. The TLS server name is used to verify identity during the handshake. The request destination is the domain the app is actually trying to reach. These may be the same or different. Changing the server name in a share link to “fix the domain” can break the handshake instead. If a value is unclear, compare each field with the original details from the provider.
Trace Problems Along the Request Path
A typical request passes through the app, a local listening port, core routing, and the remote server before reaching its destination. The system proxy affects only apps that honor that setting. Once a request reaches the local proxy, the core still uses its rules to choose an outbound route. DNS resolves domain names to addresses and may be handled by the app, the operating system, or the core. Treating all of this as one “proxy switch” makes it easy to change the wrong setting repeatedly.
When troubleshooting, first identify where the request fails. If the client will not start, check the runtime environment and ports. If the browser never reaches the client, check its proxy settings. If the log shows a handshake error, check the protocol settings and system time. If only some domains fail, look at routing rules and DNS results. Interpret log entries in context and correlate them with the time of your test; a failed background request may have nothing to do with the page you are testing.
Establish a Reproducible Baseline
For the initial setup, use one server you know works, one app entry point, and a simple routing configuration. Temporarily disable unnecessary automatic switching and avoid enabling multiple traffic-capture methods at once. Change one variable per test so the result is meaningful. After connecting, record the client, core, listening port, and routing mode. Those details are far more useful for reproducing a working setup than “it worked yesterday.”
Before moving on, make sure you can explain where the server settings came from, which program starts the core, and which local port your test app connects to. If any of those are unclear, document the source and settings before adding complex routing. Once the basics are clear, choose a client in the next section; later sections add subscription management, domain rules, and a virtual network interface one step at a time, with a way to roll back each change.
2. Choose a Client and Prepare Your Platform
Start with v2rayN on Desktop
For desktop use on Windows, macOS, or Linux, start with v2rayN. Its consistent interface makes it easier to understand servers, subscription groups, the system proxy, and routing. Visit the client downloads page to choose your platform, then check your processor architecture and package format. Packages are not interchangeable just because they list the same platform. The wrong architecture can prevent the app from launching or require an additional compatibility runtime.
The Windows desktop edition uses a cross-platform interface, while the classic WPF edition retains the traditional workflow. If you are new to v2rayN, start with the desktop edition. If you are used to the classic interface, choose WPF if it better suits your needs. The layouts differ, so do not rely on tutorial screenshots alone to find a button. Before switching, export any settings you need to keep. Test that the new interface can import your servers before replacing your existing setup.
Choose a Package for Your Chip and Distribution
On macOS, check the chip type in the system’s device information: Apple Silicon uses arm64, while Intel uses x64. Do not guess based on the computer’s appearance or purchase year. After installation, check that the app has the permissions it needs to run. TUN requires different permissions from a regular launch, so an open interface does not mean every network feature is ready. Use the system proxy for your first connection test.
On Linux, check the processor architecture, distribution package system, and desktop session. deb and rpm packages belong to different package ecosystems; arm64 and x64 are different instruction set architectures. If the tray icon or system proxy behaves unexpectedly after installation, check whether your desktop environment is supported. Configuring a local proxy in the app is usually easier to verify; the tray icon alone does not tell you whether the core is running.
| Platform | Client | Check Before Downloading |
|---|---|---|
| Windows | v2rayN | Desktop or classic WPF edition; processor architecture |
| macOS | v2rayN | Apple Silicon or Intel chip |
| Android | v2rayNG; v2flyNG as an alternative | Device architecture, required core, and protocol settings |
| Linux | v2rayN | deb or rpm; x64 or arm64 |
On Android, Choose Based on Core Requirements
On Android, start with v2rayNG. If you need a V2Fly-based configuration, consider v2flyNG. Most recent mainstream devices use arm64; if you are unsure about your device’s architecture, check the system information or consider the universal build if the download page recommends it. Do not run both clients at once to test connectivity. They may compete for the system VPN interface, causing the later connection to replace the earlier one and making the results hard to interpret.
When an Android client uses the system VPN interface to handle traffic, Android displays a permission prompt. This creates a local network entry point; it does not verify that the remote server works. Also check battery optimization, background permissions, and per-app proxy lists. If the connection works in the foreground but stops when the screen is locked, check background restrictions before changing protocols. Settings locations vary by device manufacturer, so search by permission name.
Choose for Your Needs, Not the Number of Features
The right client depends on the protocols, subscription format, routing features, and traffic entry points you need. A regular local proxy is often enough if you only need browser traffic; consider TUN when you need to cover more apps. Before using a specific setup such as REALITY, check that the selected core supports all its parameters. A feature-rich interface does not mean every option needs to be enabled; each extra switch adds another variable to troubleshoot.
Switching clients will not fix an unavailable server. Keep the same server settings and network environment when comparing two clients, then compare their logs and behavior. For a closer look at their management features, read the comparison of three V2Ray clients. Once you have chosen a client, stick with it through installation so you can establish a baseline before moving configurations around.
3. Installation and a First-Run Baseline
Install Somewhere You Can Keep Writing to
Follow the download page to install or extract the client, then launch it. If it comes as an archive, extract the entire archive to a dedicated folder before running the app; do not launch it from the archive preview. Choose a folder where your user account can write configuration and log files and where you can make backups. Avoid testing in a folder that a sync tool is constantly changing, as it could restore an old config or let multiple devices overwrite the same runtime state.
If a runtime prompt appears on first launch, install the required component and reopen the client. If the interface appears but the core will not start, check the core executable path, permissions, and any security software block history. Do not disable system protection wholesale; first identify the specific file that was blocked and why. Keep system-level changes as limited as possible. You do not need to enable TUN for a basic proxy test.
Check the Core and Local Listening Port
Open the settings and confirm that the selected core supports your server configuration. Then check the local listening address and port. This guide uses 10808 as an example; use the value shown in your client. Some interfaces list HTTP, SOCKS, and mixed entry points separately, while others provide a single entry point. The app’s proxy type must match the listener it connects to; copying the port number alone is not enough.
Apps on the same device usually connect to 127.0.0.1, the loopback address for that device. Entering the same address on another device connects to that device itself. For your first setup, listen only on the local device and leave LAN access off. If you later need to share the proxy with other devices, check the listening scope, access controls, and firewall rules. Exposing a port expands who can reach it; it is more than just adding a convenient entry point.
Run the First Test with as Few Variables as Possible
Import one server you are authorized to use and set it as active, leaving TUN off. Choose automatic system proxy configuration, then make a fresh request from a browser that honors the system proxy while watching the client log. Browser caches and existing long-lived connections can retain an old path, so close and reopen the test tab if needed. Note the time of the test so you can find its requests in the log instead of searching through the entire history.
“Core started” means the process is running; it does not mean the remote handshake succeeded. If a page will not load, first check whether its request appears in the log. If there is no entry, investigate the app’s connection to the client. If there is an entry but the connection fails, check the server address, port, and security layer. Fix any configuration loading errors first; switching servers usually will not help if the same broken configuration is still in use.
Separate Network Access from App Permissions
Allowing an app through the system firewall is not the same as allowing LAN devices to connect to a local port. For your first test, allow only what that connection path needs; do not open every inbound rule to troubleshoot. Handle macOS security prompts, Linux execution permissions, and Windows runtime issues separately. For installation details, see the first-install setup notes.
Once connected, record the app directory, configuration location, active core, listening port, and test app. Exit the client normally and check that the system proxy is cleaned up as expected, then relaunch it to confirm the settings persist. If the browser still points to the local port after the client exits, check for a leftover system proxy setting. Completing the start, connect, and exit checks gives you a reproducible installation baseline before adding subscriptions and rules.
4. Import Subscriptions and Manage Servers
Know the Difference Between a Subscription URL and a Share Link
A subscription URL downloads and updates a group of servers; a share link usually describes one server. Use the share-link import option for content starting with vmess://, vless://, trojan://, or ss://. Enter a subscription URL in the address field for a subscription group. Swapping the two can cause a parsing error or import plain text without creating a usable server.
Subscription URLs often contain account-specific credentials and should be treated as sensitive information. Do not include them in public screenshots or chat logs. When copying one, check the beginning and end and remove any line breaks, explanatory text, punctuation, or spaces that were included by mistake. If you scan a QR code, verify the content type recognized by the client. Avoid conversion services from unknown sources; they may expose your URL and server details to a third party.
Create a Group, Then Update It
In v2rayN’s subscription group manager, add a group, give it a recognizable name, and enter the subscription URL. Save the group and update it. On the first update, check the status message and make sure the server list actually changes. A group name is for local organization only; it does not change the remote servers. Keep different sources in separate groups to make update failures easier to trace and to prevent subscription updates from overwriting manually added servers.
If an update fails, first determine whether the download failed or the response could not be parsed. For a download failure, check whether the URL is reachable on your current network, whether it needs a working proxy, and whether the certificate and system time are valid. For a parsing failure, check that the response is a subscription format supported by the client. An account page, error page, or expired response can be returned as plain text, so “download complete” does not necessarily mean the servers were imported.
Understand How Updates Work and What They Replace
Some clients offer direct updates and updates through a proxy. If you do not yet have a working server, an update that requires a proxy can create a loop. Once you have a working connection, you can use it to reach the subscription URL. Before choosing an option, confirm which route the update traffic takes instead of repeatedly retrying through a broken entry point. If the provider requires a specific format, use a subscription import option designed for it.
A subscription update may replace entries in its group, so do not expect edits to subscribed servers to persist. If you need local changes, copy the server into a separate manual group and note why you changed it. Check before and after an update that your active server is still there, especially if names or identifiers change. An old name in the client does not prove that the connection still uses the same address; open the details to verify.
Check Key Fields After Import
After a share link is parsed, check the protocol, address, port, user ID or password, transport, and security layer. WebSocket may also use a path and Host; gRPC uses a service name; REALITY includes settings such as the public key, short ID, and server name. These fields must match the source. Do not copy settings across from another server. You can rename an entry as you like, but preserve the meaning of its connection parameters.
Test the active server after an update before setting up automatic refreshes. Set the refresh frequency to match the provider’s guidance; updating more often does not make a connection more stable. For groups you no longer use, disable automatic updates and keep only the records you need. If one group fails while others work, focus on that subscription source. For common failure cases, visit the Help Center rather than turning a localized issue into a full reinstall.
5. System Proxy and Traffic Entry Points
The System Proxy Does Not Cover Every App
The system proxy provides apps with a local proxy address, but each app decides whether to use it. Browsers usually honor the system setting; some tools have their own proxy options, and others ignore the system proxy entirely. Turning on “Automatically configure system proxy” does not mean all traffic now goes through the core. To verify the entry point, use a test app known to honor the system setting.
“Clear system proxy” usually removes the current system proxy settings, while “Do not change system proxy” leaves the existing state alone. They are not equivalent. If another proxy was already configured, record it before switching so you can restore it. If the client exits but the system still points to its local address, apps may keep trying to connect to a closed port, making the network seem worse after the client is closed.
Routing Modes Apply After Traffic Enters
Global, bypass mainland China, and direct routing modes decide which outbound route the core uses for requests that have already reached it. They are separate from the system proxy. Switching to global routing will not capture apps that ignore the system proxy, and enabling automatic system proxy does not ensure every request goes to a remote server. First confirm that the request reaches the client, then check which outbound route it takes.
Global proxying can help you temporarily check whether the remote connection works, but verify that the current preset still excludes private networks or other exceptions. Bypass mainland China typically uses domain and IP datasets to send matching destinations directly. Direct mode prioritizes direct access for traffic entering the core. Presets vary between clients, so open the rules and check what each mode actually does rather than relying on its name.
| Setting | What It Controls | How to Verify |
|---|---|---|
| System proxy | Whether an app connects to the local proxy | Make a request and check the corresponding log entry |
| App proxy | The entry point used by one app | Check the proxy type, address, and listening port |
| Core routing | The outbound route after traffic enters the core | Check the matching rule and outbound tag |
| TUN | Traffic routed in through the system | Check the virtual interface, routes, and permissions |
Configure a Proxy for One App
If an app has its own proxy settings, choose HTTP or SOCKS to match the client’s listener. Use the loopback address and the corresponding local port. Do not enter the remote server address in a regular proxy field; the core usually needs to handle the remote protocol. An option such as “resolve domains through proxy” affects which side resolves a domain, so consider it alongside your routing policy.
Keep one clear source for an app’s proxy settings during each test. When a browser extension, system proxy, and app-level setting are all enabled, check which takes precedence. You may change the system proxy while requests still use an old port saved in the extension. Close existing connections before retrying and note which setting took effect. For everyday use, avoid duplicate entry points: fewer configuration sources make recovery and migration easier.
Choose a Combination for Your Use Case
For regular browsing, start with automatic system proxy configuration and clear routing rules. For one development tool, use its app-level proxy. Consider TUN when you need to cover apps that do not follow the system proxy. Letting LAN devices connect also requires a listening scope and firewall rules; the system proxy switch does not provide that capability. Test every new entry point separately to ensure it does not change the expected route for existing traffic.
If the browser works but another app fails, first check whether that app reaches the client; do not immediately change domain rules. If the apps reach the client but only certain destinations fail, then inspect routing, DNS, and remote connectivity. For examples of how these settings work together, see system proxy vs. routing modes. The next section explains rule order and domain strategies, assuming the entry point is already clear.
6. Routing Rules and DNS Strategies
Read Rule Matching from Top to Bottom
Routing rules determine which outbound route handles a request. Common match conditions include domain, destination IP, port, and network type. Conditions combined in one rule generally need to match together, while alternatives within a condition follow that condition’s matching logic. The core checks rules in order and selects an outbound when one matches, so specific exceptions usually belong before broad rules. If nothing matches, check the default outbound and the configuration generated by the client.
Describe the desired behavior first, then choose the matching conditions. For example, to send an internal domain directly, first confirm whether the client sees a domain or only an IP address, then choose a domain or IP rule accordingly. A direct rule for one public domain may not cover all the resources it loads, since the page can request other domains too. Use actual logs to add rules incrementally rather than sending a broad set of destinations through the same route after one failure.
Domain Strategies Determine When to Resolve Names
AsIs matches using the target information already available and does not proactively resolve domains for routing. IPIfNonMatch tries to resolve a domain to an address when it does not match the relevant rules, then continues matching against IP conditions. IPOnDemand tries to resolve the domain when a rule requires an IP. Behavior depends on the selected core. Changing the domain strategy alters routing decisions; it does not replace DNS for every app on the system.
geosite:cn selects a domain dataset, while geoip:cn selects an IP address dataset. They are not interchangeable. Matching depends on whether the data files are present and whether their contents suit your needs. Resolved IP addresses can vary with the network and over time, so one lookup does not prove that a route will always be correct. After updating datasets, test important domains instead of assuming the rules behave exactly as before.
{
"routing": {
"domainStrategy": "IPIfNonMatch",
"rules": [
{
"type": "field",
"ip": ["geoip:private"],
"outboundTag": "direct"
},
{
"type": "field",
"domain": ["geosite:cn"],
"outboundTag": "direct"
}
]
}
}
The example above is a routing snippet, not a complete runtime configuration. It depends on usable data files and a direct outbound named direct, and does not define the final route for other requests. Graphical clients may generate different tag names; map the rules in the corresponding settings rather than replacing the client’s entire configuration. The first rule handles private addresses and the second handles a domain set. Remaining rules and the default outbound determine what happens to other traffic.
Separate DNS Failures from Connection Failures
If a domain cannot be resolved, the connection usually has not reached the target service’s handshake stage. If resolution succeeds but the connection times out, the problem may involve address reachability, the routing path, or the remote service. Check the stage shown in the log before changing a setting. Some apps resolve domains themselves and pass only an IP to the proxy, so adding a domain rule alone may not help. Traffic sniffing can sometimes reveal the target domain, but it cannot identify every protocol.
Traffic sniffing attempts to identify a domain from connection details. Whether the result affects routing or changes the destination depends on the configuration. It is not a universal DNS repair switch. To access LAN names, make sure an unsuitable remote resolver has not replaced the local resolution path. Business and campus networks may use internal domains; note the existing DNS setup and access requirements before changing it.
Make Small Changes and Test Them
Add one rule at a time. Test one destination that should match and one that should not, then check whether each takes the expected route. Expand the rule only after it passes, and record its purpose. If something breaks, undo the latest change and restore the smallest working rule set before adding rules again. Do not change DNS, the domain strategy, and the server all at once; even if the connection returns, you will not know which change fixed it, making future maintenance harder.
7. TUN Mode and System Traffic Capture
A Virtual Interface Solves an Entry-Point Problem
TUN uses a virtual network interface to receive IP packets routed by the system, then passes them to the relevant components for handling. It expands how traffic enters the proxy processing path; it does not fix server settings, subscriptions, or remote network problems. First verify the same server with a regular proxy. If the basic connection is not working, adding a virtual interface introduces more variables—permissions, system routes, and DNS—and makes troubleshooting harder.
TUN does not guarantee that every request goes through a remote proxy. Traffic within its capture scope may still be routed directly, through a proxy, or handled another way by the rules. Some traffic may not enter that scope because of system routes or an app’s network interface binding. An “enabled” indicator is only one part of the status. Check that the virtual interface was created, the routes took effect, and the test app’s requests appear in the log.
Resolve Interface Conflicts Before Enabling TUN
Close other VPN connections or TUN instances that are capturing network traffic. Confirm that regular networking works, then save your current settings. Grant the permissions requested by the client. After startup, check the log for errors related to drivers, interface creation, route changes, or permissions. Do not keep toggling the switch and hoping it recovers. If startup fails, address the first clear error; a later connection timeout may simply result from the interface never being created.
The remote server connection needs a route that remains reachable. Do not let it get routed back into the same capture path and create a loop. Clients usually handle the necessary routing, but multiple network adapters, other network tools, or manual routes can change the outcome. If enabling TUN immediately cuts off all network access, turn it off to restore the baseline, then check the default route and conflicting tools. Do not bulk-update rules or subscriptions while offline.
Test DNS, UDP, and LAN Access Separately
After enabling TUN, test a regular web page first. Then check an app that actually uses UDP, along with your router’s admin page, printers, and internal services. A working web page proves only that one path works, not that every protocol does. UDP forwarding depends on the client’s capture method, the core, the remote protocol, and the server configuration. If a test fails, trace that path rather than blaming all issues on system permissions.
TUN can change the DNS resolution path, so compare domain behavior before and after enabling it. If public domains work but internal names fail, check local DNS and LAN exceptions first. If only certain address ranges are unreachable, inspect private-address rules and routing. Change the MTU only when there is evidence of fragmentation or a specific transport problem. Picking a smaller value at random can hide the real cause or reduce efficiency for other connections.
Plan Separate Recovery Steps for Desktop and Android
Desktop clients may use additional network components for TUN. The exact capability depends on how the client is packaged and implemented; do not assume every core provides the same native interface. Android clients use the system VPN interface and also need their per-app lists and background restrictions checked. An app excluded from the list or a client paused by the system can cause partial failures that have nothing to do with the remote server.
After waking from sleep or switching Wi-Fi or network adapters, verify that traffic capture is still active. A stale interface or DNS state may linger temporarily. A normal client shutdown and restart can rebuild the environment, but record the issue first so you do not lose useful evidence. If the same issue occurs after every network change, note the network type, trigger sequence, interface state, and relevant logs, then look up the symptom in the Help Center. Avoid relying on force-quitting the process as a permanent fix.
8. Routine Maintenance and Troubleshooting
Maintain the App, Configuration, and Subscription Separately
Routine maintenance involves three separate things: the client and its network components, your saved settings, and remote subscription content. Updating the client does not necessarily update subscriptions; refreshing a subscription does not automatically change local routing rules. Before maintenance, identify the problem you want to solve and update only the relevant part. If you replace the client, core, and rules all at once, it will be hard to tell which change caused a problem.
Before updating the app, export the settings you need and check what the backup includes. Some exports save servers but may omit routing, subscription groups, or interface settings. Copying the whole runtime directory may not work for restoring across platforms. Check that the import feature can read the backup file. Backups can contain account details and subscription credentials, so restrict access to where you store them rather than placing them in a public shared folder.
Follow a Consistent Troubleshooting Order
If nothing connects, first disable traffic capture and check that the basic network works. Then check the client process and core, the app’s entry point, the active server, the handshake, and access to the destination. If only some apps fail, compare whether they use the same entry point. If only some domains fail, focus on routing and DNS. This order follows the dependencies and prevents you from changing downstream rules while an upstream step is still broken.
Collect logs around one specific action. Note the test time, app, destination type, and active mode. Clear unrelated old output, then reproduce the issue. For a configuration parsing error, check the affected field and core compatibility. For an authentication or handshake error, verify the parameters and system time. For a timeout, check the connection address, outbound route, and network. The word “timeout” alone does not prove a server is permanently down or a protocol is unsuitable.
| Symptom | Check First | Do Not Jump to the Conclusion That |
|---|---|---|
| No matching request in the log | App entry point, port, and traffic capture scope | The server must be unavailable |
| Startup reports that the listener failed | Port conflicts, duplicate instances, and permissions | The subscription is invalid |
| Only some domains fail | Resolution, rule order, and destination status | The client must be reinstalled |
| Connection fails after locking or waking the device | Background restrictions, network adapters, and connection recovery | All servers need to be replaced |
Match Test Metrics to the Task
Latency usually measures a probe’s round-trip time; a speed test measures data transfer under specific connection conditions. Neither substitutes for the other. A server with a good probe result may still be a poor fit for your task because of the target service, concurrency, or time of day. Test with the apps you actually use and keep test frequency reasonable. Bulk tests generate connections and traffic and can disrupt a download or meeting in progress.
An incorrect system time can affect a secure handshake, so check the clock and network state after waking from sleep. If switching to another network restores the connection, investigate the original network path, but do not assume you have identified one specific device as the cause. Compare with the same client and settings on a different network, or keep the network unchanged and try one server known to work. Change only one major variable per comparison.
Remove Sensitive Fields Before Sharing Diagnostics
To start troubleshooting, provide the client name, platform, selected core, mode, and full error stage. Hide subscription URLs, user IDs, passwords, public-key-related details, and server information that should not be public. Do not upload the entire configuration directory. Logs may also contain destination domains and local file paths, so review the context before sharing. Keep enough information to explain the error while removing unrelated personal data.
Once the setup is stable, keep a short maintenance note: what changed, why, how you tested it, and how to undo it. If a problem occurs, restore the last known working state instead of repeatedly importing the same subscription or reinstalling the app. For common quick answers, see a quick guide to common connection issues. If the problem still reproduces after restoring your baseline, trace it through the entry point, DNS, routing, and remote connection.
9. Advanced Configuration and a Testing Path
Inspect Generated Configuration Before Customizing It
Once you are comfortable with the graphical interface, use the client’s configuration preview or export feature to understand what it generates. Focus on inbound, outbound, routing, DNS, and logging, and see how an interface option maps to a configuration field. Read first; do not rush to edit. A client may regenerate its files at startup, so direct edits to the active configuration may not persist or may be overwritten when you switch servers or update a subscription.
Custom configuration is useful for a specific need the interface does not cover, not as a substitute for understanding the basic request path. Save the original configuration, confirm that the selected core accepts the syntax, and test one small change. Outbound tags must match the rules that refer to them, ports must not conflict with existing listeners, and a snippet may depend on data files or components that are not included. If startup fails, return to the last working configuration instead of stacking on more fields.
Use Small Experiments to Understand the Boundaries
The following basic example configures a local SOCKS inbound and a direct outbound. Use it in an isolated test environment to understand how an entry point and outbound route work together. It does not connect to a remote proxy server and cannot replace your imported server configuration. Use it only if the example port is free and the active core accepts the fields. If you use a graphical client, prefer setting up the equivalent through its interface.
{
"log": {
"loglevel": "warning"
},
"inbounds": [
{
"tag": "local-socks",
"listen": "127.0.0.1",
"port": 10808,
"protocol": "socks",
"settings": {
"auth": "noauth",
"udp": true
}
}
],
"outbounds": [
{
"tag": "direct",
"protocol": "freedom",
"settings": {}
}
]
}
This experiment checks whether an app can reach a specified port, then whether the direct outbound works. It leaves remote authentication and security handshakes out of scope, so it can help explain a local entry-point failure but cannot prove the remote server works. Restore your original configuration after testing; do not mistake a temporary direct-connection setup for your everyday proxy configuration. The point is to understand the variables, not to copy every example into one ever-growing configuration file.
Learn Protocols and Transports as Needed
Start learning a protocol by identifying the fields that must match: user identity, transport, security layer, and any optional extensions. Then learn which connection stage each field affects, and only after that look at performance. REALITY and XTLS Vision are specific technical combinations. Whether they work depends on the client core and server configuration; changing one dropdown is not enough to migrate. For background, see the notes on REALITY and XTLS Vision.
When comparing transports, keep the network, server resources, test destination, and timing as consistent as possible. Differences in response from different services cannot be attributed to a protocol name alone. Connection reuse, UDP handling, and DNS strategy can also affect the results, so test them separately. If you have no specific need, keep a compatible, stable setup. Changing several components at once to pursue a theoretical advantage makes it impossible to tell what changed performance.
Turn Advanced Changes into Maintainable Configuration
For each advanced setting, document its purpose, prerequisites, expected behavior, and rollback steps. For example, record the match conditions and default outbound for an app routing rule, the affected resolution path for a domain strategy change, and the LAN and network-switching tests for TUN. Describe what the setting actually does, not just how it looks in a screenshot; interface changes can make screenshots hard to interpret later.
A final regression test should cover restarting the app, updating subscriptions, switching networks, waking from sleep, and exiting normally. Confirm that the setup does not depend on a connection state that happened to persist. If a feature works only in a particular sequence, investigate the dependency instead of treating the sequence as a permanent fix. You have completed this path from beginner to advanced when you can explain a request’s entry point, resolution, rule match, and outbound route—and restore your baseline when something fails.
For follow-up, return to the section that matches the issue: reinstalling is covered in Section 3, server updates in Section 4, apps not reaching the client in Section 5, routing failures in Section 6, and virtual interface problems in Section 7. To repeat the shortest connection setup, go back to the quick-start guide. To switch platforms or package formats, visit the downloads page and choose the right client. Keep downloads, configuration, and troubleshooting as separate steps.