工作流程 1：上传备份

触发场景

当用户请求备份工作区文件时执行：

• "备份我的工作区文件"
• "将 SOUL.md 上传到 soul-upload"
• "为我的 agent 文件创建加密备份"
• "备份 SOUL.md 和 MEMORY.md"

执行步骤

1. 收集文件列表

   • 如果用户指定了文件，则使用用户指定的文件
   • 否则，使用默认列表：SOUL.md MEMORY.md IDENTITY.md AGENTS.md TOOLS.md
   • 使用 Read 工具验证文件是否存在

2. 执行备份脚本（密码自动生成）

   • 定位脚本路径（通常在 Skill 目录的 scripts/backup.py）

   • 执行命令时不带 --password 参数（脚本将自动生成）：

     python3 scripts/backup.py upload \
       --files "SOUL.md MEMORY.md IDENTITY.md"
     

   • 脚本自动生成一个 32 位字符的随机密码

   • 捕获标准输出（JSON 响应）和标准错误（进度信息，包括生成的密码）

3. 处理响应

   • 成功时，脚本输出 JSON：

     {
       "backupId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
       "downloadUrl": "https://soul-upload.com/backup/...",
       "sizeBytes": 12345,
       "sha256": "abc123...",
       "password": "auto-generated-32-char-random-password"
     }
     

   • 解析 JSON 并提取关键信息，包括自动生成的密码

4. 保存恢复信息

   • 使用 Write 工具创建/更新 .openclaw-backup-recovery.txt

   • 关键：在恢复文件中包含自动生成的密码

   • 格式：

     Backup ID: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
     Password: auto-generated-32-char-random-password
     Download URL: https://soul-upload.com/backup/...
     Created: 2024-01-15 10:30:00 UTC
     Size: 12.05 KB
     SHA256: abc123...
     Files: SOUL.md, MEMORY.md, IDENTITY.md
     ---
     

   • 追加到文件末尾（保留历史记录）

5. 显示成功消息

   • 通知用户备份已完成
   • 显示备份 ID 和文件大小
   • 重要：告知用户密码已自动生成并保存到 .openclaw-backup-recovery.txt
   • 警告用户：恢复文件至关重要 - 没有它，备份将无法恢复

错误处理

示例对话

User: Back up my SOUL.md and MEMORY.md
Claude: I'll backup these files with auto-generated encryption.
       [Executes backup script]
       Backup complete!
       - Backup ID: 3f8a2b1c-...
       - Size: 45.2 KB
       - Password: Auto-generated (32 chars)
       - Recovery info saved to .openclaw-backup-recovery.txt

       IMPORTANT: Keep .openclaw-backup-recovery.txt safe!
       It contains the password needed to restore this backup.

工作流程 2：下载备份

触发场景

当用户请求恢复备份时执行：

• "恢复我的备份"
• "下载我上次的备份"
• "恢复备份 [backup-id]"
• "从 [download-url] 恢复"

执行步骤

1. 获取备份 ID 和密码

   • 检查用户是否提供了备份 ID 或下载 URL
   • 如果未提供，使用 Read 工具读取 .openclaw-backup-recovery.txt
   • 从文件中提取最新的备份 ID 和 密码
   • 如果文件不存在或为空，则无法继续（密码未知）

2. 确定输出目录

   • 默认：当前工作目录 (.)
   • 如果用户指定了目录，则使用用户指定的目录
   • 警告用户：现有文件可能会被覆盖

3. 执行恢复脚本

   • 使用恢复文件中的密码执行命令：

     python3 scripts/backup.py download \
       --backup-id "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" \
       --password "password-from-recovery-file" \
       --output-dir "."
     

   • 捕获标准输出（JSON 响应）和标准错误（进度信息）

4. 处理响应

   • 成功时，脚本输出 JSON：

     {
       "success": true,
       "extractedFiles": ["SOUL.md", "MEMORY.md", "IDENTITY.md"],
       "outputDir": "/path/to/output"
     }
     

   • 解析提取的文件列表

5. 验证恢复结果

   • 使用 Read 工具读取已恢复文件的前几行
   • 显示文件预览以供用户确认内容正确
   • 提醒用户检查完整内容

6. 显示成功消息

   • 列出已恢复的文件
   • 显示输出目录
   • 建议用户验证文件内容

错误处理

示例对话

User: Restore my last backup
Claude: I found the most recent backup in .openclaw-backup-recovery.txt
       - Backup ID: 3f8a2b1c-...
       - Created: 2024-01-15 10:30:00 UTC
       Downloading and decrypting backup...
       Restoration complete! Extracted the following files:
       - SOUL.md
       - MEMORY.md
       - IDENTITY.md
       Files saved to current directory, please verify content is correct.

