diff --git a/CHANGELOG.md b/CHANGELOG.md index 25d20adeb8ef..082ab4c81d21 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -64,6 +64,7 @@ Docs: https://docs.openclaw.ai ### Fixes +- **Control UI owner handoff:** give browsers opened by host-issued dashboard and graphical onboarding links durable administrator access, including same-browser recovery from a limited credential, while keeping generic, Telegram, mobile, and ordinary scope-upgrade paths bounded. Thanks @shakkernerd. - **Control UI agent and skill permissions:** gate Agents, Skills, Skill Workshop, and delayed mutation dispatches by the current Gateway method catalog and operator scopes while preserving read-only browsing and legacy Gateway compatibility. Fixes #119176. Thanks @shakkernerd. - **Guided onboarding skip-UI routing:** keep `openclaw onboard --skip-ui` and `openclaw setup --skip-ui` on guided onboarding while skipping both browser and terminal handoffs, instead of silently switching to the classic wizard. Thanks @shakkernerd. - **Telegram durable ingress:** preserve pre-identity control-lane ownership during replay and attempt each drain snapshot row only once per pass, preventing targeted commands from spinning the spool and blocking polling shutdown. diff --git a/docs/cli/dashboard.md b/docs/cli/dashboard.md index e8267c46fda7..d0edbee93ce7 100644 --- a/docs/cli/dashboard.md +++ b/docs/cli/dashboard.md @@ -8,9 +8,10 @@ title: "Dashboard" # `openclaw dashboard` -Open the Control UI with a short-lived, one-time browser pairing link. A successful handoff leaves -that browser with its own durable device credential, so reopening the dashboard does not depend on -the shared Gateway token. +Open the Control UI with a short-lived, one-time owner pairing link. A successful handoff gives that +signed browser a durable administrator device credential, so reopening the dashboard does not depend +on the shared Gateway token. Opening a fresh handoff in the same browser can also repair a previously +limited device credential. ```bash openclaw dashboard @@ -43,7 +44,7 @@ Notes: - Resolves configured `gateway.auth.token` SecretRefs when possible. - `browserUrl` carries a single-use, ten-minute bootstrap in the URL fragment. The Control UI strips it immediately, binds it to the browser's signed device identity, and stores only the resulting - per-device credential. + administrator per-device credential. Another browser profile cannot inherit or replay that grant. - Follows `gateway.tls.enabled`: TLS-enabled gateways print/open `https://` Control UI URLs and connect over `wss://`. - For `lan` or a wildcard `custom` bind, same-host launches always use loopback because a wildcard is not a browser destination. Plaintext `tailnet` and `custom` binds also use `127.0.0.1` so the browser has a secure context; TLS-enabled specific hosts keep the configured address so certificate names match. - Before delivering an authenticated loopback URL for a specific-interface bind, the command probes the configured interface and verifies that it and `127.0.0.1` are owned by the same Gateway process. Ambiguous listener ownership fails closed with status guidance. diff --git a/docs/cli/onboard.md b/docs/cli/onboard.md index be5182814ec6..b09a40faa4db 100644 --- a/docs/cli/onboard.md +++ b/docs/cli/onboard.md @@ -145,11 +145,13 @@ are matched through your configured model and ClawHub search, and the step can be disabled with [`wizard.appRecommendations`](/gateway/configuration-reference#wizard). In a macOS, Linux, or Windows desktop session, it then opens the authenticated Control UI dashboard and waits up to 60 seconds for the browser client to -connect. On headless Linux or over SSH, it prints a prominent copy-pasteable -dashboard URL, including an SSH port-forward command for a loopback Gateway, -and waits up to five minutes. A successful connection continues in the browser; -an unreachable Gateway or a timeout falls back to the same terminal hatch as -before. Pass `--tui` to skip the browser handoff and force that terminal hatch. +connect. The short-lived handoff gives that exact signed browser a durable +administrator credential. On headless Linux or over SSH, it prints a prominent +copy-pasteable dashboard URL, including an SSH port-forward command for a +loopback Gateway, and waits up to five minutes. A successful connection +continues in the browser; an unreachable Gateway or a timeout falls back to the +same terminal hatch as before. Pass `--tui` to skip the browser handoff and +force that terminal hatch. If applying setup fails, onboarding falls back to the conversational OpenClaw chat to finish interactively. Channels, agents, plugins, and other optional features remain OpenClaw chat territory: run diff --git a/docs/gateway/operator-scopes.md b/docs/gateway/operator-scopes.md index e6a8531103d5..ce754d3a4926 100644 --- a/docs/gateway/operator-scopes.md +++ b/docs/gateway/operator-scopes.md @@ -92,6 +92,14 @@ An already-paired device does not get broader access silently: a reconnect that asks for a broader role or broader scopes creates a new pending upgrade request. +The explicit exception is the administrator-capable Control UI owner profile +issued directly on the Gateway host by `openclaw dashboard` or graphical +onboarding. Its short-lived, single-use bootstrap can approve the exact closed +scope set for a fresh browser or upgrade an existing limited credential only +when it binds to that same signed browser keypair. Generic Control UI and +Telegram handoffs, mobile setup profiles, shared credentials, locality, and +caller-selected scopes do not receive this exception. + Approving a device request: - A request with no operator role does not need operator scope approval. diff --git a/docs/web/control-ui.md b/docs/web/control-ui.md index b50926ab9dc8..520b37c21d2f 100644 --- a/docs/web/control-ui.md +++ b/docs/web/control-ui.md @@ -47,7 +47,7 @@ Onboarding usually configures a gateway token for shared-secret auth. If the Gat ## Device pairing (first connection) -After gateway auth succeeds, connecting from a new browser or device usually requires a **one-time pairing approval**, shown as `disconnected (1008): pairing required`. On the Gateway host, `openclaw dashboard` is the preferred recovery path: it opens a short-lived, single-use pairing link and leaves the browser with a durable per-device credential. +After gateway auth succeeds, connecting from a new browser or device usually requires a **one-time pairing approval**, shown as `disconnected (1008): pairing required`. On the Gateway host, `openclaw dashboard` is the preferred owner path: it opens a short-lived, single-use pairing link and leaves that exact signed browser with a durable administrator credential. Opening a fresh link in the same browser also repairs a previously limited credential; another browser profile cannot inherit or replay the grant. When upgrading directly from a release that used the retired @@ -78,7 +78,7 @@ silently discarding the old key. If the browser retries pairing with changed auth details (role/scopes/public key), the previous pending request is superseded and a new `requestId` is created; re-run `openclaw devices list` before approving. -Switching an already-paired remote browser from read access to write/admin access is treated as an approval upgrade, not a silent reconnect: OpenClaw keeps the old approval active, blocks the broader reconnect, and asks you to approve the new scope set explicitly. A qualifying direct-loopback Control UI connection can silently approve the upgrade after it authenticates. +Switching an already-paired browser from read access to write/admin access through ordinary stored or shared credentials is treated as an approval upgrade, not a silent reconnect: OpenClaw keeps the old approval active, blocks the broader reconnect, and asks you to approve the new scope set explicitly. The narrow exception is a fresh owner handoff issued on the Gateway host by `openclaw dashboard` or graphical onboarding; it can upgrade only the same signed browser that redeems that one-time handoff. Once approved, the device is remembered and won't require re-approval unless you revoke it with `openclaw devices revoke --device --role `. See [Devices CLI](/cli/devices) for token rotation, revocation, and the Paperclip / `openclaw_gateway` first-run approval flow. diff --git a/docs/web/dashboard.md b/docs/web/dashboard.md index 5505dc267e01..117663d8a3a8 100644 --- a/docs/web/dashboard.md +++ b/docs/web/dashboard.md @@ -35,7 +35,8 @@ The Control UI is an **admin surface** (chat, config, exec approvals). Do not ex - After onboarding, the CLI auto-opens the dashboard and prints a clean link. - Re-open or repair a browser anytime: `openclaw dashboard`. It copies/opens a single-use pairing link - that replaces stale browser credentials without granting blanket remote auto-approval. + that grants administrator access to that exact signed browser, including recovery from a previously + limited credential, without granting blanket remote auto-approval. - If clipboard and browser delivery both fail, `openclaw dashboard` either gives a safe manual-token hint or tells you to run `openclaw dashboard --json` and open its short-lived `browserUrl`; it never prints the shared token value in interactive logs. @@ -49,7 +50,8 @@ The Control UI is an **admin surface** (chat, config, exec approvals). Do not ex is kept in sessionStorage for the current tab and selected gateway URL, not localStorage. - **Host-authorized browser handoff**: `openclaw dashboard` issues a short-lived, single-use bootstrap instead of putting the shared Gateway token in the browser launch URL. The bootstrap is bound to - that browser's signed device identity and exchanged for a durable per-device credential. + that browser's signed device identity and exchanged for a durable administrator credential. A + different browser profile cannot redeem the same handoff or inherit the resulting access. - **Missing-config runtime token**: if startup says it generated a runtime token, that token is ephemeral and cannot be recovered. Loopback still requires auth. Run `openclaw doctor --generate-gateway-token`, restart the Gateway, then run `openclaw gateway auth-token --show` in an interactive terminal and paste the output into Control UI settings. - If `gateway.auth.token` is SecretRef-managed, the interactive dashboard handoff still works because it carries only the short-lived browser bootstrap; the external shared token is not placed in @@ -69,7 +71,9 @@ Requirements: - Run `/dashboard` in a DM with the bot. Group invocations only tell you to open the command in DM and do not include a button. - Docker installs: Serve/Funnel modes require the gateway to bind loopback next to `tailscaled`, which bridge networking with published ports cannot satisfy. Run the gateway container with `network_mode: host` and mount the host `tailscaled` socket (`/var/run/tailscale`) plus the `tailscale` CLI into the container. -The Mini App performs a one-time owner handoff and redirects to Control UI with a short-lived bootstrap token. It does not expose a shared gateway token in the URL. +The Mini App performs a bounded one-time dashboard handoff and redirects to Control UI with a +short-lived bootstrap token. It does not expose a shared gateway token in the URL, and it does not +receive the administrator grant reserved for handoffs issued directly by the Gateway host. Non-goals for v1: