Workspace 备份技能 | Workspace 备份技能

OpenClaw workspace 核心文件快速备份技能。仅压缩备份所有 markdown 文件（核心笔记、技能文档、记忆文件等），保持原始文件夹结构，便于迁移和还原。

快速备份工具，用于 OpenClaw workspace 的核心文件。仅压缩 .md 文件，保留完整的目录结构，方便迁移与恢复。

功能特点 | Features

• 🎯 只备份核心内容 - 仅包含 .md 文件，忽略二进制文件、node_modules、构建输出等
• 📁 保持文件夹结构 - 压缩包中保留完整目录结构，解压后可自动还原
• ⚡ 快速压缩 - 基于 zip 命令实现，性能高效
• 🔄 完整还原 - 解压即可恢复所有文件和目录结构

使用场景 | Use Cases

• 将 workspace 迁移到新机器
• 定期备份核心笔记和技能内容
• 与他人分享你的技能和笔记
• 传输前瘦身备份，仅保留文本内容

备份脚本 backup-workspace.sh | Backup Script

脚本代码 | Script Code

#!/bin/bash
# workspace-backup - 备份 OpenClaw workspace 中所有 markdown 文件，保持目录结构
# workspace-backup - Backup all markdown files from OpenClaw workspace keeping directory structure

set -euo pipefail

# 默认配置 | Default configuration
SOURCE_DIR="${1:-$HOME/.openclaw/workspace}"  # 源文件夹，默认: ~/.openclaw/workspace
OUTPUT_ZIP="${2:-workspace-backup-$(date +%Y%m%d).zip}"  # 输出压缩包路径，默认按日期命名

show_help() {
    echo "用法: ./backup-workspace.sh [source_dir] [output_zip]"
    echo ""
    echo "参数:"
    echo "  source_dir    要备份的文件夹 (默认: ~/.openclaw/workspace)"
    echo "  output_zip    输出压缩包路径 (默认: workspace-backup-YYYYMMDD.zip)"
    echo ""
    echo "示例:"
    echo "  ./backup-workspace.sh"
    echo "                          备份默认 workspace 到当前日期命名的压缩包"
    echo "  ./backup-workspace.sh ~/my-notes my-notes-backup.zip"
    echo "                          备份指定文件夹"
    exit 1
}

# 检查帮助参数 | Check for help
if [ "$#" -ge 1 ] && [ "$1" = "-h" ] || [ "$1" = "--help" ]; then
    show_help
fi

# 检查源文件夹是否存在 | Check source directory exists
if [ ! -d "$SOURCE_DIR" ]; then
    echo "错误: 源文件夹 '$SOURCE_DIR' 不存在或不是目录"
    exit 1
fi

echo "====== Workspace Markdown Backup ======"
echo "源文件夹: $SOURCE_DIR"
echo "输出文件: $OUTPUT_ZIP"
echo ""
echo "正在搜索所有 .md 文件..."

# 统计 markdown 文件数量 | Count markdown files
MD_COUNT=$(find "$SOURCE_DIR" -type f -name "*.md" | wc -l)

if [ "$MD_COUNT" -eq 0 ]; then
    echo "未找到任何 .md 文件，退出"
    exit 0
fi

echo "找到 $MD_COUNT 个 .md 文件，开始压缩..."
echo ""

# 使用 zip 命令压缩，保持目录结构 | Compress using zip, keep directory structure
find "$SOURCE_DIR" -type f -name "*.md" | xargs zip -r "$OUTPUT_ZIP"

echo ""
echo "✅ 备份完成!"
echo "压缩包: $OUTPUT_ZIP"
echo "包含 $MD_COUNT 个 .md 文件，保持原始文件夹结构"

# 显示压缩后大小 | Show compressed size
SIZE=$(du -h "$OUTPUT_ZIP" | cut -f1)
echo "压缩后大小: $SIZE"

使用方式 | Usage

需要使用时，将上述脚本代码复制保存为文件：

# 复制本文件中备份脚本代码块内容
cat > backup-workspace << 'EOF'
[paste script code here]
EOF
chmod +x backup-workspace
mv backup-workspace ~/.local/bin/

还原脚本 restore-workspace.sh | Restore Script

脚本代码 | Script Code

#!/bin/bash
# workspace-restore - 从备份压缩包还原 markdown 文件

set -euo pipefail

# 默认配置
BACKUP_ZIP="${1:-}"  # 要还原的压缩包 (必填)
TARGET_DIR="${2:-$HOME/.openclaw/workspace}"  # 还原到哪个文件夹 (默认: ~/.openclaw/workspace)

show_help() {
    echo "用法: ./restore-workspace.sh <backup_zip> [target_dir]"
    echo ""
    echo "参数:"
    echo "  backup_zip    要还原的压缩包 (必填)"
    echo "  target_dir    还原到哪个文件夹 (默认: ~/.openclaw/workspace)"
    echo ""
    echo "示例:"
    echo "  ./restore-workspace.sh workspace-backup-20260316.zip"
    echo "                          还原到默认 workspace"
    echo "  ./restore-workspace.sh my-notes-backup.zip ~/new-workspace"
    echo "                          还原到指定位置"
    exit 1
}