工作流程 3：删除备份

触发场景

当用户请求删除远程备份时执行：

• "删除我的备份"
• "移除备份 [backup-id]"
• "从 soul-upload 删除备份"

执行步骤

1. 获取备份 ID

   • 检查用户是否提供了备份 ID
   • 如果未提供，使用 Read 工具读取 .openclaw-backup-recovery.txt
   • 显示可用的备份列表供用户选择
   • 如果文件不存在或为空，请用户提供备份 ID

2. 请求确认

   • 警告：此操作不可逆，备份将被永久删除
   • 显示要删除的备份 ID 和创建时间
   • 请求用户确认删除

3. 执行删除脚本

   • 用户确认后，执行命令：

     python3 scripts/backup.py delete \
       --backup-id "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
     

   • 捕获标准输出（JSON 响应）和标准错误（进度信息）

4. 处理响应

   • 成功时，脚本输出 JSON：

     {
       "success": true,
       "backupId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
     }
     

5. 更新恢复信息文件

   • 使用 Read 工具读取 .openclaw-backup-recovery.txt
   • 移除已删除的备份记录（包括其密码）
   • 使用 Write 工具保存更新后的文件
   • 如果文件变空，可以删除该文件

6. 显示成功消息

   • 确认备份已删除
   • 显示已删除的备份 ID
   • 提醒用户：如果需要再次备份，必须使用新密码创建新的备份

错误处理

示例对话

User: Delete my backup
Claude: I found the following backups in .openclaw-backup-recovery.txt:
       1. Backup ID: 3f8a2b1c-... (2024-01-15 10:30:00)
       2. Backup ID: 7b2c9d4e-... (2024-01-14 08:20:00)
       Which backup would you like to delete? (1 or 2)
User: 1
Claude: Warning: This will permanently delete backup 3f8a2b1c-...
       This action cannot be undone. Confirm deletion? (yes/no)
User: yes
Claude: Backup deleted.
       - Backup ID: 3f8a2b1c-...
       To backup again, create a new backup with a new auto-generated password.

安全说明

密码策略（新）

• 自动生成密码：每个备份都会获得一个唯一的 32 位字符随机密码
• 永不重复使用密码：根据 soul-upload.com 政策，不要在不同备份间重复使用密码
• 密码存储：密码存储在 .openclaw-backup-recovery.txt 中（解密所必需）
• 用户责任：用户必须妥善保管恢复文件 - 没有它，备份将无法恢复

恢复文件安全性

• 文件位置：.openclaw-backup-recovery.txt（工作区根目录）
• 内容：备份 ID、密码（关键）、下载 URL、时间戳、SHA256
• 关键：恢复文件是唯一存储密码的地方
• 建议：
  • 如果敏感，请添加到 .gitignore
  • 或者提交到版本控制以供团队访问
  • 考虑将恢复文件本身备份到单独的安全位置

加密算法

• 算法：AES-256-CBC（对称加密）
• 加盐：openssl 自动添加盐以增强安全性
• 兼容性：与 soul-upload.com 官方文档保持一致

临时文件清理

• 脚本使用 try-finally 确保清理临时文件
• 避免在磁盘上留下未加密的敏感数据

文件大小限制

• 最大备份大小：20 MB（压缩和加密后）
• 检查时机：上传前自动检查
• 超出限制处理：显示实际大小，建议用户：
  • 移除大文件（如日志、缓存）
  • 拆分备份（分批备份不同的文件）

API 参考

soul-upload.com 备份 API：

常见状态码：

• 200 - 成功
• 404 - 备份未找到
• 413 - 文件过大（超过 20MB）
• 415 - 不支持的文件类型
• 500 - 服务器错误

故障排除

缺少依赖项

问题：脚本错误 "Missing required tools: tar, openssl"

解决方案：

• macOS: brew install openssl (tar 内置)
• Ubuntu/Debian: sudo apt-get install tar openssl
• 验证安装：tar --version 和 openssl version

Python requests 库缺失

问题：脚本错误 "Error: 'requests' library not found"

解决方案：

pip install requests
# 或
pip3 install requests

恢复文件丢失

问题：无法恢复备份 - 恢复文件丢失

解决方案：

• 恢复文件至关重要 - 包含密码的唯一副本
• 没有恢复文件，备份无法恢复
• 建议将恢复文件备份到单独的安全位置
• 如果丢失，备份将永久无法访问

网络超时

问题：上传/下载期间超时

