名称： claw-roam
描述： 通过 Git 在多台机器（本地 Mac 和远程 VPS）之间同步 OpenClaw 工作区。实现 OpenClaw 人格、记忆和技能的无缝迁移。适用于用户需要：(1) 关机前将工作区更改推送到远程，(2) 在新机器上拉取最新工作区，(3) 检查机器间的同步状态，(4) 将 OpenClaw 迁移到另一台机器。

Claw Roam - OpenClaw 工作区同步

通过 Git 在多台机器间同步您的 OpenClaw 工作区。这使您可以：
- 主要在本地 Mac 上工作，外出时可无缝切换到 VPS
- 在不同机器间保持连续的记忆和人格
- 将 OpenClaw 状态备份到远程 Git 仓库

快速开始

多设备推荐的 Git 分支模型：
- main = 共享基线分支
- remote = 远程服务器分支
- local = 您的笔记本电脑/台式机分支

# 检查状态（当前分支）
claw-roam status

# 一键完整同步（推荐）
claw-roam sync

# 或分步操作：
# 提交并推送当前分支
claw-roam push "提交信息"

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

# （可选）将另一台设备的分支合并到当前分支
claw-roam merge-from local
claw-roam merge-from remote

命令

push

提交工作区更改并推送到远程 Git 仓库。

claw-roam push [提交信息]

• 若未提供提交信息，则使用时间戳作为默认信息
• 自动添加所有更改 (git add -A)
• 若未检测到更改，则跳过推送

pull

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

claw-roam pull

• 从远程获取最新更改
• 将更改应用到当前工作区
• 停止并重启 OpenClaw 网关以应用更改（VPS 模式）

status

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

claw-roam status

• 显示当前分支和提交
• 显示未推送的提交（如有）
• 显示未提交的更改
• 建议下一步操作

sync（一键完整同步）

claw-roam sync

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

1. 提交并推送当前分支 - 保存您的本地更改
2. 将 main 分支合并到当前分支 - 从共享的 main 分支获取最新内容
3. 推送到 main 分支 - 将您的更改分享给其他机器

工作流示意图：

┌─────────────┐     提交+推送      ┌─────────────┐
│ local       │ ──────────────────▶│ origin/local│
│ 分支        │                    │             │
└──────┬──────┘                    └─────────────┘
       │
       │ 合并 main
       ▼
┌─────────────┐     合并+推送      ┌─────────────┐
│ local       │ ──────────────────▶│ main        │
│ 分支        │                    │ (共享)      │
└─────────────┘                    └──────┬──────┘
                                          │
                   ┌──────────────────────┘
                   │ 拉取
                   ▼
           ┌─────────────┐
           │ remote      │
           │ 分支        │
           └─────────────┘

推荐的每日工作流：

# 在每台机器上，只需运行：
claw-roam sync

这确保了：
- 您的更改已保存到您的分支
- 您从其他机器获取了最新更改（通过 main 分支）
- 其他机器可以获取您的更改（通过 main 分支）

设置

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

cd ~/.openclaw/workspace
git init
git remote add origin <您的仓库URL>

2. 创建初始提交：

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

3. 在 VPS 机器上 - 克隆仓库：

cd ~
git clone <您的仓库URL> openclaw-workspace
ln -s openclaw-workspace ~/.openclaw/workspace

分支工作流（推荐）

对于多台机器，使用以下分支策略：

local (Mac) ──┐
              ├──► main (共享) ◄── 合并 & 推送
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 "更新记忆"

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: 解决冲突"

# 或保留 main 的版本
git checkout --theirs <冲突文件>
git add -A && git commit -m "merge: 解决冲突"

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

对于无需分支的简化设置：

日常使用（本地 Mac）

正常使用 OpenClaw。关机前运行：

claw-roam push "日终同步"

或通过 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）- 但这会从记忆文件重建
- 网关运行时状态
- 配置中的平台特定路径

故障排除

"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