[codex] docs(wizard): clarify provider key update path by Pluviobyte · Pull Request #90118 · openclaw/openclaw

Pluviobyte · 2026-06-04T02:12:23Z

Summary

add an auth-choice-specific hint to the existing-config Review and update option so provider key updates are discoverable
document post-onboarding provider switching in the onboard CLI and wizard reference docs
add regression coverage for the config handling prompt hint

Validation

node scripts/run-vitest.mjs src/wizard/setup.test.ts --reporter=dot
node scripts/run-vitest.mjs src/commands/configure.gateway-auth.prompt-auth-config.test.ts --reporter=dot
npx oxfmt --check src/wizard/setup.ts src/wizard/setup.test.ts src/wizard/i18n/locales/en.ts src/wizard/i18n/locales/zh-CN.ts src/wizard/i18n/locales/zh-TW.ts docs/cli/onboard.md docs/reference/wizard.md
node scripts/run-oxlint.mjs src/wizard/setup.ts src/wizard/setup.test.ts src/wizard/i18n/locales/en.ts src/wizard/i18n/locales/zh-CN.ts src/wizard/i18n/locales/zh-TW.ts
node scripts/run-tsgo.mjs -p test/tsconfig/tsconfig.test.src.json --pretty false --incremental
git diff --check

Duplicate Check

Searched open and closed PRs for #88373, auth-choice/provider key wording, post-onboarding provider switch wording, and the target wizard/docs files.
No overlapping PR found; the only issue-number search hit was unrelated maintainer work.

Fixes #88373

Real behavior proof

Behavior or issue addressed: Existing OpenClaw setups rerun with --auth-choice <provider> did not make it clear that Review and update is the path to enter or update the selected provider key.
Real environment tested: Local OpenClaw source checkout on macOS, branch codex/onboarding-provider-switch-copy at f2d912d, with isolated OPENCLAW_HOME, OPENCLAW_STATE_DIR, and OPENCLAW_CONFIG_PATH pointing at a temporary existing config.
Exact steps or command run after this patch: Ran a source-level terminal capture against the patched onboarding/i18n/config path with node --import tsx, using an existing temporary OpenClaw config and command context equivalent to openclaw onboard --auth-choice groq-api-key --flow quickstart.
Evidence after fix (screenshot, recording, terminal capture, console output, redacted runtime log, linked artifact, or copied live output): Copied live terminal output:

terminal capture: OpenClaw onboarding existing-config menu after patch
config: existing (/tmp/openclaw-proof-SBuhuS/openclaw.json)
command context: openclaw onboard --auth-choice groq-api-key --flow quickstart
prompt: Config handling
- Keep current values
- Review and update — Choose this to enter or update the selected provider key.
- Reset before setup

Observed result after fix: The existing-config menu now shows Review and update with the explicit hint Choose this to enter or update the selected provider key. when an auth choice is supplied.
What was not tested: I did not run a full live provider credential update with a real Groq API key or capture a Windows terminal screenshot.
Proof limitations or environment constraints: The full interactive launcher in this source checkout requires build output, so the proof uses the patched source modules directly with isolated temporary config paths; focused wizard tests cover the same branch.
Before evidence (optional but encouraged): Before the patch, the Review and update option had no provider-key-specific hint in this existing-config branch.

clawsweeper · 2026-06-04T02:14:11Z

Codex review: needs changes before merge. Reviewed June 30, 2026, 8:23 AM ET / 12:23 UTC.

Summary
The PR adds an auth-choice-specific wizard hint, onboarding docs, and regression tests for the existing-config Review and update path.

PR surface: Source +10, Tests +100, Docs +8, Other 0. Total +118 across 8 files.

Reproducibility: yes. at source level: current main shows the generic existing-config menu and non-skip auth choices continue into applyAuthChoice after that gate. The linked issue's user-visible confusion is not fixed on current main.

Review metrics: 1 noteworthy metric.

Raw-fetch guard drift: 3 stale qa-lab web callsite entries. The PR touches a CI guard allowlist, so incorrect line numbers can make the guard fail or bless the wrong callsites after merge.

Root-cause cluster
Relationship: fixed_by_candidate
Canonical: #88373
Summary: The PR is the open candidate fix for the linked provider-switch discoverability issue; the stale provider/session cache issue is adjacent but distinct.

Members:

canonical: Windows post-onboarding provider switch path is not discoverable #88373 - The PR body uses closing syntax for the open issue and targets the same --auth-choice existing-config discoverability gap.
adjacent_distinct: Windows provider switch leaves stale model/provider config and session cache #88372 - That issue concerns stale provider/model config and session cache after provider switching, not just the Review and update discoverability gap.

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

