ewilliams28/openclaw
1
0
Fork 0
mirror of https://github.com/openclaw/openclaw.git synced 2026-08-12 21:53:00 -06:00
Code Issues Packages Projects Releases Wiki Activity

docs: document control ui owner handoff

Browse Source
This commit is contained in:
Shakker
2026-08-06 01:14:44 +01:00
parent c56ad42525
commit 47591e7b11
6 changed files with 30 additions and 14 deletions
Download Patch File Download Diff File Expand all files Collapse all files
CHANGELOG.md
+1
View File
@@ -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.
docs/cli/dashboard.md
+5 -4
View File
@@ -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.
docs/cli/onboard.md
+7 -5
View File
@@ -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
docs/gateway/operator-scopes.md
+8
View File
@@ -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.
docs/web/control-ui.md
+2 -2
View File
@@ -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.
<Warning>
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 <id> --role <role>`. See [Devices CLI](/cli/devices) for token rotation, revocation, and the Paperclip / `openclaw_gateway` first-run approval flow.
docs/web/dashboard.md
+7 -3
View File
@@ -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: