diff --git a/docs/cli/index.md b/docs/cli/index.md
index d6e90325861..ed84c0208c9 100644
--- a/docs/cli/index.md
+++ b/docs/cli/index.md
@@ -1024,6 +1024,10 @@ Options:
 - `--json`: emit line-delimited JSON
 - `--plain`: disable structured formatting
 - `--no-color`: disable ANSI colors
+- `--url <url>`: explicit Gateway WebSocket URL
+- `--token <token>`: Gateway token
+- `--timeout <ms>`: Gateway RPC timeout
+- `--expect-final`: wait for a final response when needed
 
 Examples:
 
@@ -1035,6 +1039,11 @@ openclaw logs --json
 openclaw logs --no-color
 ```
 
+Notes:
+
+- If you pass `--url`, the CLI does not auto-apply config or environment credentials.
+- Local loopback pairing failures fall back to the configured local log file; explicit `--url` targets do not.
+
 ### `gateway <subcommand>`
 
 Gateway CLI helpers (use `--url`, `--token`, `--password`, `--timeout`, `--expect-final` for RPC subcommands).
diff --git a/docs/cli/logs.md b/docs/cli/logs.md
index 6c02911621c..b30e843c968 100644
--- a/docs/cli/logs.md
+++ b/docs/cli/logs.md
@@ -13,16 +13,47 @@ Tail Gateway file logs over RPC (works in remote mode).
 Related:
 
 - Logging overview: [Logging](/logging)
+- Gateway CLI: [gateway](/cli/gateway)
+
+## Options
+
+- `--limit <n>`: maximum number of log lines to return (default `200`)
+- `--max-bytes <n>`: maximum bytes to read from the log file (default `250000`)
+- `--follow`: follow the log stream
+- `--interval <ms>`: polling interval while following (default `1000`)
+- `--json`: emit line-delimited JSON events
+- `--plain`: plain text output without styled formatting
+- `--no-color`: disable ANSI colors
+- `--local-time`: render timestamps in your local timezone
+
+## Shared Gateway RPC options
+
+`openclaw logs` also accepts the standard Gateway client flags:
+
+- `--url <url>`: Gateway WebSocket URL
+- `--token <token>`: Gateway token
+- `--timeout <ms>`: timeout in ms (default `30000`)
+- `--expect-final`: wait for a final response when the Gateway call is agent-backed
+
+When you pass `--url`, the CLI does not auto-apply config or environment credentials. Include `--token` explicitly if the target Gateway requires auth.
 
 ## Examples
 
 ```bash
 openclaw logs
 openclaw logs --follow
+openclaw logs --follow --interval 2000
+openclaw logs --limit 500 --max-bytes 500000
 openclaw logs --json
+openclaw logs --plain
+openclaw logs --no-color
 openclaw logs --limit 500
 openclaw logs --local-time
 openclaw logs --follow --local-time
+openclaw logs --url ws://127.0.0.1:18789 --token "$OPENCLAW_GATEWAY_TOKEN"
 ```
 
-Use `--local-time` to render timestamps in your local timezone.
+## Notes
+
+- Use `--local-time` to render timestamps in your local timezone.
+- If the local loopback Gateway asks for pairing, `openclaw logs` falls back to the configured local log file automatically. Explicit `--url` targets do not use this fallback.