Merge readiness
Overall: 🦐 gold shrimp
Proof: 🦞 diamond lobster
Patch quality: 🦐 gold shrimp
Result: needs maintainer review before merge.

Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch.

Rank-up moves:

Reword the Keep-current-values docs claim or change runtime to enforce it.
Refresh the raw-fetch guard allowlist against current main.

Risk before merge

[P1] The branch is currently CONFLICTING/DIRTY on GitHub, so maintainers need a refresh before merge.
[P1] The added docs can mislead existing users by saying Keep current values preserves provider keys even though current runtime continues non-skip auth-choice credential handling after that menu.
[P1] The PR changes a guard script allowlist and currently carries stale qa-lab web callsite line numbers.

Maintainer options:

Repair wording and guard hunk (recommended)
Reword the docs so Keep current values is not described as preserving provider keys, then update the qa-lab web raw-fetch allowlist to current main's fetch call lines.
Make Keep suppress auth-choice updates
If maintainers want the docs promise, change and test the wizard so choosing Keep current values suppresses provider credential updates for auth-choice reruns.
Wait for author refresh
Maintainers can keep the PR waiting on the contributor because the branch is dirty and the remaining issues are narrow but still merge-blocking.

Copy recommended automerge instruction

@clawsweeper automerge

Special instructions:
Reword the docs so `Keep current values` is not described as preserving provider keys unless runtime behavior is changed to enforce it, then refresh scripts/check-no-raw-channel-fetch.mjs so the qa-lab web app allowlist matches current main's actual fetch call lines.

Next step before merge

[P2] The remaining blockers are narrow mechanical repairs to docs wording and a stale guard hunk, so an automated repair could attempt them if maintainers promote the PR.

Security
Cleared: No concrete security or supply-chain concern was found in the docs, wizard-copy, regression-test, or guard line-number changes.

Review findings

[P1] Stop promising Keep preserves provider keys — docs/cli/onboard.md:58-59
[P2] Refresh the raw-fetch allowlist against main — scripts/check-no-raw-channel-fetch.mjs:50-52

Review details

Best possible solution:

Keep the Review and update hint, reword the Keep-current-values docs claim or change runtime to enforce it, and refresh the raw-fetch guard before merge.

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

Yes, at source level: current main shows the generic existing-config menu and non-skip auth choices continue into applyAuthChoice after that gate. The linked issue's user-visible confusion is not fixed on current main.

Is this the best way to solve the issue?

No as-is. The Review and update hint is the right narrow fix, but the docs overstate Keep-current-values behavior and the raw-fetch guard hunk is stale against current main.

Full review comments:

[P1] Stop promising Keep preserves provider keys — docs/cli/onboard.md:58-59
The added docs say Keep current values leaves or preserves provider keys, but the existing-config selection only special-cases reset; with a supplied non-skip --auth-choice, the wizard still later calls applyAuthChoice, which can prompt for and upsert provider credentials. Reword both docs pages to match runtime behavior, or implement and test true keep-as-auth-skip behavior.
Confidence: 0.92
[P2] Refresh the raw-fetch allowlist against main — scripts/check-no-raw-channel-fetch.mjs:50-52
Current main's qa-lab web fetch calls are at lines 23, 31, and 39, while this branch carries 22, 30, and 38 in the guard allowlist and GitHub reports the PR as dirty. Refresh this hunk so scripts/check-no-raw-channel-fetch.mjs matches the actual callsites before merge.
Confidence: 0.88

Overall correctness: patch is incorrect
Overall confidence: 0.91

AGENTS.md: found and applied where relevant.

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

Label changes

Label justifications:

P3: This is low-risk onboarding discoverability/docs polish with limited blast radius.
merge-risk: 🚨 compatibility: The docs change can mislead existing users about whether Keep current values avoids provider credential handling during an auth-choice rerun.
merge-risk: 🚨 automation: The PR changes a raw-fetch guard allowlist and the diff is stale against current main's qa-lab web callsite lines.
rating: 🦐 gold shrimp: Overall readiness is 🦐 gold shrimp; proof is 🦞 diamond lobster and patch quality is 🦐 gold shrimp.
status: ⏳ waiting on author: ClawSweeper has contributor-facing work open and is waiting for author action. Sufficient (live_output): The PR body includes copied terminal output from an isolated source-level rerun showing the new existing-config Review and update hint after the patch.
proof: sufficient: Contributor real behavior proof is sufficient. The PR body includes copied terminal output from an isolated source-level rerun showing the new existing-config Review and update hint after the patch.

