Clash Protocol and Kernel Technical Reference

02 · TCP FAMILIES

Design trade-offs among SS, VMess, Trojan and VLESS

SS: compact structure with explicit encryption requirements

Shadowsocks is usually abbreviated as SS. Its core approach is to carry proxy traffic with a lightweight protocol structure, protecting data through a pre-shared password and selected encryption method. Modern configurations should use an AEAD method supported by the current kernel, with the server and client using exactly the same method, password and port. SS has relatively few fields, making subscription imports and cross-client migration straightforward; failures can usually be traced through the port, password, encryption method and network reachability.

Fewer fields do not mean that all SS nodes perform alike. Server implementation, hardware acceleration for the cipher, UDP relaying, plugin parameters and the underlying network all affect results. Some subscriptions also include plugin and plugin-opts to add another transport layer; if the current kernel lacks the specified plugin, the node will not work even when server, port, cipher and password are correct. On resource-constrained routers, SS is often an easy starting point, but encryption overhead should be tested on the target architecture rather than inferred from desktop CPU results.

VMess: more identity, timing and transport options

VMess comes from the V2Ray ecosystem, and its configurations often include a user identifier, alterId, encryption options, network transport and TLS fields. Older configurations commonly show different alterId values, while newer server deployments tend to use simpler combinations; clients may still retain parser fields for compatibility with legacy subscriptions. VMess authentication is sensitive to clock state. A significantly incorrect device clock can cause authentication failures, so troubleshooting should check system time synchronization as well as the address and user identifier.

VMess becomes more complex because it can be paired with multiple transports. TCP, WebSocket, HTTP and gRPC have different requirements for paths, reverse proxies and server configuration. WebSocket requires checking path and Host; gRPC requires checking service-name; with TLS enabled, also check servername, certificate verification and ALPN. Subscription converters sometimes omit less common transport fields, leaving a node name and basic details intact while the handshake always fails. Compare the single-node configuration before and after conversion field by field instead of repeatedly switching proxy modes.

Trojan: TLS transport makes certificate settings critical

Trojan usually carries traffic over a standard TLS connection, with a password as its core authentication method. Its configuration may look simple, but TLS fields determine whether the connection can be established. server is the actual connection address, while servername or SNI supplies the hostname used in the TLS handshake; they may be the same or different. When connecting through a domain, DNS resolution, certificate validity and hostname matching must all succeed. If a subscription replaces the domain with an IP address but fails to preserve the correct servername, TCP may be reachable while TLS verification fails.

Some users enable skip-cert-verify immediately to bypass certificate errors, masking problems with the domain, certificate chain or system clock. A safer order is to verify the device clock, check that servername matches the certificate name, and then inspect the server certificate chain and network path. Adjust verification only when you understand why it fails and accept the associated risk. Trojan can also use WebSocket or gRPC as its carrier. Troubleshoot it like VMess: verify TLS first, then check path, Host or service-name, and finally inspect UDP and policy-group behavior.

VLESS: less protocol overhead, with security delegated to the transport

VLESS also comes from the V2Ray ecosystem, but unlike VMess it does not provide the same encryption mechanism at the protocol layer. Confidentiality and identity verification usually come from TLS or another secure transport. It authenticates with a user identifier, and common fields include uuid, flow, network, tls, servername and transport-specific options. Its simpler protocol-layer handling makes VLESS popular for flexible transport combinations, but lighter fields do not mean that secure transport can be omitted.

VLESS compatibility issues tend to center on extensions. Different kernels may support flow, Reality, client fingerprints, transport details and UDP behavior at different times. mihomo supports several VLESS extensions, but the exact usable fields should be checked against the current kernel documentation and runtime logs. When a subscription contains unknown fields, the parser may ignore them or reject the entire node. Ignoring a field is harder to notice: the node appears imported but fails at runtime. Before moving to another client, confirm that important extensions survived conversion.

proxies:
  - name: "SS baseline"
    type: ss
    server: example.com
    port: 443
    cipher: aes-128-gcm
    password: "your-password"
    udp: true

