OpenClaw 中文文档 — 升级、迁移与卸载

本文覆盖 OpenClaw 的 Day-2 运维操作：版本升级、跨机器迁移和彻底卸载。OpenClaw 还在 1.0 之前，迭代节奏较快，理解这些操作对维护一个稳定运行的 Gateway 很有必要。

升级

更新路径选择

OpenClaw 提供多种更新路径，取决于安装方式：

安装方式	推荐更新方式	备注
安装脚本	重新运行安装脚本	自动检测、原地升级
npm/pnpm	npm i -g openclaw@latest	直接更新全局包
源码	openclaw update	自动 fetch + rebase + build
Docker/Podman	重建镜像	重新运行 setup 脚本
Nix	home-manager switch	声明式更新
Ansible	重跑 playbook	幂等操作

安装脚本更新

curl -fsSL https://openclaw.ai/install.sh | bash -s -- --no-onboard

脚本会检测现有安装、执行原地升级，并在需要时运行 openclaw doctor。源码安装使用：

curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git --no-onboard

openclaw update（源码安装）

openclaw update

执行流程：检查工作树是否干净 → 切换到选定频道 → fetch + rebase → 安装依赖 → 构建 → 运行 doctor → 重启网关。

用 --no-restart 跳过自动重启。

更新后的必要操作

openclaw doctor           # 配置迁移、安全审计、服务修复
openclaw gateway restart  # 重启网关（如未自动重启）
openclaw health           # 验证健康状态

值得注意的是，openclaw doctor 不只是一个检查工具。它会主动执行配置迁移（废弃的配置键、旧版文件位置）、审计 DM 策略的安全性、检测并迁移旧版服务（launchd/systemd）。从设计角度看，这是一个将"安全更新"的复杂性封装到单一命令中的做法。

更新频道

OpenClaw 支持三个更新频道：

openclaw update --channel stable  # 稳定版（默认）
openclaw update --channel beta    # Beta 版
openclaw update --channel dev     # 开发版

自动更新器

默认关闭，通过配置启用：

{
  "update": {
    "channel": "stable",
    "auto": {
      "enabled": true,
      "stableDelayHours": 6,
      "stableJitterHours": 12,
      "betaCheckIntervalHours": 1
    }
  }
}

stable 频道的更新策略值得注意：发现新版后等待 stableDelayHours，然后在 stableJitterHours 内基于安装实例的确定性哈希添加抖动。这个设计避免了所有实例同时更新可能带来的雪崩效应。

dev 频道不自动更新，需手动执行 openclaw update。

回滚

全局安装回滚到指定版本：

npm i -g openclaw@<version>
openclaw doctor
openclaw gateway restart

源码安装按日期回滚：

git fetch origin
git checkout "$(git rev-list -n 1 --before=\"2026-01-01\" origin/main)"
pnpm install && pnpm build
openclaw gateway restart

恢复到最新：git checkout main && git pull。

迁移

迁移对象

迁移涉及两个核心目录：

目录	内容	必须迁移
$OPENCLAW_STATE_DIR（默认 ~/.openclaw/）	配置、认证、会话、渠道状态	是
工作区（默认 ~/.openclaw/workspace/）	Agent 文件、记忆、提示词	是

只迁移配置文件（openclaw.json）是不够的。凭据存储在 credentials/ 目录，Agent 状态在 agents/ 目录，这些都在状态目录下。

迁移流程

旧机器：

openclaw gateway stop
cd ~
tar -czf openclaw-state.tgz .openclaw

如果使用了 profile，每个 profile 的状态目录（~/.openclaw-<profile>/）都需要单独处理。

新机器：

# 1. 安装 OpenClaw（跳过引导）
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --no-onboard

# 2. 恢复状态
cd ~
tar -xzf openclaw-state.tgz

# 3. 运行 doctor（修复服务配置、应用迁移）
openclaw doctor

# 4. 启动
openclaw gateway restart
openclaw status

安全注意事项

状态目录包含敏感数据（API Key、OAuth Token、WhatsApp 凭据）。传输时应：

• 使用加密通道（scp/rsync over SSH）
• 备份加密存储
• 怀疑泄露时立即轮换密钥

常见问题

1. Profile/状态目录不匹配：新机器上必须使用与旧机器相同的 profile 或状态目录路径
2. 权限问题：确保状态目录和工作区的所有者是运行网关的用户
3. 远程模式：如果 UI 连接的是远程网关，迁移的是网关主机，不是客户端机器

卸载

内置卸载工具

# 交互式
openclaw uninstall

# 非交互式（完全清除）
openclaw uninstall --all --yes --non-interactive

手动卸载步骤

1. 停止网关：openclaw gateway stop
2. 卸载服务：openclaw gateway uninstall
3. 删除状态目录：rm -rf ~/.openclaw
4. 删除工作区（可选）：rm -rf ~/.openclaw/workspace
5. 移除 CLI：npm rm -g openclaw
6. macOS 应用（如有）：rm -rf /Applications/OpenClaw.app

CLI 已删除但服务仍在运行

macOS（launchd）：

launchctl bootout gui/$UID/ai.openclaw.gateway
rm -f ~/Library/LaunchAgents/ai.openclaw.gateway.plist

Linux（systemd）：

systemctl --user disable --now openclaw-gateway.service
rm -f ~/.config/systemd/user/openclaw-gateway.service
systemctl --user daemon-reload

Windows（计划任务）：

schtasks /Delete /F /TN "OpenClaw Gateway"
Remove-Item -Force "$env:USERPROFILE\.openclaw\gateway.cmd"

Profile 模式下，服务标签/单元名会包含 profile 名称（如 ai.openclaw.<profile>），需要逐一清理。

小结

升级、迁移和卸载是 Day-2 运维的基础操作。OpenClaw 在这方面的设计比较规范：openclaw doctor 作为安全更新的统一入口，迁移只需复制两个目录，卸载提供了内置工具。对于 1.0 之前的项目，这种运维体验是比较成熟的。

本文是系列第四篇。下一篇覆盖 CLI 入门与向导自动化。

---

完整中文文档：OpenClaw 中文文档

GitHub 仓库：openclaw/openclaw