# 检查帮助参数
if [ "$#" -eq 0 ] || [ "$1" = "-h" ] || [ "$1" = "--help" ]; then
    show_help
fi

# 检查备份文件是否存在
if [ ! -f "$BACKUP_ZIP" ]; then
    echo "错误: 备份文件 '$BACKUP_ZIP' 不存在"
    exit 1
fi

# 检查目标文件夹
if [ ! -d "$TARGET_DIR" ]; then
    echo "目标文件夹 '$TARGET_DIR' 不存在，创建它..."
    mkdir -p "$TARGET_DIR"
fi

echo "====== Workspace Markdown 还原 ======"
echo "备份文件: $BACKUP_ZIP"
echo "目标文件夹: $TARGET_DIR"
echo ""
echo "正在列出压缩包内容..."
echo ""

# 还原前列出内容供用户确认
unzip -l "$BACKUP_ZIP"

echo ""
echo "是否继续还原? (y/N)"
read -r CONFIRM || CONFIRM="N"
if [ "$CONFIRM" != "y" ] && [ "$CONFIRM" != "Y" ]; then
    echo "已取消"
    exit 0
fi

echo ""
echo "开始还原..."
echo ""

# 使用 unzip 还原 - 自动解压到正确的目录结构
unzip -o "$BACKUP_ZIP"

echo ""
echo "✅ 还原完成!"
echo "所有文件已还原，保持原始文件夹结构"

# 统计还原文件数量
RESTORED_COUNT=$(unzip -l "$BACKUP_ZIP" | grep -c "\.md$")
echo "共还原 $RESTORED_COUNT 个 .md 文件"

使用方式

需要使用时，复制上面的脚本代码保存为文件即可：

# 复制本文件中还原脚本代码块内容
cat > restore-workspace << 'EOF'
[paste script code here]
EOF
chmod +x restore-workspace
mv restore-workspace ~/.local/bin/

工作原理

备份逻辑

1. 参数解析 - 接受源文件夹和输出文件路径，提供默认值
2. 文件搜索 - 使用 find <dir> -type f -name "*.md" 递归搜索所有 markdown 文件
3. 数量检查 - 如果没有找到 md 文件则提前退出
4. 压缩打包 - 通过 xargs 将找到的文件传给 zip -r，zip 自动保持相对路径结构
5. 统计输出 - 显示压缩包大小和文件数量

还原逻辑

1. 参数检查 - 验证备份文件存在，若目标文件夹不存在则自动创建
2. 预览内容 - 使用 unzip -l 列出压缩包内容，供用户确认
3. 用户确认 - 必须输入 y 才开始还原，防止误操作
4. 解压还原 - 使用 unzip -o 解压，因压缩包中已保存完整路径，可自动还原目录结构
5. 统计输出 - 显示还原完成提示及文件数量

多 Workspace 处理（多 Agent 场景）

问题描述

当多个 agent 在同一环境运行时，每个 agent 可能拥有独立的 workspace。本工具支持备份任意一个 workspace。

备份策略

1. 显式指定源文件夹

备份非默认 workspace 时，始终显式指定源文件夹参数：

backup-workspace /path/to/your/workspace backup-$(whoami)-workspace.zip

1. 分别备份多个 workspace

对于多个 workspace，使用不同输出名称逐一备份：

backup-workspace ~/workspace-agent1 backup-agent1.zip
backup-workspace ~/workspace-agent2 backup-agent2.zip

1. 在备份文件名中包含 workspace 标识

推荐命名格式：workspace-backup-[用户名|agent名]-YYYYMMDD.zip

还原策略

1. 还原到正确目标目录

还原特定 workspace 的备份时，显式指定目标目录：

restore-workspace backup-agent1.zip /path/to/new/agent1/workspace

1. 跨 agent 迁移

若需将 workspace 从一个 agent 迁移到另一个：

# 在源 agent 上备份
backup-workspace /path/to/source/workspace migration.zip

# 将 migration.zip 传输至目标机器，在目标 agent 上还原
restore-workspace migration.zip /path/to/target/workspace

使用示例

备份默认 workspace | Backup default workspace

backup-workspace

输出示例:

====== Workspace Markdown Backup ======
源文件夹: /root/.openclaw/workspace
输出文件: workspace-backup-20260316.zip

正在搜索所有 .md 文件...
找到 42 个 .md 文件，开始压缩...

  adding: ... (stored 0%)
  ...

✅ 备份完成!
压缩包: workspace-backup-20260316.zip
包含 42 个 .md 文件，保持原始文件夹结构
压缩后大小: 1.2M

备份指定文件夹 | Backup specified directory

backup-workspace ~/my-notes my-notes-backup.zip

还原备份 | Restore backup

restore-workspace workspace-backup-20260316.zip

会先列出压缩包内容，然后询问确认:

... (list of files)
是否继续还原? (y/N)
y
开始还原...
✅ 还原完成!

还原到自定义位置 | Restore to custom location

