重新安装 OpenClaw 技能

本技能提供完整流程，可在安全卸载并重装 OpenClaw 的同时，完整保留所有用户配置、凭证、记忆文件、技能及自定义设置。

适用场景

• 执行干净重装以修复损坏的 OpenClaw 安装
• 移除第三方修改，恢复至官方版本
• 通过全新安装方式升级至最新版本
• 将 OpenClaw 迁移至新环境，同时复用现有配置

前提条件

• WSL（Ubuntu 20.04 或更高版本）或 Linux/macOS 系统，并已安装 Node.js
• Node.js 18+ 及 npm/pnpm
• Windows 用户需可访问 WSL 终端

完整操作流程

步骤 1：检查当前安装状态

首先确认 OpenClaw 的安装路径与版本：

# 查看 OpenClaw 版本
npx openclaw --version

# 查找 OpenClaw npm 包安装路径
npm root -g

# 列出全局安装的 npm 包
npm list -g --depth=0

步骤 2：备份全部用户数据

创建包含所有用户配置的完整备份：

# 创建带时间戳的备份目录
BACKUP_DIR=~/openclaw-backup-$(date +%Y%m%d)
mkdir -p $BACKUP_DIR

# 备份整个 .openclaw 目录
cp -r ~/.openclaw $BACKUP_DIR/

# 验证备份内容
ls -la $BACKUP_DIR/

需备份的内容（均已包含在 ~/.openclaw 中）

步骤 3：停止 OpenClaw 服务

终止所有正在运行的 OpenClaw 进程：

# 若网关正在运行，则先停止
npx openclaw gateway stop

# 强制终止残留进程
pkill -f openclaw
pkill -f "node.*openclaw"

# 验证是否仍有进程在运行
ps aux | grep openclaw

步骤 4：卸载 OpenClaw

使用官方卸载命令：

# 完全卸载（包括 CLI 工具，可选）
npx openclaw uninstall --all --yes

# 或仅卸载状态与工作区（推荐，保留 CLI 工具）
npx openclaw uninstall --state --workspace --yes

注意：--all 参数会一并卸载 CLI 工具。如需保留 CLI 以便后续重装，请勿使用该参数。

步骤 5：清理残留文件

移除可能造成干扰的剩余文件：

# 清理 npm 缓存（可选但推荐）
npm cache clean --force

# 若仍存在旧版 OpenClaw npm 包，则卸载
sudo npm uninstall -g openclaw

# 彻底删除残留的 .openclaw 目录
rm -rf ~/.openclaw
rm -rf ~/.openclaw-dev

步骤 6：安装最新版 OpenClaw

安装最新官方版本：

# 全局安装
sudo npm install -g openclaw@latest

# 验证安装结果
npx openclaw --version

步骤 7：恢复用户配置

还原已备份的用户配置：

# 恢复 .openclaw 目录
cp -r ~/openclaw-backup-YYYYMMDD/* ~/.openclaw/

# 设置正确权限
chmod 700 ~/.openclaw

步骤 8：运行健康检查与自动修复

# 运行 doctor 命令检测并修复问题
npx openclaw doctor --fix

步骤 9：启动 OpenClaw 网关

# 启动网关服务
npx openclaw gateway

# 检查健康状态
npx openclaw health

# 查看服务状态
npx openclaw status

一键式自动备份脚本

卸载前运行此命令，生成带时间戳的备份：

# 创建自动备份
BACKUP_DIR=~/openclaw-backup-$(date +%Y%m%d-%H%M%S) && mkdir -p $BACKUP_DIR && cp -r ~/.openclaw/* $BACKUP_DIR/ && echo "Backup created: $BACKUP_DIR"

一键式自动恢复脚本

重装完成后运行此命令，从最新备份中恢复配置：

# 从最新备份恢复
LATEST_BACKUP=$(ls -td ~/openclaw-backup-* | head -1) && cp -r $LATEST_BACKUP/* ~/.openclaw/ && chmod 700 ~/.openclaw && echo "Restored from: $LATEST_BACKUP"

故障排查

恢复后网关无法启动

# 终止残留进程
npx openclaw gateway stop

# 强制启动
npx openclaw gateway --force

端口已被占用

# 查找占用端口的进程
lsof -i :18788

# 终止对应进程
kill 

恢复后配置报错

# 运行 doctor 自动修复
npx openclaw doctor --fix

权限异常

# 修复 .openclaw 目录权限
chmod 700 ~/.openclaw
chmod 600 ~/.openclaw/openclaw.json
chmod 700 ~/.openclaw/credentials

文件参考

配置文件（~/.openclaw/openclaw.json）

需重点保留的关键配置项：

• gateway.port — 网关端口（默认：18788）
• gateway.auth.token — 网关认证 token
• channels.feishu — 飞书（Feishu）应用凭证
• models.providers — AI 模型 API 密钥

备份内容结构

~/.openclaw/
├── openclaw.json          # 主配置文件
├── credentials/           # API 密钥与凭证
├── memory/main.sqlite     # 记忆数据库
├── agents/main/           # Agent 配置
├── skills/                # 已安装技能
├── workspace/             # 用户工作区
│   ├── SOUL.md
│   ├── IDENTITY.md
│   ├── AGENTS.md
│   └── USER.md
├── feishu/                # 飞书（Feishu）配置
├── identity/              # 设备身份信息
├── devices/               # 已配对设备
└── cron/                  # 定时任务

重要提示

1. 卸载前务必执行备份 — 切勿跳过备份步骤
2. 妥善保管备份文件 — 建议复制到外部存储或云端
3. 恢复后务必验证功能 — 确认所有配置均可正常工作
4. 第三方修改将被清除 — 本流程将移除所有第三方补丁，回归官方版本
5. 记忆文件将被保留 — SQLite 记忆数据库已包含在备份中