QR-code pairing leaves the tray app permanently stuck in role: "node"

[Valkster70]

QR-code pairing leaves the tray app permanently stuck in role: "node"

Summary

The QR-code pairing flow in the Windows tray app produces a bootstrap token that the gateway ties to a node-role client. The tray app then enters a structural loop: it cannot mint a permanent device token (because that path is gated on !_bootstrapPairAsNode), so every reconnect re-uses the bootstrap token → role stays "node" → chat.send and any other operator.* methods fail with unauthorized role: node.

The user-visible symptom is: after the first successful QR-pair handshake, every chat message from the tray app is rejected with:

send failed: unauthorized role: node

The companion node capabilities (system.run, system.which, etc.) work, but the actual chat surface does not.

Root cause (with code references)

The role is decided by OpenClawGatewayClient.GetConnectRole() (src/OpenClaw.Shared/OpenClawGatewayClient.cs):

private string GetConnectRole()
{
    return _bootstrapPairAsNode && _tokenIsBootstrapToken && string.IsNullOrEmpty(_deviceIdentity.DeviceToken)
        ? "node"
        : OperatorRole; // "operator"
}

bootstrapPairAsNode is set from the credential in GatewayClientFactory.cs:

var client = new OpenClawGatewayClient(
    gatewayUrl,
    credential.Token,
    logger,
    tokenIsBootstrapToken: credential.IsBootstrapToken,
    bootstrapPairAsNode: credential.IsBootstrapToken,   // <-- always true for bootstrap tokens
    identityPath: identityPath);

So whenever the credential is a bootstrap token (which is exactly what the QR-code pairing path produces), the role is locked to "node".

The device-token minting path that would normally break the loop is gated on the opposite condition:

// OpenClawGatewayClient.cs (paraphrased from the pairing flow)
var newDeviceToken = !_bootstrapPairAsNode ? await MintDeviceToken(...) : null;

So:

• _bootstrapPairAsNode = true (always, for QR pairing)
• → role is "node"
• → newDeviceToken = null (minting skipped)
• → reconnect re-uses the bootstrap token
• → _bootstrapPairAsNode is still true
• → role is still "node"
• → loop

The user can break out of the loop only by:

1. Quitting the tray app
2. Deleting %APPDATA%\OpenClawTray\gateways\* and gateways.json (forcing a fresh credential)
3. Re-opening the app and using the Advanced setup wizard with a non-bootstrap gateway token directly (not QR code)

Reproduction

1. Fresh install of OpenClawCompanion-Setup-x64.exe on a Windows machine.
2. In the gateway's webui, open Settings → Nodes → "Add a device" and show the QR code.
3. On Windows: right-click the tray icon → "Pair with QR code" → scan.
4. Tray icon turns green, app registers as a node, but any chat message returns unauthorized role: node.
5. Quit and reopen the tray app — it cannot reconnect (saved credential is still a bootstrap token, the device-token path is gated, and the gateway will keep treating reconnects as node role).

Expected behavior

• The tray app should register as an operator-role client (the default) when pairing via QR code for a chat-only install.
• On first successful connect, the tray app should mint a permanent device token, save it locally, and use it on subsequent reconnects — so the bootstrap token is used exactly once.
• The role on the wire should be operator (or whatever the user chose during onboarding), not auto-flipped to node based on the credential type.

Suggested fix

In GatewayClientFactory.cs, decouple bootstrapPairAsNode from IsBootstrapToken. The bootstrap token is a first-contact credential, not a permanent role assignment. A few options:

1. Always pair as operator by default, and only use node role if the user explicitly opts in to node capabilities during onboarding. (Most aligned with the "chat app" use case for the tray.)
2. Persist a role preference in the per-gateway folder (e.g., gateways/{uuid}/role.json) so the user's choice during onboarding survives across reconnects.
3. Always mint a device token after successful bootstrap, and use that for subsequent reconnects. The bootstrap token is then only used once, and bootstrapPairAsNode becomes a transient flag, not a permanent one.

Option 1 + 3 together would fix the most cases: a fresh QR-pair flow would default to operator (chat works), and even if a user does want node capabilities, the device-token mint would break the loop and the user could re-elevate to node explicitly if they want.

Workaround (for users hitting this today)

The Advanced setup wizard accepts a non-bootstrap gateway token directly. Users hitting this bug can:

1. Quit the tray app.
2. Delete %APPDATA%\OpenClawTray\gateways\* and gateways.json.
3. Reopen → "Advanced setup" → URL = wss://gateway-host:18789 (or your tailnet URL) + Token = a real non-bootstrap gateway token + Session = main.
4. Skip the WSL gateway install. The app will register as operator and chat will work.

This workaround works because a non-bootstrap token sets bootstrapPairAsNode: false from the start, so GetConnectRole() returns "operator" immediately.

Environment

• OpenClawCompanion-Setup-x64.exe v2026.6.x (current release as of 2026-06-08)
• Windows 11 24H2, x64
• Gateway: OpenClaw v2026.6.1 (commit 2e08f0f) on a separate Linux host, exposed via Tailscale Serve (HTTPS on :443 → gateway on 127.0.0.1:18789)
• Connect URL used (tray app → gateway): wss://<your-gateway>.ts.net (no port; Tailscale Serve proxies 443→18789)

Related notes

• The tray app's NodeService registers as a separate node-platform client with full node capabilities (camera, screen, system.run, etc.) when EnableNodeMode: true in settings.json. This is a separate "node" concept from the role: "node" in this bug. Confusingly named, but distinct. (Workaround for chat-only installs: set EnableNodeMode: false and all Node*Enabled: false.)
• The tray app's GatewayUrlHelper.NormalizeForWebSocket is a pure URL normalizer — it does not add a port. If the user supplies wss://gateway:18789 but the gateway is only reachable on :443 via a proxy (e.g., Tailscale Serve), the connect will fail with "Transport error". Workaround: omit the port. (Could be worth a second issue: the wizard's "Advanced setup" should probably auto-detect and strip the port, or document the proxy case more clearly.)

[clawsweeper]

Codex review: keeping this open for maintainer follow-up; there is still a little grit to resolve. Reviewed June 8, 2026, 9:31 AM ET / 13:31 UTC.

Summary
This should stay open: current main still routes setup-code bootstrap credentials through the node-role handoff path, and the existing tests cover a no-operator-token handshake that would leave the tray without a durable operator credential for chat.

Reproducibility: yes. from source inspection, not from a live Windows/gateway run. Applying a setup code stores a bootstrap credential, the factory turns bootstrap credentials into node handoff, and the current handshake tests cover the no-operator-token outcome.

Next step
The source path, likely files, and validation commands are clear enough for one focused repair PR.

Review details

Best possible solution:

Fix the setup-code bootstrap path so QR pairing leaves the operator client with a durable operator credential for chat, while preserving device-token precedence and the explicit node-mode handoff.

Do we have a high-confidence way to reproduce the issue?

Yes from source inspection, not from a live Windows/gateway run. Applying a setup code stores a bootstrap credential, the factory turns bootstrap credentials into node handoff, and the current handshake tests cover the no-operator-token outcome.

Is this the best way to solve the issue?

Yes, the best fix is a narrow credential/role handoff repair in the setup-code path. A new persisted role preference or broad onboarding redesign should be avoided unless maintainers explicitly choose that product direction.

AGENTS.md: found and applied where relevant.

Remaining risk / open question:

• No live Windows/gateway reproduction was run in this read-only review; the source path and current tests are the basis for the keep-open decision.
• A repair needs to preserve explicit Windows node-mode pairing while ensuring the operator chat client gets a durable operator credential.

Codex review notes: model gpt-5.5, reasoning high; reviewed against 37b0ea672037.

Label changes

Label justifications:

• P1: QR pairing can leave real users with a connected tray whose chat sends are rejected after setup.
• impact:auth-provider: The issue is about bootstrap credentials, device-token persistence, and gateway role authorization.
• impact:message-loss: The user-visible failure is chat.send being rejected as unauthorized after QR pairing.

Evidence reviewed

Acceptance criteria:

• ./build.ps1
• dotnet test ./tests/OpenClaw.Connection.Tests/OpenClaw.Connection.Tests.csproj
• dotnet test ./tests/OpenClaw.Shared.Tests/OpenClaw.Shared.Tests.csproj --no-restore
• dotnet test ./tests/OpenClaw.Tray.Tests/OpenClaw.Tray.Tests.csproj --no-restore

What I checked:

