WireGuard — sing-box

Endpoint，而非 outbound

WireGuard 在 sing-box 1.11+ 中作为 endpoint 而非 outbound 配置。该块位于根层的 endpoints[] 数组下，type: "wireguard"，并像任何命名的 outbound 一样在路由规则中被引用。

Endpoint 选项

endpoints[] 下 type: "wireguard"：

字段	类型	默认值	允许值	描述
`system`	`bool`	`false`	`true \| false`	使用操作系统 TUN 设备而不是用户态 gVisor 栈。吞吐更高，但多数平台需要更高权限。
`name`	`string`	`(auto)`	`<string>`	endpoint 的显示名。用于统计与路由引擎。
`mtu`	`uint32`	`1408`	`<bytes>`	隧道 MTU。默认 1408（比 Xray 的 1420 少 12 字节，sing-box 为内层包预留了 IPv6 头开销）。
`address`	`badoption.Listable[netip.Prefix]`	`(required)`	`[<CIDR>]`	本地隧道地址，`netip.Prefix` 列表。至少需要一项。
`private_key`	`string`	`(required)`	`<base64 key>`	本地私钥，32 字节，base64 编码。
`listen_port`	`uint16`	`0 (random)`	`<port>`	出站 WireGuard 包使用的 UDP 端口。0 选随机临时端口。
`peers`	`[]WireGuardPeer`	`[]`	`[WireGuardPeer]`	远端 peer。
`udp_timeout`	`badoption.Duration`	`5m`	`<duration>`	底层 UDP 会话的空闲超时，供 gVisor 会话表使用。
`workers`	`int`	`(CPU-based)`	`<int>`	加密管线的 worker 数。0 使用 runtime.NumCPU()。

源码： option/wireguard.go:9-20 · 锚定版本 v1.13.11 (553cfa1)

该结构体还为底层 UDP 套接字内嵌了 DialerOptions —— bind_interface、routing_mark、detour 等。

`peers[]`

字段	类型	默认值	允许值	描述
`address`	`string`	`(unset)`	`<host>`	peer 主机名或 IP。给主机名时会在握手时解析。
`port`	`uint16`	`51820`	`<port>`	peer UDP 端口。
`public_key`	`string`	`(required)`	`<base64 key>`	peer 公钥，32 字节，base64 编码。
`pre_shared_key`	`string`	`(unset)`	`<base64 key>`	可选 pre-shared-key（32 字节，base64），用于握手额外混入。
`allowed_ips`	`badoption.Listable[netip.Prefix]`	`[]`	`[<CIDR>]`	路由到此 peer 的源 / 目的 CIDR。
`persistent_keepalive_interval`	`uint16`	`0`	`<seconds>`	WireGuard persistent-keepalive 间隔。0 表示禁用。
`reserved`	`[]uint8`	`(empty)`	`<3 bytes>`	部分商业实现使用的三字节 WireGuard reserved 字段覆盖。

源码： option/wireguard.go:22-30 · 锚定版本 v1.13.11 (553cfa1)

示例

使用系统 TUN 的单 peer：

json

{
  "endpoints": [
    {
      "type": "wireguard",
      "tag": "wg-ep",
      "system": true,
      "name": "wg0",
      "address": ["10.0.0.2/32", "fd00::2/128"],
      "private_key": "<base64-private-key>",
      "mtu": 1408,
      "peers": [
        {
          "address": "wg.example.com",
          "port": 51820,
          "public_key": "<base64-peer-public-key>",
          "allowed_ips": ["0.0.0.0/0", "::/0"],
          "persistent_keepalive_interval": 25
        }
      ]
    }
  ],
  "route": {
    "rules": [
      { "domain": ["geosite-private"], "outbound": "wg-ep" }
    ]
  }
}

无系统 TUN 的用户态设备（用于无权限场景）：

json

{
  "endpoints": [
    {
      "type": "wireguard",
      "tag": "wg-userspace",
      "system": false,
      "address": ["172.16.0.2/24"],
      "private_key": "<base64>",
      "peers": [
        { "address": "1.2.3.4", "port": 51820, "public_key": "<base64>", "allowed_ips": ["0.0.0.0/0"] }
      ]
    }
  ]
}

说明

当前 sing-box 中 WireGuard 始终是 endpoint。1.11 之前的 outbound: { type: wireguard } 配置加载会失败 —— 请迁移到 endpoints 模型。
system: true 直接使用平台 TUN 设备，速度更快但需要 root / Administrator。system: false（默认）使用 gVisor 用户态 TCP/IP 栈，较慢但无需高权限。
密钥必须 base64（32 字节原始字节再 base64）。Xray 接受的 hex 密钥这里不支持。
默认 MTU 是 1408，而非线路格式的 1420 —— sing-box 为内层 IPv6 头预留了 12 字节。

跨内核说明

Xray-core 仍把 WireGuard 作为协议式 outbound 放在 outbounds[] 下，protocol: "wireguard"。接受 hex 或 base64 密钥，MTU 默认 1420。参见 WireGuard — Xray-core。
mihomo 也作为 outbound，支持简化的单 peer 形式（顶层 server / port / public-key / allowed-ips）以及可选的 amnezia-wg-option 块。参见 WireGuard — mihomo。

源码： option/wireguard.go:9-30 · v1.13.11 (553cfa1)

WireGuard — sing-box ​

Endpoint 选项 ​

peers[] ​

示例 ​

说明 ​

跨内核说明 ​

WireGuard — sing-box

Endpoint 选项

`peers[]`

示例

说明

跨内核说明