V2Ray Protocol and Core Guide
First, distinguish proxy protocols, transports, and security layers. Then check that the client preserves the parameters required by the server. Setting up for the first time or importing a subscription? Follow the main steps in the setup guide to connect and verify your setup. Return to this guide for protocol choices and compatibility questions.
Protocol and configuration layers
A node type describes only one layer
A graphical client saves remote connections as nodes. Each node needs to specify at least where to connect, how to establish the proxy session, how to carry data, and whether to use a separate security layer. VMess, VLESS, Trojan, and Shadowsocks are proxy protocols. They define how the client supplies credentials, specifies the destination, and sends session data. TCP, WebSocket, and gRPC are transport options that determine how this data reaches the server. TLS and REALITY are security layer options, not session formats alongside VLESS in a proxy protocol menu. Some interfaces combine several fields in a node name for easy identification, but that label cannot be used to reconstruct the configuration.
Take a combination of VLESS, WebSocket, and TLS: the client connects to the endpoint, validates TLS, establishes a WebSocket connection using the configured path, then starts a VLESS session over it. If a reverse proxy terminates TLS at the endpoint, the remote domain usually points to that proxy, not the core process. Opening the domain in a browser only confirms that the web endpoint is reachable. It does not prove that the WebSocket path is forwarded or that the server recognizes the supplied user ID. Likewise, valid proxy credentials cannot fix an incorrect path. Checking the configuration from the outside in helps avoid repeated guesswork with authentication fields.
| Layer | Common fields | What does this field tell you? |
|---|---|---|
| Endpoint | Address, port | Where does the connection actually go? |
| Proxy session | Type, user ID, password | How does the server identify the request? |
| Transport | TCP, WebSocket path, gRPC service name | How is data delivered to the backend? |
| Security layer | TLS、REALITY、SNI | How is the outer secure connection established and verified? |
Address, SNI, Host, and path are not interchangeable
The address and port determine where the client connects. During the TLS handshake, SNI tells the endpoint which service name is being requested; the certificate must also be checked against the name the client uses for validation. The WebSocket Host is an HTTP request field that the recipient may use to select a virtual host. The path determines which handler on that host receives the request. These values often happen to match or share a domain, but they serve different purposes. An endpoint might require the address to use the connection domain, SNI to use a name covered by the certificate, and Host to retain a separate value. A script or client automatically filling a blank field with the address does not mean the server accepts that assumption.
A port number does not identify a protocol, either. Common TLS ports can carry different applications, and nonstandard ports can also use TLS. Before changing a port, find out what the endpoint actually listens on rather than guessing from the number whether it is encrypted. If the client shows the transport as automatic after import, check the node details or diagnostic output for the actual setting; do not assume a client default came from the original subscription. If the logs show both a local listening address and a remote server address, first identify which side failed. Changing remote settings usually will not help if the local port is already in use.
A successful outbound connection is not the same as app traffic reaching it
A proxy node handles outbound traffic. Getting an app to use the system proxy, a local proxy endpoint, or TUN is a separate step; DNS and routing then determine whether requests are sent through that outbound. An app that ignores the system proxy may never send its requests to the client. Even when a node test succeeds, a destination may match a direct-connection rule, or DNS may fail before the request reaches the core. To establish a baseline, test with an app known to honor the system proxy, then check the logs for the destination and expected outbound. If only TUN mode fails, first check virtual adapter permissions, routing, and DNS before considering a protocol change.
VMess and VLESS
VMess: understand legacy fields before checking compatibility
VMess is an earlier session protocol in the Project V ecosystem. Its design combines user authentication with the protocol's own data security mechanisms. It can run over different transports, so nodes with the same protocol may use plain TCP or WebSocket with TLS. The user ID in the configuration form identifies the account; the VMess encryption option controls how the session data is handled. TLS is an outer connection security option. Enabling TLS does not replace VMess authentication, and having encryption settings in both places does not make them interchangeable.
Older configurations often include alterId. Modern VMess AEAD configurations typically use a value of zero. If you see a nonzero value, check whether it is a leftover from an old export or whether the server really uses a legacy method the client no longer supports. Setting it to zero only changes the request sent by your client; it does not automatically migrate the server. Similarly, if auto appears in the VMess encryption menu, it usually means the core selects the data encryption option automatically. It does not detect the transport, security layer, or server port. When a subscription contains legacy fields, asking the server to re-export the node is usually easier than changing a series of unknown parameters.
VMess authentication depends on the system clock. After a device wakes from sleep, its time is changed manually, or automatic time syncing stops, other websites may still load while VMess requests fail during authentication. Check the device's actual time, not just the displayed time zone; changing the time zone does not correct a clock offset. Both the client and server clocks may be wrong. After correcting the time, retry with the same endpoint, transport, and account to see whether the clock caused the failure. If you also switch nodes and change DNS, even a successful connection will be hard to diagnose.
VLESS: consider session overhead separately from connection security
VLESS separates the session identifier from connection protection. In common deployments, the client starts a proxy session with a user ID, while TLS or REALITY establishes the secure outer connection. Existing share links often include encryption=none. This describes the VLESS protocol encryption field in these configurations; it does not mean the outer connection needs no protection, and it does not mean to disable the security layer. If the server has additional requirements, use the parameters specified for that core and server. Do not assume a default in one share link applies to every implementation.
VMess and VLESS interfaces both have user ID fields that look like UUIDs, but similar-looking fields are not the same thing. Switching a node's type to VLESS makes the client send a different session request, which requires a matching server inbound. Do not copy the VMess encryption option into VLESS, or migrate every VMess node in a subscription just because one VLESS node works. If the server offers both types of endpoint, create or import them as separate nodes. Keep their original names and connection settings to make comparison and rollback easier.
Narrow down the cause by failure stage
First check whether the specified address and port are reachable, then distinguish the outer handshake from inner authentication. If the logs show that the outer TLS certificate was verified but the peer still closes the session, check that the protocol, user ID, transport, and flow control match the server. If failures only affect a few long-lived connections, do not conclude from a single short request that the session layer is stable. Routing rules, idle connection timeouts at the proxy endpoint, or stale connections after a network change may only show up in longer sessions. Change one field at a time and retry with the same app and destination. Without server logs, “connection closed” narrows down the possibilities but does not prove which field is wrong.
Trojan and Shadowsocks
Trojan: check the outer certificate and session password separately
Trojan is designed around a TLS connection, with proxy data sent through the established TLS channel. For a classic configuration, check the endpoint address and port first, then the certificate name and trust chain, and finally the proxy password. The client password is neither a certificate password nor an account password. A valid certificate only confirms the expected peer at the TLS layer; it does not mean the password was accepted. Conversely, a correct proxy password cannot fix an expired certificate, an incomplete certificate chain, or validation failures caused by an incorrect device clock.
Graphical clients sometimes offer Trojan with additional transport options. These combinations depend on a specific implementation and deployment; they are not a default format supported by every Trojan service. An endpoint behind a reverse proxy may require a path or service name, while a regular TLS endpoint may not need those fields. When you receive a node, check whether transport parameters are actually specified and compare them with the service provider's instructions. Do not fill blank fields just to complete the form. If the certificate name differs from the address, confirm the required SNI and validation name. Do not disable certificate verification as a normal configuration, because that removes a critical check on the connection's destination.
A TLS connection closing immediately after it is established does not necessarily point to a password problem. The peer may accept proxy requests only on a specific transport endpoint, or the request may reach the TLS frontend but not the backend. Check the logs to confirm whether the handshake actually completed, then verify the endpoint type, transport fields, and password separately. If you already have a working entry, copy it and change only fields the server explicitly says have changed. Do not fill gaps with a webpage address or fields from another node. If the password contains reserved characters, distinguish percent-encoding in a share link from the original text entered in a form. Decoding the same password twice may change its value.
Shadowsocks: the encryption method is a protocol parameter
Shadowsocks was originally designed as a straightforward encrypted proxy, encapsulating the destination address and app data in an authenticated or encrypted session. The exact mechanism depends on the selected method and generation. Modern configurations commonly use AEAD methods such as aes-128-gcm or chacha20-ietf-poly1305. Use the method specified by the server; the same password paired with a different method creates an incompatible request. Do not switch to an algorithm just because it runs faster on your device unless the remote server is changed to match. For a legacy method, first check whether the current core supports it and whether the server can provide a maintained alternative.
Shadowsocks 2022 methods use different names and key requirements from earlier AEAD methods. Some require an encoded key of a specific length and may also support multi-user parameters; a regular password may not pass local configuration checks. Being able to import ss:// does not mean the core supports the method or its extensions. After import, check that the method was preserved, then verify the credential format and extension parameters. If the node includes additional components that have no matching fields in the client, check the client's and core's implementation support. The link prefix alone is not enough to establish compatibility.
Test UDP separately
If a node can load webpages, that usually only confirms that at least some TCP requests succeed. Apps such as real-time calling may need UDP; whether they work also depends on whether the app sends traffic to the client, how the core handles it outbound, whether the server accepts it, and whether routing selects the right path. A common source of confusion is that some apps bypass the local proxy endpoint in system proxy mode. Test with an app that needs UDP and check the logs to see whether its traffic reaches the expected outbound. If the request is missing from the logs, fix app routing and rules before investigating outbound protocol support. Keep the webpage test result separate rather than combining both checks into a single “connected” status.
REALITY and XTLS Vision
A single node can include all three names
A common Xray node may use VLESS for the proxy session, REALITY for the outer secure connection, and xtls-rprx-vision as the VLESS user's flow control value. A server may offer VLESS with TLS, or VLESS with REALITY without requiring Vision. One name does not tell you the values of the other two. Client editors usually show the protocol, transport security, and flow control separately. Confirm the endpoint's supported combination first, then enter each setting in its own field. Do not treat these names as different options in the same menu, or confuse an empty flow field with the client ignoring flow control.
In Xray, REALITY provides a handshake method that differs from conventional certificate-based deployments. The server can configure the environment needed for the handshake without issuing a regular website certificate specifically for the proxy endpoint. The client still needs the correct server authentication parameters. A form may call the client parameter a public key, or display a name that has changed as core fields have evolved. Use the value the server provides for clients, not the server's private key. The server name and short ID must also match the server configuration. A short ID may look like hexadecimal text, but valid syntax does not guarantee server acceptance. Whether it can be left blank is also determined by the server.
Fingerprint determines the client handshake profile. A common value such as chrome selects a handshake template provided by the core; it does not select a browser installed on the device or identify its hardware. SNI also does not mean you should replace the server address with the same name: the address specifies the actual connection endpoint, while the name must still follow the server's requirements. If an importer combines these fields, use a client that supports them separately or ask the service provider for a fresh export. Do not make the two values identical just to clear an interface error.
Vision reduces redundant processing on some data paths
Apps often use TLS themselves. If the outer proxy connection encrypts this already-encrypted data again through a conventional path, that can add copying, encapsulation, and cryptographic overhead. Vision optimizes data paths that meet specific conditions; it does not mean all app traffic takes the same route or cancel the handshake and peer authentication. It is not a network speed boost. If throughput is already limited by the remote exit, Wi-Fi signal, or destination throttling, reducing local work may not shorten a download. To compare results, keep the server and network conditions the same, and measure the first response separately from sustained transfers.
Check the field structure before testing the connection
This JSON is a minimal snippet showing where Xray native outbound flow control belongs: flow is a VLESS user field. Use it to check an existing entry when merging; do not overwrite an entire outbound configuration with this snippet. The command below checks whether the core can read a saved, complete configuration. Run it in the directory containing the Xray executable, or replace the program name with its actual path.
{
"flow": "xtls-rprx-vision"
}
xray run -test -config config.json
A successful local test only shows that this core can read the configuration. It does not confirm that the public key, name, short ID, or user ID matches the remote server, or that the port is reachable. A complete configuration generated by a graphical client may include other outbounds and local endpoints, so do not start it with just this snippet. During troubleshooting, first check whether the core rejects a flow control or security layer field, then use the logs to see whether the endpoint connection failed or the handshake was rejected. To distinguish the data path from the handshake, see How REALITY and XTLS Vision Work. There is no need to infer configuration structure from a single speed test.
Xray and V2Fly core compatibility
A shared ecosystem does not mean configs stay interchangeable
Project V provides the foundation for organizing proxy connections into inbounds, outbounds, routing, and transport modules. V2Fly continues community development of the V2Ray core. Xray grew from the same ecosystem as a separate implementation, with its own direction for protocol extensions and transport security. Some JSON structures, protocol names, and terminology are similar because they share a design history, but they are not different names for the same binary. Whether a configuration works depends on the core and its features, not simply on whether a guide is titled V2Ray or Xray.
Entries using shared features such as VMess may work with either core, but transport type, authentication method, and the client's generated configuration still need checking. For VLESS entries that depend on REALITY or XTLS Vision, choose an Xray setup that explicitly supports that combination. Do not assume extensions are compatible just because another core recognizes the VLESS name. A configuration is more than one outbound, too. Native JSON may include dedicated DNS settings, routing match rules, external data file references, statistics APIs, or inbound sniffing options. A single incompatible setting can prevent the entire configuration from loading.
| Platform | Client | What to check |
|---|---|---|
| Windows | v2rayN | Desktop or classic WPF version, and the core actually enabled for the node. |
| macOS | v2rayN | The package matches the processor architecture, and the client can launch the required core. |
| Linux | v2rayN | The package format and architecture match the distribution, and required resource files are readable. |
| Android | v2rayNG、v2flyNG | Use the former for Xray configurations and the latter as a V2Fly alternative. |
Start migration with one outbound
For desktop, start with v2rayN. After selecting a node, check the actual running core in the interface or startup logs. A client can manage nodes without generating them the same way for every protocol. Before switching cores, keep the original nodes and rules locally and note the current local proxy port, system proxy, or TUN settings. Do not overwrite the client's generated configuration with an entire old JSON file. Start by importing one node supported by both cores, then retest with the default route and a clearly defined app connection method. Once it works, restore custom DNS, routing, split-routing data, and extra inbounds one at a time, verifying behavior at each step.
Treat local messages about unknown fields, unsupported methods, or unreadable resources as configuration loading issues first, not remote latency problems. A node appearing in the list only proves the client accepted the input; the core may not have started. If the core starts but some websites still fail, check whether routing behaves as before. A preset with the same name may reference different data, and rule order may change which match takes precedence. If one node works but restoring multiple rules causes failures, rolling back the last batch of changes is usually easier than reimporting the entire subscription.
During migration, sort changes into three categories: form display, core syntax, and runtime environment. If a form label changes but the generated value stays the same, the server usually does not need changes. If the core does not recognize a field, choose a supported combination. Permission errors and local port conflicts in the logs point to the runtime environment. Each category needs a different fix. To understand how the cores are related and how their fields have evolved, read Xray Core vs. V2Fly Core: Key Differences, then check the current client settings instead of deciding whether to migrate based only on an old configuration screenshot.
Subscription formats, imports, and field migration
Subscription URLs, share links, and native configs are different inputs
A subscription URL lets the client fetch a set of entries remotely. A single share link carries common fields for one connection. A native configuration can describe an entire runtime setup. A subscription may return one share link per line, encoded text, or a structured document for a particular client. Being able to open the URL in a browser only means the request returned content, not that the client recognizes its format. If the response is actually a login page or error message, the client may show an empty list. First make sure the subscription URL is valid and the content matches the client's requirements, then check the entries.
Common vmess:// share links can encode an object, but field conventions vary. vless:// and trojan:// often use an address and query parameters to specify transport, security, and endpoint settings. Shadowsocks also has multiple share link formats. Do not assume every format uses the same Base64 wrapper, or that readable decoded text means parsing succeeded. Percent-encoding affects passwords, paths, and query values; symbols in a remark can also change how a link is split. Use the client's built-in import feature instead of manually assembling a full link with credentials. If needed, ask the server to generate an entry for your client.
Verify parameters after import, not just the node count
Start with a node you plan to use and compare four groups of fields: protocol type, endpoint, outer security, and transport. For WebSocket, check the Host and path; for gRPC, the service name; for REALITY, the client authentication parameters and short ID; and for Vision, the flow control. Then check whether TLS SNI inherits the address and whether that matches the service provider's instructions. Some converters preserve only fields shared by both formats, leaving a node in the list but dropping its service name. Some clients display a field that the currently selected core does not support. Check both the imported entry and runtime logs to locate whether the problem is in the parser or the core.
An importer does not convert one proxy protocol into another. Subscription conversion usually rearranges or re-encodes the same connection parameters; it cannot make a VMess server accept VLESS or guarantee that special transports, flow control, and routing rules migrate intact. If an older client has no field for a required parameter, first use a subscription adapted by the service provider. When retrieving a configuration through a subscription URL containing sensitive information, use the client's own import feature where possible. Giving the full URL to a third-party converter may also hand over access to the subscription.
Handle refresh overwrites and duplicate entries
Clients usually manage subscription groups. After a refresh, locally edited names, flow control, or routing choices may revert, depending on how the client matches and overwrites entries. To test a field, first copy the entry into a separate manual group and keep the original for reference. If a refresh creates multiple entries with the same name, compare protocol, address, port, and transport before deciding whether they are duplicates; names may only describe a region or purpose. If the server rotates credentials, refresh the active group first and check whether the selected entry is an old copy. There is no need to delete every entry up front.
A subscription that refreshes successfully while connections fail only proves that the subscription service is reachable, not that the node endpoint is. A working node with failed subscription updates may instead indicate an expired subscription, a parsing error, or an update request using a different outbound. Follow the subscription import guide for the basics. If a refresh breaks a working setup, test one newly fetched entry on its own. If the endpoint stays the same but the security layer changes, check that the new fields were preserved. If the protocol type changed too, validate it as a new node rather than relying on the old entry's test results.
Connection speed, resource use, and mobile battery life
Measure first response separately from sustained throughput
The wait for a short request may include local DNS, connecting to the endpoint, a TLS or REALITY handshake, transport setup, the proxy session, and the destination's response. A client latency test may only connect to the port, or it may send a request through the node to a fixed destination; these results are not directly comparable. If the port connects quickly but the full request is slow, look at the handshake and destination path. Caching, redirects, or throttling at the test destination can also hide protocol differences. For real-world use, record cold-connection first response, repeat requests on a warm connection, and sustained transfers separately instead of ranking every node by one latency number.
Sustained throughput depends on link bandwidth, round-trip time, packet loss, server egress, CPU capacity, and app concurrency. Common VLESS session formats have low overhead, but outer handshakes, reverse proxies, and transport paths still add cost. VMess session encryption uses CPU resources, so the real difference depends on the processor and workload. Common Trojan paths require TLS. Shadowsocks overhead varies by method and implementation. Devices with hardware acceleration and low-power devices may produce different rankings. An extra transport layer does not necessarily make the experience worse: it may reuse an existing connection or provide a better route to the backend in a particular deployment. Be clear about what you are comparing.
Multiplexing does not improve every metric
Mux puts multiple logical sessions over fewer underlying connections. This can reduce connection setup overhead in some scenarios, but congestion, packet loss, or a reconnect on the shared connection can affect all sessions using it. When long and short requests share a connection, a few large streams may also hurt responsiveness. Both client and server must support the selected multiplexing mode, and not every flow control or transport combination is suitable. Start with the default settings, then change only multiplexing and test webpages, long downloads, and the concurrent apps you actually use. If peak throughput improves but interaction slows down, record those results separately rather than hiding the difference in one overall score.
On mobile, check background wakeups and traffic capture first
Mobile battery use is not just about encryption. A wider TUN capture scope sends more traffic through the proxy processing path. Frequent keepalives, subscription refreshes, speed-test polling, and retries can all keep the wireless radio from sleeping. Weak cellular reception or switching between networks may increase reconnects. Track idle drain with the screen off separately from high power use during downloads. For the former, look at background activity first. For the latter, consider CPU load, traffic volume, and wireless conditions.
To compare, use the same network, similar signal strength, and a fixed time window, with the same background apps running in both tests. Keep the original configuration in the first round; in the second, change just one clearly defined setting, such as pausing periodic speed tests, narrowing the capture scope, or trying another combination offered by the same server. If the endpoint location, route, or device power mode also changes, the result describes the overall experience, not the protocol. When checking system battery stats, look at both the client and system network services. Different operating systems measure power differently, so one process's percentage is not the proxy's total energy use. If apps become unreachable as battery use rises, check for a retry loop first.
Choosing a protocol for your use case
Using an existing server? Follow its connection instructions, not protocol preferences
If the server offers only one endpoint, your choice is the client and core that can represent it completely. On desktop, start with v2rayN and use the download page to choose a package for your operating system and processor architecture. On mobile, for VLESS with REALITY or entries using Vision, first check the relevant settings in v2rayNG. Consider v2flyNG if you specifically need V2Fly-side features. Import an entry provided by the server and verify that all fields are present, the core starts, and the target app actually uses the outbound. Do not skip checks for the security or transport layer just because the interface has an option with the same name.
If the server offers several endpoints, ask whether they share the same exit, use different frontends, or have different transport restrictions. If a VMess node works with your current client and meets your needs, there is no need to migrate it just because newer protocols exist. If you already have a routine for managing standard certificates and TLS endpoints, maintain Trojan's certificate and password separately. For Shadowsocks, include the method and key format in your client compatibility checklist. Consider VLESS with REALITY in an Xray setup only if the server offers it, the client can fully parse it, and the combination and flow control meet your requirements. No configuration replaces real connectivity and resource testing.
Multiple devices, long-lived connections, and per-app routing
When sharing a subscription across devices, start by verifying one node on the two devices you use most. The goal is for each parser to preserve the same server parameters, not for every form to use the same labels. If one device cannot recognize an extension, ask the provider for a compatible endpoint. That may be easier to maintain than removing the extension across every device. Sync node names and server endpoints, but keep local proxy ports, system routes, and permissions specific to each device. If one device runs into trouble, the others can still retain their verified configurations.
For apps that rely on long-lived connections, voice, or frequent network changes, test session recovery, UDP availability, and TUN capture as separate requirements. Test long-lived connections through screen lock, returning to the foreground, and switching networks. If connections drop only while locked but remain stable in the foreground, first check system background restrictions and the app's reconnect behavior. If only a few apps need the client, check whether the system proxy is enough before expanding capture with the TUN mode guide. For split routing, check rule order using the routing guide. Capturing more apps does not add outbound capabilities, and capturing fewer does not change the node protocol.
Keep results you can verify before rollout
Start with a known-working baseline node. Record the client, core, protocol, transport, security layer, and connection mode without exposing personal credentials. Use the same app to test once from a closed client through reconnecting, then try a task you actually use. Keep the baseline when testing another setup and repeat the same steps. If only one domain fails, check DNS and rules. If there is no traffic at all, check app routing and the local listener. If the core exits on startup, check the configuration file, ports, and permissions. A logged-in session or an “connected” label is not a complete test. For detailed troubleshooting branches, see the connected but no internet checklist.
After checking the setup, keep the original server-provided entry and a field summary with credentials removed. When upgrading the client, test the original configuration first, then import any updates. Do not combine an app upgrade, core switch, subscription conversion, and routing changes in one test round. Your reason for choosing a setup should fit in a specific statement, such as “The existing endpoint requires a particular flow value, the client preserves it, and long-lived connections have been tested.” If you cannot make that statement yet, first identify whether you are missing connection details, core support, or test results, then decide what to do next.