---

name: gateway-auto-rollback description: | Automatic configuration rollback mechanism for OpenClaw Gateway. Provides three-layer protection: pre-modification backup, post-modification validation, and automatic rollback on failure. Includes a file watcher daemon, JSON validation, Gateway health checks, and SHA256 content-addressed backups. Use when modifying openclaw.json or other critical config files to prevent accidental breakage and ensure zero-downtime configuration changes.

Gateway Auto-Rollback

Three-layer configuration protection for OpenClaw Gateway — never break your config again.

What It Does

Automatically protects your OpenClaw configuration files with:

1. Pre-modification backup — SHA256 content-addressed snapshots before any change
2. Post-modification validation — JSON syntax check + Gateway health probe
3. Automatic rollback — instant restore if validation fails

When to Use

• Before modifying openclaw.json, exec-approvals.json, or skills.json
• When running automated config changes (cron jobs, scripts)
• As a background safety net during development
• When you want peace of mind that a bad config won't take down your agent

Quick Start

One-shot check (before manual edits)

python3 gateway-auto-rollback.py

This initializes the backup directory, validates current config, and logs status.

Watch mode (background daemon)

python3 gateway-auto-rollback.py --watch &

Monitors critical config files every 3 minutes. Auto-exits after 3 consecutive healthy checks (config is stable).

How It Works

Before Modification        During              After Modification
       ↓                    ↓                        ↓
  Backup + Hash  ───→  Execute Change  ───→  JSON Validate + Health Check
       │                                          │
       └──────────────────────────────────────→ Auto-rollback on failure

Protected Files

File	Description
openclaw.json	Main Gateway configuration
exec-approvals.json	Command execution approvals
skills.json	Skills registry

Backup Naming

Backups are stored in ~/.openclaw/backup/ with content-addressed names:

openclaw.json.20260301_053612.a1b2c3d4.bak
                 ↑ timestamp    ↑ SHA256 prefix (dedup)

API Reference

Python Functions

from gateway_auto_rollback import (
    pre_modification_check,   # Call before modifying config
    post_modification_verify, # Call after modifying config
    create_backup,            # Manual backup creation
    validate_json,            # JSON syntax validation
    check_gateway_health,     # Gateway health probe
    rollback_to_backup,       # Manual rollback
    watch_config_files,       # Start watch daemon
)

Pre-modification flow

from pathlib import Path

config = Path.home() / ".openclaw" / "openclaw.json"

# Returns backup path on success, False on failure
backup = pre_modification_check(config)

# ... make your changes ...

# Validates and auto-rolls back if needed
success = post_modification_verify(config, backup)

Watch mode details

The watcher:

• Polls every 3 minutes (gives Gateway time to restart)
• Detects changes via SHA256 hash comparison
• Auto-creates backup when change detected
• Validates JSON + health check after each change
• Auto-exits after 3 consecutive healthy checks (config stabilized)
• Logs all events to ~/.openclaw/logs/config-modification.log

Integration with Cron

Set up periodic health checks:

# Cron job example: check every hour
0 * * * * python3 /path/to/gateway-auto-rollback.py

Or use OpenClaw's built-in cron:

{
  "name": "Gateway-Auto-Rollback",
  "schedule": { "kind": "cron", "expr": "0 */6 * * *", "tz": "Asia/Shanghai" },
  "payload": {
    "kind": "agentTurn",
    "message": "Run gateway health check. If unhealthy, rollback to latest backup."
  },
  "sessionTarget": "isolated"
}

Manual Rollback

If you need to manually restore a config:

# List available backups (newest first)
ls -lt ~/.openclaw/backup/ | head -10

# Restore a specific backup
cp ~/.openclaw/backup/openclaw.json.20260301_053612.a1b2c3d4.bak \
   ~/.openclaw/openclaw.json

# Restart Gateway
openclaw gateway restart

# Verify
curl -s http://127.0.0.1:18789/api/health

Testing

Run the included test suite to verify the mechanism works:

bash test-rollback-mechanism.sh

Tests cover:

• Backup directory existence
• JSON validation
• SHA256 hash computation
• Backup creation and restore
• Watch daemon status
• Log file integrity
• Script permissions

Logs

All events are logged to ~/.openclaw/logs/config-modification.log:

[2026-03-01 05:37:00] INFO: ✅ 备份创建: openclaw.json.20260301_053612.a1b2c3d4.bak
[2026-03-01 05:37:01] INFO: ✅ 修改验证通过
[2026-03-01 05:40:00] WARN: ⚠️ 检测到修改: openclaw.json
[2026-03-01 05:40:01] ERROR: JSON 验证失败 — 触发回滚

Requirements

• Python 3.8+
• OpenClaw Gateway running (for health checks)
• No additional pip packages needed (stdlib only)

File Structure

gateway-auto-rollback/
├── SKILL.md                      # This file
├── _meta.json                    # ClawHub metadata
├── gateway-auto-rollback.py      # Main script (backup/validate/rollback/watch)
└── test-rollback-mechanism.sh    # Test suite