Docs: correct the setup-code expiry contract

[steipete]

Summary

docs/gateway-node-integration.md repeatedly says official setup codes embed expiry metadata, but the Gateway payload and active Windows decoder contain only URL and bootstrap-token fields.

Current behavior

The guide describes { url, bootstrapToken, expiresAtMs }, says the decoded payload contains expiry, and retains a checklist item for a Windows expiry parser that was removed in #925.

Expected behavior

Document the upstream payload as { url, urls?, bootstrapToken }, the Windows-consumed shape as { url, bootstrapToken }, and the 10-minute lifetime as Gateway-enforced rather than serialized into the setup code.

Impact

Windows integration work can incorrectly require or implement a field that official setup codes never contain, or assume the current tray performs a client-side expiry check that no longer exists.

Evidence

• Upstream payload type and builder omit expiry: https://github.com/openclaw/openclaw/blob/d395a8e6ec2789763b746b1e96ed5870c7795bd7/src/pairing/setup-code.ts#L37-L41 and https://github.com/openclaw/openclaw/blob/d395a8e6ec2789763b746b1e96ed5870c7795bd7/src/pairing/setup-code.ts#L434-L445
• Gateway token state applies a 10-minute TTL: https://github.com/openclaw/openclaw/blob/d395a8e6ec2789763b746b1e96ed5870c7795bd7/src/infra/device-bootstrap.ts#L25-L26
• Current Windows decoder reads only url and bootstrapToken:

  openclaw-windows-node/src/OpenClaw.Connection/SetupCodeDecoder.cs

  Lines 47 to 77 in 053501c

  	string? url = null;
  	string? token = null;
  	if (doc.RootElement.TryGetProperty("url", out var urlProp))
  	{
  	if (urlProp.ValueKind != JsonValueKind.String)
  	return new DecodeResult(false, Error: "Invalid gateway URL in setup code");
  	var decoded = urlProp.GetString() ?? "";
  	if (!string.IsNullOrEmpty(decoded))
  	{
  	if (!GatewayUrlHelper.IsValidGatewayUrl(decoded))
  	return new DecodeResult(false, Error: "Invalid gateway URL in setup code");
  	url = decoded;
  	}
  	}
  	if (doc.RootElement.TryGetProperty("bootstrapToken", out var tokenProp))
  	{
  	if (tokenProp.ValueKind != JsonValueKind.String)
  	return new DecodeResult(false, Error: "Invalid bootstrap token in setup code");
  	var decoded = tokenProp.GetString() ?? "";
  	if (decoded.Length > 512)
  	return new DecodeResult(false, Error: "Bootstrap token exceeds 512 character limit");
  	if (!string.IsNullOrEmpty(decoded))
  	token = decoded;
  	}
  	if (url == null && token == null)
  	return new DecodeResult(false, Error: "Setup code must include a gateway URL or bootstrap token");
  	return new DecodeResult(true, Url: url, Token: token);

• The upstream documentation correction landed in docs(pairing): correct setup-code expiry payload openclaw#103943.

No open duplicate issue or PR was found.

[clawsweeper]

Codex review: keeping this open for maintainer follow-up; there is still a little grit to resolve. Reviewed July 10, 2026, 5:14 PM ET / 21:14 UTC.

Summary
Current main and the latest release still document an expiry field that neither the authoritative Gateway payload nor the active Windows decoder contains, and no duplicate or implementation PR owns the correction.

Reproducibility: yes. at source level. Comparing the current integration guide with SetupCodeDecoder, the architecture guide, and the upstream payload deterministically reproduces the contract mismatch.

Next step
The current mismatch is valid, confined to one guide, and has clear authoritative sources and a deterministic validation boundary.

Review details

Best possible solution:

Update only docs/gateway-node-integration.md to distinguish the upstream { url, urls?, bootstrapToken } payload from the Windows { url, bootstrapToken } result, state that Gateway token state enforces the 10-minute TTL, and remove the obsolete expiry-parser claim.

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

Yes, at source level. Comparing the current integration guide with SetupCodeDecoder, the architecture guide, and the upstream payload deterministically reproduces the contract mismatch.

Is this the best way to solve the issue?

Yes. A narrow documentation correction is the maintainable solution; reintroducing client-side expiry parsing would conflict with the authoritative Gateway payload and current Windows architecture.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning high; reviewed against 053501c6dfae.

Label changes

Label changes:

• add P3: This is a focused documentation defect that can misdirect future integration work but does not break the active runtime path.
• add issue-rating: 🦞 diamond lobster: Current issue advisory state selects this label.
• add clawsweeper:source-repro: Current issue advisory state selects this label.
• add clawsweeper:queueable-fix: Current issue advisory state selects this label.
• add clawsweeper:fix-shape-clear: Current issue advisory state selects this label.

Label justifications:

• P3: This is a focused documentation defect that can misdirect future integration work but does not break the active runtime path.

Evidence reviewed

Acceptance criteria:

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

What I checked:

• Current guide mismatch: The integration guide repeatedly says setup codes contain expiresAtMs or expiry metadata and retains a completed client-side expiry-parser checklist item. (docs/gateway-node-integration.md:210, 053501c6dfae)
• Active Windows decoder contract: The current decoder reads and returns only url and bootstrapToken; it has no expiry field or client-side expiry check. (src/OpenClaw.Connection/SetupCodeDecoder.cs:47, 053501c6dfae)
• Repository architecture contract: The current architecture guide explicitly describes setup-code decoding as { url, bootstrapToken }, independently confirming the active Windows shape. (docs/CONNECTION_ARCHITECTURE.md:201, 053501c6dfae)
• Upstream payload and TTL authority: At upstream commit d395a8e6ec2789763b746b1e96ed5870c7795bd7, PairingSetupPayload contains url, optional urls, and bootstrapToken, while DEVICE_BOOTSTRAP_TOKEN_TTL_MS separately enforces a 10-minute lifetime. (d395a8e6ec27)
• Feature-history provenance: Commit ed218e9 added the obsolete expiry-parser checklist claim, explaining why it remains after the parser was removed during later onboarding work. (docs/gateway-node-integration.md:358, ed218e960712)
• Latest release remains affected: The v0.6.12 snapshot contains the same inaccurate payload and expiry-parser statements, so the issue is not already resolved in the latest release. (docs/gateway-node-integration.md:210, 4166e0fd63f8)

Likely related people:

• shanselman: Authored the QR setup-pairing and expired-setup-code commits and has the strongest history across the integration guide, decoder, and setup-code tests. (role: feature introducer; confidence: high; commits: 00670860ed76, ed218e960712; files: docs/gateway-node-integration.md, src/OpenClaw.Connection/SetupCodeDecoder.cs, tests/OpenClaw.Connection.Tests/SetupCodeDecoderTests.cs)
• steipete: Authored the merged onboarding redesign that established the current setup flow and removed the obsolete client-side expiry behavior referenced by this issue. (role: recent setup redesign contributor; confidence: high; commits: adcb4c378f90; files: src/OpenClaw.Connection/SetupCodeDecoder.cs, docs/CONNECTION_ARCHITECTURE.md, docs/ONBOARDING_WIZARD.md)

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.