Git 版本控制 | OpenClaw 配置保护

通过基于 Git 的检查点与回滚能力，保障您的 OpenClaw 环境安全。

概述

OpenClaw 配置目录（~/.openclaw/）本身即为一个 Git 仓库。本能力为系统配置变更提供安全、可靠的版本控制支持。

受保护的文件包括：

• workspace/SOUL.md、AGENTS.md、USER.md、IDENTITY.md
• workspace/skills/ —— 已安装的技能
• workspace/memory/ —— 记忆文件
• openclaw.json —— 主配置文件
• cron/jobs.json —— 定时任务配置

排除在版本控制之外的文件：

• 会话日志（*.jsonl、*.jsonl.lock）
• SQLite 数据库（*.sqlite）
• 临时文件
• 凭证信息（敏感数据）

核心操作

1. SAVE — 创建检查点

在执行敏感变更前创建一次 Git 提交，作为可恢复的基准状态。

适用场景：

• 修改核心配置文件之前
• 安装或卸载技能之前
• 执行批量记忆更新之前
• 用户显式请求创建保存点

命令流程：

cd ~/.openclaw

# 查看当前状态
git status

# 添加所有已跟踪文件（遵循 .gitignore 规则）
git add -A

# 使用描述性消息创建提交
git commit -m "checkpoint: {待执行变更的简要说明}"

实现逻辑：

当用户说："save before..." 或 "create checkpoint"

1. 基于上下文生成具有描述性的提交消息
2. 执行：git add -A
3. 执行：git commit -m "checkpoint: {描述}"
4. 向用户报告提交哈希值及变更文件数量

示例：

User: "Save before I install a new skill"
Action:
  git add -A
  git commit -m "checkpoint: before installing new skill"
Output: "✓ Checkpoint created: abc1234 (5 files changed)"

2. ROLLBACK — 恢复至先前状态

当系统出现异常时，回退至之前的某个提交版本。

适用场景：

• 用户反馈近期变更后系统出现异常
• 用户显式请求回滚操作
• 检测到配置损坏
• 技能安装失败后

回滚选项：

推荐默认方式：--hard（用于完整回滚）

实现逻辑：

当用户说："rollback" 或 "undo last change" 或 "restore previous"

1. 展示最近若干次提交供用户选择
   git log --oneline -10
   
2. 确认目标提交版本
   "Rollback to commit X? This will discard: {列出将被丢弃的变更}"
   
3. 执行回滚
   git reset --hard {commit-hash}
   
4. 报告结果
   "✓ Rolled back to commit abc1234"

示例：

User: "Rollback to before the skill installation"
Action:
  git log --oneline -5
  # 显示如下：
  # abc1234 checkpoint: before skill install
  # def5678 previous config
  git reset --hard abc1234
Output: "✓ Rolled back to 'before skill install' (abc1234)"

辅助操作

查看历史记录

# 查看最近 10 条提交
git log --oneline -10

# 查看上一次提交中具体变更了哪些文件
git show --stat HEAD

# 对比当前工作区与最新提交之间的差异
git diff HEAD

检查当前状态

# 查看未提交的变更
git status

# 查看差异摘要
git diff --stat

列出受保护文件

当前纳入版本控制（Git 跟踪）的文件列表：

git ls-files

.gitignore 配置

确保 ~/.openclaw/.gitignore 正确排除易变或敏感文件：

# 会话日志（易变）
*.jsonl
*.jsonl.lock
*.jsonl.reset.*

# 数据库（易变）
*.sqlite
*.sqlite-journal

# 凭证（敏感）
credentials/
*.pem
*.key

# 临时文件
*.tmp
*.temp
.DS_Store

# 日志
logs/

# 投递队列
delivery-queue/

决策流程图

User requests sensitive operation
        ↓
    Is SAVE needed?
    ┌─────┴─────┐
   Yes          No
    ↓            ↓
 SAVE first   Execute directly
    ↓
Execute operation
    ↓
  Success?
  ┌─────┴─────┐
 Yes          No
  ↓            ↓
 Done      ROLLBACK?
           ┌─────┴─────┐
          Yes          No
           ↓            ↓
       Rollback     Debug manually

与其他技能的集成

安全准则

✅ 最佳实践

1. 高风险操作前务必 SAVE

   • 从外部源安装技能
   • 修改 AGENTS.md、SOUL.md
   • 执行批量记忆更新

2. 使用具有描述性的提交消息

   checkpoint: before installing news skill
   checkpoint: before modifying SOUL.md persona
   checkpoint: before cron job changes
   

3. 执行 ROLLBACK 前务必确认

   • 明确展示将丢失的内容
   • 对硬重置操作必须获得用户确认

❌ 应避免的行为

1. 未经确认不得执行回滚

   • 硬重置会销毁所有未提交的更改
   • 必须向用户明确提示数据丢失风险

2. 禁止提交敏感数据

   • 确保 .gitignore 已排除凭证目录
   • 切勿将 credentials/ 加入 Git 跟踪

3. 不可用于会话数据管理

   • 会话日志已被有意排除
   • 聚焦于配置管理，而非运行时数据

速查表

示例会话

User: Install a new skill from ClawHub

Agent (internal):
  1. SAVE checkpoint first
     $ git add -A
     $ git commit -m "checkpoint: before installing {skill-name}"
     ✓ Checkpoint: abc1234

  2. Install skill
     $ clawhub install {skill-name}
     
  3. Verify success
     ✓ Skill installed successfully
     
User: That skill broke something, rollback!

Agent:
  1. Show options
     $ git log --oneline -3
     abc1234 checkpoint: before installing {skill-name}
     def5678 previous state
     
  2. Confirm rollback
     "Rollback to abc1234? This will remove the newly installed skill."
     
  3. Execute
     $ git reset --hard abc1234
     ✓ Rolled back successfully

最后更新时间：2026-03-05