解决方案：

• 检查网络连接
• 减小备份文件大小（移除不必要的文件）
• 脚本默认超时为 5 分钟，通常足够

文件已存在

问题：恢复期间覆盖现有文件

解决方案：

• 恢复前备份现有文件
• 指定不同的输出目录
• 手动将现有文件移动到其他位置

使用示例

示例 1：备份所有默认文件

User: Back up my workspace files
Claude: [Execute upload workflow using default file list]
       [Auto-generate password and save to recovery file]

示例 2：备份特定文件

User: Back up only SOUL.md and MEMORY.md
Claude: [Execute upload workflow, backup only specified files]
       [Auto-generate password and save to recovery file]

示例 3：恢复最新备份

User: Restore my last backup
Claude: [Read latest Backup ID and password from .openclaw-backup-recovery.txt]
       [Execute download workflow]

示例 4：恢复特定备份

User: Restore backup 3f8a2b1c-1234-5678-90ab-cdef12345678
Claude: [Read password for this Backup ID from recovery file]
       [Execute download workflow]

示例 5：删除旧备份

User: Delete my old backups
Claude: [Show available backup list from recovery file]
       [User selects backup to delete]
       [Execute delete workflow]
       [Remove entry from recovery file]

最佳实践

1. 定期备份：建议每周备份或在重要更改后进行备份
2. 恢复文件管理：妥善保管 .openclaw-backup-recovery.txt 并单独备份
3. 验证恢复：定期测试备份恢复过程，确保备份可用
4. 清理旧备份：定期删除不需要的旧备份以节省存储空间
5. 多份副本：考虑将恢复文件保存在多个安全位置

脚本路径

脚本文件位于 Skill 目录的 scripts/backup.py。

执行 Bash 命令时，请确保使用正确的相对或绝对路径。通常：

• 如果当前在 Skill 目录：python3 scripts/backup.py ...
• 如果在其他目录：使用绝对路径或先 cd 到 Skill 目录

参考文档

• soul-upload.com 备份指南
• soul-upload.com 恢复指南
• OpenClaw Agent 文档

版本 : 2.0.0 作者 : Claude Code 许可证 : MIT 密码策略 : 每个备份自动生成唯一密码（v2.0.0 新增）

每周安装量

1.8K

仓库

theagentservice/skills

首次出现

Feb 15, 2026

安全审计

Gen Agent Trust HubFailSocketFailSnykFail

安装于

github-copilot1.7K

opencode1.7K

codex1.7K

gemini-cli1.7K

cursor1.7K

kimi-cli1.7K

Workflow 1: Upload Backup

Trigger Scenarios

Execute when the user requests to backup workspace files:

• "Back up my workspace files"
• "Upload SOUL.md to soul-upload"
• "Create an encrypted backup of my agent files"
• "Backup SOUL.md and MEMORY.md"

Execution Steps

1. Collect File List

   • If user specified files, use the user-specified files
   • Otherwise, use default list: SOUL.md MEMORY.md IDENTITY.md AGENTS.md TOOLS.md
   • Use Read tool to verify files exist

2. Execute Backup Script (Password Auto-Generated)

   • Locate script path (usually scripts/backup.py in Skill directory)

   • Execute command WITHOUT --password argument (script will auto-generate):

     python3 scripts/backup.py upload \
       --files "SOUL.md MEMORY.md IDENTITY.md"
     

   • Script automatically generates a 32-character random password

   • Capture stdout (JSON response) and stderr (progress info including generated password)

3. Process Response

   • On success, script outputs JSON:

     {
       "backupId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
       "downloadUrl": "https://soul-upload.com/backup/...",
       "sizeBytes": 12345,
       "sha256": "abc123...",
       "password": "auto-generated-32-char-random-password"
     }
     

   • Parse JSON and extract key information including the auto-generated password

4. Save Recovery Information

   • Use Write tool to create/update .openclaw-backup-recovery.txt

   • CRITICAL : Include the auto-generated password in the recovery file

   • Format:

     Backup ID: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
     Password: auto-generated-32-char-random-password
     Download URL: https://soul-upload.com/backup/...
     Created: 2024-01-15 10:30:00 UTC
     Size: 12.05 KB
     SHA256: abc123...
     Files: SOUL.md, MEMORY.md, IDENTITY.md
     ---
     

   • Append to end of file (preserve history)

5. Display Success Message

   • Inform user backup is complete
   • Show Backup ID and file size
   • IMPORTANT : Inform user that password was auto-generated and saved to .openclaw-backup-recovery.txt
   • Warn user: Recovery file is CRITICAL - without it, backup cannot be restored

