LLM/moltbot
1
0
Fork 0
mirror of https://github.com/moltbot/moltbot.git synced 2026-03-21 16:41:56 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: rewrite updating.md (276→128 lines) and migrating.md (193→107 lines) for readability

Browse Source
This commit is contained in:
Vincent Koc
2026-03-19 11:52:39 -07:00
parent 517570d0fb
commit 7187d1da06
2 changed files with 127 additions and 356 deletions
Download Patch File Download Diff File Expand all files Collapse all files

230
docs/install/migrating.md
View File

@@ -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)
<Tip>
Run `openclaw status` on the old machine to confirm your state directory path.
Custom profiles use `~/.openclaw-<profile>/` or a path set via `OPENCLAW_STATE_DIR`.
</Tip>
### 1) Identify your state directory
## Migration Steps
Most installs use the default:
<Steps>
<Step title="Stop the gateway and back up">
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 <name>` (often becomes `~/.openclaw-<profile>/`)
- `OPENCLAW_STATE_DIR=/some/path`
</Step>
If you’re not sure, run on the **old** machine:
<Step title="Install OpenClaw on the new 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.
</Step>
```bash
openclaw status
```
<Step title="Copy state directory and workspace">
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:
</Step>
- `~/.openclaw/workspace/` (recommended workspace)
- a custom folder you created
<Step title="Run doctor and verify">
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
</Step>
</Steps>
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.)
<AccordionGroup>
<Accordion title="Profile or state-dir mismatch">
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`.
</Accordion>
If you copy **only** the workspace (e.g., via Git), you do **not** preserve:
<Accordion title="Copying only openclaw.json">
The config file alone is not enough. Credentials live under `credentials/`, and agent
state lives under `agents/`. Always migrate the **entire** state directory.
</Accordion>
- sessions
- credentials
- channel logins
<Accordion title="Permissions and ownership">
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.
</Accordion>
Those live under `$OPENCLAW_STATE_DIR`.
<Accordion title="Remote mode">
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).
</Accordion>
## Migration steps (recommended)
<Accordion title="Secrets in backups">
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.
</Accordion>
</AccordionGroup>
### 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/<agentId>/...`
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

253
docs/install/updating.md
View File

@@ -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 <dist-tag|version|spec>` 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:
<Steps>
### 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:
</Steps>
- 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.<profile>`; legacy `com.openclaw.*` still works)
- Linux systemd user service: `systemctl --user restart openclaw-gateway[-<profile>].service`
- Windows (WSL2): `systemctl --user restart openclaw-gateway[-<profile>].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 `<version>` with the last working one):
### Pin a version (npm)
```bash
npm i -g openclaw@<version>
```
```bash
pnpm add -g openclaw@<version>
```
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)