fix(setup): allow optional wizard text input

[omandryk]

Closes #1331

What Problem This Solves

Fixes an issue where users configuring an OpenAI-compatible provider in Companion could not continue past Model alias (optional) without entering an alias.

It also resolves a related wizard-client problem where Gateway validation errors returned for a text answer could be cleared immediately, append a rejected answer to the transcript, and count the same validation retry as another step visit.

Why This Change Was Made

The Gateway wizard protocol does not expose whether an individual text step is required, while the Gateway already owns each text prompt's authoritative validator. Companion now submits the current text value, including an empty string, and handles a successful non-terminal response containing an error plus the same step as an inline validation rejection.

This keeps optional fields usable without guessing requiredness from localized labels. Required fields remain protected by the Gateway validator.

User Impact

Users can leave optional text fields such as Model alias (optional) empty and continue onboarding. If a required or invalid value is rejected by the Gateway, Companion keeps the current input visible, shows the validation message, and does not add the rejected answer to the transcript.

Evidence

• Added focused selection-policy coverage proving text answers are submitted for Gateway validation.
• Added payload-classification coverage for current-step validation errors.
• Added a source contract protecting the UI ordering that refreshes Continue state before making the Gateway validation error visible.
• git diff --check passed at commit c6b73ad1.
• Two rubber-duck reviews were performed. The reviews identified validation-error handling and visibility-ordering gaps; both were corrected before publication.
• The Gateway contract was independently verified against OpenClaw core commit 20d0daa063c0cc5eaee98043b673d413be5945f4: WizardSession.answer runs the prompt validator and keeps the current step pending when validation returns an error; wizard.next returns a successful non-terminal payload containing that error plus session.next(), which is the same current step.
• Current-head Windows UI proof is pending because the authoring host is macOS without .NET 10, PowerShell, Windows, or Parallels. A separate Windows host is being prepared for the required proof.

Change Type

• Bug fix
• Feature
• Refactor
• Docs or instructions
• Tests or validation
• Security hardening
• Chore or infrastructure

Scope

• Tray or WinUI UX
• Windows node capability
• Local MCP or winnode
• Gateway, connection, or pairing
• Setup or onboarding
• Permissions, privacy, or security
• Tests, CI, or docs

Required proof pools

• windows-winui-interactive: the onboarding wizard's Continue state and inline Gateway validation-error behavior changed.

Validation

Local required validation was attempted but could not start on the macOS authoring host:

• ./build.ps1 - blocked, PowerShell and the Windows build environment are unavailable.
• dotnet test ./tests/OpenClaw.Shared.Tests/OpenClaw.Shared.Tests.csproj --no-restore - blocked, .NET 10 SDK is unavailable.
• dotnet test ./tests/OpenClaw.Tray.Tests/OpenClaw.Tray.Tests.csproj --no-restore - blocked, .NET 10 SDK is unavailable.
• Focused WizardSelectionTests - blocked, .NET 10 SDK is unavailable.
• git diff --check - passed.

No automated test is reported as passing without a non-zero test count. GitHub CI and Windows proof remain required before this draft is ready for review.

Real Behavior Proof

• Environment tested: native Windows 11 x64 on Windows Node (CALATONPC), isolated Dev launch (run-app-local.ps1 -Dev -Isolated -AllowNonMain).
• Exact code commit tested: c6b73ad1237e92ee7ff730ccbea70ee66ecd4991 (verified in the Windows checkout immediately after the run).
• Exact path exercised: manual setup → local gateway → custom provider → OpenAI-compatible endpoint → model ID → endpoint ID → Model alias (optional).
• Before submission, Windows UI Automation reported:

{"Title":"Enter value","Message":"Model alias (optional)","ButtonEnabled":true,"ValueLength":0}

• Continue was invoked while the alias value length was zero. The wizard advanced and UI Automation then reported:

{"Action":"Invoke PrimaryButton","Result":"INVOKED_BLANK_ALIAS"}
{"Title":"Enter value","Message":"Gateway port","ButtonEnabled":true}

Focused, sanitized screenshots

Blank optional alias; Continue enabled at exact PR code commit:

After submission: the checked, value-less transcript entry records the blank answer, and the wizard is now on Gateway port:

The image URLs and proof notes were verified publicly resolvable. Captures exclude provider endpoint, endpoint ID, model ID, API-key state, gateway records, and unrelated desktop content.

