安全平滑升级OpenClaw需先备份~/.openclaw/目录，再通过内置update命令、官方安装脚本、Git手动同步、Docker容器内升级四种方式之一完成，全程保留配置、凭证与工作区数据。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
如果您正在运行 OpenClaw 服务，但希望升级到新版同时保留全部配置、凭证与工作区数据，则需避开直接覆盖或重装导致的配置丢失风险。以下是确保配置不丢失的安全平滑更新步骤：
一、升级前强制备份关键目录
OpenClaw 的所有用户级配置、认证凭据和记忆数据均集中存储于 ~/.openclaw/ 目录下。任何升级操作前必须先停止服务并完成原子性备份，否则后续恢复将不可逆。
1、执行 Gateway 停止命令以冻结状态：
openclaw gateway stop
2、创建带精确时间戳的完整目录副本：
cp -r ~/.openclaw ~/.openclaw.backup-$(date +%Y%m%d-%H%M%S)
3、验证备份完整性（检查是否存在 credentials/、workspace/、openclaw.json）：
ls -la ~/.openclaw.backup-$(date +%Y%m%d-%H%M%S)/
二、使用内置 update 命令升级（推荐）
该方式由 CLI 内置实现，自动拉取最新 stable 渠道代码、校验依赖一致性，并在升级后重启 Gateway，全程不触碰 ~/.openclaw/ 下的用户数据，是默认最安全路径。
1、确认当前版本并检查可更新状态：
openclaw --version && openclaw status
2、执行标准更新流程：
openclaw update
3、等待终端输出 “Update completed” 并显示新版本号（如 v2026.4.1）后，手动验证服务健康：
openclaw health
三、通过官方安装脚本就地升级
当内置 update 命令因权限异常、网络策略拦截或 CLI 损坏失效时，此方式可绕过本地 CLI，直接调用远程脚本完成环境诊断、路径识别与增量覆盖，对源码安装用户亦兼容。
1、执行无交互式脚本安装（自动识别现有安装方式）：
curl -fsSL https://openclaw.bot/install.sh | bash -s -- --no-onboard
2、若已确认为 git 源码安装，显式声明安装方法以避免误判：
curl -fsSL https://openclaw.bot/install.sh | bash -s -- --install-method git --no-onboard
抓取并分析 OpenClaw JSONL 会话日志，重建并回填代理记忆文件。适用于：(1) 模型切换后记忆不完整，(2) 验证记忆覆盖度，(3) 重建丢失记忆，(4) 通过 cron/heartbeat 自动同步每日记忆。支持简单提取及基于 LLM 的叙事摘要，并自动清理敏感信息。
3、升级完成后立即运行环境自检：
openclaw doctor
四、Git 源码目录手动同步
适用于开发者或深度定制用户，通过原仓库 pull + 构建流程更新二进制，完全可控且不依赖全局 npm/pnpm 环境，所有配置文件保留在原 ~/.openclaw/ 路径中不受影响。
1、进入原始克隆目录（例如 ~/openclaw）：
cd ~/openclaw
2、获取远程更新并切换至 main 分支：
git fetch origin
git checkout main
git pull origin main
3、重新安装依赖并构建生产包：
pnpm install
pnpm build
4、重启服务并确认版本生效：
openclaw gateway restart
openclaw --version
五、Docker 容器内升级（root 权限必需）
Docker 默认以非 root 用户运行，而 openclaw update 需写入 node_modules 全局路径。必须临时切换用户上下文才能完成升级，否则将因权限拒绝失败，但 ~/.openclaw/ 卷挂载路径不受影响。
1、以 root 身份进入容器：
docker exec -it --user root openclaw sh
2、在容器内执行更新命令：
openclaw update
3、退出容器后重启服务：
exit
docker restart openclaw
4、检查日志末尾是否包含 “Gateway started on port 3000”：
docker logs openclaw --tail 5