Error Handling

Example Conversation

User: Back up my SOUL.md and MEMORY.md
Claude: I'll backup these files with auto-generated encryption.
       [Executes backup script]
       Backup complete!
       - Backup ID: 3f8a2b1c-...
       - Size: 45.2 KB
       - Password: Auto-generated (32 chars)
       - Recovery info saved to .openclaw-backup-recovery.txt

       IMPORTANT: Keep .openclaw-backup-recovery.txt safe!
       It contains the password needed to restore this backup.

Workflow 2: Download Backup

Trigger Scenarios

Execute when user requests to restore backup:

• "Restore my backup"
• "Download my last backup"
• "Recover backup [backup-id]"
• "Restore from [download-url]"

Execution Steps

1. Get Backup ID and Password

   • Check if user provided Backup ID or Download URL
   • If not provided, use Read tool to read .openclaw-backup-recovery.txt
   • Extract latest Backup ID AND password from file
   • If file doesn't exist or is empty, cannot proceed (password unknown)

2. Determine Output Directory

   • Default: Current working directory (.)
   • If user specified a directory, use user-specified directory
   • Warn user: Existing files may be overwritten

3. Execute Restore Script

   • Execute command with password from recovery file:

     python3 scripts/backup.py download \
       --backup-id "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" \
       --password "password-from-recovery-file" \
       --output-dir "."
     

   • Capture stdout (JSON response) and stderr (progress info)

4. Process Response

   • On success, script outputs JSON:

     {
       "success": true,
       "extractedFiles": ["SOUL.md", "MEMORY.md", "IDENTITY.md"],
       "outputDir": "/path/to/output"
     }
     

   • Parse extracted file list

5. Verify Restoration Result

   • Use Read tool to read first few lines of restored files
   • Show file preview for user to confirm content is correct
   • Remind user to check complete content

6. Display Success Message

   • List restored files
   • Show output directory
   • Suggest user verify file content

Error Handling

Example Conversation

User: Restore my last backup
Claude: I found the most recent backup in .openclaw-backup-recovery.txt
       - Backup ID: 3f8a2b1c-...
       - Created: 2024-01-15 10:30:00 UTC
       Downloading and decrypting backup...
       Restoration complete! Extracted the following files:
       - SOUL.md
       - MEMORY.md
       - IDENTITY.md
       Files saved to current directory, please verify content is correct.

Workflow 3: Delete Backup

Trigger Scenarios

Execute when user requests to delete remote backup:

• "Delete my backup"
• "Remove backup [backup-id]"
• "Delete the backup from soul-upload"

Execution Steps

1. Get Backup ID

   • Check if user provided Backup ID
   • If not provided, use Read tool to read .openclaw-backup-recovery.txt
   • Show available backup list for user to select
   • If file doesn't exist or is empty, ask user to provide Backup ID

2. Request Confirmation

   • Warning: This operation is irreversible, backup will be permanently deleted
   • Show Backup ID to delete and creation time
   • Ask user to confirm deletion

3. Execute Delete Script

   • After user confirms, execute command:

     python3 scripts/backup.py delete \
       --backup-id "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
     

   • Capture stdout (JSON response) and stderr (progress info)

4. Process Response

   • On success, script outputs JSON:

     {
       "success": true,
       "backupId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
     }
     

5. Update Recovery Info File

   • Use Read tool to read .openclaw-backup-recovery.txt
   • Remove deleted backup record (including its password)
   • Use Write tool to save updated file
   • If file becomes empty, can delete the file

6. Display Success Message

   • Confirm backup was deleted
   • Show deleted Backup ID
   • Remind user: If backup is needed again, must create new one with new password

Error Handling

Example Conversation

User: Delete my backup
Claude: I found the following backups in .openclaw-backup-recovery.txt:
       1. Backup ID: 3f8a2b1c-... (2024-01-15 10:30:00)
       2. Backup ID: 7b2c9d4e-... (2024-01-14 08:20:00)
       Which backup would you like to delete? (1 or 2)
User: 1
Claude: Warning: This will permanently delete backup 3f8a2b1c-...
       This action cannot be undone. Confirm deletion? (yes/no)
User: yes
Claude: Backup deleted.
       - Backup ID: 3f8a2b1c-...
       To backup again, create a new backup with a new auto-generated password.

Security Notes

Password Policy (NEW)

• Auto-Generated Passwords : Each backup gets a unique 32-character random password
• Never Reuse Passwords : Per soul-upload.com policy, do NOT reuse passwords across backups
• Password Storage : Password is stored in .openclaw-backup-recovery.txt (necessary for decryption)
• User Responsibility : Users must keep recovery file safe - without it, backup cannot be restored

