Claw Roam — OpenClaw 工作区同步

通过 Git 在多台设备间同步你的 OpenClaw 工作区。这使你可以：

• 以本地 Mac 为主力设备开发，出行时无缝切换至 VPS
• 在不同机器间持续保持 OpenClaw 的记忆与人格一致性
• 将 OpenClaw 状态备份至远程 Git 仓库

快速开始

多设备协作推荐的分支模型：

• main = 共享基线分支
• remote = 当前服务器（VPS）所用分支
• local = 你的笔记本/桌面电脑所用分支

# 查看当前同步状态（含当前分支）
claw-roam status

# 一键全量同步（推荐）
claw-roam sync

# 或分步执行：
# 提交并推送当前分支
claw-roam push "msg"

# 拉取当前分支的最新内容
claw-roam pull

# （可选）将其他设备分支合并至当前分支
claw-roam merge-from local
claw-roam merge-from remote

命令说明

push

提交并推送工作区至远程 Git 仓库。

claw-roam push [message]

• 若未提供提交信息，则默认使用时间戳
• 自动添加所有变更（等效于 git add -A）
• 若检测到无变更，则跳过推送

pull

从远程拉取最新工作区并完成同步。

claw-roam pull

• 从远程获取最新变更
• 将变更应用至当前工作区
• 在 VPS 模式下，会停止并重启 OpenClaw gateway 以生效变更

status

检查本地与远程之间的同步状态。

claw-roam status

• 显示当前分支及最新提交哈希
• 显示尚未推送的提交（如有）
• 显示尚未提交的变更
• 提示建议的下一步操作

sync（一键全量同步）

claw-roam sync

在一个命令中执行完整的同步流程：

1. 提交并推送当前分支 —— 保存你的本地变更
2. 将 main 分支合并至当前分支 —— 获取共享主干的最新内容
3. 推送至 main 分支 —— 将你的变更共享给其他设备

工作流示意图：

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

推荐的日常工作流：

# 在每台设备上仅需运行：
claw-roam sync

该命令确保：

• 你的变更被安全保存至对应分支
• 你获取了其他设备的最新变更（经由 main 分支）
• 其他设备也能获取你的变更（经由 main 分支）

初始化配置

1. 在工作区中初始化 Git 仓库（如尚未完成）：

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

2. 创建初始提交：

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

3. 在 VPS 上克隆仓库：

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

分支工作流（推荐）

针对多设备场景，推荐采用如下分支策略：

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

各设备初始化

本地 Mac：

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

远程 VPS：

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

日常操作流程

在每台设备上执行：

1. 从 main 分支拉取最新内容（获取其他设备的最新变更）：

claw-roam merge-from main

2. 正常工作后，推送你的变更：

claw-roam push "update memory"

3. 将变更共享至 main 分支（供其他设备获取）：

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

快捷同步（单行命令）

# 从 main 拉取，再合并推送至 main
claw-roam merge-from main && git checkout main && git merge local && git push && git checkout local

冲突解决

若执行 merge-from main 时出现冲突：

# 保留你的版本
git checkout --ours 
git add -A && git commit -m "merge: resolved conflicts"

# 或保留 main 分支的版本
git checkout --theirs 
git add -A && git commit -m "merge: resolved conflicts"

简易工作流：本地为主 + VPS 备份

适用于无需分支管理的轻量级部署：

日常使用（本地 Mac）

照常使用 OpenClaw。关机前执行：

claw-roam push "end of day sync"

或通过 cron 自动推送：

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

切换至 VPS

1. 确认本地已完成推送：claw-roam push
2. 在 VPS 上执行：claw-roam pull
3. 更新 Telegram webhook 地址指向 VPS（若启用 webhook 模式）
4. 在 VPS 上继续使用备用 bot token

切回本地

1. 在 VPS 上执行：claw-roam push
2. 在本地执行：claw-roam pull
3. 按需将 Telegram webhook 地址切回本地

同步内容说明

被同步的内容（跨设备保持一致）：

• SOUL.md —— 你的智能体人格定义
• MEMORY.md —— 长期记忆
• memory/*.md —— 每日对话日志
• skills/ —— 所有已安装技能
• AGENTS.md、USER.md —— 上下文配置文件
• TOOLS.md —— 设备相关配置
• HEARTBEAT.md —— 周期性任务定义

不被同步的内容（设备专属）：

• 会话数据库（SQLite）—— 但可通过 memory 文件重建
• gateway 运行时状态
• 配置中平台相关的路径

故障排查

“Repository not found”

请执行上述初始化步骤，完成 Git 仓库配置。

“Merge conflicts”

若你在两台设备上均进行了编辑但未及时同步：

# 在希望保留其变更的设备上执行
git pull --strategy=ours
git push

“Permission denied”

请确认 Git 远程地址已配置正确的认证方式（SSH 密钥或访问令牌）。

脚本调用

可直接调用内置脚本：

~/.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