openclaw-workspace-sync 2.3.0 → 2.4.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +283 -331
- package/README.src.md +283 -331
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +88 -25
- package/dist/index.js.map +1 -1
- package/dist/rclone.d.ts.map +1 -1
- package/dist/rclone.js +8 -3
- package/dist/rclone.js.map +1 -1
- package/package.json +2 -2
package/README.src.md
CHANGED
|
@@ -1,31 +1,107 @@
|
|
|
1
|
-
# OpenClaw Workspace
|
|
1
|
+
# OpenClaw Workspace Sync & Backup Plugin
|
|
2
2
|
|
|
3
|
-
Sync your OpenClaw agent workspace
|
|
3
|
+
Sync and back up your OpenClaw agent workspace to cloud storage via [rclone](https://rclone.org/).
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
**Sync** your workspace to Dropbox, Google Drive, OneDrive, S3, or [70+ providers](https://rclone.org/overview/) with mailbox, mirror, or bisync modes. **Back up** your entire agent system — workspace, config, sessions, memory — as encrypted snapshots to S3, R2, B2, or any rclone backend.
|
|
6
6
|
|
|
7
|
-
##
|
|
7
|
+
## What's included
|
|
8
8
|
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
9
|
+
| Feature | What it does | Cost |
|
|
10
|
+
|---------|-------------|------|
|
|
11
|
+
| [**Sync**](#sync) | Live mirror of your workspace to/from cloud storage. Three modes: mailbox (safest), mirror, bisync. | Zero LLM cost — pure file ops |
|
|
12
|
+
| [**Encrypted Backup**](#encrypted-backups) | Streaming encrypted snapshots of your entire agent system to your own bucket. Automatic retention. | Zero LLM cost, zero extra disk |
|
|
13
|
+
|
|
14
|
+
Both features use rclone under the hood and share provider credentials. You can use sync alone, backup alone, or both together with different providers — e.g. sync to Dropbox for daily access, backup to R2 for disaster recovery.
|
|
15
|
+
|
|
16
|
+
## Install
|
|
17
|
+
|
|
18
|
+
```bash
|
|
19
|
+
openclaw plugins install openclaw-workspace-sync
|
|
20
|
+
```
|
|
12
21
|
|
|
13
|
-
|
|
22
|
+
Or clone into your extensions directory:
|
|
14
23
|
|
|
15
|
-
|
|
24
|
+
```bash
|
|
25
|
+
cd ~/.openclaw/extensions
|
|
26
|
+
git clone https://github.com/ashbrener/openclaw-workspace-sync workspace-sync
|
|
27
|
+
cd workspace-sync && npm install --omit=dev
|
|
28
|
+
```
|
|
16
29
|
|
|
17
|
-
##
|
|
30
|
+
## Quick start
|
|
31
|
+
|
|
32
|
+
```bash
|
|
33
|
+
# Interactive setup wizard (recommended)
|
|
34
|
+
openclaw workspace-sync setup
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
The setup wizard guides you through:
|
|
38
|
+
1. Checking/installing rclone
|
|
39
|
+
2. Selecting cloud provider
|
|
40
|
+
3. Choosing sync mode
|
|
41
|
+
4. Dropbox app folder option (for scoped access)
|
|
42
|
+
5. Background sync interval
|
|
43
|
+
6. OAuth authorization
|
|
44
|
+
7. First sync
|
|
45
|
+
|
|
46
|
+
Or configure manually — see [Configuration](#configuration) below.
|
|
47
|
+
|
|
48
|
+
## Configuration
|
|
49
|
+
|
|
50
|
+
Add to your `openclaw.json`. The `sync` and `backup` blocks are independent — use one or both:
|
|
51
|
+
|
|
52
|
+
```json
|
|
53
|
+
{
|
|
54
|
+
"plugins": {
|
|
55
|
+
"entries": {
|
|
56
|
+
"openclaw-workspace-sync": {
|
|
57
|
+
"enabled": true,
|
|
58
|
+
"config": {
|
|
59
|
+
"sync": {
|
|
60
|
+
"provider": "dropbox",
|
|
61
|
+
"mode": "mailbox",
|
|
62
|
+
"remotePath": "",
|
|
63
|
+
"interval": 180,
|
|
64
|
+
"onSessionStart": true,
|
|
65
|
+
"exclude": [".git/**", "node_modules/**", "*.log"]
|
|
66
|
+
},
|
|
67
|
+
"backup": {
|
|
68
|
+
"enabled": true,
|
|
69
|
+
"provider": "s3",
|
|
70
|
+
"bucket": "my-backups",
|
|
71
|
+
"prefix": "habibi/",
|
|
72
|
+
"interval": 86400,
|
|
73
|
+
"encrypt": true,
|
|
74
|
+
"passphrase": "${BACKUP_PASSPHRASE}",
|
|
75
|
+
"include": ["workspace", "config", "cron", "memory"],
|
|
76
|
+
"retain": 7
|
|
77
|
+
}
|
|
78
|
+
}
|
|
79
|
+
}
|
|
80
|
+
}
|
|
81
|
+
}
|
|
82
|
+
}
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
> **Flat format still works.** Putting `provider`, `mode`, etc. at the config root (without `sync`) is supported for backwards compatibility. The nested `{ sync, backup }` format is recommended for clarity.
|
|
86
|
+
|
|
87
|
+
---
|
|
88
|
+
|
|
89
|
+
## Sync
|
|
90
|
+
|
|
91
|
+
Live workspace mirroring via rclone. The remote gateway workspace is the **source of truth**. Changes made by the agent flow down to your local machine through cloud storage. You can send files to the agent through an optional inbox.
|
|
92
|
+
|
|
93
|
+
<p align="center">
|
|
94
|
+
<img src="https://raw.githubusercontent.com/ashbrener/openclaw-workspace-sync/main/docs/how-it-works.png" alt="How it works — Local Machine syncs to Cloud Provider syncs to Remote Gateway" width="600" />
|
|
95
|
+
</p>
|
|
18
96
|
|
|
19
97
|
<p align="center">
|
|
20
98
|
<img src="https://raw.githubusercontent.com/ashbrener/openclaw-workspace-sync/main/docs/architecture.png" alt="Plugin architecture — CLI, Hooks, and Sync Manager feed into rclone wrapper" width="600" />
|
|
21
99
|
</p>
|
|
22
100
|
|
|
23
|
-
|
|
101
|
+
### Sync modes (breaking change in v2.0)
|
|
24
102
|
|
|
25
103
|
**`mode` is now required.** Previous versions used bidirectional bisync implicitly. Starting with v2.0, you must explicitly set `"mode"` in your config. The plugin will refuse to start and log an error until `mode` is set. This prevents accidental data loss from an unexpected sync direction.
|
|
26
104
|
|
|
27
|
-
The plugin supports three sync modes. Choose the one that fits your workflow:
|
|
28
|
-
|
|
29
105
|
| Mode | Direction | Description |
|
|
30
106
|
|------|-----------|-------------|
|
|
31
107
|
| `mailbox` | Push + inbox/outbox | Workspace pushes to cloud; users drop files in `_outbox` to send them to the agent. **Safest.** |
|
|
@@ -34,7 +110,7 @@ The plugin supports three sync modes. Choose the one that fits your workflow:
|
|
|
34
110
|
|
|
35
111
|
**Upgrading from a previous version?** If you were using bisync before, add `"mode": "bisync"` to your config to preserve the existing behavior. For the safest option, use `"mode": "mailbox"`.
|
|
36
112
|
|
|
37
|
-
|
|
113
|
+
#### `mailbox` mode (recommended)
|
|
38
114
|
|
|
39
115
|
The agent workspace is the source of truth. Each sync cycle:
|
|
40
116
|
|
|
@@ -72,7 +148,7 @@ On startup, the plugin bootstraps both directories:
|
|
|
72
148
|
|
|
73
149
|
Because the push explicitly excludes `_inbox/**` and `_outbox/**`, there is no risk of sync loops or accidental overwrites. Files only flow in one direction through each channel.
|
|
74
150
|
|
|
75
|
-
|
|
151
|
+
##### Inbox notifications (optional)
|
|
76
152
|
|
|
77
153
|
By default, mailbox mode is silent — files land in `_inbox` without waking the agent. This keeps costs at zero.
|
|
78
154
|
|
|
@@ -89,13 +165,12 @@ This wakes the agent on its next heartbeat. The agent sees the message and can p
|
|
|
89
165
|
"mode": "mailbox",
|
|
90
166
|
"provider": "dropbox",
|
|
91
167
|
"remotePath": "",
|
|
92
|
-
"localPath": "/",
|
|
93
168
|
"interval": 180,
|
|
94
169
|
"notifyOnInbox": true
|
|
95
170
|
}
|
|
96
171
|
```
|
|
97
172
|
|
|
98
|
-
|
|
173
|
+
#### `mirror` mode
|
|
99
174
|
|
|
100
175
|
The agent workspace is the source of truth. Every sync cycle copies the latest workspace state down to your local folder. Local files outside the workspace are never sent up.
|
|
101
176
|
|
|
@@ -117,7 +192,7 @@ flowchart LR
|
|
|
117
192
|
|
|
118
193
|
This is safe: even if something goes wrong, only your local copy is affected — the workspace stays untouched.
|
|
119
194
|
|
|
120
|
-
|
|
195
|
+
##### `ingest` option (mirror mode only)
|
|
121
196
|
|
|
122
197
|
Want to send files to the agent while using mirror mode? Enable the `ingest` option. This creates a local `inbox/` folder (sibling to the sync folder) that syncs one-way **up** to the workspace. Drop a file in the inbox — it appears on the remote workspace. The inbox is separate from the mirror, so there is no risk of overwriting workspace files.
|
|
123
198
|
|
|
@@ -133,7 +208,7 @@ When enabled, a local `inbox/` folder syncs its contents to `<remotePath>/inbox/
|
|
|
133
208
|
|
|
134
209
|
> For a more robust file-exchange pattern, consider `mailbox` mode instead. Mailbox uses `rclone move` to drain files (deleting from the source after transfer), which prevents duplicates and is easier to reason about.
|
|
135
210
|
|
|
136
|
-
|
|
211
|
+
#### `bisync` mode (advanced)
|
|
137
212
|
|
|
138
213
|
Full bidirectional sync using rclone bisync. Changes on either side propagate to the other.
|
|
139
214
|
|
|
@@ -164,136 +239,7 @@ Use this only if you understand the trade-offs:
|
|
|
164
239
|
|
|
165
240
|
If you are running on a container platform, `mailbox` mode is strongly recommended.
|
|
166
241
|
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
Getting the initial state right prevents data loss. Each mode has different requirements:
|
|
170
|
-
|
|
171
|
-
### `mailbox` mode — starting state
|
|
172
|
-
|
|
173
|
-
The first sync **pushes** your local workspace to the cloud. This means rclone makes cloud match local exactly — any files on cloud that don't exist locally will be **deleted**.
|
|
174
|
-
|
|
175
|
-
**Recommended starting state:** Local workspace is the source of truth (the agent has been writing here), or local and remote are already identical.
|
|
176
|
-
|
|
177
|
-
**If remote is the source of truth** (e.g. you've been syncing manually or switching from another mode), pull first:
|
|
178
|
-
|
|
179
|
-
```bash
|
|
180
|
-
rclone sync <remote>:<path> /data/workspace/ --config <config-path> \
|
|
181
|
-
--exclude '**/.DS_Store' --exclude '**/.git/**' \
|
|
182
|
-
--exclude '**/__pycache__/**' --exclude '**/node_modules/**' \
|
|
183
|
-
--verbose
|
|
184
|
-
```
|
|
185
|
-
|
|
186
|
-
Then verify local matches remote before enabling the plugin.
|
|
187
|
-
|
|
188
|
-
### `mirror` mode — starting state
|
|
189
|
-
|
|
190
|
-
The first sync **pulls** from cloud to local. Local can be empty, stale, or corrupted — the pull simply overwrites it. **No preparation needed.**
|
|
191
|
-
|
|
192
|
-
### `bisync` mode — starting state
|
|
193
|
-
|
|
194
|
-
The first sync requires `--resync`, which copies everything from both sides to the other. Any stale or unwanted files on either side will propagate.
|
|
195
|
-
|
|
196
|
-
**Recommended starting state:** Both sides are identical, or one side is empty and the other has the data you want. Verify both before running `--resync`.
|
|
197
|
-
|
|
198
|
-
### General first-sync checklist
|
|
199
|
-
|
|
200
|
-
1. Run a `--dry-run` first to see what would happen: `openclaw workspace-sync sync --dry-run`
|
|
201
|
-
2. Check the output for unexpected deletions
|
|
202
|
-
3. If everything looks right, run the actual sync
|
|
203
|
-
4. Only then enable periodic sync (`interval` in config)
|
|
204
|
-
|
|
205
|
-
> For maintenance, recovery, and common problems, see [TROUBLESHOOTING.md](./TROUBLESHOOTING.md).
|
|
206
|
-
|
|
207
|
-
## Setup sequence
|
|
208
|
-
|
|
209
|
-
Getting sync right depends on doing things in the right order. Follow these steps:
|
|
210
|
-
|
|
211
|
-
1. **Configure the plugin** in `openclaw.json` with your provider credentials and `mode`
|
|
212
|
-
2. **Verify the remote** is accessible: `openclaw workspace-sync status`
|
|
213
|
-
3. **Run a dry-run first** to see what would happen: `openclaw workspace-sync sync --dry-run`
|
|
214
|
-
4. **Run the first sync**: `openclaw workspace-sync sync`
|
|
215
|
-
- In `mailbox` mode, this pushes the workspace and drains the `_outbox`
|
|
216
|
-
- In `mirror` mode, this pulls the current workspace down
|
|
217
|
-
- In `bisync` mode, this requires `--resync` to establish the baseline
|
|
218
|
-
5. **Enable periodic sync** by setting `interval` in your config
|
|
219
|
-
|
|
220
|
-
Take care when changing config (switching `remotePath`, `localPath`, or `mode`) — always disable periodic sync first, verify the new paths, then re-enable.
|
|
221
|
-
|
|
222
|
-
## Install
|
|
223
|
-
|
|
224
|
-
```bash
|
|
225
|
-
openclaw plugins install openclaw-workspace-sync
|
|
226
|
-
```
|
|
227
|
-
|
|
228
|
-
Or clone into your extensions directory:
|
|
229
|
-
|
|
230
|
-
```bash
|
|
231
|
-
cd ~/.openclaw/extensions
|
|
232
|
-
git clone https://github.com/ashbrener/openclaw-workspace-sync workspace-sync
|
|
233
|
-
cd workspace-sync && npm install --omit=dev
|
|
234
|
-
```
|
|
235
|
-
|
|
236
|
-
## Quick start
|
|
237
|
-
|
|
238
|
-
```bash
|
|
239
|
-
# Interactive setup wizard (recommended)
|
|
240
|
-
openclaw workspace-sync setup
|
|
241
|
-
```
|
|
242
|
-
|
|
243
|
-
The setup wizard guides you through:
|
|
244
|
-
1. Checking/installing rclone
|
|
245
|
-
2. Selecting cloud provider
|
|
246
|
-
3. Choosing sync mode
|
|
247
|
-
4. Dropbox app folder option (for scoped access)
|
|
248
|
-
5. Background sync interval
|
|
249
|
-
6. OAuth authorization
|
|
250
|
-
7. First sync
|
|
251
|
-
|
|
252
|
-
Or configure manually — see [Configuration](#configuration) below.
|
|
253
|
-
|
|
254
|
-
## Configuration
|
|
255
|
-
|
|
256
|
-
Add to your `openclaw.json`:
|
|
257
|
-
|
|
258
|
-
```json
|
|
259
|
-
{
|
|
260
|
-
"plugins": {
|
|
261
|
-
"entries": {
|
|
262
|
-
"openclaw-workspace-sync": {
|
|
263
|
-
"enabled": true,
|
|
264
|
-
"config": {
|
|
265
|
-
"sync": {
|
|
266
|
-
"provider": "dropbox",
|
|
267
|
-
"mode": "mailbox",
|
|
268
|
-
"remotePath": "",
|
|
269
|
-
"localPath": "/",
|
|
270
|
-
"interval": 60,
|
|
271
|
-
"timeout": 1800,
|
|
272
|
-
"onSessionStart": true,
|
|
273
|
-
"onSessionEnd": false,
|
|
274
|
-
"exclude": [".git/**", "node_modules/**", "*.log"]
|
|
275
|
-
},
|
|
276
|
-
"backup": {
|
|
277
|
-
"enabled": true,
|
|
278
|
-
"provider": "s3",
|
|
279
|
-
"bucket": "my-backups",
|
|
280
|
-
"prefix": "habibi/",
|
|
281
|
-
"interval": 86400,
|
|
282
|
-
"encrypt": true,
|
|
283
|
-
"passphrase": "${BACKUP_PASSPHRASE}",
|
|
284
|
-
"include": ["workspace", "config", "cron", "memory"],
|
|
285
|
-
"retain": 7
|
|
286
|
-
}
|
|
287
|
-
}
|
|
288
|
-
}
|
|
289
|
-
}
|
|
290
|
-
}
|
|
291
|
-
}
|
|
292
|
-
```
|
|
293
|
-
|
|
294
|
-
> **Flat format still works.** Putting `provider`, `mode`, etc. at the config root (without `sync`) is supported for backwards compatibility. The nested `{ sync, backup }` format is recommended for clarity.
|
|
295
|
-
|
|
296
|
-
### Config reference
|
|
242
|
+
### Sync config reference
|
|
297
243
|
|
|
298
244
|
| Key | Type | Default | Description |
|
|
299
245
|
|-----|------|---------|-------------|
|
|
@@ -303,7 +249,7 @@ Add to your `openclaw.json`:
|
|
|
303
249
|
| `ingestPath` | string | `"inbox"` | Local subfolder name for ingestion (relative to `localPath`) |
|
|
304
250
|
| `notifyOnInbox` | boolean | `false` | Wake the agent when files arrive in `_inbox` (mailbox mode). Off by default — enabling this costs LLM credits per notification. |
|
|
305
251
|
| `remotePath` | string | `"openclaw-share"` | Folder name in cloud storage |
|
|
306
|
-
| `localPath` | string | `"
|
|
252
|
+
| `localPath` | string | `""` (workspace root) | Relative subfolder within the workspace to sync. Defaults to the workspace root (e.g. `/data/workspace`). Must be a relative path — absolute paths like `"/"` are rejected. Set to a subfolder name like `"shared"` to sync only that directory. |
|
|
307
253
|
| `interval` | number | `0` | Background sync interval in seconds (0 = manual only, min 60) |
|
|
308
254
|
| `timeout` | number | `1800` | Max seconds for a single rclone sync operation (min 60) |
|
|
309
255
|
| `onSessionStart` | boolean | `false` | Sync when an agent session begins |
|
|
@@ -316,93 +262,7 @@ Add to your `openclaw.json`:
|
|
|
316
262
|
|
|
317
263
|
Default excludes: `**/.DS_Store`
|
|
318
264
|
|
|
319
|
-
###
|
|
320
|
-
|
|
321
|
-
**Dropbox with app folder (recommended for security):**
|
|
322
|
-
|
|
323
|
-
```json
|
|
324
|
-
{
|
|
325
|
-
"provider": "dropbox",
|
|
326
|
-
"remotePath": "",
|
|
327
|
-
"dropbox": {
|
|
328
|
-
"appFolder": true,
|
|
329
|
-
"appKey": "your-app-key",
|
|
330
|
-
"appSecret": "your-app-secret",
|
|
331
|
-
"token": "{\"access_token\":\"...\"}"
|
|
332
|
-
}
|
|
333
|
-
}
|
|
334
|
-
```
|
|
335
|
-
|
|
336
|
-
With `appFolder: true`, set `remotePath` to `""`. The app folder root is your sync root — do not repeat the app folder name in `remotePath` or rclone will fail with "directory not found."
|
|
337
|
-
|
|
338
|
-
**Google Drive:**
|
|
339
|
-
|
|
340
|
-
```json
|
|
341
|
-
{
|
|
342
|
-
"provider": "gdrive",
|
|
343
|
-
"remotePath": "openclaw-sync",
|
|
344
|
-
"gdrive": {
|
|
345
|
-
"token": "{\"access_token\":\"...\"}",
|
|
346
|
-
"teamDrive": "0ABcDeFgHiJ",
|
|
347
|
-
"rootFolderId": "folder-id"
|
|
348
|
-
}
|
|
349
|
-
}
|
|
350
|
-
```
|
|
351
|
-
|
|
352
|
-
`teamDrive` and `rootFolderId` are optional — omit them for personal Google Drive.
|
|
353
|
-
|
|
354
|
-
**OneDrive:**
|
|
355
|
-
|
|
356
|
-
```json
|
|
357
|
-
{
|
|
358
|
-
"provider": "onedrive",
|
|
359
|
-
"remotePath": "openclaw-sync",
|
|
360
|
-
"onedrive": {
|
|
361
|
-
"token": "{\"access_token\":\"...\"}",
|
|
362
|
-
"driveId": "drive-id",
|
|
363
|
-
"driveType": "business"
|
|
364
|
-
}
|
|
365
|
-
}
|
|
366
|
-
```
|
|
367
|
-
|
|
368
|
-
`driveType` can be `personal`, `business`, or `sharepoint`. Both fields are optional.
|
|
369
|
-
|
|
370
|
-
**S3 / Cloudflare R2 / Minio:**
|
|
371
|
-
|
|
372
|
-
```json
|
|
373
|
-
{
|
|
374
|
-
"provider": "s3",
|
|
375
|
-
"remotePath": "openclaw-sync",
|
|
376
|
-
"s3": {
|
|
377
|
-
"endpoint": "https://s3.us-east-1.amazonaws.com",
|
|
378
|
-
"bucket": "your-bucket",
|
|
379
|
-
"region": "us-east-1",
|
|
380
|
-
"accessKeyId": "AKID...",
|
|
381
|
-
"secretAccessKey": "SECRET..."
|
|
382
|
-
}
|
|
383
|
-
}
|
|
384
|
-
```
|
|
385
|
-
|
|
386
|
-
**Any rclone backend (SFTP, B2, Mega, pCloud, etc.):**
|
|
387
|
-
|
|
388
|
-
```json
|
|
389
|
-
{
|
|
390
|
-
"provider": "custom",
|
|
391
|
-
"remotePath": "openclaw-sync",
|
|
392
|
-
"custom": {
|
|
393
|
-
"rcloneType": "sftp",
|
|
394
|
-
"rcloneOptions": {
|
|
395
|
-
"host": "example.com",
|
|
396
|
-
"user": "deploy",
|
|
397
|
-
"key_file": "/path/to/key"
|
|
398
|
-
}
|
|
399
|
-
}
|
|
400
|
-
}
|
|
401
|
-
```
|
|
402
|
-
|
|
403
|
-
The `custom` provider accepts any [rclone backend type](https://rclone.org/overview/) and passes `rcloneOptions` directly to the rclone config. This gives you config-driven access to all 70+ providers without manually editing `rclone.conf`.
|
|
404
|
-
|
|
405
|
-
## CLI commands
|
|
265
|
+
### Sync CLI commands
|
|
406
266
|
|
|
407
267
|
```bash
|
|
408
268
|
# Interactive setup wizard
|
|
@@ -432,9 +292,9 @@ openclaw workspace-sync authorize --provider gdrive
|
|
|
432
292
|
openclaw workspace-sync list
|
|
433
293
|
```
|
|
434
294
|
|
|
435
|
-
|
|
295
|
+
### Auto-sync
|
|
436
296
|
|
|
437
|
-
|
|
297
|
+
#### Session hooks
|
|
438
298
|
|
|
439
299
|
Sync automatically when sessions start or end. These run during existing agent activity and incur zero LLM cost:
|
|
440
300
|
|
|
@@ -445,7 +305,7 @@ Sync automatically when sessions start or end. These run during existing agent a
|
|
|
445
305
|
}
|
|
446
306
|
```
|
|
447
307
|
|
|
448
|
-
|
|
308
|
+
#### Periodic background sync
|
|
449
309
|
|
|
450
310
|
Set `interval` to enable automatic background sync (in seconds):
|
|
451
311
|
|
|
@@ -460,72 +320,54 @@ The gateway runs sync in the background at this interval. Minimum interval is 60
|
|
|
460
320
|
|
|
461
321
|
In `mailbox` mode, periodic sync pushes the workspace to the cloud and drains the `_outbox`. In `mirror` mode, periodic sync pulls the latest workspace state down to local. In `bisync` mode, it runs a full bidirectional sync.
|
|
462
322
|
|
|
463
|
-
|
|
323
|
+
#### External cron (alternative)
|
|
464
324
|
|
|
465
325
|
```bash
|
|
466
326
|
# Add to crontab (crontab -e)
|
|
467
327
|
*/5 * * * * openclaw workspace-sync sync >> /var/log/openclaw-sync.log 2>&1
|
|
468
328
|
```
|
|
469
329
|
|
|
470
|
-
|
|
330
|
+
### Before your first sync
|
|
471
331
|
|
|
472
|
-
|
|
473
|
-
|----------|-------------|-------------|---------------|
|
|
474
|
-
| Dropbox | `dropbox` | OAuth token | Full (token, appKey, appSecret, appFolder) |
|
|
475
|
-
| Google Drive | `gdrive` | OAuth token | Full (token, teamDrive, rootFolderId) |
|
|
476
|
-
| OneDrive | `onedrive` | OAuth token | Full (token, driveId, driveType) |
|
|
477
|
-
| S3/R2/Minio | `s3` | Access keys | Full (endpoint, bucket, region, credentials) |
|
|
478
|
-
| Any rclone backend | `custom` | Varies | Full (rcloneType + rcloneOptions) |
|
|
479
|
-
|
|
480
|
-
All providers are fully config-driven — no manual `rclone.conf` editing needed. The `custom` provider gives access to all [70+ rclone backends](https://rclone.org/overview/) (SFTP, B2, Mega, pCloud, Azure Blob, etc.).
|
|
332
|
+
Getting the initial state right prevents data loss. Each mode has different requirements:
|
|
481
333
|
|
|
482
|
-
|
|
334
|
+
#### `mailbox` mode — starting state
|
|
483
335
|
|
|
484
|
-
|
|
336
|
+
The first sync **pushes** your local workspace to the cloud. This means rclone makes cloud match local exactly — any files on cloud that don't exist locally will be **deleted**.
|
|
485
337
|
|
|
486
|
-
|
|
487
|
-
# 1. Authorize with your cloud provider
|
|
488
|
-
openclaw workspace-sync authorize --provider dropbox
|
|
338
|
+
**Recommended starting state:** Local workspace is the source of truth (the agent has been writing here), or local and remote are already identical.
|
|
489
339
|
|
|
490
|
-
|
|
491
|
-
openclaw workspace-sync sync --dry-run
|
|
340
|
+
**If remote is the source of truth** (e.g. you've been syncing manually or switching from another mode), pull first:
|
|
492
341
|
|
|
493
|
-
|
|
494
|
-
|
|
342
|
+
```bash
|
|
343
|
+
rclone sync <remote>:<path> /data/workspace/ --config <config-path> \
|
|
344
|
+
--exclude '**/.DS_Store' --exclude '**/.git/**' \
|
|
345
|
+
--exclude '**/__pycache__/**' --exclude '**/node_modules/**' \
|
|
346
|
+
--verbose
|
|
495
347
|
```
|
|
496
348
|
|
|
497
|
-
|
|
349
|
+
Then verify local matches remote before enabling the plugin.
|
|
498
350
|
|
|
499
|
-
|
|
351
|
+
#### `mirror` mode — starting state
|
|
500
352
|
|
|
501
|
-
|
|
353
|
+
The first sync **pulls** from cloud to local. Local can be empty, stale, or corrupted — the pull simply overwrites it. **No preparation needed.**
|
|
502
354
|
|
|
503
|
-
|
|
504
|
-
2. Click **Create app** > **Scoped access** > **App folder**
|
|
505
|
-
3. Name it (e.g., `openclaw-sync`)
|
|
506
|
-
4. In **Settings** tab, add a **Redirect URI**: `http://localhost:53682/`
|
|
507
|
-
- This is required for rclone's OAuth flow to work. Without it, Dropbox returns "Invalid redirect_uri" during authorization.
|
|
508
|
-
5. In **Permissions** tab, enable:
|
|
509
|
-
- `files.metadata.read` / `files.metadata.write`
|
|
510
|
-
- `files.content.read` / `files.content.write`
|
|
511
|
-
6. Copy **App key** and **App secret** from Settings
|
|
355
|
+
#### `bisync` mode — starting state
|
|
512
356
|
|
|
513
|
-
|
|
357
|
+
The first sync requires `--resync`, which copies everything from both sides to the other. Any stale or unwanted files on either side will propagate.
|
|
514
358
|
|
|
515
|
-
|
|
516
|
-
- Token only accesses one folder, not your entire Dropbox
|
|
517
|
-
- If token is compromised, blast radius is limited
|
|
518
|
-
- Clean separation — sync folder lives under `Apps/<your-app-name>/`
|
|
359
|
+
**Recommended starting state:** Both sides are identical, or one side is empty and the other has the data you want. Verify both before running `--resync`.
|
|
519
360
|
|
|
520
|
-
|
|
361
|
+
#### General first-sync checklist
|
|
521
362
|
|
|
522
|
-
|
|
363
|
+
1. Run a `--dry-run` first to see what would happen: `openclaw workspace-sync sync --dry-run`
|
|
364
|
+
2. Check the output for unexpected deletions
|
|
365
|
+
3. If everything looks right, run the actual sync
|
|
366
|
+
4. Only then enable periodic sync (`interval` in config)
|
|
523
367
|
|
|
524
|
-
|
|
525
|
-
- **Use `exclude` patterns liberally** — skip `node_modules`, `.git`, `__pycache__`, build output, and anything you don't need synced. Fewer files = fewer API calls.
|
|
526
|
-
- **If you see `too_many_requests` errors** in the logs, increase the interval and add more excludes.
|
|
368
|
+
> For maintenance, recovery, and common problems, see [TROUBLESHOOTING.md](./TROUBLESHOOTING.md).
|
|
527
369
|
|
|
528
|
-
|
|
370
|
+
### Sync safety
|
|
529
371
|
|
|
530
372
|
Cloud sync involves two copies of your data. When things go wrong, one side can overwrite the other. Here is what to keep in mind:
|
|
531
373
|
|
|
@@ -536,6 +378,7 @@ Cloud sync involves two copies of your data. When things go wrong, one side can
|
|
|
536
378
|
**Bisync requires both sides to agree.** Bisync tracks what changed since the last sync. If that tracking state is lost (deploy, disk wipe, moving to a new machine), rclone does not know what changed and requires a `--resync`. A resync copies everything from both sides — if one side has stale or unwanted files, they propagate to the other.
|
|
537
379
|
|
|
538
380
|
**Common pitfalls to avoid:**
|
|
381
|
+
- Setting `localPath` to an absolute path like `"/"` — this syncs your entire filesystem, not your workspace. The plugin now rejects absolute paths with a clear error. Use `""` for the workspace root or a relative subfolder like `"shared"`.
|
|
539
382
|
- Changing `remotePath` or `localPath` while periodic sync is enabled
|
|
540
383
|
- Running `--resync` without checking both sides first
|
|
541
384
|
- Using `bisync` on container platforms where state is ephemeral
|
|
@@ -545,7 +388,7 @@ Cloud sync involves two copies of your data. When things go wrong, one side can
|
|
|
545
388
|
|
|
546
389
|
> For recovery procedures, mode switching, and maintenance tips, see [TROUBLESHOOTING.md](./TROUBLESHOOTING.md).
|
|
547
390
|
|
|
548
|
-
|
|
391
|
+
#### Important: `--resync` is destructive (bisync only)
|
|
549
392
|
|
|
550
393
|
**Never use `--resync` unless you know exactly what it does.** The `--resync` flag tells rclone to throw away its knowledge of what has changed and do a full reconciliation — it copies every file that exists on either side to the other side. This means:
|
|
551
394
|
|
|
@@ -560,15 +403,15 @@ Normal bisync (without `--resync`) only transfers files that changed since the l
|
|
|
560
403
|
openclaw workspace-sync sync --resync
|
|
561
404
|
```
|
|
562
405
|
|
|
563
|
-
|
|
406
|
+
### Sync troubleshooting
|
|
564
407
|
|
|
565
|
-
|
|
408
|
+
#### Token expired
|
|
566
409
|
|
|
567
410
|
```bash
|
|
568
411
|
openclaw workspace-sync authorize
|
|
569
412
|
```
|
|
570
413
|
|
|
571
|
-
|
|
414
|
+
#### Conflicts (bisync only)
|
|
572
415
|
|
|
573
416
|
Files modified on both sides get a `.conflict` suffix. The winner is determined by `conflictResolve` (default: `newer`). To find conflict files:
|
|
574
417
|
|
|
@@ -576,7 +419,7 @@ Files modified on both sides get a `.conflict` suffix. The winner is determined
|
|
|
576
419
|
find <workspace>/shared -name "*.conflict"
|
|
577
420
|
```
|
|
578
421
|
|
|
579
|
-
|
|
422
|
+
#### Stale lock files
|
|
580
423
|
|
|
581
424
|
The plugin automatically handles stale rclone lock files. If a sync is interrupted (timeout, crash, kill), the next run detects the stale lock, clears it, and retries. Lock files older than 15 minutes are treated as expired by rclone's `--max-lock` flag.
|
|
582
425
|
|
|
@@ -586,7 +429,7 @@ If you still see lock errors, you can manually clear them:
|
|
|
586
429
|
rclone deletefile ~/.cache/rclone/bisync/<lockfile>.lck
|
|
587
430
|
```
|
|
588
431
|
|
|
589
|
-
|
|
432
|
+
#### Sync times out
|
|
590
433
|
|
|
591
434
|
Increase the `timeout` config (in seconds). The default is 1800 (30 min). For large workspaces:
|
|
592
435
|
|
|
@@ -596,28 +439,21 @@ Increase the `timeout` config (in seconds). The default is 1800 (30 min). For la
|
|
|
596
439
|
}
|
|
597
440
|
```
|
|
598
441
|
|
|
599
|
-
|
|
442
|
+
#### Permission errors
|
|
600
443
|
|
|
601
444
|
```bash
|
|
602
445
|
chmod -R 755 <workspace>/shared
|
|
603
446
|
```
|
|
604
447
|
|
|
605
|
-
|
|
606
|
-
|
|
607
|
-
If you are running OpenClaw on a cloud container (Fly.io, Railway, Render) or a VPS:
|
|
448
|
+
#### Dropbox rate limiting
|
|
608
449
|
|
|
609
|
-
|
|
610
|
-
- **Enable daily volume snapshots.** Most cloud providers offer automated snapshots (Fly.io does this by default with 5-day retention). If something goes wrong — a bad sync, accidental deletion, or a failed reorganization — a recent snapshot lets you restore in minutes instead of rebuilding from scratch.
|
|
611
|
-
- **Test your restore process.** A backup you have never restored is a backup you do not have. Create a volume from a snapshot at least once to confirm the process works and you know the steps.
|
|
612
|
-
|
|
613
|
-
These recommendations apply regardless of whether you use this plugin. Cloud sync adds convenience but is not a substitute for proper backups.
|
|
450
|
+
Dropbox enforces API rate limits (`too_many_requests`). If your workspace has many files (10k+), each sync cycle can consume a large number of API calls just for checking. To avoid hitting limits:
|
|
614
451
|
|
|
615
|
-
|
|
452
|
+
- **Set `interval` high enough** for the sync to complete between cycles. A workspace with ~40k files takes ~2 minutes to scan. An `interval` of 180 (3 min) is the minimum; 300 (5 min) is safer.
|
|
453
|
+
- **Use `exclude` patterns liberally** — skip `node_modules`, `.git`, `__pycache__`, build output, and anything you don't need synced. Fewer files = fewer API calls.
|
|
454
|
+
- **If you see `too_many_requests` errors** in the logs, increase the interval and add more excludes.
|
|
616
455
|
|
|
617
|
-
|
|
618
|
-
- **Sensitive files**: Don't sync secrets, API keys, or credentials
|
|
619
|
-
- **Encryption**: Consider [rclone crypt](https://rclone.org/crypt/) for sensitive data
|
|
620
|
-
- **App folder**: Use Dropbox app folder access for minimal permissions
|
|
456
|
+
---
|
|
621
457
|
|
|
622
458
|
## Encrypted backups
|
|
623
459
|
|
|
@@ -653,32 +489,6 @@ flowchart TD
|
|
|
653
489
|
|
|
654
490
|
> **Disk-constrained?** Because backups stream directly, you don't need any free disk space for the backup itself. Only the restore downloads to a staging directory.
|
|
655
491
|
|
|
656
|
-
### Configuration
|
|
657
|
-
|
|
658
|
-
Add `sync` and `backup` blocks to your plugin config. The backup provider can differ from your sync provider — sync to Dropbox for live mirror, backup to S3 for disaster recovery:
|
|
659
|
-
|
|
660
|
-
```json
|
|
661
|
-
{
|
|
662
|
-
"sync": {
|
|
663
|
-
"provider": "dropbox",
|
|
664
|
-
"mode": "mailbox",
|
|
665
|
-
"remotePath": "",
|
|
666
|
-
"interval": 180
|
|
667
|
-
},
|
|
668
|
-
"backup": {
|
|
669
|
-
"enabled": true,
|
|
670
|
-
"provider": "s3",
|
|
671
|
-
"bucket": "my-backups",
|
|
672
|
-
"prefix": "habibi/",
|
|
673
|
-
"interval": 86400,
|
|
674
|
-
"encrypt": true,
|
|
675
|
-
"passphrase": "${BACKUP_PASSPHRASE}",
|
|
676
|
-
"include": ["workspace", "config", "cron", "memory"],
|
|
677
|
-
"retain": { "daily": 7, "weekly": 4 }
|
|
678
|
-
}
|
|
679
|
-
}
|
|
680
|
-
```
|
|
681
|
-
|
|
682
492
|
### Backup config reference
|
|
683
493
|
|
|
684
494
|
| Key | Type | Default | Description |
|
|
@@ -714,7 +524,7 @@ Add `sync` and `backup` blocks to your plugin config. The backup provider can di
|
|
|
714
524
|
|
|
715
525
|
Default: `["workspace", "config", "cron", "memory"]`
|
|
716
526
|
|
|
717
|
-
### CLI commands
|
|
527
|
+
### Backup CLI commands
|
|
718
528
|
|
|
719
529
|
```bash
|
|
720
530
|
# Create a backup now
|
|
@@ -740,7 +550,7 @@ openclaw workspace-sync backup status
|
|
|
740
550
|
|
|
741
551
|
By default, `restore` extracts to a staging directory (`~/.openclaw/.backup-restore/`), not directly over your live workspace. This lets you inspect the contents before copying them into place. Use `--to` to control where files land.
|
|
742
552
|
|
|
743
|
-
###
|
|
553
|
+
### Backup provider examples
|
|
744
554
|
|
|
745
555
|
**Cloudflare R2 (free tier: 10GB):**
|
|
746
556
|
|
|
@@ -801,6 +611,148 @@ By default, `restore` extracts to a staging directory (`~/.openclaw/.backup-rest
|
|
|
801
611
|
}
|
|
802
612
|
```
|
|
803
613
|
|
|
614
|
+
---
|
|
615
|
+
|
|
616
|
+
## Provider-specific options
|
|
617
|
+
|
|
618
|
+
These provider blocks work for both sync and backup. Place them inside the `sync` or `backup` config block as needed.
|
|
619
|
+
|
|
620
|
+
**Dropbox with app folder (recommended for security):**
|
|
621
|
+
|
|
622
|
+
```json
|
|
623
|
+
{
|
|
624
|
+
"provider": "dropbox",
|
|
625
|
+
"remotePath": "",
|
|
626
|
+
"dropbox": {
|
|
627
|
+
"appFolder": true,
|
|
628
|
+
"appKey": "your-app-key",
|
|
629
|
+
"appSecret": "your-app-secret",
|
|
630
|
+
"token": "{\"access_token\":\"...\"}"
|
|
631
|
+
}
|
|
632
|
+
}
|
|
633
|
+
```
|
|
634
|
+
|
|
635
|
+
With `appFolder: true`, set `remotePath` to `""`. The app folder root is your sync root — do not repeat the app folder name in `remotePath` or rclone will fail with "directory not found."
|
|
636
|
+
|
|
637
|
+
**Google Drive:**
|
|
638
|
+
|
|
639
|
+
```json
|
|
640
|
+
{
|
|
641
|
+
"provider": "gdrive",
|
|
642
|
+
"remotePath": "openclaw-sync",
|
|
643
|
+
"gdrive": {
|
|
644
|
+
"token": "{\"access_token\":\"...\"}",
|
|
645
|
+
"teamDrive": "0ABcDeFgHiJ",
|
|
646
|
+
"rootFolderId": "folder-id"
|
|
647
|
+
}
|
|
648
|
+
}
|
|
649
|
+
```
|
|
650
|
+
|
|
651
|
+
`teamDrive` and `rootFolderId` are optional — omit them for personal Google Drive.
|
|
652
|
+
|
|
653
|
+
**OneDrive:**
|
|
654
|
+
|
|
655
|
+
```json
|
|
656
|
+
{
|
|
657
|
+
"provider": "onedrive",
|
|
658
|
+
"remotePath": "openclaw-sync",
|
|
659
|
+
"onedrive": {
|
|
660
|
+
"token": "{\"access_token\":\"...\"}",
|
|
661
|
+
"driveId": "drive-id",
|
|
662
|
+
"driveType": "business"
|
|
663
|
+
}
|
|
664
|
+
}
|
|
665
|
+
```
|
|
666
|
+
|
|
667
|
+
`driveType` can be `personal`, `business`, or `sharepoint`. Both fields are optional.
|
|
668
|
+
|
|
669
|
+
**S3 / Cloudflare R2 / Minio:**
|
|
670
|
+
|
|
671
|
+
```json
|
|
672
|
+
{
|
|
673
|
+
"provider": "s3",
|
|
674
|
+
"remotePath": "openclaw-sync",
|
|
675
|
+
"s3": {
|
|
676
|
+
"endpoint": "https://s3.us-east-1.amazonaws.com",
|
|
677
|
+
"bucket": "your-bucket",
|
|
678
|
+
"region": "us-east-1",
|
|
679
|
+
"accessKeyId": "AKID...",
|
|
680
|
+
"secretAccessKey": "SECRET..."
|
|
681
|
+
}
|
|
682
|
+
}
|
|
683
|
+
```
|
|
684
|
+
|
|
685
|
+
**Any rclone backend (SFTP, B2, Mega, pCloud, etc.):**
|
|
686
|
+
|
|
687
|
+
```json
|
|
688
|
+
{
|
|
689
|
+
"provider": "custom",
|
|
690
|
+
"remotePath": "openclaw-sync",
|
|
691
|
+
"custom": {
|
|
692
|
+
"rcloneType": "sftp",
|
|
693
|
+
"rcloneOptions": {
|
|
694
|
+
"host": "example.com",
|
|
695
|
+
"user": "deploy",
|
|
696
|
+
"key_file": "/path/to/key"
|
|
697
|
+
}
|
|
698
|
+
}
|
|
699
|
+
}
|
|
700
|
+
```
|
|
701
|
+
|
|
702
|
+
The `custom` provider accepts any [rclone backend type](https://rclone.org/overview/) and passes `rcloneOptions` directly to the rclone config. This gives you config-driven access to all 70+ providers without manually editing `rclone.conf`.
|
|
703
|
+
|
|
704
|
+
### Supported providers
|
|
705
|
+
|
|
706
|
+
| Provider | Config value | Auth method | Config-driven |
|
|
707
|
+
|----------|-------------|-------------|---------------|
|
|
708
|
+
| Dropbox | `dropbox` | OAuth token | Full (token, appKey, appSecret, appFolder) |
|
|
709
|
+
| Google Drive | `gdrive` | OAuth token | Full (token, teamDrive, rootFolderId) |
|
|
710
|
+
| OneDrive | `onedrive` | OAuth token | Full (token, driveId, driveType) |
|
|
711
|
+
| S3/R2/Minio | `s3` | Access keys | Full (endpoint, bucket, region, credentials) |
|
|
712
|
+
| Any rclone backend | `custom` | Varies | Full (rcloneType + rcloneOptions) |
|
|
713
|
+
|
|
714
|
+
All providers are fully config-driven — no manual `rclone.conf` editing needed. The `custom` provider gives access to all [70+ rclone backends](https://rclone.org/overview/) (SFTP, B2, Mega, pCloud, Azure Blob, etc.).
|
|
715
|
+
|
|
716
|
+
### Dropbox app folder access (recommended)
|
|
717
|
+
|
|
718
|
+
For better security, create a scoped Dropbox app that only accesses a single folder:
|
|
719
|
+
|
|
720
|
+
1. Go to [Dropbox App Console](https://www.dropbox.com/developers/apps)
|
|
721
|
+
2. Click **Create app** > **Scoped access** > **App folder**
|
|
722
|
+
3. Name it (e.g., `openclaw-sync`)
|
|
723
|
+
4. In **Settings** tab, add a **Redirect URI**: `http://localhost:53682/`
|
|
724
|
+
- This is required for rclone's OAuth flow to work. Without it, Dropbox returns "Invalid redirect_uri" during authorization.
|
|
725
|
+
5. In **Permissions** tab, enable:
|
|
726
|
+
- `files.metadata.read` / `files.metadata.write`
|
|
727
|
+
- `files.content.read` / `files.content.write`
|
|
728
|
+
6. Copy **App key** and **App secret** from Settings
|
|
729
|
+
|
|
730
|
+
> **Important:** When using an app folder scoped app, set `"remotePath": ""` (empty string) in your config. The app folder **is** the root — rclone sees it as `/`. If you set `remotePath` to your app folder name (e.g., `"openclaw-sync"`), rclone will look for a subfolder *inside* the app folder with that name and fail with "directory not found."
|
|
731
|
+
|
|
732
|
+
Benefits:
|
|
733
|
+
- Token only accesses one folder, not your entire Dropbox
|
|
734
|
+
- If token is compromised, blast radius is limited
|
|
735
|
+
- Clean separation — sync folder lives under `Apps/<your-app-name>/`
|
|
736
|
+
|
|
737
|
+
---
|
|
738
|
+
|
|
739
|
+
## Deployment recommendations
|
|
740
|
+
|
|
741
|
+
If you are running OpenClaw on a cloud container (Fly.io, Railway, Render) or a VPS:
|
|
742
|
+
|
|
743
|
+
- **Use a separate persistent volume for the workspace.** Container root filesystems are ephemeral — a redeploy wipes everything. Mount a dedicated volume (e.g., Fly.io volumes, EBS, DigitalOcean block storage) at your workspace path so data survives deploys and restarts.
|
|
744
|
+
- **Enable daily volume snapshots.** Most cloud providers offer automated snapshots (Fly.io does this by default with 5-day retention). If something goes wrong — a bad sync, accidental deletion, or a failed reorganization — a recent snapshot lets you restore in minutes instead of rebuilding from scratch.
|
|
745
|
+
- **Test your restore process.** A backup you have never restored is a backup you do not have. Create a volume from a snapshot at least once to confirm the process works and you know the steps.
|
|
746
|
+
- **Use encrypted backups for off-site disaster recovery.** Volume snapshots protect against accidental deletes, but not against provider outages or account issues. Streaming encrypted backups to a separate provider (e.g., R2, B2) gives you a fully independent recovery path.
|
|
747
|
+
|
|
748
|
+
## Security notes
|
|
749
|
+
|
|
750
|
+
- **Token storage**: rclone tokens are stored in `rclone.conf` with `0600` permissions
|
|
751
|
+
- **Sensitive files**: Don't sync secrets, API keys, or credentials
|
|
752
|
+
- **Encryption**: Backups support AES-256 client-side encryption. For sync, consider [rclone crypt](https://rclone.org/crypt/) for sensitive data.
|
|
753
|
+
- **App folder**: Use Dropbox app folder access for minimal permissions
|
|
754
|
+
- **Passphrase safety**: Use environment variables (`${BACKUP_PASSPHRASE}`) — never hardcode passphrases in config files
|
|
755
|
+
|
|
804
756
|
## Development
|
|
805
757
|
|
|
806
758
|
```bash
|