workspace-sync

---

name: workspace-sync

description: Sync agent workspace with cloud storage (Dropbox, Google Drive, S3, etc.) using rclone.

metadata: {"openclaw":{"emoji":"☁️","requires":{"bins":["rclone"]}}}

---

# workspace-sync

Sync the agent workspace with cloud storage. `mode` is required — choose `mailbox` (inbox/outbox, safest), `mirror` (remote->local), or `bisync` (bidirectional, advanced).

Trigger

Use this skill when the user asks to:

Sync modes

| Mode | Direction | Description |

|------|-----------|-------------|

| `mailbox` (recommended) | Push + inbox/outbox | Workspace pushes to cloud; `_outbox` sends files up to the agent's `_inbox`. Safest. |

| `mirror` | Remote → Local | One-way: workspace mirrors down. Safe — local can never overwrite remote. |

| `bisync` | Bidirectional | Two-way sync. Powerful but requires careful setup. |

Mailbox mode

Each sync cycle: (1) pushes workspace to cloud excluding `_inbox/` and `_outbox/`, (2) drains cloud `_outbox/` into workspace `_inbox/` via `rclone move` (deletes from cloud after transfer). On startup, bootstraps `cloud:_outbox` and local `_inbox/`.

Users drop files in the local `_outbox/` folder (created by the cloud provider's desktop app). Files arrive in the agent's `_inbox/`. The agent or a skill processes them from there.

With `notifyOnInbox: true`, the agent is woken when files land in `_inbox`. A system event lists the new filenames so the agent can process them. Off by default — each notification costs an agent turn.

Mirror mode with ingest

With `ingest: true`, a local `inbox/` folder syncs one-way **up** to the remote workspace (additive only). For a more robust pattern, use `mailbox` mode instead.

Commands

Check sync status

openclaw workspace-sync status

Shows: provider, mode, last sync time, sync count, error count, running state.

Trigger manual sync

openclaw workspace-sync sync

In `mailbox` mode: pushes workspace and drains `_outbox`. In `mirror` mode: pulls latest from remote. In `bisync` mode: runs bidirectional sync.

Preview changes

openclaw workspace-sync sync --dry-run

One-way sync (explicit direction)

openclaw workspace-sync sync --direction pull   # remote -> local
openclaw workspace-sync sync --direction push   # local -> remote

Force re-establish bisync baseline (destructive)

openclaw workspace-sync sync --resync

**WARNING: `--resync` is destructive (bisync only).** It copies ALL files from both sides to make them identical — deleted files come back, and it transfers everything. Only use when you explicitly need to re-establish the bisync baseline. The plugin never auto-resyncs.

View remote files

openclaw workspace-sync list

Lists files in the configured cloud storage path.

Configuration

Workspace sync is configured via the plugin entry in `openclaw.json`. The preferred format uses nested `sync` and `backup` blocks (flat config at root level is also supported):

{
  "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"]
          }
        }
      }
    }
  }
}

Config keys

These keys live under `sync` in the nested format, or at the config root in flat format.

| Key | Default | Description |

|-----|---------|-------------|

| `provider` | `"off"` | `dropbox`, `gdrive`, `onedrive`, `s3`, `custom`, or `off` |

| `mode` | **required** | `mailbox` (inbox/outbox, safest), `mirror` (remote->local), or `bisync` (bidirectional) |

| `ingest` | `false` | Enable local inbox for sending files to the agent (mirror mode only) |

| `ingestPath` | `"inbox"` | Local subfolder name for ingestion |

| `notifyOnInbox` | `false` | Wake the agent when files arrive in `_inbox` (mailbox mode). Costs credits per notification. |

| `remotePath` | `"openclaw-share"` | Folder name in cloud storage |

| `localPath` | `"shared"` | Subfolder within workspace to sync |

| `interval` | `0` | Background sync interval in seconds (0 = manual only, min 60) |

| `timeout` | `1800` | Max seconds for a single sync operation (min 60) |

| `onSessionStart` | `false` | Sync when an agent session begins |

| `onSessionEnd` | `false` | Sync when an agent session ends |

| `conflictResolve` | `"newer"` | `newer`, `local`, or `remote` (bisync only) |

| `exclude` | `**/.DS_Store` | Glob patterns to exclude from sync |

Automatic sync

When configured, sync runs automatically:

Safety notes

Auto-recovery

Troubleshooting

"rclone not configured"

Run the setup wizard:

openclaw workspace-sync setup

"requires --resync" (bisync only)

Bisync state was lost. **Before running `--resync`, verify both sides are correct**:

openclaw workspace-sync sync --resync

Sync times out

Increase the `timeout` in your config (default is 1800 seconds / 30 min):

{ "timeout": 3600 }

Check rclone directly

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

Notes

Encrypted backups

Add a `backup` block to the plugin config for automated encrypted snapshots to your own cloud storage (S3, R2, B2, etc.). Backups stream directly (`tar | rclone rcat`) — no local temp files, so they work even when disk space is tight.

Backup commands

openclaw workspace-sync backup now        # Create a snapshot immediately
openclaw workspace-sync backup list       # List available snapshots
openclaw workspace-sync backup restore    # Restore latest snapshot
openclaw workspace-sync backup status     # Check backup service status

Backup config

{
  "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 }
  }
}

| Key | Default | Description |

|-----|---------|-------------|

| `enabled` | `false` | Enable scheduled backups |

| `provider` | parent provider | Cloud provider (can differ from sync provider) |

| `bucket` | — | S3/R2 bucket name |

| `prefix` | `""` | Path prefix within the bucket |

| `interval` | `86400` | Backup interval in seconds (clamped to min 300) |

| `encrypt` | `false` | AES-256 client-side encryption |

| `passphrase` | — | Encryption passphrase (use env var) |

| `include` | `["workspace", "config", "cron", "memory"]` | What to back up |

| `retain` | `7` | Keep N snapshots, or `{ daily: N, weekly: N }` |