Shadowsocks — mihomo

mihomo speaks Shadowsocks on both sides, with a rich plugin ecosystem that wraps the wire format inside obfs, WebSocket (v2ray-plugin / gost-plugin), Shadow-TLS, REALTLS, or KCP. Plugin configuration goes under the typed plugin-opts YAML map.

Outbound

Entry under proxies: with type: ss. Embeds BasicOption.

Field	Type	Default	Allowed values	Description
name	string	(required)	<string>	Unique proxy name.
server	string	(required)	<host>	Upstream server hostname or IP.
port	int	(required)	<port>	Upstream server port.
password	string	(required)	<string> | <base64 key>	Server password (AEAD) or EIH key (SS-2022).
cipher	string	(required)	aes-128-gcm | aes-256-gcm | chacha20-ietf-poly1305 | xchacha20-ietf-poly1305 | 2022-blake3-aes-128-gcm | 2022-blake3-aes-256-gcm | 2022-blake3-chacha20-poly1305 | none	mihomo's name for the Shadowsocks cipher / key-derivation scheme.
udp	bool	false	true | false	Allow UDP packets to be relayed through this outbound.
plugin	string	(unset)	obfs | v2ray-plugin | gost-plugin | shadow-tls | restls | kcptun	Obfuscation / transport plugin to wrap the stream. Each plugin has its own `plugin-opts` schema (documented below).
plugin-opts	map[string]any	{}	<plugin-specific YAML map>	Plugin-specific configuration. Schema depends on `plugin` — see the sub-sections below.
udp-over-tcp	bool	false	true | false	Wrap UDP inside the TCP stream.
udp-over-tcp-version	int	2	1 | 2	UoT framing version.
client-fingerprint	string	(global)	chrome | firefox | safari | ios | edge | random | randomized	uTLS client-hello fingerprint applied when the plugin uses TLS.

Source: adapter/outbound/shadowsocks.go:41-54 · pinned at v1.19.27 (5184081)

plugin-opts — when plugin: obfs

Wraps the stream in simple-obfs (TLS-shaped or HTTP-shaped).

Field	Type	Default	Allowed values	Description
mode	string	tls	tls | http	Obfs mode. `tls` mimics a TLS Client Hello; `http` mimics a plain HTTP request.
host	string	(unset)	<host>	Cover hostname used in the obfs payload.

Source: adapter/outbound/shadowsocks.go:56-59 · pinned at v1.19.27 (5184081)

plugin-opts — when plugin: v2ray-plugin

Wraps the stream in a WebSocket handshake. Optional TLS.

Field	Type	Default	Allowed values	Description
mode	string	(required)	websocket	Currently only `websocket` is supported.
host	string	(unset)	<host>	Host header sent on the WS handshake.
path	string	/	/<path>	WebSocket path.
tls	bool	false	true | false	Wrap the WS handshake in TLS.
ech-opts	ECHOptions	—	—
fingerprint	string	(unset)	<SHA256 hex>	Pin the server's TLS certificate fingerprint.
certificate	string	(unset)	<PEM file path>	Client certificate (mTLS).
private-key	string	(unset)	<key file path>	Private key matching `certificate`.
headers	map[string]string	{}	{<header>: <value>}	Extra HTTP headers on the upgrade request.
skip-cert-verify	bool	false	true | false	Disable TLS verification.
mux	bool	false	true | false	Enable smux on top of the WS stream.
v2ray-http-upgrade	bool	false	true | false	Use V2Ray HTTP-upgrade instead of standard WebSocket.
v2ray-http-upgrade-fast-open	bool	false	true | false	Piggyback the payload on the HTTP-upgrade request.

Source: adapter/outbound/shadowsocks.go:61-75 · pinned at v1.19.27 (5184081)

plugin-opts — when plugin: shadow-tls

Adds a Shadow-TLS handshake in front of the Shadowsocks stream.

Field	Type	Default	Allowed values	Description
password	string	(unset)	<string>	Shadow-TLS v2/v3 password.
host	string	(required)	<host>	Cover hostname for the TLS handshake.
fingerprint	string	(unset)	<SHA256 hex>	Pin the cover server's TLS certificate.
certificate	string	(unset)	<PEM file path>	Client certificate.
private-key	string	(unset)	<key file path>	Private key.
skip-cert-verify	bool	false	true | false	Disable cert verification (test only).
version	int	3	1 | 2 | 3	Shadow-TLS protocol version. v3 is the current production version.
alpn	[]string	[]	h2 | http/1.1	ALPN list offered during the cover-TLS handshake.