Evidence reviewed

PR surface:

Source +10, Tests +100, Docs +8, Other 0. Total +118 across 8 files.

View PR surface stats

Area	Files	Added	Removed	Net
Source	4	11	1	+10
Tests	1	100	0	+100
Docs	2	8	0	+8
Config	0	0	0	0
Generated	0	0	0	0
Other	1	3	3	0
Total	8	122	4	+118

Acceptance criteria:

[P1] node scripts/check-no-raw-channel-fetch.mjs.
[P1] node scripts/run-vitest.mjs src/wizard/setup.test.ts --reporter=dot.
[P1] npx oxfmt --check src/wizard/setup.ts src/wizard/setup.test.ts src/wizard/i18n/locales/en.ts src/wizard/i18n/locales/zh-CN.ts src/wizard/i18n/locales/zh-TW.ts docs/cli/onboard.md docs/reference/wizard.md scripts/check-no-raw-channel-fetch.mjs.
[P1] node scripts/run-oxlint.mjs src/wizard/setup.ts src/wizard/setup.test.ts src/wizard/i18n/locales/en.ts src/wizard/i18n/locales/zh-CN.ts src/wizard/i18n/locales/zh-TW.ts.
[P1] git diff --check.

What I checked:

Current wizard menu lacks the requested hint: Current main shows generic Keep, Review and update, and Reset options in the existing-config menu; there is no auth-choice-specific hint on Review and update. (src/wizard/setup.ts:364, 6cb82eaab865)
Auth choice still runs after existing-config gate: After the existing-config gate, current main calls applyAuthChoice for non-skip auth choices, so choosing Keep current values at that menu does not suppress provider credential handling. (src/wizard/setup.ts:731, 6cb82eaab865)
Provider auth can update stored profiles: Provider auth methods can upsert auth profiles and apply auth profile config, so docs should not promise provider keys are preserved unless the wizard enforces that behavior. (src/plugins/provider-auth-choice.ts:305, 6cb82eaab865)
Raw-fetch guard drift: Current main allowlists qa-lab web fetch calls at lines 23, 31, and 39, while the PR diff changes those entries to 22, 30, and 38. (scripts/check-no-raw-channel-fetch.mjs:51, 6cb82eaab865)
Actual qa-lab fetch callsites: The qa-lab web app fetch calls are on current-main lines 23, 31, and 39. (extensions/qa-lab/web/src/app.ts:23, 6cb82eaab865)
Live PR state: GitHub reports the PR head c2e803e as CONFLICTING/DIRTY against base b311fd6. (c2e803e67f02)

Likely related people:

ml12580: Authored recent setup wizard work preserving existing default models during setup auth-choice reruns, directly adjacent to the affected flow. (role: recent auth-choice path contributor; confidence: medium; commits: b83694687977; files: src/wizard/setup.ts)
steipete: Recent history includes wizard helper docs, onboarding CLI docs, provider docs, and recurring setup/docs work across the affected surfaces. (role: recent onboarding and docs contributor; confidence: medium; commits: b6ce59d367b0, 735f59af7366, 0369672691cf; files: docs/cli/onboard.md, docs/reference/wizard.md, src/wizard/setup.ts)
Solvely-Colin: Authored the qa-lab evidence artifact gallery work that shifted the web app fetch call lines referenced by the raw-fetch guard. (role: recent qa-lab contributor; confidence: medium; commits: c677424edba0; files: extensions/qa-lab/web/src/app.ts)
RomneyDa: Authored and merged the recent raw-fetch allowlist repair in the same guard script area touched by this PR. (role: recent guard drift contributor; confidence: medium; commits: fb750e6eed9f; files: scripts/check-no-raw-channel-fetch.mjs)

What the crustacean ranks mean

🦀 challenger crab: rare, exceptional readiness with strong proof, clean implementation, and convincing validation.
🦞 diamond lobster: very strong readiness with only minor maintainer review expected.
🐚 platinum hermit: good normal PR, likely mergeable with ordinary maintainer review.
🦐 gold shrimp: useful signal, but proof or patch confidence is still limited.
🦪 silver shellfish: thin signal; proof, validation, or implementation needs work.
🧂 unranked krab: not merge-ready because proof is missing/unusable or there are serious correctness or safety concerns.
🌊 off-meta tidepool: rating does not apply to this item.

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.

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.

Review history (1 earlier review cycle)

reviewed 2026-06-21T12:57:43.054Z sha c2e803e :: needs changes before merge. :: [P1] Stop promising Keep preserves provider keys | [P2] Refresh the raw-fetch allowlist against main

Pluviobyte · 2026-06-04T06:32:09Z

