workspace-sync

将 agent 工作区与云存储同步。mode 为必填项 —— 可选 mailbox（收件箱/发件箱，最安全）、mirror（远程 → 本地）或 bisync（双向同步，高级模式）。

触发场景

当用户提出以下请求时，使用该技能：

• 将工作区与云存储双向同步
• 备份工作区文件
• 检查同步状态
• 修复同步问题
• 向 agent 工作区发送文件

同步模式

Mailbox 模式

每次同步周期执行以下操作：(1) 将工作区内容推送至云端（排除 _inbox/ 和 _outbox/）；(2) 使用 rclone move 将云端 _outbox/ 中的文件移入工作区 _inbox/（传输完成后从云端删除）。启动时，会初始化云端 cloud:_outbox 和本地 _inbox/。

用户将文件放入本地 _outbox/ 文件夹（由云服务提供商桌面应用自动创建），这些文件将到达 agent 的 _inbox/。agent 或其他技能可从此处处理这些文件。

启用 notifyOnInbox: true 后，当文件进入 _inbox 时，agent 将被唤醒。系统事件将列出新增文件名，供 agent 处理。默认关闭 —— 每次通知均消耗一次 agent 调用次数。

启用 ingest 的 Mirror 模式

启用 ingest: true 后，本地 inbox/ 文件夹将单向 **上传** 至远程工作区（仅追加，不可删除）。如需更健壮的方案，请改用 mailbox 模式。

命令

检查同步状态

openclaw workspace-sync status

显示：云服务提供商、同步模式、上次同步时间、同步次数、错误次数、运行状态。

手动触发同步

openclaw workspace-sync sync

在 mailbox 模式下：推送工作区并清空 _outbox；在 mirror 模式下：从远程拉取最新内容；在 bisync 模式下：执行双向同步。

预览变更

openclaw workspace-sync sync --dry-run

单向同步（显式指定方向）

openclaw workspace-sync sync --direction pull   # 远程 → 本地
openclaw workspace-sync sync --direction push   # 本地 → 远程

强制重建 bisync 基线（破坏性操作）

openclaw workspace-sync sync --resync

警告：--resync 具有破坏性（仅限 bisync 模式）。 该操作会将双方所有文件完整复制一遍，使其完全一致 —— 已删除的文件将恢复，且全部内容均会被重新传输。仅当明确需要重建 bisync 基线时才使用。插件绝不会自动执行 resync。

查看远程文件

openclaw workspace-sync list

列出已配置的云存储路径中的文件。

配置

工作区同步通过 openclaw.json 中的插件条目进行配置。推荐格式采用嵌套的 sync 和 backup 块（也支持扁平化配置，即键值直接置于 config 根层级）：

{
  "plugins": {
    "entries": {
      "openclaw-workspace-sync": {
        "enabled": true,
        "config": {
          "sync": {
            "provider": "dropbox",
            "mode": "mailbox",
            "remotePath": "",
            "localPath": "/",
            "interval": 60,
            "timeout": 1800,
            "onSessionStart": true,
            "onSessionEnd": true,
            "exclude": [".git/**", "node_modules/**", "*.log"]
          }
        }
      }
    }
  }
}

配置项说明

以下键位于嵌套格式的 sync 对象下，或扁平化格式中直接位于 config 根层级。

自动同步

配置启用后，同步将自动执行：

• 会话启动时：推送工作区并清空发件箱（mailbox）、拉取最新内容（mirror）或执行双向同步（bisync）
• 会话结束时：在对话结束后同步变更
• 周期性定时：每隔 N 秒执行一次后台同步（不消耗 LLM Token）

安全须知

• Mailbox 模式最安全。 工作区向云端推送；用户通过 _outbox 发送文件。数据流永不重叠。
• Mirror 模式在设计上即为安全。 远程工作区具有权威性，本地仅为只读副本。
• Bisync 需谨慎配置。 双方必须保持状态一致。若状态丢失，需使用 --resync 强制重建，且将全量复制所有文件。
• 在容器平台（如 Fly.io、Railway）上，bisync 状态为临时性 —— 请改用 mailbox 或 mirror 模式。
• 修改配置时（如 remotePath、localPath、mode），请先禁用周期性同步，验证无误后再重新启用。

自动恢复机制

• 陈旧锁文件：检测到后将在重试前自动清除（超时 15 分钟的锁文件将被自动过期）
• 中断的同步任务：使用 --recover 和 --resilient 参数在中断后恢复（仅 bisync 支持）
• resync 永不自动触发：若 bisync 状态丢失，插件仅记录日志，但绝不会自动执行 resync

故障排查

“rclone not configured”

首先，通过操作系统包管理器安装 rclone：

# macOS
brew install rclone

# Debian/Ubuntu
sudo apt-get install rclone

# Fedora
sudo dnf install rclone

# Arch
sudo pacman -S rclone

# Alpine
sudo apk add rclone

其他平台请参考 https://rclone.org/install/

安全提示： 本技能绝不会将远程安装脚本管道至您的 shell。请始终通过操作系统包管理器安装 rclone，然后运行配置向导：

openclaw workspace-sync setup

配置向导仅尝试通过检测到的操作系统包管理器（brew/apt/dnf/yum/pacman/apk）安装 —— 绝不会使用 curl | sudo sh 方式。

“requires --resync”（仅 bisync）

bisync 状态已丢失。执行 --resync 前，请务必确认双方状态正确：

openclaw workspace-sync sync --resync

同步超时

在配置中增大 timeout 值（默认为 1800 秒 / 30 分钟）：

{ "timeout": 3600 }

直接检查 rclone

rclone lsd cloud:/
rclone ls cloud:openclaw-share

注意事项

• mode 为 必填项 —— 请设置为 mailbox（收件箱/发件箱，最安全）、mirror（远程 → 本地）或 bisync（双向同步）
• Mailbox 模式在启动时自动初始化云端 _outbox 和工作区 _inbox
• Bisync 面向需要双向同步能力的高级用户
• Ingest 收件箱（仅 mirror 模式）为仅追加模式 —— 无法删除远程文件
• 默认仅排除 **/.DS_Store —— 可在配置中自定义排除规则
• 同步操作在后台执行（不消耗 LLM Token）
• 所有 rclone 操作均以 info 级别记录日志，便于可观测性

加密备份

在插件配置中添加 backup 块，即可实现自动化的加密快照备份至您自己的云存储（S3、R2、B2 等）。备份通过流式方式（tar | rclone rcat）完成 —— 不生成本地临时文件，即使磁盘空间紧张亦可正常运行。

备份命令

openclaw workspace-sync backup now        # 立即创建快照
openclaw workspace-sync backup list       # 列出可用快照
openclaw workspace-sync backup restore    # 恢复最新快照
openclaw workspace-sync backup status     # 检查备份服务状态

备份配置

{
  "backup": {
    "enabled": true,
    "provider": "s3",
    "bucket": "my-backups",
    "prefix": "agent-name/",
    "interval": 86400,
    "encrypt": true,
    "passphrase": "${BACKUP_PASSPHRASE}",
    "include": ["workspace", "config", "cron", "memory"],
    "retain": { "daily": 7, "weekly": 4 }
  }
}