Remote gateway node pairing broken — node token scopes empty, approval flow incomplete

[AS76]

Issue: Remote gateway node pairing broken — node token scopes empty, approval flow incomplete

Replaces locked issue #663

Summary

The Windows tray Node Mode can connect to a remote gateway, but the pairing and token scoping flow is broken for remote gateway setups. The feature was described as "already implemented" in #663 which was then locked, but the implementation doesn't work in practice.

Environment

• Client: OpenClaw Windows Hub v0.6.0 (latest)
• Gateway: VPS behind reverse proxy (wss:// Traefik + Let's Encrypt)
• Setup: Node Mode enabled, remote gateway URL + auth token configured

What works

• Device (operator) connection via wss:// ✅
• Paired device shows on gateway ✅
• Control UI session over remote WebSocket ✅

What doesn't work (remote Node Mode)

1. Node token scopes empty — after device pairing approval, the node token is issued with scopes: [] while the operator token gets proper scopes. The gateway doesn't assign node-appropriate scopes for remote connections.

2. openclaw nodes approve returns unknown requestId — node-specific pairing requests never appear as pending on the gateway side. The approval flow advertised in the docs doesn't work.

3. openclaw devices rotate --role node denied — token rotation rejects the node role, so even manually fixing scopes in paired.json doesn't survive rotation.

4. Tray UI stuck — Windows tray UI stays in "Awaiting approval" state indefinitely even after device approval completes on the gateway.

Use case

Corporate laptop with restricted IT policy, no local gateway possible. A lightweight Windows node client connecting to a remote VPS gateway would enable:

• exec host=node commands from the remote agent on the Windows machine
• Local file access without GDrive/workaround
• Agent availability on the laptop without full gateway installation

Request

Re-open and track the remaining pairing/scoping bugs so remote Node Mode actually works. Happy to provide logs and reproduce on demand.

[clawsweeper]

Codex review: keeping this open for maintainer follow-up; there is still a little grit to resolve. Reviewed June 7, 2026, 4:50 AM ET / 08:50 UTC.

Summary
Keep open: this is a concrete follow-up to #663, and current main does not conclusively prove the remote node token/approval flow is fixed. The client has node-pairing support, but source still shows empty node handshake scopes, mixed manual approval guidance, and no automated live remote gateway/node pairing coverage.

Reproducibility: no. high-confidence live reproduction was established in this read-only review. The report has concrete steps and current source shows matching risk signals, but full remote gateway/node pairing is explicitly not covered by automated tests here.

Ways to help us reproduce this

• Add a screenshot or short recording showing the behavior.
• Add expected vs actual behavior.

Next step
Maintainer/gateway auth review and a live remote-gateway reproduction are needed before a safe repair can be scoped.

Security
Needs attention: The issue is security-sensitive because it involves node token scopes, pairing authorization, and remote execution enablement.

Review details

Best possible solution:

Keep this issue open until a maintainer validates a current v0.6.3/current-main remote gateway smoke and either fixes the node token/approval contract or documents the supported remote setup path precisely.

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

No high-confidence live reproduction was established in this read-only review. The report has concrete steps and current source shows matching risk signals, but full remote gateway/node pairing is explicitly not covered by automated tests here.

Is this the best way to solve the issue?

No, closing as implemented is not the best path yet. The safer path is to reproduce on current release/main and repair or clarify the role-specific node token and approval flow across Windows client and gateway surfaces.

AGENTS.md: found and applied where relevant.

Remaining risk / open question:

• The report was made against v0.6.0 while the repository context says v0.6.3 is the latest release, so maintainers should first confirm whether any symptoms still reproduce on v0.6.3 or current main.
• Some symptoms, especially token scopes, requestId ownership, and node-role rotation, may require gateway CLI/API changes outside this repository.

Codex review notes: model gpt-5.5, reasoning high; reviewed against 4be005707f44.

Label changes

Label changes:

• add P1: Remote Node Mode pairing reportedly blocks the real agent-to-Windows-node workflow for a remote gateway user.
• add impact:security: Node pairing and scoped device tokens are authorization boundaries for remote execution on the Windows machine.
• add impact:auth-provider: The report centers on token scopes, role-specific pairing, approval request IDs, and node-role credential rotation.
• add issue-rating: 🐚 platinum hermit: Current issue advisory state selects this label.
• add clawsweeper:needs-live-repro: Current issue advisory state selects this label.
• add clawsweeper:no-new-fix-pr: Current issue advisory state selects this label.
• add clawsweeper:needs-maintainer-review: Current issue advisory state selects this label.
• add clawsweeper:needs-product-decision: Current issue advisory state selects this label.
• add clawsweeper:needs-security-review: Current issue advisory state selects this label.

Label justifications:

• P1: Remote Node Mode pairing reportedly blocks the real agent-to-Windows-node workflow for a remote gateway user.
• impact:auth-provider: The report centers on token scopes, role-specific pairing, approval request IDs, and node-role credential rotation.
• impact:security: Node pairing and scoped device tokens are authorization boundaries for remote execution on the Windows machine.

Evidence reviewed

Security concerns:

• [medium] Node token and pairing authorization need owner review — src/OpenClaw.Shared/WindowsNodeClient.cs:651
  The reported empty scopes and denied node-role rotation affect whether a remote Windows node is correctly authorized after pairing, so maintainers should review the gateway and client auth contract before treating this as resolved.
  Confidence: 0.75

What I checked:

• Repository policy read: AGENTS.md was read fully, and its connection/pairing guidance led the review through the connection architecture, MCP mode, Windows node testing, and onboarding docs before assessing the issue. (AGENTS.md:1, 4be005707f44)
• Reporter follow-up context: The reporter had already commented on the locked predecessor with the same concrete remote gateway symptoms: empty node scopes, node approval unknown requestId, denied node-role rotation, and tray awaiting approval.
• Current node handshake still sends empty scopes: WindowsNodeClient signs and sends the node connect payload with Array.Empty() scopes while relying on role, caps, commands, and gateway-issued auth scopes; this matches a central part of the report and needs gateway-contract confirmation before closing. (src/OpenClaw.Shared/WindowsNodeClient.cs:651, 4be005707f44)
• Client-side node auto-approval exists: GatewayConnectionManager can auto-approve node pairing through NodePairApproveAsync when the operator client is connected and has operator.admin/operator.pairing scope, so the remaining failure may be specific to remote gateway token/CLI behavior rather than absence of client plumbing. (src/OpenClaw.Connection/GatewayConnectionManager.cs:1057, 4be005707f44)
• Manual approval surfaces are inconsistent: The Connection page builds noun-first node approval commands, but the lower-level Windows node client still logs devices approve guidance for NOT_PAIRED, which is relevant to the reported approval-flow confusion. (src/OpenClaw.Tray.WinUI/Pages/ConnectionPagePlan.cs:523, 4be005707f44)
• Remote pairing is not fully covered: The test coverage document explicitly lists full live gateway/node pairing against a remote gateway as not fully covered by automated tests, so source support alone is not enough to close this real remote setup report. (docs/TEST_COVERAGE.md:92, 4be005707f44)

Likely related people:

• Ranjesh Jaganathan: Auth bootstrap, node pairing, and node.pair.approve history point to this contributor across WindowsNodeClient, GatewayConnectionManager, and SetupEngine pairing work. (role: feature-history contributor; confidence: high; commits: 8cc2c545be62, 398420a92843, cf0f3f3192f8; files: src/OpenClaw.Shared/WindowsNodeClient.cs, src/OpenClaw.Connection/GatewayConnectionManager.cs, src/OpenClaw.SetupEngine/SetupSteps.cs)
• Vincent Koc: Recent merged node reconnect and persisted node token work is directly adjacent to the reported remote node pairing/token persistence problem. (role: recent area contributor; confidence: high; commits: ee8fd4ef4ff0, 66683a33e770, 64b650cb3313; files: src/OpenClaw.Shared/WindowsNodeClient.cs, src/OpenClaw.Connection/GatewayConnectionManager.cs)
• Scott Hanselman: Recent history removed operator-side node pair auto-approve behavior, which is adjacent to the manual and automatic approval boundary this report is about. (role: adjacent behavior contributor; confidence: medium; commits: 45dccec60c51; files: src/OpenClaw.Connection/GatewayConnectionManager.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.

[AS76]

Live reproduction — screenshots attached

Here are the screenshots from OpenClaw Windows Companion v2026.6.1 connected to a remote gateway:

Evidence

Screenshot 1 — Connection overview:

• "Node active · 0 capabilities" / "Providing no capabilities"
• Operator: "Active · no current sessions"
• Gateway connected via wss://[redacted]/ (remote VPS, not local)

Screenshot 2 — Full view:

• Same connection from overview + gateways list
• Node mode confirmed active but providing zero capabilities
• Device registered as operator but node role has no functional scopes

Summary

Item	Expected	Actual
Node mode ON	Tool execution, file access	0 capabilities, nothing provided
Role: Node	Scopes for node operations	Empty scopes (confirmed via paired.json)
nodes approve	Match node pairing requests	Returns unknown requestId
Token rotation	Rotate with --role node	Denied for node role

Happy to provide gateway logs or paired.json excerpts (with tokens redacted) on request.

[AS76]

[AS76]

[sorry123luck]

I can reproduce a closely related approval/token/capability-registration issue in a fully local loopback setup.

Unlike the remote gateway setup in #710, this does not require a VPS, reverse proxy, or public wss:// endpoint. The Gateway is running locally in WSL on the same Windows machine, and the Windows Companion connects to ws://127.0.0.1:18789.

This suggests the same approval/token state-machine problem can also affect the default/local Windows + WSL setup. I also have a concrete recovery path from this machine.

Environment

• OpenClaw Windows Companion: v2026.6.1
• Companion app/node version: 0.6.3
• Gateway: OpenClaw v2026.6.1, running in local WSL on the same Windows machine
• Gateway URL used by Companion: ws://127.0.0.1:18789
• Windows user: Administrator
• Windows build reported by device.info: Microsoft Windows 10.0.26220
• Companion identity file:
  • %APPDATA%\OpenClawTray\gateways\<gateway-id>\device-key-ed25519.json
• Gateway state files involved:
  • ~/.openclaw/devices/paired.json
  • ~/.openclaw/nodes/paired.json

Loopback connectivity was already working:

curl.exe http://127.0.0.1:18789/
Test-NetConnection 127.0.0.1 -Port 18789

So this was not a port/firewall issue.

Symptoms

Windows Companion UI showed:

• Gateway connected
• operator online
• node mode enabled
• Node active
• System tools / Browser control / Camera toggles enabled
• but node activity still showed 0 capabilities

Gateway initially showed the Windows node as paired but disconnected, or later connected with no caps/commands:

{
  "clientId": "node-host",
  "clientMode": "node",
  "caps": [],
  "commands": [],
  "paired": true,
  "connected": true
}

Trying to invoke a node command failed with:

nodes invoke failed: GatewayClientRequestError: node command not allowed: the node did not declare any supported commands

Evidence

Gateway logs showed repeated auth/repair paths:

unauthorized ... role=node ... reason=device_token_mismatch
device access upgrade requested reason=role-upgrade ... roleFrom=operator roleTo=node ... client=node-host
device metadata upgrade requested reason=metadata-upgrade ... client=cli

Companion logs showed that the Windows node did build and send capabilities:

Capabilities registered: system, canvas, screen, camera, location, tts, stt, device, browser (9 caps)
[NodeService] AttachClient DONE: client.Registration.Capabilities=9, client.Registration.Commands=29

[HANDSHAKE] role=node, clientId=node-host, mode=node
[HANDSHAKE] caps=9: [system, canvas, screen, camera, location, tts, stt, device, browser]
[HANDSHAKE] commands=29: [...]
[HANDSHAKE] isBootstrap=False, hasNodeDeviceToken=True
Node registered successfully!
Node status: Connected

But openclaw nodes status --json still showed caps=[] / commands=[] until the separate node capability approval was completed.

What fixed it

The working recovery required three separate pieces to line up:

1. Device/operator approval:

openclaw devices approve <operator-request-id>

2. Device/node role approval:

openclaw devices approve <node-role-request-id>

3. Node capability approval:

openclaw nodes pending --json
openclaw nodes approve <node-capability-request-id>

In this case, nodes pending contained the actual capability surface:

{
  "caps": [
    "system",
    "canvas",
    "screen",
    "camera",
    "location",
    "tts",
    "stt",
    "device",
    "browser"
  ],
  "commands": [
    "system.notify",
    "system.run",
    "system.run.prepare",
    "system.which",
    "canvas.present",
    "canvas.hide",
    "canvas.navigate",
    "canvas.eval",
    "canvas.snapshot",
    "canvas.a2ui.push",
    "canvas.a2ui.pushJSONL",
    "canvas.a2ui.reset",
    "screen.snapshot",
    "camera.list",
    "location.get",
    "tts.speak",
    "stt.transcribe",
    "device.info",
    "device.status",
    "browser.proxy"
  ]
}

Also, the Companion local identity could drift from the Gateway state. In my case I had to verify/sync:

DeviceToken      <-> ~/.openclaw/devices/paired.json[deviceId].tokens.operator.token
NodeDeviceToken  <-> ~/.openclaw/devices/paired.json[deviceId].tokens.node.token

After approving the node capability request, nodes status showed:

{
  "clientId": "node-host",
  "clientMode": "node",
  "caps": [
    "browser",
    "camera",
    "canvas",
    "device",
    "location",
    "screen",
    "stt",
    "system",
    "tts"
  ],
  "commands": [
    "browser.proxy",
    "camera.list",
    "canvas.a2ui.push",
    "canvas.a2ui.pushJSONL",
    "canvas.a2ui.reset",
    "canvas.eval",
    "canvas.hide",
    "canvas.navigate",
    "canvas.present",
    "canvas.snapshot",
    "device.info",
    "device.status",
    "location.get",
    "screen.snapshot",
    "stt.transcribe",
    "system.notify",
    "system.run",
    "system.run.prepare",
    "system.which",
    "tts.speak"
  ],
  "paired": true,
  "connected": true
}

And this succeeded:

openclaw nodes invoke --node <device-id> --command device.info --params '{}' --json

UX issue

From a user perspective this flow is extremely hard to understand.

The UI can show "Connected", "Node active", and enabled permission toggles, while the Gateway still exposes 0 capabilities. The missing step is not obvious because devices approve and nodes approve are separate approval paths.

The Companion should either guide the user through all required approvals, or show a clear state such as:

Node capabilities approval pending
Run: openclaw nodes approve <request-id>

It would also help if the UI distinguished:

• operator/device approval pending
• node role approval pending
• node capability approval pending
• token mismatch / repair required

Right now all of these can look like "Connected / Node active / 0 capabilities", which is very hard to recover from without inspecting logs and Gateway state manually.

Suggested local-loopback behavior

For the local WSL Gateway + Windows Companion case, it would be much better if the app exposed this as one trusted local-node approval flow instead of several separate hidden approval paths.

Possible fixes:

• Auto-approve the Companion's own local node role/capability request when the Gateway is local loopback and the operator has already approved the same local device.
• Or show a single "Approve local Windows node" action that performs both the node role approval and the node capability approval.
• If auto-approval is not acceptable, the UI should at least surface the exact pending request and command, for example:

Node capabilities approval pending
Run: openclaw nodes approve <request-id>

This seems related to previous fixes in the same area, especially #382 (node.pair.approve vs device.pair.approve causing 0 effective commands), #461 (capability binding diagnostics), #587 (stale token mismatch recovery), and #616 (clearer reconnect/startup state).