fix(onboard): keep the wizard alive through provider auth failures and polish standalone install UX by steipete · Pull Request #100632 · openclaw/openclaw

steipete · 2026-07-06T05:47:57Z

What Problem This Solves

Fixes three ways a fresh standalone install (install.sh → openclaw onboard) could dead-end or mislead a new user, found by running the full flow in a clean Debian/Node 24 container:

Fixes an issue where selecting a CLI-reuse auth option (e.g. the preselected "Anthropic Claude CLI") on a host without that CLI login crashed the entire wizard with Error: Claude CLI is not authenticated on this host. and threw away every prior answer.
Resolves a problem where a crash or cancel during channel pairing (e.g. Esc in a QR wait) lost the already-entered provider auth and gateway settings, because config was only written after the channels step.
Fixes an issue where onboarding with model auth skipped still auto-launched the TUI and auto-sent "Wake up, my friend!", which always failed with a confusing No API key found for provider "openai" error.

Also polishes two smaller rough edges: the search-provider picker labeled SearXNG "Self-hosted meta-search with no API key required · API key required" (its credential is a base URL), and install.sh ended with a "PATH missing npm global bin dir" warning telling users to hand-edit their shell rc even though the installer had already persisted the export line.

Why This Change Was Made

Interactive provider setup failures now note the error and return to the provider picker (explicit --auth-choice automation still fails fast); the wizard persists config before the channel/search/skills steps; and the finalize hatch seed is gated on a new resolveDefaultModelAuthStatus helper (shared with the existing model check) with a "Model auth missing" note pointing at openclaw configure --section model. The dead interactive hooks step (setupInternalHooks) left behind by the onboarding streamline (#98218) is deleted along with its i18n keys. Net −103 LOC.

User Impact

New users can no longer lose all onboarding progress from one wrong menu pick, keep their auth/gateway answers if channel pairing goes sideways, and get an accurate next step instead of a failing first chat when they skipped auth. Installer output now tells the truth about PATH setup.

Evidence

All verified live in a clean node:24-bookworm container with a packed tarball of this branch, fresh user each run:

Before: choosing "Anthropic Claude CLI" without the CLI exited the wizard (reproduced on shipped 2026.6.11 and on a main build). After: shows "Provider setup failed — Claude CLI is not authenticated on this host. … Pick another provider or auth method, or choose Skip for now." and re-prompts the provider picker.
Before: skipped auth → TUI auto-sent seed message → run error: No API key found for provider "openai". After: "Model auth missing" note during finalize, TUI opens idle with no doomed message.
Before: install.sh ended with "PATH missing npm global bin dir … Fix (zsh: ~/.zshrc, bash: ~/.bashrc)" despite having written the rc line. After: "PATH updated in /home/user/.bashrc … For this shell, run: source /home/user/.bashrc".
Tests: pnpm test src/wizard (11 files / 124 tests) and pnpm test src/commands/onboard (28 files / 240 tests) green; new regression tests in src/wizard/setup.model-auth.test.ts and src/wizard/setup.finalize.test.ts; pnpm tsgo:core clean; bash -n scripts/install.sh clean.
Autoreview (Codex gpt-5.5): clean, no actionable findings.

🤖 Generated with Claude Code

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: d8a3d9bdae

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

chatgpt-codex-connector · 2026-07-06T05:52:04Z

+    // Without model credentials the seeded first message is guaranteed to fail
+    // with a provider auth error, so hatch quietly and explain instead.
+    const { resolveDefaultModelAuthStatus } = await import("../commands/auth-choice.js");
+    const modelAuthStatus = resolveDefaultModelAuthStatus(nextConfig);


Check auth in the default agent store

When a fresh user completes model setup through the wizard with any profile-backed provider method, the profile is written to the default agent directory (the same path runProviderPluginAuthMethod resolves before upserting profiles), not to the global store. This new finalize gate calls resolveDefaultModelAuthStatus without the already-imported resolveDefaultAgentDir(nextConfig), so it reads the wrong store, reports hasAuth: false, suppresses the bootstrap hatch message, and shows the new “Model auth missing” note even though onboarding just saved credentials. Pass the default agent dir (and agent id if needed) into the helper before deciding whether to seed.

Useful? React with 👍 / 👎.

clawsweeper · 2026-07-06T06:00:16Z

Codex review: needs changes before merge. Reviewed July 6, 2026, 2:06 AM ET / 06:06 UTC.

Summary
This PR updates onboarding provider-auth retry behavior, pre-channel config persistence, first-run hatch gating, search credential labels, installer PATH messaging, docs, and related wizard tests.

PR surface: Source -20, Tests -103, Docs +6, Other +14. Total -103 across 18 files.

Reproducibility: yes. by source inspection for the review finding: provider auth writes profiles under the configured default agentDir, while the new finalize gate reads the implicit default store. I did not run the wizard locally because this was a read-only review.

Review metrics: 2 noteworthy metrics.

Onboarding persistence timing: 1 config write moved earlier. Setup/config timing is compatibility-sensitive because it changes what survives channel or plugin setup failures.
Finalize auth gate: 1 new auth-status gate added. The new gate must use the same auth-profile scope as provider setup or existing custom-agent configurations can be misread.

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:

[P2] Fix the finalize auth-status call to pass the configured default agent id/agentDir from nextConfig.
[P2] Add a regression test where the default agent is not the implicit main-agent store.

Risk before merge

[P1] Merging as-is can make a configured default agent with its own agentDir look unauthenticated during finalize, suppressing the intended hatch seed and showing a false Model auth missing note after credentials were saved.

Maintainer options:

Fix auth-store scope before merge (recommended)
Pass the configured default agent id and agentDir into the finalize auth-status helper and add a regression test for a custom default agent config.
Accept custom-agent false warning
Maintainers could accept the false missing-auth note for custom default-agent installs, but that weakens the first-run UX this PR is trying to repair.

Copy recommended automerge instruction

@clawsweeper automerge

Special instructions:
Fix the finalize model-auth gate so it resolves the same default agent id and agentDir from nextConfig that provider auth uses, and add regression coverage for a custom default agent id/agentDir.

Next step before merge

[P2] A narrow mechanical repair can make the new finalize auth gate use the same configured agent store as provider auth setup.

Security
Cleared: The diff touches onboarding auth checks and install messaging, but I found no new dependency, workflow, permission, shell execution, or secret-exposure concern beyond the functional auth-store scope bug.

Review findings

[P2] Pass the configured agent store into the auth gate — src/wizard/setup.finalize.ts:602

Review details

Best possible solution:

Keep the onboarding fixes, but make the finalize model-auth check resolve and pass the same default agent id and agentDir from nextConfig that provider auth uses before merge.

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

Yes by source inspection for the review finding: provider auth writes profiles under the configured default agentDir, while the new finalize gate reads the implicit default store. I did not run the wizard locally because this was a read-only review.

Is this the best way to solve the issue?

No, not yet: the PR is the right shape for the reported onboarding bugs, but the finalize gate must share the provider-auth agent scope before it is the best fix.

Full review comments:

[P2] Pass the configured agent store into the auth gate — src/wizard/setup.finalize.ts:602
The new gate reads resolveDefaultModelAuthStatus(nextConfig) with no agent scope. Provider auth saves profiles under resolveAgentDir(params.config, agentId), while an undefined auth store falls back to resolveDefaultAgentDir({}); a user with a configured default agent id or custom agentDir can finish auth and still get the new false “Model auth missing” path. Resolve the default agent id/dir from nextConfig and pass them into the helper, with coverage for that custom-agent case.
Confidence: 0.9

Overall correctness: patch is incorrect
Overall confidence: 0.86

AGENTS.md: found and applied where relevant.

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

Label changes

Label changes:

add P0: The PR fixes first-time standalone setup/auth paths that can block a non-technical user or leave them with a failing first useful run.
add merge-risk: 🚨 auth-provider: The new finalize auth check can mis-detect saved provider credentials when the configured default agent store is not the implicit main-agent store.
add proof: sufficient: Contributor real behavior proof is sufficient. The PR body includes before/after live output from a clean Node 24 container for the main standalone onboarding flows; it does not cover the custom-agent edge raised in review.
add rating: 🦐 gold shrimp: Overall readiness is 🦐 gold shrimp; proof is 🦞 diamond lobster and patch quality is 🦐 gold shrimp.
add status: ⏳ waiting on author: ClawSweeper has contributor-facing work open and is waiting for author action. Sufficient (live_output): The PR body includes before/after live output from a clean Node 24 container for the main standalone onboarding flows; it does not cover the custom-agent edge raised in review.

Label justifications:

P0: The PR fixes first-time standalone setup/auth paths that can block a non-technical user or leave them with a failing first useful run.
merge-risk: 🚨 auth-provider: The new finalize auth check can mis-detect saved provider credentials when the configured default agent store is not the implicit main-agent store.
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 before/after live output from a clean Node 24 container for the main standalone onboarding flows; it does not cover the custom-agent edge raised in review.
proof: sufficient: Contributor real behavior proof is sufficient. The PR body includes before/after live output from a clean Node 24 container for the main standalone onboarding flows; it does not cover the custom-agent edge raised in review.

Evidence reviewed

PR surface:

Source -20, Tests -103, Docs +6, Other +14. Total -103 across 18 files.

View PR surface stats

Area	Files	Added	Removed	Net
Source	10	116	136	-20
Tests	5	172	275	-103
Docs	2	8	2	+6
Config	0	0	0	0
Generated	0	0	0	0
Other	1	14	0	+14
Total	18	310	413	-103

Acceptance criteria:

[P1] pnpm test src/wizard/setup.finalize.test.ts src/commands/auth-choice.model-check.test.ts.
[P1] pnpm test src/wizard.
[P1] pnpm tsgo:core.
[P1] bash -n scripts/install.sh.

What I checked:

Repository policy read: Root AGENTS.md plus scoped docs/AGENTS.md and scripts/AGENTS.md were read; their setup/auth compatibility and docs-source rules affected this review. (AGENTS.md:1, f9bf5f589763)
Finalize gate omits auth scope: The PR calls resolveDefaultModelAuthStatus(nextConfig) without passing the default agent id or agentDir before deciding whether auth exists for the hatch seed. (src/wizard/setup.finalize.ts:602, d8a3d9bdae06)
Provider auth writes into resolved agent dir: Provider setup resolves agentId from config, resolves agentDir from that agent id, and upserts profiles under that agentDir. (src/plugins/provider-auth-choice.ts:272, f9bf5f589763)
Undefined auth store scope uses default empty config: Auth-profile path resolution with no agentDir falls back to resolveDefaultAgentDir({}), while configured defaults can resolve to a different agent id or custom agentDir. (src/agents/auth-profiles/path-resolve.ts:18, f9bf5f589763)
Prior review comment matches source finding: The existing Codex review comment also flags the missing default agent store scope on src/wizard/setup.finalize.ts line 602. (src/wizard/setup.finalize.ts:602, d8a3d9bdae06)
Related onboarding streamline provenance: Merged PR Streamline OpenClaw onboarding #98218 introduced the recent streamlined onboarding surfaces that this PR builds on, including setup.finalize.ts, setup.ts, and onboard hook/search/auth files. (src/wizard/setup.finalize.ts, 786abe78df53)

Likely related people:

fuller-stack-dev: Auth/setup and finalize onboarding surfaces were substantially introduced or reshaped in merged onboarding streamline PR Streamline OpenClaw onboarding #98218. (role: feature owner; confidence: high; commits: 1f97bd519955, 0a6e90d8f651, 786abe78df53; files: src/wizard/setup.finalize.ts, src/wizard/setup.ts, src/commands/onboard-hooks.ts)
steipete: The current PR author also has recent same-day current-main history in this checkout, and the PR carries the maintainer label for onboarding cleanup routing. (role: recent area contributor; confidence: medium; commits: f53103de72da, d8a3d9bdae06; files: src/wizard/setup.finalize.ts, src/wizard/setup.model-auth.ts, scripts/install.sh)

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.

…d polish standalone install UX Rough edges found by running the standalone install flow (install.sh -> openclaw onboard) in a clean Debian/Node 24 container: - Provider auth setup failures (e.g. the preselected "Anthropic Claude CLI" option on a host without a Claude CLI login) killed the whole wizard and lost all progress. The interactive wizard now notes the error and returns to the provider picker; explicit --auth-choice automation still fails fast. - Onboarding config was only written after the channels step, so a crash or cancel during channel pairing lost auth + gateway decisions. The wizard now persists config before the channel/search/skills steps. - With model auth skipped, finalize auto-launched the TUI and auto-sent "Wake up, my friend!", which always failed with a confusing provider auth error. The seed message is now gated on usable model credentials and a "Model auth missing" note explains the next step (new resolveDefaultModelAuthStatus helper shared with the model check). - Search provider picker suffix said "API key required" even for non-key credentials (SearXNG base URL); it now uses the provider's credentialLabel. - install.sh warned "PATH missing npm global bin dir" with manual fix instructions even though it had already persisted the export line to the shell rc; it now says the PATH was updated and how to reload the current shell. - Delete the dead interactive hooks onboarding step (setupInternalHooks) left behind by the onboarding streamline; quickstart enables default hooks silently. Verified live in a clean container per fix (wizard re-prompt, no-auth hatch note, installer PATH message) plus wizard/onboard test suites.

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 16597863de

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

chatgpt-codex-connector · 2026-07-07T03:06:37Z

+    // Without model credentials the seeded first message is guaranteed to fail
+    // with a provider auth error, so hatch quietly and explain instead.
+    const { resolveDefaultModelAuthStatus } = await import("../commands/auth-choice.js");
+    const modelAuthStatus = resolveDefaultModelAuthStatus(nextConfig);


Honor CLI-backed auth before suppressing hatch

Fresh evidence beyond the existing agent-dir comment: Anthropic CLI setup stores the usable profile under provider claude-cli while keeping the selected default model as anthropic/... with a claude-cli runtime policy (extensions/anthropic/cli-migration.ts:181 and :221). This new gate calls resolveDefaultModelAuthStatus(nextConfig), whose candidates only cover the model provider/OpenAI aliases, so a valid Claude CLI onboarding is reported as hasAuth: false; the wizard then suppresses the first TUI hatch message and shows “Model auth missing” even though auth is present. Include the resolved harness/synthetic auth provider, in addition to the scoped agent dir, before using this status to block the hatch.

Useful? React with 👍 / 👎.

…d polish standalone install UX (openclaw#100632) Fixes rough edges in the standalone install flow (install.sh -> openclaw onboard), found and verified by running the flow in a clean container and on a clean macOS Tahoe VM: - Provider auth setup failures (e.g. the preselected "Anthropic Claude CLI" option on a host without a Claude CLI login) no longer kill the whole wizard. The interactive wizard notes the error and returns to the provider picker; explicit --auth-choice automation still fails fast. - Onboarding config now persists before the channel/search/skills steps, so a crash or cancel during channel pairing no longer loses auth + gateway decisions. - With model auth skipped, finalize no longer auto-sends the "Wake up, my friend!" message (which always failed with a provider auth error). The hatch seed is gated on usable model credentials and a "Model auth missing" note explains the next step. - Search provider picker no longer labels non-key credentials (e.g. SearXNG base URL) as "API key required". - install.sh no longer warns "PATH missing npm global bin dir" with manual fix steps after it already persisted the export line; it reports the PATH was updated and how to reload the current shell. - Removed the dead interactive hooks onboarding step (setupInternalHooks); quickstart enables default hooks silently. Verified live per fix in a clean Debian/Node 24 container and on a clean macOS 26.5 Parallels VM (wizard re-prompt, SearXNG label), plus wizard/onboard test suites and tsgo:core. 🤖 Generated with [Claude Code](https://claude.com/claude-code)

openclaw-barnacle Bot added docs Improvements or additions to documentation scripts Repository scripts commands Command implementations size: L maintainer Maintainer-authored PR labels Jul 6, 2026

chatgpt-codex-connector Bot reviewed Jul 6, 2026

View reviewed changes

steipete force-pushed the work/onboarding-standalone branch from d8a3d9b to 1659786 Compare July 7, 2026 03:01

chatgpt-codex-connector Bot reviewed Jul 7, 2026

View reviewed changes

steipete merged commit 21d919d into main Jul 7, 2026
109 of 110 checks passed

steipete deleted the work/onboarding-standalone branch July 7, 2026 03:11

clawsweeper Bot mentioned this pull request Jul 7, 2026

fix(installer): complete first-run onboarding #101901

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

fix(onboard): keep the wizard alive through provider auth failures and polish standalone install UX#100632

fix(onboard): keep the wizard alive through provider auth failures and polish standalone install UX#100632
steipete merged 1 commit into
mainfrom
work/onboarding-standalone

steipete commented Jul 6, 2026

Uh oh!

chatgpt-codex-connector Bot left a comment

Uh oh!

chatgpt-codex-connector Bot Jul 6, 2026

Uh oh!

clawsweeper Bot commented Jul 6, 2026 •

edited

Loading

Uh oh!

chatgpt-codex-connector Bot left a comment

Uh oh!

chatgpt-codex-connector Bot Jul 7, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Uh oh!

Uh oh!

Conversation

steipete commented Jul 6, 2026

What Problem This Solves

Why This Change Was Made

User Impact

Evidence

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

chatgpt-codex-connector Bot Jul 6, 2026

Choose a reason for hiding this comment

Uh oh!

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

Uh oh!

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

chatgpt-codex-connector Bot Jul 7, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

clawsweeper Bot commented Jul 6, 2026 •

edited

Loading