fix: clarify install switching

docs/help/faq-first-run.md

@@ -766,30 +766,32 @@ and troubleshooting see the main [FAQ](/help/faq).
   </Accordion>
 
   <Accordion title="Can I switch between npm and git installs later?">
-    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).
 

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:

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
 

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)
             }

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"

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:")}