The example above shows only the minimum structure of an SS node, for identifying field relationships. The actual address, port, password and encryption method must come from the server configuration. YAML is indentation-sensitive, and fields under a list item must remain at the same level. Passwords containing colons, hash marks or other special characters should be quoted. Configuration-load failures and connection failures are different problems: check YAML syntax and field names for the former, then network access, authentication and server status for the latter.

04 · PERFORMANCE

Connection speed, resource use and mobile battery life

Connection setup time and sustained throughput are different metrics

Web page load time reflects DNS, TCP or QUIC handshakes, TLS, server processing and the number of page resources. A lighter protocol handshake can reduce only part of that time. If DNS is slow or a page connects to many domains, a node's single-connection advantage may not translate into a noticeable experience. Sustained downloads depend more on path capacity, congestion control and the server's egress. Repeat short-connection tests across multiple targets while minimizing cache effects; run sustained transfers long enough to see whether speed remains stable, periodically drops to zero or recovers after a network change.

Multiplexing also needs careful interpretation. Putting multiple logical connections on fewer underlying connections can reduce repeated handshakes, but congestion or interruption of an underlying connection affects more traffic. Multiplexing over TCP can still be affected by loss recovery on one TCP connection. QUIC's multi-stream design reduces blocking between streams but adds user-space state management. Multiplexing may help with many short requests, while the benefit may be limited for a few long, high-volume connections. Neither enabled nor disabled should be treated as an absolute rule; test according to the application type.

CPU, memory and encryption overhead

SS resource use depends on the cipher, processor instruction set and concurrency. Desktop CPUs with hardware acceleration can process common AEAD algorithms efficiently, while some low-power architectures favor other algorithms. Trojan, VMess over TLS and VLESS over TLS all incur TLS processing; actual overhead also depends on whether the transport uses WebSocket, gRPC or additional multiplexing. In addition to encryption, Hysteria2 and TUIC maintain QUIC acknowledgment, retransmission, congestion and stream state in user space.

Memory use is rarely determined by the protocol name alone. Connection count, rule-set size, DNS cache, TUN routing, log level and provider count can make a larger difference than a single node. When a router is under memory pressure, first remove unnecessary rule sets, shorten excessive provider chains and limit verbose logging before comparing protocols. On desktops, watch for sustained growth during long runs instead of recording only the startup value. When usage rises abnormally, preserve the configuration structure and reproduction steps; that is more useful for diagnosis than simply declaring one protocol “more memory-hungry.”

Mobile battery drain is driven mainly by wakeup frequency

Phone battery life depends not only on encryption work but also on how often the wireless module and CPU wake up. Frequent node health checks, short DNS caches, continuous logging, background speed tests and aggressive keep-alive settings all increase wakeups. Even tiny per-event workloads can materially affect standby time when accumulated over hours. QUIC-based nodes may send keep-alives to maintain NAT mappings, while TUN mode processes more system traffic; with many background applications, these factors compound.

Optimize global behavior before changing protocols. Set health-check intervals to a reasonable value that meets failure-detection needs, avoid having multiple providers probe at high frequency, keep only the policy groups you use, restore normal logging after debugging, prefer a system proxy when full traffic interception is unnecessary, and make sure the LAN-access setting matches actual needs. Only then compare TCP and QUIC nodes during the same period. Keep screen brightness, app activity and network type similar during testing, or system scheduling differences may hide protocol differences.

Create repeatable test records

A test sheet should record at least the device, operating system, client, kernel, network type, interception method, DNS mode, node protocol and test period. Change one variable at a time: for example, keep rule mode and system proxy fixed while swapping SS and Hysteria2 nodes; in the next round, keep the node fixed and compare system proxy with TUN. Record both success rate and error type for every round. If two of five connections time out, the node is unsuitable as the sole member of an automatic selection group even if its successful runs are very fast.

On mobile, observe at least one full day of normal use and check the system battery page for the client's foreground and background activity. A few minutes of runtime cannot represent standby keep-alive costs. When battery use is abnormal, stop all active health checks and disable verbose logging first, then restore settings one by one to identify the wakeup source. For further background-use and power-saving steps, read How to reduce Clash battery drain on phones.

06 · SUBSCRIPTIONS

Subscription formats, configuration compatibility and field fidelity

Node links, node lists and complete configurations