Pre-fix evidence: the reporter's original screenshot directly shows the same blank Model alias (optional) field with Continue disabled, but it remains private and is not republished here. Current-main source at 305bb4ef5334ded9f8541aca19c66ba2c4b08754 independently reproduces that client gate: empty text disables Continue and is rejected before wizard.next.

Not verified / blocked: GitHub fork CI remains action_required pending upstream approval.

Security Impact

• New permissions or capabilities? (Yes/No): No
• Secrets or tokens handling changed? (Yes/No): No
• New or changed network calls? (Yes/No): No
• Command or tool execution surface changed? (Yes/No): No
• Data access scope changed? (Yes/No): No
• If any answer is Yes, explain the risk and mitigation: N/A

Compatibility and Migration

• Backward compatible? (Yes/No): Yes
• Config or environment changes? (Yes/No): No
• Migration needed? (Yes/No): No
• If yes, list the exact upgrade steps: N/A

Review Conversations

• I replied to or resolved every bot review conversation addressed by this PR.
• I left unresolved only conversations that still need maintainer judgment.

[clawsweeper]

🦞👀
ClawSweeper picked this up.

Pull request received. I will update this pull request when review starts.

ClawSweeper review complete

ClawSweeper finished reviewing this revision. The review result is being finalized.

View the workflow run.

[clawsweeper]

Codex review: needs real behavior proof before merge. Reviewed September 5, 2026, 4:35 PM ET / 20:35 UTC.

ClawSweeper review

What this changes

The onboarding wizard allows blank text submissions and preserves the current input and inline Gateway error when validation rejects an answer.

Merge readiness

⛔ Blocked before merge - 3 items remain

This remains a useful, focused fix for behavior still present on main and in the latest release. No concrete introduced correctness defect was found, but the previous review's rejection-and-correction proof gap remains.

Priority: P2
Reviewed head: c6b73ad1237e92ee7ff730ccbea70ee66ecd4991

Review scores

Measure	Result	What it means
Overall readiness	🦐 gold shrimp (3/6)	The patch is focused and has meaningful native proof, but rejection recovery and required validation remain unverified.
Proof confidence	🦐 gold shrimp (3/6)	Needs stronger real behavior proof before merge: The inspected Windows screenshots and UI Automation output demonstrate blank-alias submission and advancement through WizardPage on the reviewed head. They do not exercise the added same-step rejection branch, visible error, preserved input, or successful correction; this is partial real proof, not mock-only evidence. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.
Patch quality	🐚 platinum hermit (4/6)	No actionable review findings were identified.

Verification

Check	Result	Evidence
Real behavior	Needs proof	Needs stronger real behavior proof before merge: The inspected Windows screenshots and UI Automation output demonstrate blank-alias submission and advancement through WizardPage on the reviewed head. They do not exercise the added same-step rejection branch, visible error, preserved input, or successful correction; this is partial real proof, not mock-only evidence. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.
Evidence reviewed	9 items	Current main still blocks blank text: The main revision's text overload disables Continue for null, empty, or whitespace input. WizardPage uses that policy both when enabling Continue and before submitting an answer. Latest release retains the gate: Inspection of the supplied latest release revision, v2026.7.1-4, shows the same unconditional non-whitespace requirement for text steps. Rejection handling follows the existing UI boundary: The introduced branch restores the controls and displays the error before input reset or visit counting. The submission path suppresses rejected transcript entries. The classifier and source-order tests cover these decisions, but do not exercise the native UI with a real rejected Gateway answer.
Findings	None	None.
Security	None	None.

How this fits together

Companion renders onboarding questions supplied by the Gateway and submits users' answers through wizard RPCs. Gateway responses determine whether the UI advances or retains the current question for correction.

flowchart LR
  A[Gateway question] --> B[Companion wizard]
  B --> C[User text answer]
  C --> D[Gateway validation]
  D --> E[Accepted answer]
  D --> F[Rejected answer]
  E --> G[Transcript and next question]
  F --> B

Loading

Before merge

