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