Source: adapter/outbound/shadowsocks.go:91-100 · pinned at v1.19.27 (5184081)

Other plugin variants (gost-plugin, restls, kcptun) carry their own schema under plugin-opts. Their structs (gostObfsOption, restlsOption, kcpTunOption) live in the same source file; see the extracted data for the full field list.

Inbound

Entry under listeners: with type: ss. Embeds BaseOption.

Field	Type	Default	Allowed values	Description
password	string	(required)	<string> | <base64 key>	Server password or SS-2022 key.
cipher	string	(required)	<cipher>	Same cipher set as the outbound.
udp	bool	false	true | false	Accept UDP packets.
mux-option	MuxOption	(disabled)	MuxOption	sing-style multiplex.
shadow-tls	ShadowTLS	(disabled)	ShadowTLS	Optional inbound Shadow-TLS wrap.
kcp-tun	KcpTun	(disabled)	KcpTun	Optional inbound KCP transport.
simple-obfs	SimpleObfs	(disabled)	SimpleObfs	simple-obfs (obfs-local) settings: `{ enable, mode }` where `mode` is `http` or `tls`.

Source: listener/inbound/shadowsocks.go:12-21 · pinned at v1.19.27 (5184081)

simple-obfs

Built-in simple-obfs wrap on the listener — no external plugin binary.

Field	Type	Default	Allowed values	Description
enable	bool	false	true | false	Enable simple-obfs on the listener.
mode	string	tls	http | tls	Obfs mode. `tls` mimics a TLS Client Hello; `http` mimics a plain HTTP request.

Source: listener/inbound/shadowsocks.go:23-26 · pinned at v1.19.27 (5184081)

Examples

Plain SS outbound:

proxies:
  - name: ss-aead
    type: ss
    server: example.com
    port: 8388
    password: <password>
    cipher: aes-256-gcm
    udp: true

SS-2022 outbound with UDP-over-TCP:

proxies:
  - name: ss22
    type: ss
    server: example.com
    port: 8388
    password: <base64 16-byte key>
    cipher: 2022-blake3-aes-128-gcm
    udp-over-tcp: true
    udp-over-tcp-version: 2

SS over v2ray-plugin (WebSocket + TLS):

proxies:
  - name: ss-v2ray
    type: ss
    server: example.com
    port: 443
    password: <password>
    cipher: aes-256-gcm
    udp: true
    plugin: v2ray-plugin
    plugin-opts:
      mode: websocket
      tls: true
      host: example.com
      path: /ss

SS in front of Shadow-TLS v3:

proxies:
  - name: ss-stls
    type: ss
    server: example.com
    port: 443
    password: <ss password>
    cipher: aes-256-gcm
    plugin: shadow-tls
    plugin-opts:
      password: <stls password>
      host: www.cloudflare.com
      version: 3

Inbound under listeners:

listeners:
  - name: ss-in
    type: ss
    listen: 0.0.0.0
    port: 8388
    password: <password>
    cipher: aes-256-gcm
    udp: true

Notes

• mihomo's outbound takes plugin-opts as a typed YAML map decoded into one of the per-plugin structs. Tag values on those structs use obfs: instead of proxy: — this is a mihomo-internal convention, not user-facing — see for example simpleObfsOption at adapter/outbound/shadowsocks.go:56-59.
• The plugin: obfs option is mihomo's name for simple-obfs; pass mode: tls for the TLS-shaped form and mode: http for the HTTP-shaped one.
• mihomo's listener inbound does not currently support users[] multi-user — for multiple SS-2022 users on the same port, define one listener per user.

Cross-core notes

• Xray uses method (not cipher) and uot/uotVersion. It has no plugin system — wrap the Shadowsocks payload in another streamSettings transport instead. See Shadowsocks — Xray-core.
• sing-box uses method, supports the destinations[] relay shape for SS-2022, and represents UoT as the object form udp_over_tcp: {enabled, version}. It also accepts external plugin binaries via plugin / plugin_opts. See Shadowsocks — sing-box.

Source: adapter/outbound/shadowsocks.go:41-100 · v1.19.27 (5184081)