Claw Roam

Claw Roam - OpenClaw Workspace Sync

Sync your OpenClaw workspace across machines via Git. This allows you to:

Quick Start

Recommended branch model for multi-device:

# Check status (current branch)
claw-roam status
One-command full sync (recommended)
claw-roam sync
Or step by step:
Commit+push current branch
claw-roam push "msg"
Pull latest for current branch
claw-roam pull
(Optional) merge another device branch into current branch
claw-roam merge-from local
claw-roam merge-from remote

Commands

push

claw-roam push [message]

pull

claw-roam pull

status

claw-roam status

sync (One-Command Full Sync)

claw-roam sync

Performs the complete sync workflow in one command:

1. Commit and push current branch - Saves your local changes 2. Merge main into current branch - Gets latest from shared main 3. Push to main branch - Shares your changes with other machines

Workflow diagram:

┌─────────────┐     commit+push     ┌─────────────┐
│ local       │ ───────────────────▶│ origin/local│
│ 分支        │                     │             │
└──────┬──────┘                     └─────────────┘
       │
       │ merge main
       ▼
┌─────────────┐     merge+push      ┌─────────────┐
│ local       │ ───────────────────▶│ main        │
│ 分支        │                     │ (shared)    │
└─────────────┘                     └──────┬──────┘
                                           │
                    ┌──────────────────────┘
                    │ pull
                    ▼
            ┌─────────────┐
            │ remote      │
            │ 分支        │
            └─────────────┘

Recommended daily workflow:

# On each machine, just run:
claw-roam sync

This ensures:

Setup

1. Initialize Git repo in workspace (if not already done):

cd ~/.openclaw/workspace
git init
git remote add origin 

2. Create initial commit:

git add -A
git commit -m "initial"
git push -u origin main

3. On VPS machine - clone the repo:

cd ~
git clone  openclaw-workspace
ln -s openclaw-workspace ~/.openclaw/workspace

Branch Workflow (Recommended)

For multiple machines, use this branch strategy:

local (Mac) ──┐
              ├──► main (shared) ◄── merge & push
remote (VPS) ─┘

Setup Each Machine

Local Mac:

cd ~/.openclaw/workspace
git checkout -b local
git push -u origin local

Remote VPS:

cd ~/.openclaw/workspace
git checkout -b remote
git push -u origin remote

Daily Workflow

On each machine:

1. Get latest from main (获取其他机器的最新内容):

claw-roam merge-from main

2. Work normally, then push your changes:

claw-roam push "update memory"

3. Share to main (让其他机器能获取):

git checkout main
git merge local -m "merge: local -> main"
git push origin main
git checkout local

Quick Sync (One-liner)

# Pull from main, then push to main
claw-roam merge-from main && git checkout main && git merge local && git push && git checkout local

Conflict Resolution

If merge-from main has conflicts:

# Keep your version
git checkout --ours 
git add -A && git commit -m "merge: resolved conflicts"
Or keep main's version
git checkout --theirs 
git add -A && git commit -m "merge: resolved conflicts"

Simple Workflow: Local Primary + VPS Backup

For simpler setups without branches:

Daily Usage (Local Mac)

claw-roam push "end of day sync"

Or let it auto-push via cron:

# Add to crontab
*/10 * * * * cd ~/.openclaw/workspace && git add -A && git commit -m "auto: $(date)" && git push

Switching to VPS

Returning to Local

What Gets Synced

Synced (preserved across machines):

Not Synced (machine-specific):

Troubleshooting

"Repository not found"

"Merge conflicts"

# On the machine with changes you want to keep
git pull --strategy=ours
git push

"Permission denied"

Scripts

Use bundled scripts directly:

~/.openclaw/workspace/skills/claw-roam/scripts/claw-roam.sh push
~/.openclaw/workspace/skills/claw-roam/scripts/claw-roam.sh pull
~/.openclaw/workspace/skills/claw-roam/scripts/claw-roam.sh status

Recommended branch model for multi-device:

# Check status (current branch)
claw-roam status
One-command full sync (recommended)
claw-roam sync
Or step by step:
Commit+push current branch
claw-roam push "msg"
Pull latest for current branch
claw-roam pull
(Optional) merge another device branch into current branch
claw-roam merge-from local
claw-roam merge-from remote

1. Initialize Git repo in workspace (if not already done):

cd ~/.openclaw/workspace
git init
git remote add origin 

2. Create initial commit:

git add -A
git commit -m "initial"
git push -u origin main

3. On VPS machine - clone the repo:

cd ~
git clone  openclaw-workspace
ln -s openclaw-workspace ~/.openclaw/workspace

"Repository not found"

"Merge conflicts"

# On the machine with changes you want to keep
git pull --strategy=ours
git push

"Permission denied"