docs: refresh gateway probe warning mirrors

docs/.i18n/glossary.zh-CN.json

@@ -231,6 +231,14 @@
     "source": "CLI",
     "target": "CLI"
   },
+  {
+    "source": "/cli/gateway",
+    "target": "/cli/gateway"
+  },
+  {
+    "source": "/gateway#multiple-gateways-same-host",
+    "target": "/gateway#multiple-gateways-same-host"
+  },
   {
     "source": "install sanity",
     "target": "安装完整性检查"

docs/cli/daemon.md

@@ -43,12 +43,14 @@ Notes:
 - `status` resolves configured auth SecretRefs for probe auth when possible.
 - If a required auth SecretRef is unresolved in this command path, `daemon status --json` reports `rpc.authWarning` when probe connectivity/auth fails; pass `--token`/`--password` explicitly or resolve the secret source first.
 - If the probe succeeds, unresolved auth-ref warnings are suppressed to avoid false positives.
+- `status --deep` adds a best-effort system-level service scan. When it finds other gateway-like services, human output prints cleanup hints and warns that one gateway per machine is still the normal recommendation.
 - On Linux systemd installs, `status` token-drift checks include both `Environment=` and `EnvironmentFile=` unit sources.
 - Drift checks resolve `gateway.auth.token` SecretRefs using merged runtime env (service command env first, then process env fallback).
 - If token auth is not effectively active (explicit `gateway.auth.mode` of `password`/`none`/`trusted-proxy`, or mode unset where password can win and no token candidate can win), token-drift checks skip config token resolution.
 - When token auth requires a token and `gateway.auth.token` is SecretRef-managed, `install` validates that the SecretRef is resolvable but does not persist the resolved token into service environment metadata.
 - If token auth requires a token and the configured token SecretRef is unresolved, install fails closed.
 - If both `gateway.auth.token` and `gateway.auth.password` are configured and `gateway.auth.mode` is unset, install is blocked until mode is set explicitly.
+- If you intentionally run multiple gateways on one host, isolate ports, config/state, and workspaces; see [/gateway#multiple-gateways-same-host](/gateway#multiple-gateways-same-host).
 
 ## Prefer
 

docs/cli/gateway.md

@@ -132,6 +132,7 @@ Notes:
 - If a required auth SecretRef is unresolved in this command path, `gateway status --json` reports `rpc.authWarning` when probe connectivity/auth fails; pass `--token`/`--password` explicitly or resolve the secret source first.
 - If the probe succeeds, unresolved auth-ref warnings are suppressed to avoid false positives.
 - Use `--require-rpc` in scripts and automation when a listening service is not enough and you need the Gateway RPC itself to be healthy.
+- `--deep` adds a best-effort scan for extra launchd/systemd/schtasks installs. When multiple gateway-like services are detected, human output prints cleanup hints and warns that most setups should run one gateway per machine.
 - Human output includes the resolved file log path plus the CLI-vs-service config paths/validity snapshot to help diagnose profile or state-dir drift.
 - On Linux systemd installs, service auth drift checks read both `Environment=` and `EnvironmentFile=` values from the unit (including `%h`, quoted paths, multiple files, and optional `-` files).
 - Drift checks resolve `gateway.auth.token` SecretRefs using merged runtime env (service command env first, then process env fallback).
@@ -170,11 +171,22 @@ JSON notes (`--json`):
 - Top level:
   - `ok`: at least one target is reachable.
   - `degraded`: at least one target had scope-limited detail RPC.
+  - `primaryTargetId`: best target to treat as the active winner in this order: explicit URL, SSH tunnel, configured remote, then local loopback.
+  - `warnings[]`: best-effort warning records with `code`, `message`, and optional `targetIds`.
+  - `network`: local loopback/tailnet URL hints derived from current config and host networking.
+  - `discovery.timeoutMs` and `discovery.count`: the actual discovery budget/result count used for this probe pass.
 - Per target (`targets[].connect`):
   - `ok`: reachability after connect + degraded classification.
   - `rpcOk`: full detail RPC success.
   - `scopeLimited`: detail RPC failed due to missing operator scope.
 
+Common warning codes:
+
+- `ssh_tunnel_failed`: SSH tunnel setup failed; the command fell back to direct probes.
+- `multiple_gateways`: more than one target was reachable; this is unusual unless you intentionally run isolated profiles, such as a rescue bot.
+- `auth_secretref_unresolved`: a configured auth SecretRef could not be resolved for a failed target.
+- `probe_scope_limited`: WebSocket connect succeeded, but detail RPC was limited by missing `operator.read`.
+
 #### Remote over SSH (Mac app parity)
 
 The macOS app “Remote over SSH” mode uses a local port-forward so the remote gateway (which may be bound to loopback only) becomes reachable at `ws://127.0.0.1:<port>`.

docs/gateway/index.md

@@ -140,6 +140,30 @@ openclaw doctor
 `gateway status --deep` is for extra service discovery (LaunchDaemons/systemd system
 units/schtasks), not a deeper RPC health probe.
 
+## Multiple gateways (same host)
+
+Most installs should run one gateway per machine. A single gateway can host multiple
+agents and channels.
+
+You only need multiple gateways when you intentionally want isolation or a rescue bot.
+
+Useful checks:
+
+```bash
+openclaw gateway status --deep
+openclaw gateway probe
+```
+
+What to expect:
+
+- `gateway status --deep` can report `Other gateway-like services detected (best effort)`
+  and print cleanup hints when stale launchd/systemd/schtasks installs are still around.
+- `gateway probe` can warn about `multiple reachable gateways` when more than one target
+  answers.
+- If that is intentional, isolate ports, config/state, and workspace roots per gateway.
+
+Detailed setup: [/gateway/multiple-gateways](/gateway/multiple-gateways).
+
 ## Remote access
 
 Preferred: Tailscale/VPN.

docs/gateway/multiple-gateways.md

@@ -106,7 +106,15 @@ openclaw gateway --port 19001
 ## Quick checks
 
 ```bash
+openclaw --profile main gateway status --deep
+openclaw --profile rescue gateway status --deep
+openclaw --profile rescue gateway probe
 openclaw --profile main status
 openclaw --profile rescue status
 openclaw --profile rescue browser status
 ```
+
+Interpretation:
+
+- `gateway status --deep` helps catch stale launchd/systemd/schtasks services from older installs.
+- `gateway probe` warning text such as `multiple reachable gateways detected` is expected only when you intentionally run more than one isolated gateway.

docs/gateway/troubleshooting.md

@@ -192,12 +192,14 @@ Look for:
 - Service config mismatch (`Config (cli)` vs `Config (service)`).
 - Port/listener conflicts.
 - Extra launchd/systemd/schtasks installs when `--deep` is used.
+- `Other gateway-like services detected (best effort)` cleanup hints.
 
 Common signatures:
 
 - `Gateway start blocked: set gateway.mode=local` or `existing config is missing gateway.mode` → local gateway mode is not enabled, or the config file was clobbered and lost `gateway.mode`. Fix: set `gateway.mode="local"` in your config, or re-run `openclaw onboard --mode local` / `openclaw setup` to restamp the expected local-mode config. If you are running OpenClaw via Podman, the default config path is `~/.openclaw/openclaw.json`.
 - `refusing to bind gateway ... without auth` → non-loopback bind without a valid gateway auth path (token/password, or trusted-proxy where configured).
 - `another gateway instance is already listening` / `EADDRINUSE` → port conflict.
+- `Other gateway-like services detected (best effort)` → stale or parallel launchd/systemd/schtasks units exist. Most setups should keep one gateway per machine; if you do need more than one, isolate ports + config/state/workspace. See [/gateway#multiple-gateways-same-host](/gateway#multiple-gateways-same-host).
 
 Related:
 
@@ -205,6 +207,34 @@ Related:
 - [/gateway/configuration](/gateway/configuration)
 - [/gateway/doctor](/gateway/doctor)
 
+## Gateway probe warnings
+
+Use this when `openclaw gateway probe` reaches something, but still prints a warning block.
+
+```bash
+openclaw gateway probe
+openclaw gateway probe --json
+openclaw gateway probe --ssh user@gateway-host
+```
+
+Look for:
+
+- `warnings[].code` and `primaryTargetId` in JSON output.
+- Whether the warning is about SSH fallback, multiple gateways, missing scopes, or unresolved auth refs.
+
+Common signatures:
+
+- `SSH tunnel failed to start; falling back to direct probes.` → SSH setup failed, but the command still tried direct configured/loopback targets.
+- `multiple reachable gateways detected` → more than one target answered. Usually this means an intentional multi-gateway setup or stale/duplicate listeners.
+- `Probe diagnostics are limited by gateway scopes (missing operator.read)` → connect worked, but detail RPC is scope-limited; pair device identity or use credentials with `operator.read`.
+- unresolved `gateway.auth.*` / `gateway.remote.*` SecretRef warning text → auth material was unavailable in this command path for the failed target.
+
+Related:
+
+- [/cli/gateway](/cli/gateway)
+- [/gateway#multiple-gateways-same-host](/gateway#multiple-gateways-same-host)
+- [/gateway/remote](/gateway/remote)
+
 ## Channel connected messages not flowing
 
 If channel state is connected but message flow is dead, focus on policy, permissions, and channel specific delivery rules.