fix(installer): complete first-run onboarding by fuller-stack-dev · Pull Request #101901 · openclaw/openclaw

fuller-stack-dev · 2026-07-07T22:50:05Z

Summary

send fresh installs into onboarding before doctor or gateway finalization probes
use the just-installed OpenClaw binary for follow-up commands and explain hash -r when the shell still caches a removed path
let onboarding persist gateway configuration and authentication before installing or starting the managed service
preserve doctor, plugin update, gateway restart, and dashboard behavior for configured upgrades
add installer regression coverage for fresh installs, upgrades, no-TTY behavior, stale PATH resolution, and gateway finalization

What Problem This Solves

A fresh git install could report success without creating ~/.openclaw/openclaw.json, gateway authentication, or a managed gateway service. Its suggested follow-up then failed first through a stale /usr/bin/openclaw shell lookup, and subsequently through missing gateway mode/auth/service state. The TUI also failed with Missing gateway auth token because setup had never completed.

This change makes first-run onboarding the installer finalization path. Doctor and gateway health behavior remain on the configured-upgrade path instead of being used as a substitute for initial setup.

Verification

node scripts/run-vitest.mjs test/scripts/install-sh.test.ts (61 passed)
bash -n scripts/install.sh
git diff --check
final structured autoreview: no accepted/actionable findings
earlier exact-patch proof: formatting, ShellCheck, focused tests, onboarding/Crestodian Docker scenarios, gateway-auth tests, and the changed-files gate passed
rebased patch ID matches the reviewed and tested pre-rebase patch

Real behavior proof

Behavior addressed: Fresh --install-method git --version main installs could finish without first-run config, gateway auth, or a managed gateway service, then recommend commands that could not work in that state.

Real environment tested: Linux installer regression coverage plus onboarding/Crestodian Docker scenarios and gateway-auth scenarios on the same patch.

Exact steps or command run after this patch: node scripts/run-vitest.mjs test/scripts/install-sh.test.ts; bash -n scripts/install.sh; the existing Docker onboarding/Crestodian and gateway-auth scenario lanes were also run before the final rebase.

Evidence after fix: All 61 installer regression tests pass, including fresh-install onboarding, configured-upgrade doctor behavior, stale PATH handling, no-TTY guidance, gateway finalization ordering, and successful-upgrade dashboard behavior.

Observed result after fix: Fresh installs enter onboarding before doctor/gateway probes; setup owns gateway config and token creation before service installation; follow-up commands resolve the newly installed binary; configured upgrades continue through doctor and plugin update behavior.

What was not tested: The isolated black-box fresh install did not complete because dependency installation was still running after 23 minutes and was terminated. No successful full fresh-VPS install artifact is claimed.

clawsweeper · 2026-07-07T22:51:56Z

Codex review: needs maintainer review before merge. Reviewed July 7, 2026, 7:47 PM ET / 23:47 UTC.

Summary
The PR reorders installer finalization so unconfigured fresh installs enter onboarding before doctor/gateway checks, uses the just-installed binary in follow-up commands, updates installer docs, and expands installer shell regression coverage.

PR surface: Tests +328, Docs 0, Other -1. Total +327 across 3 files.

Reproducibility: yes. Source inspection of current main shows installer finalization can run gateway refresh/doctor and only bootstrap-based onboarding before the config-driven onboarding path, while the PR's shell tests model the failing unconfigured/no-TTY and stale PATH cases.

Review metrics: 2 noteworthy metrics.

Installer finalization modes: 3 paths re-ordered. Unconfigured install, configured fresh install, and configured upgrade now choose different onboarding, doctor, gateway refresh, and verify sequences.
Config detection overrides: 2 env surfaces handled. The PR changes how OPENCLAW_CONFIG_PATH and OPENCLAW_STATE_DIR decide whether setup is already complete before merge-sensitive installer actions run.

Stored data model
Persistent data-model change detected: migration/backfill/repair: docs/install/installer.md. Confirm migration or upgrade compatibility proof before merge.

Merge readiness
Overall: 🐚 platinum hermit
Proof: 🐚 platinum hermit
Patch quality: 🐚 platinum hermit
Result: ready for maintainer review.

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

Rank-up moves:

[P2] A maintainer can decide whether to require one clean fresh-install transcript before merge.

Risk before merge

[P1] The PR changes installer finalization, config-presence detection, doctor/plugin-update timing, and gateway-auth setup ordering; focused tests and CI cover much of this, but a successful full fresh-VPS install artifact is explicitly not claimed.
[P1] Because the branch is mergeable but behind the moving base, maintainers should ensure the exact merge result keeps the same installer finalization behavior before landing.

Maintainer options:

Accept the focused installer proof (recommended)
Maintainers can land after exact-head CI if they accept the focused regression and installer-sync proof for the urgent first-run blocker.
Ask for one fresh-install transcript
Require a clean fresh install run that reaches persisted config, gateway auth, and managed service state before merge.
Pause for installer-owner review
Hold the PR if maintainers want a deeper upgrade/auth walkthrough before changing installer finalization order.

