diff --git a/docs/channels/troubleshooting.md b/docs/channels/troubleshooting.md index 9c22d4b601e..889c0d01f67 100644 --- a/docs/channels/troubleshooting.md +++ b/docs/channels/troubleshooting.md @@ -25,7 +25,8 @@ openclaw channels status --probe Healthy baseline: - `Runtime: running` -- `RPC probe: ok` +- `Connectivity probe: ok` +- `Capability: read-only`, `write-capable`, or `admin-capable` - Channel probe shows transport connected and, where supported, `works` or `audit ok` ## WhatsApp diff --git a/docs/cli/gateway.md b/docs/cli/gateway.md index d0566ce674a..6f8dad312f5 100644 --- a/docs/cli/gateway.md +++ b/docs/cli/gateway.md @@ -106,7 +106,7 @@ Options: ### `gateway status` -`gateway status` shows the Gateway service (launchd/systemd/schtasks) plus an optional RPC probe. +`gateway status` shows the Gateway service (launchd/systemd/schtasks) plus an optional probe of connectivity/auth capability. ```bash openclaw gateway status @@ -120,17 +120,18 @@ Options: - `--token `: token auth for the probe. - `--password `: password auth for the probe. - `--timeout `: probe timeout (default `10000`). -- `--no-probe`: skip the RPC probe (service-only view). +- `--no-probe`: skip the connectivity probe (service-only view). - `--deep`: scan system-level services too. -- `--require-rpc`: exit non-zero when the RPC probe fails. Cannot be combined with `--no-probe`. +- `--require-rpc`: upgrade the default connectivity probe to a read probe and exit non-zero when that read probe fails. Cannot be combined with `--no-probe`. Notes: - `gateway status` stays available for diagnostics even when the local CLI config is missing or invalid. +- Default `gateway status` proves service state, WebSocket connect, and the auth capability visible at handshake time. It does not prove read/write/admin operations. - `gateway status` resolves configured auth SecretRefs for probe auth when possible. - 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. +- Use `--require-rpc` in scripts and automation when a listening service is not enough and you need read-scope RPC calls to be healthy too. - `--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). @@ -161,8 +162,9 @@ openclaw gateway probe --json Interpretation: - `Reachable: yes` means at least one target accepted a WebSocket connect. -- `RPC: ok` means detail RPC calls (`health`/`status`/`system-presence`/`config.get`) also succeeded. -- `RPC: limited - missing scope: operator.read` means connect succeeded but detail RPC is scope-limited. This is reported as **degraded** reachability, not full failure. +- `Capability: read-only|write-capable|admin-capable|pairing-pending|connect-only` reports what the probe could prove about auth. It is separate from reachability. +- `Read probe: ok` means read-scope detail RPC calls (`health`/`status`/`system-presence`/`config.get`) also succeeded. +- `Read probe: limited - missing scope: operator.read` means connect succeeded but read-scope RPC is limited. This is reported as **degraded** reachability, not full failure. - Exit code is non-zero only when no probed target is reachable. JSON notes (`--json`): @@ -170,6 +172,7 @@ JSON notes (`--json`): - Top level: - `ok`: at least one target is reachable. - `degraded`: at least one target had scope-limited detail RPC. + - `capability`: best capability seen across reachable targets (`read_only`, `write_capable`, `admin_capable`, `pairing_pending`, `connected_no_operator_scope`, or `unknown`). - `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. @@ -178,13 +181,17 @@ JSON notes (`--json`): - `ok`: reachability after connect + degraded classification. - `rpcOk`: full detail RPC success. - `scopeLimited`: detail RPC failed due to missing operator scope. +- Per target (`targets[].auth`): + - `role`: auth role reported in `hello-ok` when available. + - `scopes`: granted scopes reported in `hello-ok` when available. + - `capability`: the surfaced auth capability classification for that target. 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`. +- `probe_scope_limited`: WebSocket connect succeeded, but the read probe was limited by missing `operator.read`. #### Remote over SSH (Mac app parity) diff --git a/docs/gateway/index.md b/docs/gateway/index.md index e40d8290186..1f6ebda4ca2 100644 --- a/docs/gateway/index.md +++ b/docs/gateway/index.md @@ -47,7 +47,7 @@ openclaw status openclaw logs --follow ``` -Healthy baseline: `Runtime: running` and `RPC probe: ok`. +Healthy baseline: `Runtime: running`, `Connectivity probe: ok`, and `Capability: ...` that matches what you expect. Use `openclaw gateway status --require-rpc` when you need read-scope RPC proof, not just reachability. diff --git a/docs/gateway/troubleshooting.md b/docs/gateway/troubleshooting.md index 87e6bc92f67..61a18dc8059 100644 --- a/docs/gateway/troubleshooting.md +++ b/docs/gateway/troubleshooting.md @@ -25,7 +25,7 @@ openclaw channels status --probe Expected healthy signals: -- `openclaw gateway status` shows `Runtime: running` and `RPC probe: ok`. +- `openclaw gateway status` shows `Runtime: running`, `Connectivity probe: ok`, and a `Capability: ...` line. - `openclaw doctor` reports no blocking config/service issues. - `openclaw channels status --probe` shows live per-account transport status and, where supported, probe/audit results such as `works` or `audit ok`. @@ -281,7 +281,8 @@ 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`. +- `Read-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`. +- `Capability: pairing-pending` or `gateway closed (1008): pairing required` → the gateway answered, but this client still needs pairing/approval before normal operator access. - unresolved `gateway.auth.*` / `gateway.remote.*` SecretRef warning text → auth material was unavailable in this command path for the failed target. Related: @@ -471,7 +472,7 @@ What to check: Common signatures: - `refusing to bind gateway ... without auth` → non-loopback bind without a valid gateway auth path. -- `RPC probe: failed` while runtime is running → gateway alive but inaccessible with current auth/url. +- `Connectivity probe: failed` while runtime is running → gateway alive but inaccessible with current auth/url. ### 3) Pairing and device identity state changed diff --git a/docs/help/faq.md b/docs/help/faq.md index 4c1ebfb5033..f40e55b3429 100644 --- a/docs/help/faq.md +++ b/docs/help/faq.md @@ -2728,8 +2728,8 @@ Related: [/concepts/oauth](/concepts/oauth) (OAuth flows, token storage, multi-a - - Because "running" is the **supervisor's** view (launchd/systemd/schtasks). The RPC probe is the CLI actually connecting to the gateway WebSocket and calling `status`. + + Because "running" is the **supervisor's** view (launchd/systemd/schtasks). The connectivity probe is the CLI actually connecting to the gateway WebSocket. Use `openclaw gateway status` and trust these lines: diff --git a/docs/help/troubleshooting.md b/docs/help/troubleshooting.md index 49e02780a49..b9f5b98ae8d 100644 --- a/docs/help/troubleshooting.md +++ b/docs/help/troubleshooting.md @@ -28,8 +28,8 @@ Good output in one line: - `openclaw status` → shows configured channels and no obvious auth errors. - `openclaw status --all` → full report is present and shareable. -- `openclaw gateway probe` → expected gateway target is reachable (`Reachable: yes`). `RPC: limited - missing scope: operator.read` is degraded diagnostics, not a connect failure. -- `openclaw gateway status` → `Runtime: running` and `RPC probe: ok`. +- `openclaw gateway probe` → expected gateway target is reachable (`Reachable: yes`). `Capability: ...` tells you what auth level the probe could prove, and `Read probe: limited - missing scope: operator.read` is degraded diagnostics, not a connect failure. +- `openclaw gateway status` → `Runtime: running`, `Connectivity probe: ok`, and a plausible `Capability: ...` line. Use `--require-rpc` if you need read-scope RPC proof too. - `openclaw doctor` → no blocking config/service errors. - `openclaw channels status --probe` → reachable gateway returns live per-account transport state plus probe/audit results such as `works` or `audit ok`; if the @@ -117,7 +117,8 @@ flowchart TD Good output looks like: - `Runtime: running` - - `RPC probe: ok` + - `Connectivity probe: ok` + - `Capability: read-only`, `write-capable`, or `admin-capable` - Your channel shows transport connected and, where supported, `works` or `audit ok` in `channels status --probe` - Sender appears approved (or DM policy is open/allowlist) @@ -147,7 +148,8 @@ flowchart TD Good output looks like: - `Dashboard: http://...` is shown in `openclaw gateway status` - - `RPC probe: ok` + - `Connectivity probe: ok` + - `Capability: read-only`, `write-capable`, or `admin-capable` - No auth loop in logs Common log signatures: @@ -189,7 +191,8 @@ flowchart TD - `Service: ... (loaded)` - `Runtime: running` - - `RPC probe: ok` + - `Connectivity probe: ok` + - `Capability: read-only`, `write-capable`, or `admin-capable` Common log signatures: