Git Version Control | OpenClaw Configuration Protection

Protect your OpenClaw environment with git-based checkpoints and rollback capability.

⚠️ Security Notice

v0.2.0 includes critical safety enhancements:

- Pre-commit sensitive file scanning
Mandatory .gitignore verification
Hard reset confirmation with data loss warning
Safer alternatives (soft/mixed reset)
Autonomous operation restrictions

Overview

OpenClaw configuration directory (~/.openclaw/) is a git repository. This skill provides safe version control for system configuration changes.

Protected files include:

- workspace/SOUL.md, AGENTS.md, USER.md, INLINECODE4
INLINECODE5 - installed skills
INLINECODE6 - memory files
INLINECODE7 - main configuration
INLINECODE8 - cron jobs

Excluded from version control:

- Session logs (*.jsonl, *.jsonl.lock)
SQLite databases (*.sqlite)
Temporary files
Credentials (sensitive)
Python cache (__pycache__/)

Core Operations

1. SAVE - Create Checkpoint

Create a git commit before making sensitive changes. This provides a recovery point.

⚠️ SAFETY REQUIREMENTS (MUST follow in order):

1. Verify .gitignore exists

   test -f ~/.openclaw/.gitignore && echo "✓ .gitignore found" || echo "✗ .gitignore MISSING"

If missing: STOP and create .gitignore first

2. Scan for sensitive files (before staging)

CODEBLOCK1

3. Review what will be committed

   git add -A --dry-run
   git status

Confirm no sensitive data before proceeding

4. Commit with descriptive message

CODEBLOCK3

When to use:

- Before modifying core configuration files
Before installing/uninstalling skills
Before making bulk memory changes
User explicitly requests a save point

SAFER ALTERNATIVE - Targeted Add:

Instead of git add -A, use targeted paths to avoid accidental commits:

CODEBLOCK4

Implementation:
CODEBLOCK5

Example:

User: "Save before I install a new skill"

Agent:
  1. Checking .gitignore... ✓ Found
  2. Scanning for sensitive files... ✓ None detected
  3. Files to commit:
     M workspace/AGENTS.md
     A workspace/skills/new-skill/SKILL.md
  4. Creating checkpoint...
     $ git add -A
     $ git commit -m "checkpoint: before installing new skill"
  
Output: "✓ Checkpoint created: abc1234 (5 files changed)"

2. ROLLBACK - Restore Previous State

Revert to a previous commit when issues occur.

⚠️ DANGER: Hard Reset Destroys Data

INLINECODE14 permanently deletes all uncommitted changes. There is NO undo.

When to use:

- User reports system issues after recent changes
User explicitly requests rollback
Configuration corruption detected
After a failed skill installation

Rollback Options (try in order of safety):

Option	Command	Safety	Effect
Soft reset	INLINECODE15	✅ Safe	Undo commit, keep changes staged
Mixed reset

Recommended: Always try soft reset first. Only use hard reset if absolutely necessary.

Implementation:
CODEBLOCK7

Example:

User: "Rollback to before the skill installation"

Agent:
  1. Recent commits:
     abc1234 checkpoint: before skill install
     def5678 previous config
     
  2. Restore to abc1234?
  
  3. Checking uncommitted changes...
     M workspace/skills/broken-skill/SKILL.md
     ?? workspace/skills/broken-skill/cache/
     
  4. ⚠️ Hard reset will DELETE these changes permanently. 
     Use soft reset to keep changes unstaged?
     
     [User confirms hard reset]
     
  5. Executing hard reset...
     $ git reset --hard abc1234
     
Output: "✓ Rolled back to 'before skill install' (abc1234)"

Helper Operations

View History

CODEBLOCK9

Check Status

CODEBLOCK10

List Protected Files

Files tracked for version control (in git):
CODEBLOCK11

Verify .gitignore

CODEBLOCK12

.gitignore Configuration