• Add real behavior proof - Needs stronger real behavior proof before merge: The inspected Windows screenshots and UI Automation output demonstrate blank-alias submission and advancement through WizardPage on the reviewed head. They do not exercise the added same-step rejection branch, visible error, preserved input, or successful correction; this is partial real proof, not mock-only evidence. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.
• Resolve merge risk (P1) - Independent verification of the cited upstream Gateway rejection contract was blocked by source retrieval failures.
• Complete next step (P2) - Add the rejection-and-correction Windows proof and required build/test results described above. Prefer screenshots or video for visible behavior; copied diagnostics and redacted logs also count. Remove private endpoints, keys, and other sensitive details. Update the PR body to trigger re-review, or ask a maintainer to comment @clawsweeper re-review if it does not run.

Agent review details

Security

None.

Review metrics

None.

Root-cause cluster

Relationship: fixed_by_candidate
Canonical: #1331
Summary: This PR is the explicit candidate fix for the paired optional-alias report.

Members:

• canonical: [Bug]: Optional model alias blocks OpenAI-compatible onboarding #1331 - The report defines the same blank-alias failure and Gateway-validation expectation.

Proposal only: this assessment does not dispatch repair, suppress jobs, mutate sibling items, close, or merge anything.

Merge-risk options

Maintainer options:

1. Decide the mitigation before merge
   Keep Gateway-owned text validation, with optional blanks accepted and rejected answers recoverable inline without resetting input or advancing the transcript.
2. Pause or close
   Do not merge this PR until maintainers decide whether the risk is worth taking.

Technical review

Best possible solution:

Keep Gateway-owned text validation, with optional blanks accepted and rejected answers recoverable inline without resetting input or advancing the transcript.

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

Yes, source establishes that leaving Model alias empty disables Continue and fails the submission gate on current main; this review did not execute a failing native run.

Is this the best way to solve the issue?

Yes, delegating validation to the existing Gateway flow is narrower and more maintainable than guessing requiredness from labels; the added rejection path still needs real runtime evidence.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning medium; reviewed against 305bb4ef5334.

Labels

Label changes:

• add proof: 📸 screenshot: Contributor real behavior proof includes screenshot evidence. The inspected Windows screenshots and UI Automation output demonstrate blank-alias submission and advancement through WizardPage on the reviewed head. They do not exercise the added same-step rejection branch, visible error, preserved input, or successful correction; this is partial real proof, not mock-only evidence.

Label justifications:

• P2: This fixes a bounded onboarding defect with an available in-product workaround: entering an alias.
• rating: 🦐 gold shrimp: Overall readiness is 🦐 gold shrimp; proof is 🦐 gold shrimp and patch quality is 🐚 platinum hermit.
• status: 📣 needs proof: The PR needs real behavior proof before ClawSweeper can clear the contributor ask. Needs stronger real behavior proof before merge: The inspected Windows screenshots and UI Automation output demonstrate blank-alias submission and advancement through WizardPage on the reviewed head. They do not exercise the added same-step rejection branch, visible error, preserved input, or successful correction; this is partial real proof, not mock-only evidence. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.
• proof: 📸 screenshot: Contributor real behavior proof includes screenshot evidence. The inspected Windows screenshots and UI Automation output demonstrate blank-alias submission and advancement through WizardPage on the reviewed head. They do not exercise the added same-step rejection branch, visible error, preserved input, or successful correction; this is partial real proof, not mock-only evidence.

Evidence

What I checked:

• Current main still blocks blank text: The main revision's text overload disables Continue for null, empty, or whitespace input. WizardPage uses that policy both when enabling Continue and before submitting an answer. (src/OpenClaw.SetupEngine/WizardSelection.cs:42, 305bb4ef5334)
• Latest release retains the gate: Inspection of the supplied latest release revision, v2026.7.1-4, shows the same unconditional non-whitespace requirement for text steps. (src/OpenClaw.SetupEngine/WizardSelection.cs:42, c7c6fb06be03)
• Rejection handling follows the existing UI boundary: The introduced branch restores the controls and displays the error before input reset or visit counting. The submission path suppresses rejected transcript entries. The classifier and source-order tests cover these decisions, but do not exercise the native UI with a real rejected Gateway answer. (src/OpenClaw.SetupEngine.UI/Pages/WizardPage.xaml.cs:301, c6b73ad1237e)
• Inspected native Windows proof: Both prepared images were inspected locally. They show an empty optional alias with Continue enabled, then Gateway port with a completed transcript entry. The captured PR body and author comment tie these images and UI Automation observations to Windows 11 at c6b73ad. They demonstrate successful blank submission, but contain no rejection-and-correction scenario. Source: fix(setup): allow optional wizard text input #1332 (comment). (c6b73ad1237e)
• Gateway dependency signal: The changed selection policy explicitly delegates text validation to the Gateway, and the PR cites WizardSession.answer and wizard.next as the authoritative rejection contract. Repository documentation likewise identifies the Gateway as the owner of the question flow. (src/OpenClaw.SetupEngine/WizardSelection.cs:41, c6b73ad1237e)
• Upstream inspection limitation: The PR cites upstream revision 20d0daa063c0cc5eaee98043b673d413be5945f4. Browser retrieval of both cited source files returned cache misses; direct retrieval failed with curl error 6, unable to resolve raw.githubusercontent.com. Their contents were not independently verified. This limitation does not invalidate the inspected blank-alias proof. (src/wizard/session.ts)

