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:

On session start: Pushes workspace and drains outbox (mailbox), pulls latest (mirror), or runs bisync
On session end: Syncs changes after conversation ends
Periodic interval: Background sync every N seconds (no LLM cost)

Safety notes

Mailbox mode is the safest. Workspace pushes to cloud; users send files via _outbox. Streams never overlap.
Mirror mode is safe by design. Remote workspace is the authority. Local is a read-only copy.
Bisync requires careful setup. Both sides must agree. If state is lost, --resync is needed and it copies everything.
On container platforms (Fly.io, Railway), bisync state is ephemeral — use mailbox or mirror mode instead.
When changing config (remotePath, localPath, mode), disable periodic sync first, verify, then re-enable.

Auto-recovery

Stale lock files: Detected and cleared before retrying (lock files older than 15 min are expired automatically)
Interrupted syncs: Uses --recover and --resilient flags to resume after interruptions (bisync only)
Resync never automatic: If bisync state is lost, the plugin logs a message but does NOT auto-resync

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

mode is required — set mailbox (inbox/outbox, safest), mirror (remote→local), or bisync (bidirectional)
Mailbox mode bootstraps _outbox on cloud and _inbox on workspace at startup
Bisync is available for power users who need bidirectional sync
Ingest inbox (mirror mode only) is additive only — cannot delete remote files
Only **/.DS_Store excluded by default — add your own excludes in config
Sync operations run in background (no LLM tokens used)
All rclone activity is logged at info level for visibility

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 }`

workspace-sync

workspace-sync

Trigger

Sync modes