Ensure ~/.openclaw/.gitignore excludes volatile/sensitive files:

CODEBLOCK13

Decision Tree

CODEBLOCK14

Integration with Other Skills

Skill	Integration	Restriction
self-improvement	Record rollback events as learnings	✅ Safe
skill-creator

⚠️ Autonomous Operation Restrictions:

When invoked autonomously (by other skills or automated triggers):

- SAVE: Require user confirmation unless explicitly whitelisted
ROLLBACK: ALWAYS require user confirmation
Hard reset: NEVER allowed autonomously

Safety Guidelines

✅ Best Practices

1. Always verify .gitignore before SAVE

CODEBLOCK15

2. Scan for sensitive files before committing

CODEBLOCK16

3. Use targeted add instead of -A when possible

CODEBLOCK17

4. Prefer soft/mixed reset over hard reset

CODEBLOCK18

5. Always confirm before hard reset

- Show what will be lost - Require explicit "yes" confirmation

6. Use descriptive commit messages

CODEBLOCK19

❌ Avoid

1. Don't use git add -A blindly

- Check what will be staged first - Consider targeted paths instead

2. Don't commit without checking .gitignore

- Sensitive files may be exposed - Verify exclusions are working

3. Don't hard reset without confirmation

- Changes are permanently lost - No undo possible

4. Don't allow autonomous hard resets

- Too risky for automated operations - Always require human confirmation

5. Don't commit session data

- Session logs are excluded intentionally - Focus on configuration, not runtime data

Quick Reference

Action	Command	Safety	Alias
Verify .gitignore	INLINECODE19	✅ Safe	INLINECODE20
Scan sensitive files

Example Session

CODEBLOCK20

Last updated: 2026-03-07

Git版本控制 | OpenClaw配置保护

通过基于git的检查点和回滚功能保护您的OpenClaw环境。

⚠️ 安全通知

v0.2.0 包含关键安全增强：

- 提交前敏感文件扫描
强制.gitignore验证
硬重置确认及数据丢失警告
更安全的替代方案（软/混合重置）
自主操作限制

概述

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）
临时文件
凭证（敏感信息）
Python缓存（pycache/）

核心操作

1. 保存 - 创建检查点

在进行敏感更改前创建git提交。这提供了恢复点。

⚠️ 安全要求（必须按顺序执行）：

1. 验证.gitignore是否存在

bash test -f ~/.openclaw/.gitignore && echo ✓ 已找到.gitignore || echo ✗ .gitignore缺失

如果缺失：停止并先创建.gitignore

2. 扫描敏感文件（暂存前）

3. 审查将要提交的内容

bash git add -A --dry-run git status

确认无敏感数据后再继续

4. 使用描述性信息提交

bash git commit -m checkpoint: {待变更的描述}

何时使用：

- 修改核心配置文件前
安装/卸载技能前
批量修改记忆前
用户明确要求创建保存点

更安全的替代方案 - 定向添加：

使用定向路径代替git add -A，避免意外提交：

bash

仅添加特定配置文件

git add workspace/SOUL.md workspace/AGENTS.md workspace/USER.md

或使用显式路径添加整个目录

git add workspace/skills/

实现方式：

当用户说：保存前...或创建检查点

1. [必需] 检查.gitignore是否存在

- 如果缺失：停止并警告用户

2. [必需] 扫描敏感文件

- 如果检测到：停止并显示列表 - 要求用户验证.gitignore

3. 显示将要提交的内容

git status --short

4. 如果是自主操作，询问用户确认

将提交{count}个文件。是否继续？

5. 执行提交

git add -A # 或定向路径 git commit -m checkpoint: {描述}

6. 报告提交哈希和文件数量

示例：

用户：安装新技能前保存一下