Next step before merge

No automated repair is needed; a maintainer should decide whether the focused proof is enough for this compatibility-sensitive installer/auth change before landing.

Maintainer decision needed

Question: Is the current focused installer, onboarding, and gateway-auth proof enough to land this P0 installer fix without a completed full fresh-VPS install transcript?
Rationale: The patch is code-review clean, but installer/auth first-run behavior is compatibility-sensitive and the PR body explicitly says the isolated black-box fresh install did not complete.
Likely owner: steipete — steipete is the current assignee and recently changed the standalone install/onboarding flow this PR builds on.
Options:
- Accept focused proof and land (recommended): Treat the installer regression tests, scenario proof, and successful installer-sync CI as sufficient once required checks finish on the exact head.
- Require fresh install proof: Ask for a terminal transcript or artifact from one successful clean fresh install before merge.
- Hold for broader installer owner review: Pause landing until the installer owner rechecks the configured-upgrade and gateway-auth paths manually.

Security
Cleared: The diff changes installer shell flow, docs, and tests without new dependencies, workflows, permissions, downloads, secret exposure, or unquoted command execution concerns.

Review details

Best possible solution:

Land the installer finalization change after a maintainer accepts the focused proof and current CI, or request one successful fresh install transcript if the full black-box proof gap matters for this P0 setup path.

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

Yes. Source inspection of current main shows installer finalization can run gateway refresh/doctor and only bootstrap-based onboarding before the config-driven onboarding path, while the PR's shell tests model the failing unconfigured/no-TTY and stale PATH cases.

Is this the best way to solve the issue?

Yes, with a proof-sufficiency caveat. Moving the finalization decision to active config presence and the selected installed binary is the narrow owner-boundary fix; no existing supported path already solved the fresh-install onboarding gap on current main.

AGENTS.md: found and applied where relevant.

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

Label changes

Label changes:

add merge-risk: 🚨 compatibility: Changing installer finalization and configured-upgrade doctor/plugin/gateway ordering can affect existing install and upgrade workflows.
add merge-risk: 🚨 auth-provider: The central behavior is gateway authentication setup and missing-token recovery during first-run onboarding.
add rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🐚 platinum hermit and patch quality is 🐚 platinum hermit.
add status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Not applicable: The external-contributor proof gate does not apply to this maintainer-labeled PR, but the body includes terminal/test proof and clearly notes the missing full fresh-VPS artifact.

Label justifications:

P0: The PR targets a first-run installer/onboarding failure that can leave a new user without config, gateway auth, or a usable managed gateway path.
merge-risk: 🚨 compatibility: Changing installer finalization and configured-upgrade doctor/plugin/gateway ordering can affect existing install and upgrade workflows.
merge-risk: 🚨 auth-provider: The central behavior is gateway authentication setup and missing-token recovery during first-run onboarding.
rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🐚 platinum hermit and patch quality is 🐚 platinum hermit.
status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Not applicable: The external-contributor proof gate does not apply to this maintainer-labeled PR, but the body includes terminal/test proof and clearly notes the missing full fresh-VPS artifact.

Evidence reviewed

PR surface:

Tests +328, Docs 0, Other -1. Total +327 across 3 files.

View PR surface stats

Area	Files	Added	Removed	Net
Source	0	0	0	0
Tests	1	347	19	+328
Docs	1	4	4	0
Config	0	0	0	0
Generated	0	0	0	0
Other	1	117	118	-1
Total	3	468	141	+327

What I checked:

Current main probes before setup: Current main resolves an openclaw binary, refreshes gateway service, runs doctor for git installs/upgrades, and only then tries bootstrap-based onboarding, which matches the reported fresh-install failure surface. (scripts/install.sh:3236, 6db0506474ce)
PR gates finalization on active config: The PR adds config-presence detection and only refreshes gateway service when config exists; unconfigured installs go to onboarding/no-TTY guidance before gateway health verification. (scripts/install.sh:3241, af2646dd4652)
PR honors canonical config path behavior: The new shell config detection mirrors the TypeScript config path contract where OPENCLAW_STATE_DIR defaults to stateDir/openclaw.json and OPENCLAW_CONFIG_PATH is tilde-expanded against OpenClaw's effective home. (src/config/paths.ts:152, 6db0506474ce)
Regression coverage added: The PR tests unconfigured git install/no-onboard paths, verifies doctor/gateway probes are skipped before setup, preserves --verify without TTY, and covers stale PATH guidance. (test/scripts/install-sh.test.ts:857, af2646dd4652)
Docs aligned with finalization order: The installer docs now describe installed-binary resolution, onboarding before doctor/gateway probes for unconfigured installs, configured-install doctor/gateway behavior, and verify gating. Public docs: docs/install/installer.md. (docs/install/installer.md:87, af2646dd4652)
Prior ClawSweeper findings were addressed: The durable review history asked for installer docs and preserving --verify before the no-TTY return; the current diff includes the docs update and removes the early return so verify can still run. (af2646dd4652)