Likely related people:

• Karen: Suggested for follow-up; no historical authorship or introduction is verified. (role: unverified routing candidate; confidence: low)
• Barbara Kudiess: Suggested for follow-up; no historical authorship or introduction is verified. (role: unverified routing candidate; confidence: low)

Rank-up moves

Optional improvements that raise the rating; they are not merge blockers.

• Add current-head Windows/Gateway rejection-and-correction evidence showing the error, preserved input, unchanged transcript and visit counting, covering fresh setup and an existing-install wizard rerun.
• Report the required build, Shared and Tray tests, and focused SetupEngine wizard tests with actual test counts.

Rating scale

Score	Internal tier	Crab rank	Meaning
6/6	S	🦀 challenger crab	Exceptional readiness
5/6	A	🦞 diamond lobster	Very strong readiness
4/6	B	🐚 platinum hermit	Good normal PR; ordinary maintainer review
3/6	C	🦐 gold shrimp	Useful, but confidence is limited
2/6	D	🦪 silver shellfish	Proof or implementation needs work
1/6	F	🧂 unranked krab	Not merge-ready
N/A	NA	🌊 off-meta tidepool	Rating does not apply

Overall follows the weaker of proof and patch quality.
Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

Workflow

• 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.

History

Review history (3 earlier review cycles)

• reviewed 2026-09-05T06:21:42.561Z sha c6b73ad :: needs real behavior proof before merge. :: none
• reviewed 2026-09-05T14:36:51.642Z sha c6b73ad :: needs real behavior proof before merge. :: none
• reviewed 2026-09-05T19:38:48.074Z sha c6b73ad :: needs real behavior proof before merge. :: none

[omandryk]

Native Windows proof added — c6b73ad

Validated on Windows Node (CALATONPC) at exact contributor code commit c6b73ad1237e92ee7ff730ccbea70ee66ecd4991, using the isolated Dev launch.

The exact reported path was exercised on the fixed build:

1. Reached Model alias (optional) with the input empty.
2. UI Automation reported ValueLength: 0 and PrimaryButton.IsEnabled: true.
3. Invoked Continue without entering an alias.
4. The wizard advanced to Gateway port.

Focused, sanitized, publicly resolvable screenshots and UIA observations are now in the PR body's Real Behavior Proof section and in the proof package.

The reporter's original pre-fix screenshot directly shows the same blank optional-alias field with Continue disabled, but it remains private and was not republished. Current-main source at 305bb4ef5334ded9f8541aca19c66ba2c4b08754 independently reproduces the old client gate.

Remaining blocker: fork CI run 33949435559 is action_required and needs upstream approval. The PR remains draft until that gate is resolved and review is satisfactory.

[omandryk]

@clawsweeper re-review

Exact-head native Windows proof is now publicly linked in the PR body: blank Model alias (optional) with Continue enabled, followed by the next wizard step after submitting the blank value.

[clawsweeper]

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event exact_review_queue).
Result: when the review finishes, ClawSweeper will create the durable review comment if needed or update the existing comment in place.

Re-review progress:

• State: Complete
• Detail: The durable review result and its route handoff completed.
• Run: https://github.com/openclaw/clawsweeper/actions/runs/33987807636
• Updated: 2026-09-05T19:40:30.352Z

[github-actions]

This pull request has been automatically marked as stale due to inactivity.
Please update it or it will be closed.