Addressed the skip edge case in 6504bb6 by hiding the provider-key update hint when rerunning with --auth-choice skip, and added a regression test for that path.

Validation run locally:

node scripts/run-vitest.mjs src/wizard/setup.test.ts --reporter=dot
npx oxfmt --check src/wizard/setup.ts src/wizard/setup.test.ts src/wizard/i18n/locales/en.ts src/wizard/i18n/locales/zh-CN.ts src/wizard/i18n/locales/zh-TW.ts docs/cli/onboard.md docs/reference/wizard.md
node scripts/run-oxlint.mjs src/wizard/setup.ts src/wizard/setup.test.ts src/wizard/i18n/locales/en.ts src/wizard/i18n/locales/zh-CN.ts src/wizard/i18n/locales/zh-TW.ts

@clawsweeper re-review

clawsweeper · 2026-06-04T06:32:12Z

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

Re-review progress:

State: Failed
Detail: The targeted re-review did not finish cleanly. Check the workflow run for details.
Run: https://github.com/openclaw/clawsweeper/actions/runs/26935123098
Updated: 2026-06-04T06:40:07.845Z

…ovider-switch-copy

openclaw-barnacle · 2026-07-20T04:40:16Z

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

docs(wizard): clarify provider key update path

f2d912d

openclaw-barnacle Bot added docs Improvements or additions to documentation size: S triage: needs-real-behavior-proof Candidate: external PR needs after-fix proof from a real setup. labels Jun 4, 2026

openclaw-barnacle Bot added proof: supplied External PR includes structured after-fix real behavior proof. and removed triage: needs-real-behavior-proof Candidate: external PR needs after-fix proof from a real setup. labels Jun 4, 2026

fix(wizard): skip provider key hint for auth skip

6504bb6

openclaw-barnacle Bot removed the proof: sufficient ClawSweeper judged the real behavior proof convincing. label Jun 4, 2026

Pluviobyte marked this pull request as ready for review June 4, 2026 06:39

Merge remote-tracking branch 'upstream/main' into codex/onboarding-pr…

1c8b13e

…ovider-switch-copy

openclaw-barnacle Bot removed the proof: sufficient ClawSweeper judged the real behavior proof convincing. label Jun 5, 2026

Pluviobyte added 2 commits June 5, 2026 10:12

Merge remote-tracking branch 'upstream/main' into codex/onboarding-pr…

6b91d0e

…ovider-switch-copy

test(qa-lab): refresh raw fetch allowlist

c2e803e

openclaw-barnacle Bot added the scripts Repository scripts label Jun 5, 2026

clawsweeper Bot removed the rating: 🦪 silver shellfish Thin PR readiness signal; proof, validation, or implementation needs work. label Jun 5, 2026

clawsweeper Bot added the rating: 🦐 gold shrimp Decent PR readiness signal, but merge confidence is limited. label Jun 5, 2026

clawsweeper Bot mentioned this pull request Jun 15, 2026

Windows post-onboarding provider switch path is not discoverable #88373

Open

clawsweeper Bot added merge-risk: 🚨 compatibility 🚨 May break existing users, config, migrations, defaults, or upgrade paths. merge-risk: 🚨 automation 🚨 May affect CI, automerge, proof capture, label sync, or maintainer automation. labels Jun 19, 2026

openclaw-barnacle Bot added the stale Marked as stale due to inactivity label Jul 20, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

[codex] docs(wizard): clarify provider key update path#90118

[codex] docs(wizard): clarify provider key update path#90118
Pluviobyte wants to merge 5 commits into
openclaw:mainfrom
Pluviobyte:codex/onboarding-provider-switch-copy

Pluviobyte commented Jun 4, 2026 •

edited

Loading

Uh oh!

clawsweeper Bot commented Jun 4, 2026 •

edited

Loading

Uh oh!

Pluviobyte commented Jun 4, 2026

Uh oh!

clawsweeper Bot commented Jun 4, 2026 •

edited

Loading

Uh oh!

openclaw-barnacle Bot commented Jul 20, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Uh oh!

Conversation

Pluviobyte commented Jun 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Validation

Duplicate Check

Real behavior proof

Uh oh!

clawsweeper Bot commented Jun 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Pluviobyte commented Jun 4, 2026

Uh oh!

clawsweeper Bot commented Jun 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

openclaw-barnacle Bot commented Jul 20, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Pluviobyte commented Jun 4, 2026 •

edited

Loading

clawsweeper Bot commented Jun 4, 2026 •

edited

Loading

clawsweeper Bot commented Jun 4, 2026 •

edited

Loading