Likely related people:

steipete: Recent merged standalone install/onboarding polish changed the install.sh to onboard flow, and this PR is currently assigned to steipete. (role: recent area contributor and assignee; confidence: high; commits: 21d919deb801; files: scripts/install.sh, docs/install/installer.md)
SebTardif: Recent merged installer work changed upgrade doctor cancellation, dashboard gating, and adjacent installer regression tests on the same finalization path. (role: recent installer reliability contributor; confidence: medium; commits: 0d6a1dcb53a4; files: scripts/install.sh, test/scripts/install-sh.test.ts)
vincentkoc: Multiple recent direct installer commits cover git wrapper runtime, repo pnpm use, and stale shell helper cleanup around the same script. (role: adjacent installer owner; confidence: medium; commits: be7198f6a222, adc4d9fe02af, bd74a62118aa; files: scripts/install.sh, test/scripts/install-sh.test.ts)
fuller-stack-dev: The current branch author also has recent merged installer/test history for Node runtime validation and installer CI coverage. (role: recent installer contributor; confidence: medium; commits: cccc856b82f7, af2646dd4652; files: scripts/install.sh, test/scripts/install-sh.test.ts, docs/install/installer.md)

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 (3 earlier review cycles)

reviewed 2026-07-07T22:58:22.041Z sha 1ab792b :: needs changes before merge. :: [P3] Update installer docs for the new finalization order
reviewed 2026-07-07T23:06:34.507Z sha 1ab792b :: needs changes before merge. :: [P3] Update installer docs for the new finalization order
reviewed 2026-07-07T23:22:05.513Z sha 9563865 :: needs changes before merge. :: [P2] Preserve --verify before the no-TTY return

fuller-stack-dev · 2026-07-07T23:28:54Z

@clawsweeper re-review

clawsweeper · 2026-07-07T23:28:57Z

🦞🧹
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.

fuller-stack-dev · 2026-07-08T00:24:00Z

Merged via squash.

Prepared head SHA: af2646dd4652867164556b3af04de294576b79c2
Landed commit: 2fbd4cdcbaec07e542f4d8310319c609b9123570

* fix(installer): complete first-run onboarding * docs(installer): document finalization paths * fix(installer): honor verify without tty * fix(installer): align config finalization

fix(installer): complete first-run onboarding

1ab792b

fuller-stack-dev mentioned this pull request Jul 7, 2026

feat(crestodian): guide providerless model setup #101887

Merged

openclaw-barnacle Bot added scripts Repository scripts size: M maintainer Maintainer-authored PR labels Jul 7, 2026

github-actions Bot mentioned this pull request Jul 7, 2026

🦞 OpenClaw 生态日报 2026-07-08 huajiao1998/big_model_radar#19

Open

fuller-stack-dev assigned steipete Jul 7, 2026

docs(installer): document finalization paths

9563865

openclaw-barnacle Bot added the docs Improvements or additions to documentation label Jul 7, 2026

fix(installer): honor verify without tty

bd524e2

openclaw-barnacle Bot added size: L and removed size: M labels Jul 7, 2026

fix(installer): align config finalization

af2646d

clawsweeper Bot added the rating: 🐚 platinum hermit Good normal PR readiness with ordinary maintainer review expected. label Jul 7, 2026

fuller-stack-dev merged commit 2fbd4cd into openclaw:main Jul 8, 2026
120 of 125 checks passed

fuller-stack-dev deleted the codex/fix-first-run-onboarding branch July 8, 2026 00:24

This was referenced Jul 8, 2026

fix(installer): bypass onboard exec when existing config is present #81154

Closed

[Bug]: Umbrel openclaw version 2026.4.12 setup wizard - impossible to scroll past models #66785

Closed

github-actions Bot mentioned this pull request Jul 8, 2026

📡 Upstream Digest — 2026-07-08 01:54 UTC curtismercier/openclaw-mods#1235

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

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

fix(installer): complete first-run onboarding#101901
fuller-stack-dev merged 4 commits into
openclaw:mainfrom
fuller-stack-dev:codex/fix-first-run-onboarding

fuller-stack-dev commented Jul 7, 2026

Uh oh!

clawsweeper Bot commented Jul 7, 2026 •

edited

Loading

Uh oh!

fuller-stack-dev commented Jul 7, 2026

Uh oh!

clawsweeper Bot commented Jul 7, 2026 •

edited

Loading

Uh oh!

Uh oh!

fuller-stack-dev commented Jul 8, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Uh oh!

Conversation

fuller-stack-dev commented Jul 7, 2026

Summary

What Problem This Solves

Verification

Real behavior proof

Uh oh!

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

Uh oh!

Uh oh!

fuller-stack-dev commented Jul 7, 2026

Uh oh!

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

Uh oh!

Uh oh!

Uh oh!

fuller-stack-dev commented Jul 8, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

clawsweeper Bot commented Jul 7, 2026 •

edited

Loading

clawsweeper Bot commented Jul 7, 2026 •

edited

Loading