WireGuard

How WireGuard outbound works

WireGuard is a network-layer tunnel outbound in the current core. The client creates an internal WireGuard network device and sends TCP or UDP traffic selected for this node through the tunnel; it does not take over the operating system's entire default route.

The configuration must describe both the local interface and the remote Peer. The local address and private key belong to the client interface; the server endpoint, public key, and Allowed IPs belong to the Peer. These field sets are not interchangeable.

Minimum single-Peer configuration

For a single Peer, you may use the shorthand form and place the endpoint and Peer keys directly at the node's top level.ip and ipv6 At least one must be provided, or the client cannot create a local tunnel address.

nameRequired

The node name used by policy groups and rules.

typeRequired

Set this to wireguard。

private-keyRequired

The Base64-encoded client private key. Keep it secret.

ipConditionally required

The client's IPv4 address on the WireGuard network. At least one of this and ipv6 must be present.

ipv6Conditionally required

The client's IPv6 address on the WireGuard network. It may be omitted when IPv6 is not used.

serverRequired

The remote Peer's domain name or IP address.

portRequired

The remote Peer's WireGuard port.

public-keyRequired

The Base64-encoded public key of the remote Peer.

Single-Peer routingIn the current implementation,

the shorthand form automatically creates 0.0.0.0/0 and ::/0 routes based on the local address family; the top-level allowed-ips is not read.

Full multi-Peer form

When multiple Peer entries are needed, use the peers array.private-key and the local ip or ipv6 remain at the node's top level, while each array item contains the server endpoint and Peer keys.

Each Peer must provide a nonempty allowed-ipsand should use distinct subnets. When peers is used, the top-level server、port、public-key and pre-shared-key is ignored. The top-level reserved serves as the fallback for any Peer without its own reserved value.

Keys, routing, and connectivity fields

Key and value formats are validated during node initialization. If the network is reachable but no traffic passes through the tunnel, check Allowed IPs, MTU, and keepalive before changing Clash rules.

pre-shared-keyOptional

An additional Base64-encoded pre-shared key. It must match the corresponding Peer.

reservedOptional

A WireGuard reserved value of exactly 3 bytes, required by some WARP nodes.

persistent-keepaliveOptional

Sends keepalive packets periodically in seconds; commonly used for clients behind NAT.

mtuOptional

The internal WireGuard device MTU. When omitted, the current implementation uses 1408.

udpOptional

Allows UDP application traffic selected for this node to enter the WireGuard outbound.

dialer-proxyOptional

Connects to the WireGuard endpoint through another outbound or policy group.

Remote DNS and AmneziaWG

A WireGuard outbound can use a dedicated resolver for domain requests entering the tunnel. Set AmneziaWG options only when the server uses the same extension; the fields are also constrained by the AmneziaWG version.

remote-dns-resolveOptional

Set to true enables remote resolution through the current WireGuard outbound. Default: false。

dnsConditionally active

DNS servers used for remote resolution; active only when remote-dns-resolve: true is selected.

amnezia-wg-optionAdvanced

The presence of this object enables AmneziaWG. Its parameters must come from the corresponding server configuration.

Map a standard configuration to client fields

Standard WireGuard [Interface] Address and PrivateKey map to the top-level address and private key;[Peer] Endpoint, PublicKey, and AllowedIPs map to Peer fields. ListenPort in a standard configuration is a local listening port and must not be mistaken for the remote port。

The two keys below are only format-valid example values and cannot authenticate a real connection. The single-Peer shorthand does not read the top-level allowed-ips; to customize the routing range, use the peers array and set allowed-ips for each Peer.

• If you see missing local address, add the correct ip or ipv6。
• If key decoding fails, confirm that you copied a Base64 key, not a configuration-file path or hexadecimal text.
• If a multi-Peer configuration reports missing allowed_ips, give each Peer a nonempty, explicit subnet list.
• If a handshake exists but no data passes, verify the peer public key, Allowed IPs, NAT, firewall, and MTU.

proxies:
  - name: wg-node
    type: wireguard
    private-key: ZXhhbXBsZS1jbGllbnQtcHJpdmF0ZS1rZXktMDAwMDA=
    ip: 10.0.0.2
    server: 203.0.113.10
    port: 51820
    public-key: ZXhhbXBsZS1wZWVyLXB1YmxpYy1rZXktMDAwMDAwMDA=
    udp: true
    mtu: 1408
    persistent-keepalive: 25