“Subscription” can refer to three different things. The first is a list of protocol links, such as ss, vmess, trojan or vless links; the client or conversion service parses them into Clash nodes. The second is an already converted proxies list containing nodes but no complete rules or DNS settings. The third is a complete Clash or mihomo configuration containing proxy-groups, rules, rule-providers, dns, tun and other sections in addition to nodes. Identify the type before importing to avoid treating a full configuration as a node provider or overwriting local rules with a subscription update.

Node links are convenient for moving data between tools, but not every extension has a standardized representation. VLESS flow and Reality fields, Hysteria2 bandwidth and obfuscation parameters, and TUIC authentication and congestion-control options may be lost depending on the link format, generator or converter. Complete YAML can express more fields but makes its dependency on the target kernel clearer. When moving complex configurations among mihomo clients, retaining YAML is usually more reliable than repeatedly converting to share links.

proxy-providers manage sources, not protocol conversion

proxy-providers let mihomo load a node collection from a file or URL and update it at a chosen interval. They separate node sources from the main configuration, allowing multiple policy groups to reference the same provider. A provider health-check can periodically access a test URL to assess node availability, but its frequency affects network requests and mobile battery use. A provider reads content that the target kernel can parse; placing an incompatible format inside a provider does not automatically convert arbitrary protocols.

proxy-providers:
  primary:
    type: http
    url: "https://example.com/subscription.yaml"
    path: ./providers/primary.yaml
    interval: 21600
    health-check:
      enable: true
      interval: 1800
      url: "https://www.example.com/"

The domain in the example represents structure only. Replace url with the actual subscription address and avoid publicly sharing links containing access credentials. path points to a cache file under the kernel's working directory; interval is the update period, while health-check interval is the health-check period. These are different settings. Use a stable, lightweight test address comparable to the real network target. If several providers use very short check intervals, the client will create continuous background connections, so mobile devices require particular care.

Conversion is most likely to lose extension fields

Subscription conversion usually involves three steps: parsing the source format, mapping fields and generating the target YAML. Common fields for SS, VMess and Trojan map relatively well, while plugins, gRPC, Reality, client fingerprints, Hysteria2 and TUIC extensions are more constrained by converter capabilities. After conversion, sample at least one node of each protocol and compare key fields such as server, port, uuid or password, network, tls, servername, alpn, flow and udp. Do not compare node counts alone; equal counts can still hide missing fields.

Node names can also affect management. A converter may rename nodes to remove duplicates, while proxy-groups that still refer to old names will fail with a missing-proxy error. Referencing node collections through providers reduces name coupling, but rule targets and policy-group names must still exist. During a full migration, check the policy group targeted by every rule first, then the nodes or providers referenced by each group, forming a reference chain from rules to proxy-groups to proxies.

Valid YAML can still contain semantic errors

YAML validation can detect indentation, duplicate structures and type problems, but it cannot confirm that a remote address, password, SNI or rule target is correct. Common semantic errors include ports written as strings that some parsers reject, inconsistent boolean values, duplicate policy-group names, rules pointing to nonexistent groups, provider paths without write permission, and nodes enabling UDP unsupported by the server. Run the kernel's configuration check first, then start it and watch the first provider update, DNS initialization and node-handshake logs.

When a provider maintains the complete subscription, local changes may be overwritten on the next update. Rules that must persist should go in the client's supported override, merge or local configuration layer rather than directly editing a remote cache file. Override names and capabilities differ between clients, so export local rules before migrating. Clients such as Clash Plus can simplify configuration management, but you still need to distinguish the remote subscription, generated runtime configuration and local overrides, and confirm which layer is actually active during troubleshooting.

08 · MIGRATION

Protocol testing, configuration migration and troubleshooting

Build a recoverable minimal configuration before migrating

When moving from an older client to Clash Plus, Clash Verge Rev, FlClash or another mihomo client, keep the old working configuration and do not delete it immediately. In the new client, import only one node or one provider and create minimal rules containing DIRECT, a single proxy and MATCH. Confirm that the core starts and DNS and the system proxy work before adding full policy groups, rule sets and TUN. This separates installation, kernel compatibility and complex-configuration problems.

