OpenClaw Config Guardian

Auto backup & one-click rollback for OpenClaw configuration.

✨ Features

| Feature | Description | |---------|-------------| | 🔄 Auto Backup | Automatic daily backups at 2:00 AM (only when OpenClaw is healthy) | | 🌐 Web UI | Beautiful web interface at fixed port 3737 | | ⚡ One-Click Rollback | Restore to any backup point instantly | | 🏥 Health Check | Verifies OpenClaw status before backup | | 🧹 Auto Cleanup | Keeps only the latest N backups automatically | | 🖥️ CLI Support | Full command-line interface | | 🔧 Fixed Port | Web UI always at http://localhost:3737 |

🚀 Quick Start (推荐 - 3步上手)

非技术用户最简单的使用方式：

# 1. 安装插件
npm install -g openclaw-config-guardian

# 2. 启动 Web UI（不要关闭命令行窗口）
ocg webui

# 3. 浏览器访问 http://localhost:3737
# 在网页上点击"立即备份"或"回滚"即可

📖 其他使用方式

Option 1: npx (无需安装)

npx openclaw-config-guardian webui

Option 2: 命令行方式

# 安装
npm install -g openclaw-config-guardian

# 使用
ocg status      # 查看状态
ocg backup      # 手动备份
ocg list        # 查看备份列表
ocg restore <id> # 回滚到指定备份

📖 Usage

CLI Commands

# View status
openclaw-config-guardian status

# Create backup immediately
openclaw-config-guardian backup

# List all backups
openclaw-config-guardian list

# Restore to specific backup
openclaw-config-guardian restore backup-2024-01-01T00-00-00-000Z

# Delete a backup
openclaw-config-guardian delete backup-2024-01-01T00-00-00-000Z

# Start Web UI
openclaw-config-guardian webui

# Show help
openclaw-config-guardian help

Web UI

Start the Web UI and open http://localhost:3737:

openclaw-config-guardian webui

Features:

• Toggle auto backup on/off
• View system status
• Create backups with one click
• Restore to any backup point
• Delete old backups

⚙️ Configuration

Edit ~/.openclaw/extensions/openclaw-config-guardian/config.json:

{
  "autoBackup": true,
  "maxBackups": 10,
  "webUIPort": 3456,
  "backupItems": [
    "config.json",
    "gateway.json",
    "agents.json",
    "skills.json",
    "memory",
    "workspace"
  ]
}

| Option | Description | Default | |--------|-------------|---------| | autoBackup | Enable automatic daily backups | true | | maxBackups | Maximum backups to keep | 10 | | webUIPort | Port for Web UI (fixed at 3737) | 3737 | | backupItems | Files/directories to backup | See above |

📦 What's Backed Up

By default, the following are backed up:

• config.json - Main configuration
• gateway.json - Gateway configuration
• agents.json - Agents configuration
• skills.json - Skills configuration
• memory/ - Memory files
• workspace/ - Workspace files

🔒 Safety Features

• Emergency Backup: Before rollback, current config is backed up
• Health Check: Only backs up when OpenClaw is running normally
• Auto Cleanup: Old backups are automatically deleted
• Safe Restore: Stops Gateway before restore, restarts after

🛠️ Development

# Clone the repo
git clone https://github.com/openclaw/config-guardian.git
cd config-guardian

# Install dependencies
npm install

# Build
npm run build

# Local install
npm install -g .

# Or use local script
bash scripts/install.sh --local

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📄 License

MIT License - see LICENSE file for details.

📝 Changelog

v1.0.13 (2026-05-14)

• ✅ Improved: Backup now includes all config file types (.md, .json, .yaml, .yml, .toml, .ini, .conf, .config)
• ✅ Improved: Rollback now properly cleans up old files not in backup (true replacement)
• ✅ Improved: Web UI backup list shows max 2 lines with ellipsis for long file lists
• ✅ Fixed: Better file display with tooltip showing full list on hover

v1.0.12 (2026-05-09)

• ✅ Improved: README Quick Start simplified to 3 steps for non-technical users
• ✅ Fixed: npm badge link to correct package name

v1.0.11 (2026-05-09)

• ✅ Improved: Web UI backup list now shows max 3 items with "X more" indicator
• ✅ Fixed: Backup list layout issues with many files

v1.0.10 (2026-05-09)

• ✅ Fixed: Auto-detect and migrate old config to new auto-scan mode
• ✅ Fixed: No more "file not found" warnings for old hardcoded files
• ✅ Fixed: Properly backup all .md and .json files including openclaw.json

v1.0.9 (2026-05-09)

• ✅ Changed: Auto-scan all .md and .json files in ~/.openclaw/
• ✅ No need to manually specify backup items - automatically finds all config files

v1.0.8 (2026-05-09)

• ✅ Fixed: Backup correct OpenClaw config files:
  • openclaw.json
  • workspace/agents.md, bootstrap.md, heartbeat.md, memory.md, soul.md, tools.md, user.md

v1.0.7 (2026-05-09)

• ✅ Changed: Backup entire ~/.openclaw/ directory instead of specific files
• ✅ Added: Exclude large files (logs, cache, node_modules) from backup
• ✅ Improved: Emergency backup also uses exclude patterns

v1.0.6 (2026-05-09)

• ✅ Fixed: Web UI conflicts with OpenClaw Gateway by using pgrep instead of openclaw gateway status

v1.0.5 (2026-05-09)

• ✅ Fixed: Invalid date display for last backup time
• ✅ Fixed: Restore success message not showing in Web UI

v1.0.4 (2026-05-09)

• ✅ Fixed: Web UI restore API endpoint mismatch

v1.0.3 (2026-05-09)

• ✅ Fixed: Web UI static files not included in npm package

v1.0.2 (2026-05-09)

• ✅ Added: Detailed rollback status (config restored + Gateway start status)
• ✅ Added: Clear error messages when Gateway fails to start after rollback
• ✅ Improved: Web UI shows warning when Gateway start fails

v1.0.1 (2026-05-09)

• ✅ Fixed: Gateway status detection
• ✅ Fixed: Invalid date display in Web UI
• ✅ Fixed: Rollback failure due to URL encoding
• ✅ Fixed: Web UI port now fixed at 3737
• ✅ Improved: Better error handling

v1.0.0 (2026-05-08)

• 🎉 Initial release

Made with ❤️ for the OpenClaw community