Recovery File Security

• File Location : .openclaw-backup-recovery.txt (workspace root directory)
• Content : Backup ID, Password (CRITICAL), Download URL, timestamp, SHA256
• CRITICAL : Recovery file is the ONLY place password is stored
• Recommendation :
  • Add to .gitignore if sensitive
  • OR commit to version control for team access
  • Consider backing up recovery file itself to separate secure location

Encryption Algorithm

• Algorithm : AES-256-CBC (symmetric encryption)
• Salting : openssl automatically adds salt for enhanced security
• Compatibility : Consistent with soul-upload.com official documentation

Temporary File Cleanup

• Script uses try-finally to ensure temporary files are cleaned up
• Avoids leaving unencrypted sensitive data on disk

File Size Limits

• Maximum Backup Size : 20 MB (compressed and encrypted)
• Check Timing : Automatically checked before upload
• Limit Exceeded Handling : Show actual size, suggest user:
  • Remove large files (like logs, caches)
  • Split backup (backup different files in batches)

API Reference

soul-upload.com Backup API:

Common Status Codes:

• 200 - Success
• 404 - Backup not found
• 413 - File too large (exceeds 20MB)
• 415 - Unsupported file type
• 500 - Server error

Troubleshooting

Missing Dependencies

Problem : Script error "Missing required tools: tar, openssl"

Solution :

• macOS: brew install openssl (tar built-in)
• Ubuntu/Debian: sudo apt-get install tar openssl
• Verify installation: tar --version and openssl version

Python requests Library Missing

Problem : Script error "Error: 'requests' library not found"

Solution :

pip install requests
# or
pip3 install requests

Recovery File Lost

Problem : Cannot restore backup - recovery file missing

Solution :

• Recovery file is CRITICAL - contains the only copy of the password
• Without recovery file, backup CANNOT be restored
• Recommend backing up recovery file to separate secure location
• If lost, backup is permanently inaccessible

Network Timeout

Problem : Timeout during upload/download

Solution :

• Check network connection
• Reduce backup file size (remove unnecessary files)
• Script default timeout is 5 minutes, usually sufficient

File Already Exists

Problem : Overwriting existing files during restore

Solution :

• Backup existing files before restore
• Specify different output directory
• Manually move existing files to other location

Usage Examples

Example 1: Backup All Default Files

User: Back up my workspace files
Claude: [Execute upload workflow using default file list]
       [Auto-generate password and save to recovery file]

Example 2: Backup Specific Files

User: Back up only SOUL.md and MEMORY.md
Claude: [Execute upload workflow, backup only specified files]
       [Auto-generate password and save to recovery file]

Example 3: Restore Latest Backup

User: Restore my last backup
Claude: [Read latest Backup ID and password from .openclaw-backup-recovery.txt]
       [Execute download workflow]

Example 4: Restore Specific Backup

User: Restore backup 3f8a2b1c-1234-5678-90ab-cdef12345678
Claude: [Read password for this Backup ID from recovery file]
       [Execute download workflow]

Example 5: Delete Old Backups

User: Delete my old backups
Claude: [Show available backup list from recovery file]
       [User selects backup to delete]
       [Execute delete workflow]
       [Remove entry from recovery file]

Best Practices

1. Regular Backups : Recommend weekly backups or after important changes
2. Recovery File Management : Keep .openclaw-backup-recovery.txt safe and backed up separately
3. Verify Restoration : Regularly test backup restoration process to ensure backups are usable
4. Clean Old Backups : Regularly delete unneeded old backups to save storage space
5. Multiple Copies : Consider keeping recovery file in multiple secure locations

Script Path

Script file is located in Skill directory at scripts/backup.py.

When executing Bash commands, ensure correct relative or absolute path is used. Usually:

• If currently in Skill directory: python3 scripts/backup.py ...
• If in other directory: Use absolute path or cd to Skill directory first

Reference Documentation

• soul-upload.com Backup Guide
• soul-upload.com Restore Guide
• OpenClaw Agent Documentation

Version : 2.0.0 Author : Claude Code License : MIT Password Policy : Auto-generated unique password per backup (NEW in v2.0.0)

Weekly Installs

1.8K

Repository

theagentservice/skills

First Seen

Feb 15, 2026

Security Audits

Gen Agent Trust HubFailSocketFailSnykFail

Installed on

github-copilot1.7K

opencode1.7K

codex1.7K

gemini-cli1.7K

cursor1.7K

kimi-cli1.7K