mkdir -p ~/new-workspace
unzip workspace-backup-20260316.zip -d ~/new-workspace

兼容性 | Compatibility

Linux / macOS | Linux / macOS

• 原生支持，系统自带 find、zip、unzip 即可运行
• 如果缺少 zip：Ubuntu/Debian 执行 apt install zip unzip

Windows | Windows

方案 1: WSL（推荐） | Option 1: WSL (Recommended)

在 Windows 子系统 for Linux (WSL) 中运行完全兼容，使用方法和 Linux 相同。

方案 2: Git Bash / MinGW | Option 2: Git Bash / MinGW

Git Bash / MinGW 环境通常包含 find、zip、unzip 命令，脚本只需微调路径即可工作：

• 将 Windows 路径 C:\ 转换为 /c/ 格式
• 保存脚本时行结尾必须是 LF（不是 CRLF）

方案 3: PowerShell 移植 | Option 3: PowerShell Port

参考上述逻辑移植为 PowerShell：

# PowerShell 等价逻辑：

# 1. 查找所有 .md 文件
$mdFiles = Get-ChildItem -Path $sourceDir -Recurse -Filter "*.md"

# 2. 使用 Compress-Archive 压缩
$mdFiles | Compress-Archive -DestinationPath $outputZip

# 3. 还原时
# Expand-Archive -Path $backupZip -DestinationPath $targetDir

主要区别:

• PowerShell 原生保持目录结构
• 使用 Get-ChildItem -Recurse 替代 find
• 使用 Compress-Archive/Expand-Archive 替代 zip/unzip

依赖 | Dependencies

• zip - 压缩 (Ubuntu/Debian: apt install zip)
• unzip - 解压 (Ubuntu/Debian: apt install unzip)

文件结构 | File Structure

skills/workspace-backup/
└── SKILL.md              # 技能文档（本文件，包含全部逻辑描述和脚本代码）

本技能仅包含这一个 markdown 文件，所有备份和还原逻辑都在此文档中描述，代码以代码块形式提供。使用时复制代码块保存为可执行文件即可。

注意事项 | Notes

1. 路径处理 - 如果你使用绝对路径进行备份，还原时也会还原到相同路径
2. 增量备份 - 重复备份到同一个 zip 会追加文件，建议使用日期命名
3. 大文件排除 - 脚本只备份 .md，会自动忽略图片、视频、node_modules、git 数据等
4. 权限 - 还原到系统目录需要适当权限，普通用户还原到自己的 home 目录不需要 sudo

最佳实践 | Best Practices

• 定期备份 - 每周备份一次 workspace 核心内容
• 命名规范 - 使用 workspace-backup-YYYYMMDD.zip 格式便于识别
• 离线存储 - 将备份压缩包保存到其他地方，防止意外丢失
• 还原测试 - 重要备份后建议测试一下能否正常还原

技能使用提示词示例 | Prompt Examples

以下是在 AI agent 中使用此技能时的常见提示词示例：

示例 1: 备份当前 workspace | Example 1: Backup current workspace

使用 workspace-backup 技能帮我备份当前 OpenClaw workspace 所有 markdown 文件
Use the workspace-backup skill to backup all markdown files in current OpenClaw workspace

示例 2: 备份自定义目录 | Example 2: Backup custom directory

帮我备份 ~/my-notes 目录下所有 markdown 文件，保存为 my-notes-backup.zip
Help me backup all markdown files under ~/my-notes directory, save as my-notes-backup.zip

示例 3: 还原备份 | Example 3: Restore backup

使用 workspace-backup 技能帮我还原 backup-20260316.zip 到当前 workspace
Use the workspace-backup skill to restore backup-20260316.zip to current workspace

示例 4: 在 workspace 之间迁移 | Example 4: Migrate between workspaces

我要将这个 workspace 的所有 markdown 文件迁移到另一个机器的新 workspace，请帮我创建备份
I need to migrate all markdown files from this workspace to a new workspace on another machine, help me create the backup

示例 5: 多 agent 备份 | Example 5: Multi-agent backup

我这里有三个不同的 workspace，帮我分别备份它们，每个使用不同的文件名
I have three different workspaces here, help me backup them separately with different filenames

示例 6: Windows WSL 备份 | Example 6: Windows WSL backup

markdown

name: Workspace Zip Backup

version: 0.1.0

description: 在 Windows WSL 环境下，备份 /home/user/workspace 目录中的所有 Markdown 文件

summary: 备份指定路径下的所有 Markdown 文件为 ZIP 压缩包

在 Windows WSL 环境下，帮我备份 /home/user/workspace 所有 markdown 文件

How Agents Use This Skill | Agent 如何使用本技能

当用户请求备份/还原时，agent 应遵循以下步骤：

1. 阅读本技能文档 - 理解备份和还原逻辑
2. 创建脚本文件 - 从本文档复制相应的脚本代码到可执行文件
3. 添加执行权限 - chmod +x <script-file>
4. 使用正确参数运行脚本 - 如果参数不明确，与用户确认
5. 验证结果 - 检查输出来确保备份/还原成功