Guide terminal-required setup and channel configuration instead of leaving dead ends

[RomneyDa]

Problem

The Windows Hub setup experience can still lead users to terminal-only steps for chat-channel configuration and other Gateway configuration. The product should complete the step in-app when possible, or provide an explicit guided handoff rather than leaving a user or agent to infer commands.

Desired outcome

A first-time user can understand every remaining terminal requirement, perform it safely, and return to a verified ready state.

Definition of done

• Inventory first-run and channel-setup paths that require terminal input.
• Add a guided in-app path, or a terminal handoff containing the exact command, why it is needed, expected result, and return-to-app verification.
• Distinguish Gateway connected from ready for mobile/channel use in the completion state.
• Add functional/UI coverage for the handoff and return path.

Related

• First-run experience — default onboarding into the local gateway #843 tracks the broader goal that first-time users reach a working node without manual steps; this issue narrows the terminal/channel handoff seam.
• The PCMag report observed that Telegram setup still required opening a terminal and pasting a command: https://www.pcmag.com/opinions/microsoft-thinks-openclaw-is-the-future-of-windows-my-testing-says-otherwise

[clawsweeper]

Codex review: keeping this open for maintainer follow-up; there is still a little grit to resolve. Reviewed August 13, 2026, 4:22 PM ET / 20:22 UTC.

Summary
Keep open. This member-authored issue has an active linked implementation PR that addresses the requested handoff, so it should remain paired with that work until the PR is reviewed and merged or closed.

Reproducibility: unclear. The report gives a coherent first-run path and the linked PR describes the affected states, but the local inspection environment failed before a current-main reproduction or source trace could be established.

Ways to help us reproduce this

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

Next step
An open PR already owns the concrete implementation, and this MEMBER-authored issue should remain open until that work is resolved.

Review details

Best possible solution:

Review the linked PR against the established first-run onboarding goal, require native Windows proof of the handoff and return verification, then merge it if the flow is acceptable.

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

Unclear. The report gives a coherent first-run path and the linked PR describes the affected states, but the local inspection environment failed before a current-main reproduction or source trace could be established.

Is this the best way to solve the issue?

Yes, conditionally. A guided terminal handoff with an exact command, expected result, and return-to-app verification is a narrow way to improve the stated flow; the active PR still needs native Windows proof.

AGENTS.md: found and applied where relevant.

Remaining risk / open question:

• The linked PR is a draft and reports no native-Windows validation or current-head visible proof; merge review must establish the setup-to-Channels handoff on Windows.
• Local read-only inspection was blocked before source, history, and current-main behavior could be checked.

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

Label changes

Label changes:

• add issue-rating: 🦪 silver shellfish: Current issue advisory state selects this label.
• add clawsweeper:needs-info: Current issue advisory state selects this label.

Label justifications:

• P2: The reported first-run configuration dead end is a bounded user-experience improvement, with an active implementation path rather than evidence of an emergency outage.
• impact:ux-friction: Users can reach terminal-only channel setup without an explicit in-app explanation or verified return path.

Evidence reviewed

What I checked:

• Active implementation candidate: The issue timeline cross-references an open draft PR, feat(setup): guide channel readiness handoff #1159, whose stated scope covers the connected-versus-channel-ready distinction, a copyable terminal handoff, and return-to-Channels verification. (6a3cb68de4d8)
• Member-authored item: The supplied GitHub context identifies the issue author as a repository MEMBER. Repository policy requires maintainer-authored or member-associated items to remain open for explicit maintainer handling.
• Repository inspection blocked: Read-only local inspection could not start: the sandbox failed before executing commands with bwrap: loopback: Failed RTM_NEWADDR: Operation not permitted. Current-main source, history, VISION.md, maturity data, and the linked PR diff were therefore not independently verified.

Likely related people:

• RomneyDa: Submitted the current UX boundary and has MEMBER association in the supplied issue context. (role: issue author and repository member; confidence: medium)
• samanthamsong: Authored the open related first-run onboarding epic at First-run experience — default onboarding into the local gateway #843. (role: related onboarding epic owner; confidence: medium)

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.