diff --git a/docs/install/migrating.md b/docs/install/migrating.md index 64c136be425..49e8e7606bb 100644 --- a/docs/install/migrating.md +++ b/docs/install/migrating.md @@ -6,187 +6,105 @@ read_when: title: "Migration Guide" --- -# Migrating OpenClaw to a new machine +# Migrating OpenClaw to a New Machine -This guide migrates an OpenClaw Gateway from one machine to another **without redoing onboarding**. +This guide moves an OpenClaw gateway to a new machine without redoing onboarding. -The migration is simple conceptually: +## What Gets Migrated -- Copy the **state directory** (`$OPENCLAW_STATE_DIR`, default: `~/.openclaw/`) — this includes config, auth, sessions, and channel state. -- Copy your **workspace** (`~/.openclaw/workspace/` by default) — this includes your agent files (memory, prompts, etc.). +When you copy the **state directory** (`~/.openclaw/` by default) and your **workspace**, you preserve: -But there are common footguns around **profiles**, **permissions**, and **partial copies**. +- **Config** -- `openclaw.json` and all gateway settings +- **Auth** -- API keys, OAuth tokens, credential profiles +- **Sessions** -- conversation history and agent state +- **Channel state** -- WhatsApp login, Telegram session, etc. +- **Workspace files** -- `MEMORY.md`, `USER.md`, skills, and prompts -## Before you start (what you are migrating) + +Run `openclaw status` on the old machine to confirm your state directory path. +Custom profiles use `~/.openclaw-/` or a path set via `OPENCLAW_STATE_DIR`. + -### 1) Identify your state directory +## Migration Steps -Most installs use the default: + + + On the **old** machine, stop the gateway so files are not changing mid-copy, then archive: -- **State dir:** `~/.openclaw/` + ```bash + openclaw gateway stop + cd ~ + tar -czf openclaw-state.tgz .openclaw + ``` -But it may be different if you use: + If you use multiple profiles (e.g. `~/.openclaw-work`), archive each separately. -- `--profile ` (often becomes `~/.openclaw-/`) -- `OPENCLAW_STATE_DIR=/some/path` + -If you’re not sure, run on the **old** machine: + + [Install](/install) the CLI (and Node if needed) on the new machine. + It is fine if onboarding creates a fresh `~/.openclaw/` -- you will overwrite it next. + -```bash -openclaw status -``` + + Transfer the archive via `scp`, `rsync -a`, or an external drive, then extract: -Look for mentions of `OPENCLAW_STATE_DIR` / profile in the output. If you run multiple gateways, repeat for each profile. + ```bash + cd ~ + tar -xzf openclaw-state.tgz + ``` -### 2) Identify your workspace + Ensure hidden directories were included and file ownership matches the user that will run the gateway. -Common defaults: + -- `~/.openclaw/workspace/` (recommended workspace) -- a custom folder you created + + On the new machine, run [Doctor](/gateway/doctor) to apply config migrations and repair services: -Your workspace is where files like `MEMORY.md`, `USER.md`, and `memory/*.md` live. + ```bash + openclaw doctor + openclaw gateway restart + openclaw status + ``` -### 3) Understand what you will preserve + + -If you copy **both** the state dir and workspace, you keep: +## Common Pitfalls -- Gateway configuration (`openclaw.json`) -- Auth profiles / API keys / OAuth tokens -- Session history + agent state -- Channel state (e.g. WhatsApp login/session) -- Your workspace files (memory, skills notes, etc.) + + + If the old gateway used `--profile` or `OPENCLAW_STATE_DIR` and the new one does not, + channels will appear logged out and sessions will be empty. + Launch the gateway with the **same** profile or state-dir you migrated, then rerun `openclaw doctor`. + -If you copy **only** the workspace (e.g., via Git), you do **not** preserve: + + The config file alone is not enough. Credentials live under `credentials/`, and agent + state lives under `agents/`. Always migrate the **entire** state directory. + -- sessions -- credentials -- channel logins + + If you copied as root or switched users, the gateway may fail to read credentials. + Ensure the state directory and workspace are owned by the user running the gateway. + -Those live under `$OPENCLAW_STATE_DIR`. + + If your UI points at a **remote** gateway, the remote host owns sessions and workspace. + Migrate the gateway host itself, not your local laptop. See [FAQ](/help/faq#where-does-openclaw-store-its-data). + -## Migration steps (recommended) + + The state directory contains API keys, OAuth tokens, and channel credentials. + Store backups encrypted, avoid insecure transfer channels, and rotate keys if you suspect exposure. + + -### Step 0 - Make a backup (old machine) - -On the **old** machine, stop the gateway first so files aren’t changing mid-copy: - -```bash -openclaw gateway stop -``` - -(Optional but recommended) archive the state dir and workspace: - -```bash -# Adjust paths if you use a profile or custom locations -cd ~ -tar -czf openclaw-state.tgz .openclaw - -tar -czf openclaw-workspace.tgz .openclaw/workspace -``` - -If you have multiple profiles/state dirs (e.g. `~/.openclaw-main`, `~/.openclaw-work`), archive each. - -### Step 1 - Install OpenClaw on the new machine - -On the **new** machine, install the CLI (and Node if needed): - -- See: [Install](/install) - -At this stage, it’s OK if onboarding creates a fresh `~/.openclaw/` — you will overwrite it in the next step. - -### Step 2 - Copy the state dir + workspace to the new machine - -Copy **both**: - -- `$OPENCLAW_STATE_DIR` (default `~/.openclaw/`) -- your workspace (default `~/.openclaw/workspace/`) - -Common approaches: - -- `scp` the tarballs and extract -- `rsync -a` over SSH -- external drive - -After copying, ensure: - -- Hidden directories were included (e.g. `.openclaw/`) -- File ownership is correct for the user running the gateway - -### Step 3 - Run Doctor (migrations + service repair) - -On the **new** machine: - -```bash -openclaw doctor -``` - -Doctor is the “safe boring” command. It repairs services, applies config migrations, and warns about mismatches. - -Then: - -```bash -openclaw gateway restart -openclaw status -``` - -## Common footguns (and how to avoid them) - -### Footgun: profile / state-dir mismatch - -If you ran the old gateway with a profile (or `OPENCLAW_STATE_DIR`), and the new gateway uses a different one, you’ll see symptoms like: - -- config changes not taking effect -- channels missing / logged out -- empty session history - -Fix: run the gateway/service using the **same** profile/state dir you migrated, then rerun: - -```bash -openclaw doctor -``` - -### Footgun: copying only `openclaw.json` - -`openclaw.json` is not enough. Many providers store state under: - -- `$OPENCLAW_STATE_DIR/credentials/` -- `$OPENCLAW_STATE_DIR/agents//...` - -Always migrate the entire `$OPENCLAW_STATE_DIR` folder. - -### Footgun: permissions / ownership - -If you copied as root or changed users, the gateway may fail to read credentials/sessions. - -Fix: ensure the state dir + workspace are owned by the user running the gateway. - -### Footgun: migrating between remote/local modes - -- If your UI (WebUI/TUI) points at a **remote** gateway, the remote host owns the session store + workspace. -- Migrating your laptop won’t move the remote gateway’s state. - -If you’re in remote mode, migrate the **gateway host**. - -### Footgun: secrets in backups - -`$OPENCLAW_STATE_DIR` contains secrets (API keys, OAuth tokens, WhatsApp creds). Treat backups like production secrets: - -- store encrypted -- avoid sharing over insecure channels -- rotate keys if you suspect exposure - -## Verification checklist +## Verification Checklist On the new machine, confirm: -- `openclaw status` shows the gateway running -- Your channels are still connected (e.g. WhatsApp doesn’t require re-pair) -- The dashboard opens and shows existing sessions -- Your workspace files (memory, configs) are present - -## Related - -- [Doctor](/gateway/doctor) -- [Gateway troubleshooting](/gateway/troubleshooting) -- [Where does OpenClaw store its data?](/help/faq#where-does-openclaw-store-its-data) +- [ ] `openclaw status` shows the gateway running +- [ ] Channels are still connected (no re-pairing needed) +- [ ] The dashboard opens and shows existing sessions +- [ ] Workspace files (memory, configs) are present diff --git a/docs/install/updating.md b/docs/install/updating.md index ddae557c9f2..bbe3e949d96 100644 --- a/docs/install/updating.md +++ b/docs/install/updating.md @@ -8,44 +8,35 @@ title: "Updating" # Updating -OpenClaw is moving fast (pre “1.0”). Treat updates like shipping infra: update → run checks → restart (or use `openclaw update`, which restarts) → verify. +Keep OpenClaw up to date. -## Recommended: re-run the website installer (upgrade in place) +## Recommended: `openclaw update` -The **preferred** update path is to re-run the installer from the website. It -detects existing installs, upgrades in place, and runs `openclaw doctor` when -needed. +The fastest way to update. It detects your install type (npm or git), fetches the latest version, runs `openclaw doctor`, and restarts the gateway. + +```bash +openclaw update +``` + +To switch channels or target a specific version: + +```bash +openclaw update --channel beta +openclaw update --tag main +openclaw update --dry-run # preview without applying +``` + +See [Development channels](/install/development-channels) for channel semantics. + +## Alternative: re-run the installer ```bash curl -fsSL https://openclaw.ai/install.sh | bash ``` -Notes: +Add `--no-onboard` to skip onboarding. For source installs, pass `--install-method git --no-onboard`. -- Add `--no-onboard` if you don’t want onboarding to run again. -- For **source installs**, use: - - ```bash - curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git --no-onboard - ``` - - The installer will `git pull --rebase` **only** if the repo is clean. - -- For **global installs**, the script uses `npm install -g openclaw@latest` under the hood. -- Legacy note: `clawdbot` remains available as a compatibility shim. - -## Before you update - -- Know how you installed: **global** (npm/pnpm) vs **from source** (git clone). -- Know how your Gateway is running: **foreground terminal** vs **supervised service** (launchd/systemd). -- Snapshot your tailoring: - - Config: `~/.openclaw/openclaw.json` - - Credentials: `~/.openclaw/credentials/` - - Workspace: `~/.openclaw/workspace` - -## Update (global install) - -Global install (pick one): +## Alternative: manual npm or pnpm ```bash npm i -g openclaw@latest @@ -55,43 +46,9 @@ npm i -g openclaw@latest pnpm add -g openclaw@latest ``` -We do **not** recommend Bun for the Gateway runtime (WhatsApp/Telegram bugs). +## Auto-updater -To switch update channels (git + npm installs): - -```bash -openclaw update --channel beta -openclaw update --channel dev -openclaw update --channel stable -``` - -Use `--tag ` for a one-off package target override. - -For the current GitHub `main` head via a package-manager install: - -```bash -openclaw update --tag main -``` - -Manual equivalents: - -```bash -npm i -g github:openclaw/openclaw#main -``` - -```bash -pnpm add -g github:openclaw/openclaw#main -``` - -You can also pass an explicit package spec to `--tag` for one-off updates (for example a GitHub ref or tarball URL). - -See [Development channels](/install/development-channels) for channel semantics and release notes. - -Note: on npm installs, the gateway logs an update hint on startup (checks the current channel tag). Disable via `update.checkOnStart: false`. - -### Core auto-updater (optional) - -Auto-updater is **off by default** and is a core Gateway feature (not a plugin). +The auto-updater is off by default. Enable it in `~/.openclaw/openclaw.json`: ```json5 { @@ -107,169 +64,65 @@ Auto-updater is **off by default** and is a core Gateway feature (not a plugin). } ``` -Behavior: +| Channel | Behavior | +| -------- | ------------------------------------------------------------------------------------------------------------- | +| `stable` | Waits `stableDelayHours`, then applies with deterministic jitter across `stableJitterHours` (spread rollout). | +| `beta` | Checks every `betaCheckIntervalHours` (default: hourly) and applies immediately. | +| `dev` | No automatic apply. Use `openclaw update` manually. | -- `stable`: when a new version is seen, OpenClaw waits `stableDelayHours` and then applies a deterministic per-install jitter in `stableJitterHours` (spread rollout). -- `beta`: checks on `betaCheckIntervalHours` cadence (default: hourly) and applies when an update is available. -- `dev`: no automatic apply; use manual `openclaw update`. +The gateway also logs an update hint on startup (disable with `update.checkOnStart: false`). -Use `openclaw update --dry-run` to preview update actions before enabling automation. +## After updating -Then: + + +### Run doctor ```bash openclaw doctor +``` + +Migrates config, audits DM policies, and checks gateway health. Details: [Doctor](/gateway/doctor) + +### Restart the gateway + +```bash openclaw gateway restart +``` + +### Verify + +```bash openclaw health ``` -Notes: + -- If your Gateway runs as a service, `openclaw gateway restart` is preferred over killing PIDs. -- If you’re pinned to a specific version, see “Rollback / pinning” below. +## Rollback -## Update (`openclaw update`) - -For **source installs** (git checkout), prefer: - -```bash -openclaw update -``` - -It runs a safe-ish update flow: - -- Requires a clean worktree. -- Switches to the selected channel (tag or branch). -- Fetches + rebases against the configured upstream (dev channel). -- Installs deps, builds, builds the Control UI, and runs `openclaw doctor`. -- Restarts the gateway by default (use `--no-restart` to skip). - -If you installed via **npm/pnpm** (no git metadata), `openclaw update` will try to update via your package manager. If it can’t detect the install, use “Update (global install)” instead. - -## Update (Control UI / RPC) - -The Control UI has **Update & Restart** (RPC: `update.run`). It: - -1. Runs the same source-update flow as `openclaw update` (git checkout only). -2. Writes a restart sentinel with a structured report (stdout/stderr tail). -3. Restarts the gateway and pings the last active session with the report. - -If the rebase fails, the gateway aborts and restarts without applying the update. - -## Update (from source) - -From the repo checkout: - -Preferred: - -```bash -openclaw update -``` - -Manual (equivalent-ish): - -```bash -git pull -pnpm install -pnpm build -pnpm ui:build # auto-installs UI deps on first run -openclaw doctor -openclaw health -``` - -Notes: - -- `pnpm build` matters when you run the packaged `openclaw` binary ([`openclaw.mjs`](https://github.com/openclaw/openclaw/blob/main/openclaw.mjs)) or use Node to run `dist/`. -- If you run from a repo checkout without a global install, use `pnpm openclaw ...` for CLI commands. -- If you run directly from TypeScript (`pnpm openclaw ...`), a rebuild is usually unnecessary, but **config migrations still apply** → run doctor. -- Switching between global and git installs is easy: install the other flavor, then run `openclaw doctor` so the gateway service entrypoint is rewritten to the current install. - -## Always Run: `openclaw doctor` - -Doctor is the “safe update” command. It’s intentionally boring: repair + migrate + warn. - -Note: if you’re on a **source install** (git checkout), `openclaw doctor` will offer to run `openclaw update` first. - -Typical things it does: - -- Migrate deprecated config keys / legacy config file locations. -- Audit DM policies and warn on risky “open” settings. -- Check Gateway health and can offer to restart. -- Detect and migrate older gateway services (launchd/systemd; legacy schtasks) to current OpenClaw services. -- On Linux, ensure systemd user lingering (so the Gateway survives logout). - -Details: [Doctor](/gateway/doctor) - -## Start / stop / restart the Gateway - -CLI (works regardless of OS): - -```bash -openclaw gateway status -openclaw gateway stop -openclaw gateway restart -openclaw gateway --port 18789 -openclaw logs --follow -``` - -If you’re supervised: - -- macOS launchd (app-bundled LaunchAgent): `launchctl kickstart -k gui/$UID/ai.openclaw.gateway` (use `ai.openclaw.`; legacy `com.openclaw.*` still works) -- Linux systemd user service: `systemctl --user restart openclaw-gateway[-].service` -- Windows (WSL2): `systemctl --user restart openclaw-gateway[-].service` - - `launchctl`/`systemctl` only work if the service is installed; otherwise run `openclaw gateway install`. - -Runbook + exact service labels: [Gateway runbook](/gateway) - -## Rollback / pinning (when something breaks) - -### Pin (global install) - -Install a known-good version (replace `` with the last working one): +### Pin a version (npm) ```bash npm i -g openclaw@ -``` - -```bash -pnpm add -g openclaw@ -``` - -Tip: to see the current published version, run `npm view openclaw version`. - -Then restart + re-run doctor: - -```bash openclaw doctor openclaw gateway restart ``` -### Pin (source) by date +Tip: `npm view openclaw version` shows the current published version. -Pick a commit from a date (example: “state of main as of 2026-01-01”): +### Pin a commit (source) ```bash git fetch origin git checkout "$(git rev-list -n 1 --before=\"2026-01-01\" origin/main)" -``` - -Then reinstall deps + restart: - -```bash -pnpm install -pnpm build +pnpm install && pnpm build openclaw gateway restart ``` -If you want to go back to latest later: - -```bash -git checkout main -git pull -``` +To return to latest: `git checkout main && git pull`. ## If you are stuck -- Run `openclaw doctor` again and read the output carefully (it often tells you the fix). +- Run `openclaw doctor` again and read the output carefully. - Check: [Troubleshooting](/gateway/troubleshooting) - Ask in Discord: [https://discord.gg/clawd](https://discord.gg/clawd)