Clash TUIC v4 / v5 Outbound Configuration and QUIC Parameters

Proxy Protocols

Authentication fields determine the version

TUIC runs over QUIC and TLS 1.3. The current core has no separate version field; it selects the protocol branch from the authentication fields. A nonempty token selects v4; otherwise, v5 is used.

Both versions require a name,type: tuic, server, and port. v4 also requires a token; v5 requires a UUID and password. The client version must match the server.

TUIC v4 and v5 authentication fields
Protocol version	Required	Must be omitted	Selection condition in the current implementation
TUIC v4	`token`	`uuid`、`password`	token is nonempty
TUIC v5	`uuid`、`password`	`token`	token is empty

nameRequired: The node name, used by policy groups and rules.
type: tuicRequired: Selects a TUIC outbound.
server / portRequired: Enter the server address and a single UDP listening port.
tokenTUIC v4: The v4 user identifier. Do not provide it for v5.
uuid / passwordTUIC v5: The v5 user UUID and password. Do not provide them for v4.

Server address and TLS validation

TUIC uses TLS 1.3. If sni is not specified, server is used as the server name. If alpn is not specified, the client uses h3. The connection address, SNI, and certificate name can be controlled independently, but their relationship should remain coherent and explainable.

ipOptional: Overrides the DNS result for server. This changes only the actual connection IP, not the default SNI.
sniTLS: Sets the TLS Server Name. This is especially important when the connection IP differs from the certificate domain.
alpnDefault: h3: Enter the ALPN list supported by the server; the default usually does not need to be overridden.
skip-cert-verifyRisk: Skips certificate validation. Enable only when you clearly understand the risk.
name-cert-verifyTLS: Specifies a separate certificate-name validation target.
fingerprintTLS: Pins the server certificate fingerprint.
certificate / private-keymTLS: Provide both when the server requires a client certificate.
ech-optsCurrently has no effect: TUIC options can parse this field, but the current dialer does not apply it to the TLS handshake. Do not treat entering it as enabling ECH.
disable-sniHigh risk: Clears the TLS Server Name. The current implementation also forces certificate validation to be skipped; it does more than hide SNI.

QUIC setup and connection lifecycle

TUIC latency options alter the QUIC handshake, timeouts, and concurrent-stream behavior. The defaults cover normal use; override them only when the server or troubleshooting evidence provides a reason.

heartbeat-intervalDefault: 10000 milliseconds: The interval for sending QUIC keepalive heartbeats. The unit is milliseconds, not seconds.
reduce-rtt0-RTT: Allows QUIC 0-RTT to reduce connection setup time, but early data may be vulnerable to replay.
request-timeoutDefault: 8000 milliseconds: Timeout for establishing a TUIC proxy request. The current implementation reads it only in the v4 client branch; v5 ignores it.
congestion-controllerOptional: Options are cubic, new_reno, and bbr. When omitted, the QUIC library retains its default behavior.
bbr-profileBBR only: Selects the standard, conservative, or aggressive preset for BBR.
max-open-streamsDefault: 100: Limits the number of concurrently open QUIC streams. A high value can increase memory use and scheduling pressure.
fast-openOptional: Reduces the wait for proxy-request setup. The current TUIC v4 client branch uses this field directly.

UDP relay and packet size

TUIC supports both TCP streams and UDP relay. The UDP relay mode must be compatible with the server implementation, and packet size must respect the path MTU; a larger value does not mean higher throughput.

udp-relay-modeDefault: native: Options are native and quic. The current implementation uses native unless quic is explicitly selected.
max-udp-relay-packet-sizeDefault: 1252: Maximum UDP relay payload. The client also adjusts it for the QUIC Datagram limit and v4/v5 header overhead.
max-datagram-frame-sizeAdvanced: Controls the QUIC Datagram frame limit. The current implementation caps it at 1400 bytes.
disable-mtu-discoveryAdvanced: Disables path MTU discovery. Use only after confirming an MTU problem on the link.
recv-window-conn / recv-windowAdvanced: Control the per-stream and connection-level QUIC receive windows, respectively. Usually keep the defaults.

Port, obfuscation, and session boundaries

TUIC and Hysteria2 both use QUIC, but they do not offer the same configurable features. Do not guess and copy fields from one protocol to the other based on their names.

Cross-protocol fields unsupported by TUIC
Capability	TUIC behavior	Do not use
Port	Single `port`	Hysteria2's `ports`、`hop-interval`
Obfuscation	No protocol-specific obfs field	salamander、gecko、obfs-password
Connection keepalive	heartbeat-interval and QUIC streams	AnyTLS idle-session-*
Authentication	v4 token or v5 UUID plus password	Hysteria auth-str

v5 and v4 configuration examples

The examples below define two separate nodes. In production, keep only the authentication field set that matches the server version.

Leaving token in a v5 node causes the current implementation to create the client through the v4 branch.
An invalid UUID cannot pass v5 server authentication.
Entering 10 for heartbeat-interval as though it were seconds actually makes the interval 10 milliseconds.
Enabling disable-sni while expecting normal certificate validation is unsafe; the current implementation also skips certificate validation.

proxies:
  - name: tuic-v5
    type: tuic
    server: server.example.com
    port: 10443
    uuid: 00000000-0000-0000-0000-000000000001
    password: replace-with-v5-password
    sni: server.example.com
    alpn:
      - h3
    udp-relay-mode: native

  - name: tuic-v4
    type: tuic
    server: server.example.com
    port: 10443
    token: replace-with-v4-token
    sni: server.example.com
    alpn:
      - h3
    udp-relay-mode: native

Previous articleHysteria2 Next articleWireGuard