Skills workspace-sync

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

install

source · Clone the upstream repo

git clone https://github.com/openclaw/skills

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/openclaw/skills "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/ashbrener/openclaw-workspace-sync" ~/.claude/skills/clawdbot-skills-workspace-sync && rm -rf "$T"

OpenClaw · Install into ~/.openclaw/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/openclaw/skills "$T" && mkdir -p ~/.openclaw/skills && cp -r "$T/skills/ashbrener/openclaw-workspace-sync" ~/.openclaw/skills/clawdbot-skills-workspace-sync && rm -rf "$T"

manifest: skills/ashbrener/openclaw-workspace-sync/SKILL.md

source content

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 workspace to/from cloud
Back up workspace files
Check sync status
Fix sync issues
Send files to the agent workspace

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

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