From 6f50253a4d08b567da0c244f33a2d526d0bbea0c Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Sun, 26 Apr 2026 09:46:34 +0100 Subject: [PATCH] fix: clarify install switching --- docs/help/faq-first-run.md | 28 +++++++++++++++------------- docs/install/index.md | 4 ++++ docs/install/updating.md | 31 ++++++++++++++++++++++++++++++- scripts/install.ps1 | 19 ++++++++++++++++--- scripts/install.sh | 2 +- src/cli/update-cli.ts | 2 +- 6 files changed, 67 insertions(+), 19 deletions(-) diff --git a/docs/help/faq-first-run.md b/docs/help/faq-first-run.md index 87c0c83ba99..ff9a9e947fe 100644 --- a/docs/help/faq-first-run.md +++ b/docs/help/faq-first-run.md @@ -766,30 +766,32 @@ and troubleshooting see the main [FAQ](/help/faq). - Yes. Install the other flavor, then run Doctor so the gateway service points at the new entrypoint. - This **does not delete your data** - it only changes the OpenClaw code install. Your state - (`~/.openclaw`) and workspace (`~/.openclaw/workspace`) stay untouched. + Yes. Use `openclaw update --channel ...` when OpenClaw is already installed. + This **does not delete your data** - it only changes the OpenClaw code install. + Your state (`~/.openclaw`) and workspace (`~/.openclaw/workspace`) stay untouched. From npm to git: ```bash - git clone https://github.com/openclaw/openclaw.git - cd openclaw - pnpm install - pnpm build - openclaw doctor - openclaw gateway restart + openclaw update --channel dev ``` From git to npm: ```bash - npm install -g openclaw@latest - openclaw doctor - openclaw gateway restart + openclaw update --channel stable ``` - Doctor detects a gateway service entrypoint mismatch and offers to rewrite the service config to match the current install (use `--repair` in automation). + Add `--dry-run` to preview the planned mode switch first. The updater runs + Doctor follow-ups, refreshes plugin sources for the target channel, and + restarts the gateway unless you pass `--no-restart`. + + The installer can force either mode too: + + ```bash + curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git + curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method npm + ``` Backup tips: see [Backup strategy](#where-things-live-on-disk). diff --git a/docs/install/index.md b/docs/install/index.md index b943c7db533..0c641cd1163 100644 --- a/docs/install/index.md +++ b/docs/install/index.md @@ -61,6 +61,10 @@ curl -fsSL https://openclaw.ai/install-cli.sh | bash It supports npm installs by default, plus git-checkout installs under the same prefix flow. Full reference: [Installer internals](/install/installer#install-clish). +Already installed? Switch between package and git installs with +`openclaw update --channel dev` and `openclaw update --channel stable`. See +[Updating](/install/updating#switch-between-npm-and-git-installs). + ### npm, pnpm, or bun If you already manage Node yourself: diff --git a/docs/install/updating.md b/docs/install/updating.md index 375d08ade8f..b46539f3c44 100644 --- a/docs/install/updating.md +++ b/docs/install/updating.md @@ -20,6 +20,7 @@ To switch channels or target a specific version: ```bash openclaw update --channel beta +openclaw update --channel dev openclaw update --tag main openclaw update --dry-run # preview without applying ``` @@ -30,13 +31,41 @@ if you want the raw npm beta dist-tag for a one-off package update. See [Development channels](/install/development-channels) for channel semantics. +## Switch between npm and git installs + +Use channels when you want to change the install type. The updater keeps your +state, config, credentials, and workspace in `~/.openclaw`; it only changes +which OpenClaw code install the CLI and gateway use. + +```bash +# npm package install -> editable git checkout +openclaw update --channel dev + +# git checkout -> npm package install +openclaw update --channel stable +``` + +Run with `--dry-run` first to preview the exact install-mode switch: + +```bash +openclaw update --channel dev --dry-run +openclaw update --channel stable --dry-run +``` + +The `dev` channel ensures a git checkout, builds it, and installs the global CLI +from that checkout. The `stable` and `beta` channels use package installs. If the +gateway is already installed, `openclaw update` refreshes the service metadata +and restarts it unless you pass `--no-restart`. + ## Alternative: re-run the installer ```bash curl -fsSL https://openclaw.ai/install.sh | bash ``` -Add `--no-onboard` to skip onboarding. For source installs, pass `--install-method git --no-onboard`. +Add `--no-onboard` to skip onboarding. To force a specific install type through +the installer, pass `--install-method git --no-onboard` or +`--install-method npm --no-onboard`. ## Alternative: manual npm, pnpm, or bun diff --git a/scripts/install.ps1 b/scripts/install.ps1 index 4b08fbdb6fe..df86aaac385 100644 --- a/scripts/install.ps1 +++ b/scripts/install.ps1 @@ -3,6 +3,7 @@ # Or: & ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -NoOnboard param( + [ValidateSet("npm", "git")] [string]$InstallMethod = "npm", [string]$Tag = "latest", [string]$GitDir = "$env:USERPROFILE\openclaw", @@ -336,11 +337,13 @@ function Install-OpenClawGit { if (!(Test-Path $wrapperDir)) { New-Item -ItemType Directory -Path $wrapperDir -Force | Out-Null } - + + $entryPath = Join-Path $RepoDir "dist\entry.js" @" @echo off -node "%~dp0..\openclaw\dist\entry.js" %* +node "$entryPath" %* "@ | Out-File -FilePath "$wrapperDir\openclaw.cmd" -Encoding ASCII -Force + Add-ToPath -Path $wrapperDir Write-Host "OpenClaw installed" -Level success return $true @@ -432,7 +435,12 @@ function Main { if ($DryRun) { Write-Host "[DRY RUN] Would install OpenClaw from git to $GitDir" -Level info } else { - Install-OpenClawGit -RepoDir $GitDir -Update:(-not $NoGitUpdate) + try { + npm uninstall -g openclaw 2>$null | Out-Null + } catch { } + if (!(Install-OpenClawGit -RepoDir $GitDir -Update:(-not $NoGitUpdate))) { + return (Fail-Install) + } } } else { # npm method @@ -443,6 +451,11 @@ function Main { if ($DryRun) { Write-Host "[DRY RUN] Would install OpenClaw via npm ($((Resolve-PackageInstallSpec -Target $Tag)))" -Level info } else { + $gitWrapper = "$env:USERPROFILE\.local\bin\openclaw.cmd" + if (Test-Path $gitWrapper) { + Remove-Item -Force $gitWrapper + Write-Host "Removed git wrapper (switching to npm)" -Level info + } if (!(Install-OpenClawNpm -Target $Tag)) { return (Fail-Install) } diff --git a/scripts/install.sh b/scripts/install.sh index 9e56b40517e..6e1084d958a 100755 --- a/scripts/install.sh +++ b/scripts/install.sh @@ -2667,7 +2667,7 @@ main() { ui_section "Source install details" ui_kv "Checkout" "$final_git_dir" ui_kv "Wrapper" "$HOME/.local/bin/openclaw" - ui_kv "Update command" "openclaw update --restart" + ui_kv "Update command" "openclaw update" ui_kv "Switch to npm" "curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --install-method npm" elif [[ "$is_upgrade" == "true" ]]; then ui_info "Upgrade complete" diff --git a/src/cli/update-cli.ts b/src/cli/update-cli.ts index f0c669de3b8..2413de7fdb6 100644 --- a/src/cli/update-cli.ts +++ b/src/cli/update-cli.ts @@ -75,7 +75,7 @@ ${theme.heading("Switch channels:")} ${theme.heading("Non-interactive:")} - Use --yes to accept downgrade prompts - - Combine with --channel/--tag/--restart/--json/--timeout as needed + - Combine with --channel/--tag/--no-restart/--json/--timeout as needed - Use --dry-run to preview actions without writing config/installing/restarting ${theme.heading("Examples:")}