智能体：
1. 检查.gitignore... ✓ 已找到
2. 扫描敏感文件... ✓ 未检测到
3. 待提交文件：
M workspace/AGENTS.md
A workspace/skills/new-skill/SKILL.md
4. 创建检查点...
$ git add -A
$ git commit -m checkpoint: 安装新技能前

输出：✓ 检查点已创建：abc1234（5个文件已更改）

2. 回滚 - 恢复之前状态

在出现问题时恢复到之前的提交。

⚠️ 危险：硬重置会销毁数据

git reset --hard 永久删除所有未提交的更改。无法撤销。

何时使用：

- 用户报告最近更改后出现系统问题
用户明确要求回滚
检测到配置损坏
技能安装失败后

回滚选项（按安全性顺序尝试）：

选项	命令	安全性	效果
软重置	git reset --soft HEAD~1	✅ 安全	撤销提交，保留更改已暂存
混合重置

git reset --mixed HEAD~1 | ⚠️ 中等 | 撤销提交，保留更改未暂存 |
| 硬重置 | git reset --hard HEAD~1 | 🔴 破坏性 | 永久删除提交+更改 |

推荐：始终先尝试软重置。仅在绝对必要时使用硬重置。

实现方式：

当用户说：回滚或撤销上次更改

1. 显示最近的提交

git log --oneline -10

2. 询问恢复到哪个提交

恢复到哪个提交？

3. [硬重置必需] 显示将丢失的内容

git diff --stat {commit-hash} git status --short

4. [硬重置必需] 明确确认

⚠️ 硬重置将永久删除{count}个未提交的更改： - {文件列表} 此操作无法撤销。是否继续？（是/否）

5. 执行回滚

- 优先：git reset --soft {commit-hash} - 如果用户确认硬重置：git reset --hard {commit-hash}

6. 报告结果

✓ 已回滚到提交abc1234

示例：

用户：回滚到技能安装之前

智能体：
1. 最近的提交：
abc1234 checkpoint: 技能安装前
def5678 之前的配置

2. 恢复到abc1234？

3. 检查未提交的更改...
M workspace/skills/broken-skill/SKILL.md
?? workspace/skills/broken-skill/cache/

4. ⚠️ 硬重置将永久删除这些更改。
使用软重置以保留更改未暂存？

[用户确认硬重置]

5. 执行硬重置...
$ git reset --hard abc1234

输出：✓ 已回滚到技能安装前（abc1234）

辅助操作

查看历史

bash

显示最近的提交

git log --oneline -10

显示上次提交的更改内容

git show --stat HEAD

比较当前状态与上次提交

git diff HEAD

检查状态

bash

查看未提交的更改

git status

查看差异摘要

git diff --stat

列出受保护文件

版本控制跟踪的文件（在git中）：
bash
git ls-files

验证.gitignore

bash

检查.gitignore是否存在

test -f ~/.openclaw/.gitignore && echo ✓ .gitignore存在 || echo ✗ 缺失

测试文件是否会被忽略

git check-ignore -v path/to/file

.gitignore配置

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

gitignore

会话日志（易变）

*.jsonl
*.jsonl.lock
.jsonl.reset.

数据库（易变）

*.sqlite *.sqlite-journal

凭证（敏感 - 绝不提交）

credentials/ *.pem *.key *.token

临时文件

*.tmp *.temp .DS_Store

日志

logs/

投递队列

delivery-queue/

Python缓存

pycache/ *.pyc *.pyo

技能管理器存档

.skill-manager/archive/

决策树

用户请求敏感操作
↓
是否需要保存？
┌─────┴─────┐
是否
↓ ↓
先保存直接执行
↓
[检查.gitignore]
↓
[扫描敏感文件]
↓
[自主操作需确认]
↓
执行操作
↓
成功？
┌─────┴─────┐
是否
↓ ↓
完成需要回滚？
┌─────┴─────┐
是否
↓ ↓
[尝试软重置] 手动调试
↓
[仅确认后硬重置]

git-version-controlGit版本控制