OpenClaw Workspace Sharing & Sync

A production-ready OpenClaw plugin for real-time workspace sharing, file synchronization, and access management — powered by MongoDB.

Multiple OpenClaw agents on different machines can share the same workspace: files created, updated, or deleted on one machine automatically appear (or disappear) on every other connected machine.

✨ Features

• Automatic two-way file sync — chokidar watches your local workspace directory; changes propagate to all connected peers in real time
• File create / update / delete — full lifecycle synced, not just state blobs
• Real-time delivery — MongoDB Change Streams (with polling fallback for standalone instances)
• Role-based access control — OWNER, EDITOR, VIEWER roles enforced on every operation
• Shareable access keys — invite collaborators without needing their user ID upfront; set expiry and max-use limits
• Optimistic concurrency — version-checked writes prevent silent conflicts
• Audit log — every action recorded with who did what and when
• Auto-start on plugin load — configure once, sync starts automatically every time the gateway restarts

📦 Installation

openclaw plugins install @gauravprasadgp/openclaw-share-workspace

⚙️ Configuration

Add the plugin config to ~/.openclaw/openclaw.json under plugins.entries:

Minimal (manual sync)

{
  "plugins": {
    "entries": {
      "shared-workspace": {
        "enabled": true,
        "mongodbUri": "mongodb://localhost:27017"
      }
    }
  }
}

Full (auto-start file sync on every gateway restart)

{
  "plugins": {
    "entries": {
      "shared-workspace": {
        "enabled": true,
        "mongodbUri": "mongodb+srv://user:pass@cluster.mongodb.net/",
        "dbName": "openclaw",
        "syncProvider": "mongodb",
        "pollIntervalMs": 3000,
        "enableChangeStreams": true,
        "autoSync": {
          "enabled": true,
          "workspaceId": "ws-001",
          "userId": "agent-main",
          "workspaceDir": "/Users/alice/.openclaw/workspace",
          "debounceMs": 300,
          "ignore": ["*.log", "tmp/**", "*.tmp"]
        }
      }
    }
  }
}

All configuration options

Built-in ignore list (always excluded, regardless of config): node_modules/, .git/, dist/, .env*, *.log, package-lock.json, yarn.lock, pnpm-lock.yaml, .DS_Store

🚀 Use Cases

1 — Two agents on different machines sharing a workspace

Both machines configure autoSync pointing at the same workspaceId. After gateway restart on both:

Machine A edits src/agent.ts
  → FileSyncService detects change
  → uploads to MongoDB (file_update event)
  → Machine B receives event via Change Stream / polling
  → Machine B writes src/agent.ts to disk automatically

No manual steps after initial config.

2 — Invite a collaborator with an access key

The workspace owner generates a key with an expiry and role:

Tool: generate_access_key
  workspaceId: "ws-001"
  createdBy:   "user-alice"
  role:        "EDITOR"
  expiresInHours: 48
  maxUses: 1

Share the returned key string with the collaborator. They join with:

Tool: join_workspace
  key:    "<key-string>"
  userId: "user-bob"

Bob now has EDITOR access. No OWNER involvement needed at join time. Keys can be revoked at any time — already-joined users are not removed.

3 — Read-only observer

Share a workspace with role: VIEWER. Viewers can:

• get_workspace, get_workspace_state, list_user_workspaces
• Receive inbound file sync events (files written to their disk)

Viewers cannot write: create_workspace_file, update_workspace_file, delete_workspace_file, update_workspace_state all return ACCESS_DENIED.

4 — Selective sync with ignore patterns

Ignore build artifacts and secrets while syncing source:

"autoSync": {
  "enabled": true,
  "workspaceId": "ws-001",
  "userId": "agent-main",
  "workspaceDir": "/workspace",
  "ignore": ["build/**", "*.secret", "coverage/**", ".cache/**"]
}

5 — On-demand sync without auto-start

If autoSync is not configured, use the tools directly:

Tool: start_file_sync
  workspaceId:  "ws-001"
  userId:       "agent-main"
  workspaceDir: "/Users/alice/.openclaw/workspace"
  debounceMs:   500

# ... when done ...

Tool: stop_file_sync
  workspaceId: "ws-001"
  userId:      "agent-main"

6 — Audit who changed what

Tool: get_workspace_audit_log
  workspaceId: "ws-001"
  limit: 50

Returns a log of every FILE_CREATED, FILE_UPDATED, FILE_DELETED, WORKSPACE_SHARED, ACCESS_REVOKED, ACCESS_KEY_GENERATED, and more — with userId, timestamp, and changed fields.

🛠 Available Tools

Workspace management

Access control

File sync

State & audit

🔄 How file sync works

┌─────────────────────────────────────────────────────┐
│ Machine A (OWNER/EDITOR)                            │
│                                                     │
│  Local filesystem change (create/edit/delete)       │
│      ↓  chokidar detects it (debounced 300ms)       │
│  FileSyncService reads file content                 │
│      ↓                                              │
│  WorkspacePlugin stores in MongoDB workspace_states │
│      + inserts event into workspace_updates         │
└──────────────────────┬──────────────────────────────┘
                       │ MongoDB Change Stream / polling
┌──────────────────────▼──────────────────────────────┐
│ Machine B (any role with connectSync)               │
│                                                     │
│  FileSyncService receives WorkspaceUpdate           │
│      operationType = file_create / file_update      │
│          → fs.writeFile(path, content)              │
│      operationType = file_delete                    │
│          → fs.rm(path)                              │
│                                                     │
│  Echo-loop guard: writes marked in-flight so the    │
│  local watcher doesn't re-broadcast them back       │
└─────────────────────────────────────────────────────┘

Conflict detection: every write accepts an optional expectedVersion. If the current version in MongoDB doesn't match, a ConflictError is thrown — no silent overwrites.

🗄 MongoDB collections

❓ Troubleshooting

Plugin skips initialization

⚠️ shared-workspace: skipping initialization because mongodbUri is not configured

Add mongodbUri to your config or export MONGODB_URI and restart the gateway.

autoSync fields warning

⚠️ shared-workspace: autoSync.enabled=true but missing fields: workspaceId, workspaceDir

All three fields (workspaceId, userId, workspaceDir) must be set for auto-start to work. The plugin still loads and all tools remain available.

Change streams not working Set enableChangeStreams: false if your MongoDB is a standalone instance (not a replica set). The plugin will fall back to polling every pollIntervalMs ms automatically.

Files not appearing on the remote machine

• Confirm both machines are pointed at the same workspaceId and same MongoDB instance
• Check that the receiving agent called start_file_sync (or has autoSync configured)
• Verify the userId on the receiving machine is different from the sender — the inbound handler skips its own updates

Version conflict errors Pass expectedVersion only when you know the current version. Omit it to always overwrite regardless of the current version.

🔗 Links

• Registry: ClawHub Plugin Page
• OpenClaw docs: https://docs.openclaw.ai
• MongoDB Atlas (free tier): https://www.mongodb.com/atlas