When moving an original Clash configuration to mihomo, most basic fields can continue to work, but still check DNS and TUN defaults. For the reverse migration, remove VLESS, Hysteria2, TUIC and other nodes unsupported by the original, along with Meta extension rules. Update policy-group references at the same time or the configuration will fail when a target is missing. Copy the file before any batch change, run the kernel check command, and only then replace the active configuration.

Read logs by phase

Startup logs answer whether the configuration can load. Focus on YAML parsing, unknown fields, provider files, listening ports and TUN permissions. Update logs answer whether remote content can be fetched and parsed; check subscription requests, response format, cache paths and node counts. Connection logs answer whether traffic matches a rule and completes its handshake; check rule targets, node names, DNS, timeouts, TLS and authentication. Mixing these phases leads to false conclusions: a successful subscription update does not prove that a node handshake succeeded.

The common dial tcp timeout means a TCP connection did not complete within the allowed time. Possible causes include an unreachable address, blocked port, abnormal DNS result or a server that is not listening. connection refused means the target actively rejected the connection, so check the port and service first. TLS errors require checking the system clock, servername and certificate. authentication failed points to a password, UUID or authentication string. If a QUIC node repeatedly times out, switch networks first to assess the UDP path, then check protocol parameters. For more log examples and troubleshooting order, see How to read Clash runtime logs.

Check ports, system proxy and TUN in layers

mixed-port is commonly used to provide HTTP and SOCKS entry points together. When the system proxy is enabled, the operating system must point to the address and port the client is actually listening on. If another program already occupies the port, the kernel may fail to start; an enabled switch in the interface does not prove that a listener exists. Close other proxy tools first and check listening errors in the logs. LAN sharing also requires allow-lan, firewall access and a correct listening address; entering the local machine's address on another device is not enough.

TUN operates at a lower interception layer and requires system permissions, a virtual network adapter or the relevant network extension. If enabling it removes network access, disable TUN and return to the system-proxy baseline. If the system proxy works, the node, subscription and basic DNS are probably fine; the issue is more likely TUN permissions, routing or DNS interception. Re-enable TUN and check automatic routes, interface selection, private-address exclusions and DNS mode one at a time. Do not change the protocol node while TUN is failing, or you will lose a useful control.

Replace protocols one variable at a time

When switching from VMess to VLESS or from Trojan to Hysteria2, keep the target service, client, rules, DNS and interception method as consistent as possible. First confirm that the new node connects by itself in a manual-selection group, then add it to an automatic-test or fallback group. Test browsing, sustained downloads, UDP applications and network-switch recovery, and record errors. If the new protocol is better only for one workload, create a dedicated policy group instead of replacing the global default all at once.

Tune complex protocols in layers: use subscription defaults in round one; adjust only transport options in round two; consider multiplexing, bandwidth or congestion control in round three; and handle TUN and DNS last. Each round must be reversible. If performance drops after tuning, undo the most recent change instead of adding more settings. Reversibility is an important production property because it provides a clear way back when updating the kernel, switching clients or changing networks.

mode: rule
mixed-port: 7890
allow-lan: false
log-level: info

rules:
  - DOMAIN-SUFFIX,example.com,DIRECT
  - GEOIP,LAN,DIRECT
  - MATCH,PROXY

This fragment shows a basic troubleshooting structure: rule mode, mixed port, LAN access, a normal log level and three rules. A real configuration also needs a policy group or proxy named PROXY. Rules are matched in order, so specific domains should come before broader GEOIP and MATCH rules. If logs show that a target matched DIRECT, stop troubleshooting the proxy handshake and correct the rule target first.

Create a final selection record

After testing, record each default node's protocol, transport, TLS hostname, suitable networks, UDP support, associated provider and fallback node. Do not save passwords or other sensitive content; record only structural information needed for diagnosis. On mobile, also note whether TUN is enabled, the health-check interval and background restrictions. On routers, record the core architecture, service startup method and rule-set source. After the next client or kernel update, retest against the same record rather than choosing again by intuition.

A final configuration does not need to cover every protocol. One or two stable TCP nodes, one verified QUIC node and clear policy groups are enough for most desktop and mobile scenarios. Too many nodes increase health-check, naming and troubleshooting costs. The purpose of this guide is not to require every technology at once, but to explain the problem each option solves, the conditions it depends on and the fallback path when it fails.