VMess

VMess outbound fields

This page describes clients in the Clash ecosystem proxies VMess outbound fields in the array; it does not replace VMess server documentation. Client authentication, transport, and TLS parameters must match the server field by field.

A minimally parseable node consists of the common required fields and the required VMess fields. UDP, TLS, and other transports depend on the actual server deployment.

nameRequired

The node name, which must be unique within the configuration.

typeRequired

Set this to vmess。

serverRequired

The domain name or IP address of the VMess server.

portRequired

The server's listening port, which must match the server.

Authentication, version, and encryption fields

uuid、alterId and cipher are both marked as required in the current field reference. They are not interchangeable authentication options.

uuidRequired

The VMess user ID. Use the value assigned by the server.

alterIdRequired

Modern configurations generally use 0. A nonzero value enables a legacy protocol form and should be used only when the server still requires it.

cipherRequired

Available values are auto、none、zero、aes-128-gcm or chacha20-poly1305。

global-paddingOptional

Enables VMess global padding, which adds traffic overhead. Do not enable it without a server-side or compatibility requirement.

authenticated-lengthOptional

Controls length-chunk encryption. Client and server capabilities must match.

UDP and packet encoding

Allowing UDP through the node and selecting a UDP encapsulation format are separate decisions. Providing only one field does not guarantee that UDP will work.

udpOptional

Common field; the default is false. Set it to truewhen UDP proxying is required, and confirm server support.

packet-encodingOptional

Uses the original encoding when empty. Available options include packetaddr or xudp, which must be compatible with the server implementation.

Choose a VMess transport

network Select the transport that carries VMess. An omitted value or one the current core does not recognize is treated as TCP, so an invalid value may appear as a connection timeout rather than an immediate error.

TLS, Reality, and certificate verification

TLS and Reality operate at the transport-security layer and do not change the VMess uuid、alterId or cipher. Choose the applicable configuration for ordinary TLS, Reality, or another TLS carrier according to the server.

tlsOptional

Set to true enables TLS. Do not provide it when the server does not use TLS.

servernameOptional

The VMess SNI field. When empty, it generally uses server. If the WebSocket configuration includes a Host request header, the current implementation prefers that Host as the SNI.

alpnOptional

The TLS application-protocol list. Its order and values must match the server transport.

client-fingerprintOptional

A uTLS client fingerprint, such as chrome. It is not a certificate fingerprint.

fingerprintOptional

The SHA-256 fingerprint of the server certificate, which differs from client-fingerprint .

reality-optsOptional

A non-empty value enables Reality. At minimum, verify public-key and short-idand provide it together with tls: true、servername as specified by the server.

skip-cert-verifyUse with caution

Skipping TLS certificate verification weakens identity verification and should not be a long-term troubleshooting measure.

WebSocket and TLS configuration example

The example below demonstrates only the field hierarchy for VMess, WebSocket, and TLS. Replace the domain, path, UUID, and certificate name with values supplied by the server.

proxies:
  - name: vmess-ws-tls
    type: vmess
    server: edge.example.com
    port: 443
    uuid: 00000000-0000-0000-0000-000000000001
    alterId: 0
    cipher: auto
    udp: true
    packet-encoding: xudp
    tls: true
    servername: origin.example.com
    network: ws
    ws-opts:
      path: /vmess
      headers:
        Host: origin.example.com

Common configuration mismatches

If VMess cannot connect, compare each field with the server instead of changing several fields at once.

• Writing network as xhttp or another unsupported value causes the current core to treat it as TCP, which then differs from the server transport.
• A modern server requires alterId: 0, but the client retains a nonzero value from a legacy subscription.
• The WebSocket path or Host does not match the reverse-proxy rule.
• After enabling TLS, setting servername to the node IP causes the certificate name or Reality target to mismatch.