Git Version Control | OpenClaw Configuration Protection#

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

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, IDENTITY.md
• workspace/skills/ - installed skills
• workspace/memory/ - memory files
• openclaw.json - main configuration
• cron/jobs.json - cron jobs

Excluded from version control:

• Session logs ( *.jsonl, *.jsonl.lock)
• SQLite databases ( *.sqlite)
• Temporary files
• Credentials (sensitive)

---

Core Operations#

1. SAVE - Create Checkpoint#

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

When to use:

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

Command Flow:

bash

cd ~/.openclaw

# Check current status
git status

# Add all tracked files (respecting .gitignore)
git add -A

# Create commit with descriptive message
git commit -m "checkpoint: {description of pending change}"

Implementation:

text

When user says: "save before..." or "create checkpoint"

1. Generate descriptive commit message based on context
2. Run: git add -A
3. Run: git commit -m "checkpoint: {description}"
4. Report commit hash and file count to user

Example:

text

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 - Restore Previous State#

Revert to a previous commit when issues occur.

When to use:

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

Rollback Options:

OptionCommandEffectSoft resetgit reset --soft HEAD~1Undo commit, keep changes stagedMixed resetgit reset --mixed HEAD~1Undo commit, keep changes unstagedHard resetgit reset --hard HEAD~1Completely undo commit and changes

Recommended default: --hard for full rollback

Implementation:

text

When user says: "rollback" or "undo last change" or "restore previous"

1. Show recent commits for user to choose
   git log --oneline -10

2. Confirm which commit to restore to
   "Rollback to commit X? This will discard: {list changes}"

3. Execute rollback
   git reset --hard {commit-hash}

4. Report result
   "✓ Rolled back to commit abc1234"

Example:

text

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

---

Helper Operations#

View History#

bash

# Show recent commits
git log --oneline -10

# Show what changed in last commit
git show --stat HEAD

# Compare current state to last commit
git diff HEAD

Check Status#

bash

# See uncommitted changes
git status

# See diff summary
git diff --stat

List Protected Files#

Files tracked for version control (in git):

bash

git ls-files

---

.gitignore Configuration#

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

gitignore

# Session logs (volatile)
*.jsonl
*.jsonl.lock
*.jsonl.reset.*

# Databases (volatile)
*.sqlite
*.sqlite-journal

# Credentials (sensitive)
credentials/
*.pem
*.key

# Temporary files
*.tmp
*.temp
.DS_Store

# Logs
logs/

# Delivery queue
delivery-queue/

---

Decision Tree#

text

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

---

Integration with Other Skills#

SkillIntegrationself-improvementRecord rollback events as learningsskill-creatorAuto-SAVE before creating new skillshealthcheckCheck git status during health checks

---

Safety Guidelines#

✅ Best Practices#

1. Always SAVE before risky operations

   • Installing skills from external sources
   • Modifying AGENTS.md, SOUL.md
   • Bulk memory updates

2. Use descriptive commit messages text

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

3. Verify before ROLLBACK

   • Show what will be lost
   • Confirm with user for hard reset

❌ Avoid#

1. Don't rollback without confirmation
   • Hard reset destroys uncommitted changes
   • Always warn user about data loss
2. Don't commit sensitive data
   • Check .gitignore excludes credentials
   • Never add credentials/ to git
3. Don't use for session data
   • Session logs are excluded intentionally
   • Focus on configuration, not runtime data

---

Quick Reference#

ActionCommandAliasSAVE checkpointgit add -A && git commit -m "checkpoint: {desc}"``saveROLLBACKgit reset --hard HEAD~1``rollbackView historygit log --oneline -10``historyCheck statusgit status``statusCompare diffgit diff HEAD``diff

---

Example Session#

text

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

---

Last updated: 2026-03-05