diff --git a/docs/cli/gateway.md b/docs/cli/gateway.md
index 61982a36032..38f2606eb01 100644
--- a/docs/cli/gateway.md
+++ b/docs/cli/gateway.md
@@ -262,10 +262,10 @@ Wide-Area discovery records include (TXT):
 - `role` (gateway role hint)
 - `transport` (transport hint, e.g. `gateway`)
 - `gatewayPort` (WebSocket port, usually `18789`)
-- `sshPort` (SSH port; defaults to `22` if not present)
+- `sshPort` (optional; clients default SSH targets to `22` when it is absent)
 - `tailnetDns` (MagicDNS hostname, when available)
 - `gatewayTls` / `gatewayTlsSha256` (TLS enabled + cert fingerprint)
-- `cliPath` (optional hint for remote installs)
+- `cliPath` (remote-install hint written to the wide-area zone)
 
 ### `gateway discover`
 
@@ -290,3 +290,6 @@ Notes:
 - The CLI scans `local.` plus the configured wide-area domain when one is enabled.
 - `wsUrl` in JSON output is derived from the resolved service endpoint, not from TXT-only
   hints such as `lanHost` or `tailnetDns`.
+- On `local.` mDNS, `sshPort` and `cliPath` are only broadcast when
+  `discovery.mdns.mode` is `full`. Wide-area DNS-SD still writes `cliPath`; `sshPort`
+  stays optional there too.
diff --git a/docs/gateway/bonjour.md b/docs/gateway/bonjour.md
index d9d0b4185ae..ee7aa639f24 100644
--- a/docs/gateway/bonjour.md
+++ b/docs/gateway/bonjour.md
@@ -96,10 +96,10 @@ The Gateway advertises small non‑secret hints to make UI flows convenient:
 - `gatewayTls=1` (only when TLS is enabled)
 - `gatewayTlsSha256=<sha256>` (only when TLS is enabled and fingerprint is available)
 - `canvasPort=<port>` (only when the canvas host is enabled; currently the same as `gatewayPort`)
-- `sshPort=<port>` (defaults to 22 when not overridden)
 - `transport=gateway`
-- `cliPath=<path>` (optional; absolute path to a runnable `openclaw` entrypoint)
 - `tailnetDns=<magicdns>` (optional hint when Tailnet is available)
+- `sshPort=<port>` (mDNS full mode only; wide-area DNS-SD may omit it)
+- `cliPath=<path>` (mDNS full mode only; wide-area DNS-SD still writes it as a remote-install hint)
 
 Security notes:
 
@@ -169,7 +169,7 @@ sequences (e.g. spaces become `\032`).
 
 - `OPENCLAW_DISABLE_BONJOUR=1` disables advertising (legacy: `OPENCLAW_DISABLE_BONJOUR`).
 - `gateway.bind` in `~/.openclaw/openclaw.json` controls the Gateway bind mode.
-- `OPENCLAW_SSH_PORT` overrides the SSH port advertised in TXT (legacy: `OPENCLAW_SSH_PORT`).
+- `OPENCLAW_SSH_PORT` overrides the SSH port when `sshPort` is advertised (legacy: `OPENCLAW_SSH_PORT`).
 - `OPENCLAW_TAILNET_DNS` publishes a MagicDNS hint in TXT (legacy: `OPENCLAW_TAILNET_DNS`).
 - `OPENCLAW_CLI_PATH` overrides the advertised CLI path (legacy: `OPENCLAW_CLI_PATH`).
 
diff --git a/docs/gateway/discovery.md b/docs/gateway/discovery.md
index 9983a687831..829cc7460c7 100644
--- a/docs/gateway/discovery.md
+++ b/docs/gateway/discovery.md
@@ -66,13 +66,13 @@ Troubleshooting and beacon details: [Bonjour](/gateway/bonjour).
   - `transport=gateway`
   - `displayName=<friendly name>` (operator-configured display name)
   - `lanHost=<hostname>.local`
-  - `sshPort=22` (or whatever is advertised)
   - `gatewayPort=18789` (Gateway WS + HTTP)
   - `gatewayTls=1` (only when TLS is enabled)
   - `gatewayTlsSha256=<sha256>` (only when TLS is enabled and fingerprint is available)
   - `canvasPort=<port>` (canvas host port; currently the same as `gatewayPort` when the canvas host is enabled)
-  - `cliPath=<path>` (optional; absolute path to a runnable `openclaw` entrypoint or binary)
   - `tailnetDns=<magicdns>` (optional hint; auto-detected when Tailscale is available)
+  - `sshPort=<port>` (mDNS full mode only; wide-area DNS-SD may omit it, in which case SSH defaults stay at `22`)
+  - `cliPath=<path>` (mDNS full mode only; wide-area DNS-SD still writes it as a remote-install hint)
 
 Security notes:
 
@@ -85,7 +85,7 @@ Disable/override:
 
 - `OPENCLAW_DISABLE_BONJOUR=1` disables advertising.
 - `gateway.bind` in `~/.openclaw/openclaw.json` controls the Gateway bind mode.
-- `OPENCLAW_SSH_PORT` overrides the SSH port advertised in TXT (defaults to 22).
+- `OPENCLAW_SSH_PORT` overrides the SSH port advertised when `sshPort` is emitted.
 - `OPENCLAW_TAILNET_DNS` publishes a `tailnetDns` hint (MagicDNS).
 - `OPENCLAW_CLI_PATH` overrides the advertised CLI path.