• Repository policy applied: AGENTS.md was read fully; its connection/pairing guidance requires reviewing the gateway registry, credential precedence, connection manager, node/MCP behavior, and tray UX before changing this area. (AGENTS.md:34, 37b0ea672037)
• Documented setup-code flow expects a persisted device token: The architecture docs say setup codes decode to url/bootstrapToken, clear stored tokens, connect, then the gateway returns hello-ok.auth.deviceToken and the connection manager persists it. (docs/CONNECTION_ARCHITECTURE.md:158, 37b0ea672037)
• Setup-code path stores bootstrap and clears existing tokens: ApplySetupCodeAsync stores the decoded token as BootstrapToken, clears stored device tokens, and connects to the gateway record, which recreates the reported fresh QR-pairing path. (src/OpenClaw.Connection/GatewayConnectionManager.cs:492, 37b0ea672037)
• Bootstrap credentials are still mapped to node handoff: GatewayClientFactory still passes bootstrapPairAsNode: credential.IsBootstrapToken for the operator client, so any bootstrap setup-code credential selects the node handoff behavior. (src/OpenClaw.Connection/GatewayClientFactory.cs:17, 37b0ea672037)
• Connect role becomes node for a fresh bootstrap credential: GetConnectRole returns node when bootstrapPairAsNode and tokenIsBootstrapToken are true and no operator DeviceToken is stored. (src/OpenClaw.Shared/OpenClawGatewayClient.cs:1225, 37b0ea672037)
• Current tests preserve the no-operator-token case: BootstrapNodeHandoff_HelloOkWithNodeRole_DoesNotStorePrimaryNodeTokenAsOperator asserts that a node-role hello-ok stores only the node token and leaves the operator token null. (tests/OpenClaw.Shared.Tests/OpenClawGatewayClientTests.cs:601, 37b0ea672037)

Likely related people:

• Vincent Koc: git log -S shows the bootstrap setup-code-as-node behavior in 5aeb8f6 and the complete node bootstrap handoff/test work in eb06fba. (role: introduced behavior and recent pairing handoff owner; confidence: high; commits: 5aeb8f6bcbde, eb06fba21c44; files: src/OpenClaw.Connection/GatewayClientFactory.cs, src/OpenClaw.Shared/OpenClawGatewayClient.cs, tests/OpenClaw.Shared.Tests/OpenClawGatewayClientTests.cs)
• Ranjesh Jaganathan: The extracted OpenClaw.Connection project, GatewayConnectionManager, GatewayClientFactory, and SetupCodeFlowTests entered through ffeff39, which is central to the current setup-code path. (role: connection-layer refactor owner; confidence: medium; commits: ffeff39c16c5; files: src/OpenClaw.Connection/GatewayConnectionManager.cs, src/OpenClaw.Connection/GatewayClientFactory.cs, tests/OpenClaw.Connection.Tests/SetupCodeFlowTests.cs)
• Mike Harsh: The WSL local gateway onboarding work in 581f78d modified OpenClawGatewayClient around the setup/onboarding pairing surface that later gained the node handoff behavior. (role: adjacent onboarding contributor; confidence: low; commits: 581f78d276e1; files: src/OpenClaw.Shared/OpenClawGatewayClient.cs)

How this review workflow works

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

[Valkster70]

Heads up — I scrubbed a personal tailnet hostname from the Environment section (replaced with a placeholder). The technical content, repro steps, root-cause analysis, and suggested fixes are unchanged. Thanks to ClawSweeper for the P1 + impact labels.

[github-actions]

🤖 This is an automated response from Repo Assist.

I have investigated and confirmed the root cause described in this issue. A fix is in review:

PR branch: repo-assist/fix-issue-720-operator-qr-pair-role

Root cause confirmed: GatewayClientFactory.Create() passed bootstrapPairAsNode: credential.IsBootstrapToken for the operator (chat) client. For bootstrap tokens this set bootstrapPairAsNode: true, which caused GetConnectRole() to return "node" — permanently locking the tray in node role with no upgrade path.

Fix: Set bootstrapPairAsNode: false unconditionally for the operator client. The operator client should always connect as operator role. The node-platform client has its own creation path (NodeConnector) and sets bootstrapPairAsNode independently.

All tests pass (Connection.Tests: 297/297, Shared.Tests: 2123 passed, Tray.Tests: 974/974).

Generated by 🌈 Repo Assist, see workflow run. Learn more.

Add this agentic workflows to your repo

To install this agentic workflow, run

gh aw add githubnext/agentics/workflows/repo-assist.md@97143ac59cb3a13ef2a77581f929f06719c7402a