Safe Guard

Name: Safe Guard
Rating: 3.5 (1 reviews)
Author: wezuntanglang-create

By wezuntanglang-create 👁 48 views ▲ 0 votes

OpenClaw plugin: auto-backup critical workspace files before writes, warn on missing memory updates

GitHub

Install

openclaw plugins install github:wezuntanglang-create/openclaw-safe-guard

Configuration Example

{
  "plugins": {
    "entries": {
      "safe-guard": {
        "enabled": true,
        "config": {
          "protectedFiles": ["cron/jobs.json", "my-config.yaml"],
          "maxBackups": 5
        }
      }
    }
  }
}

README

# openclaw-safe-guard

Auto-backup critical workspace files before agent writes, rotate old backups, and warn when protected files change without memory updates.

## What It Does

Three hooks, zero friction:

1. `before_tool_call` — When an agent `write`s or `edit`s a protected file, Safe Guard copies the current version to a timestamped `.bak-*` file (atomic copy-then-rename). Old backups are auto-rotated to stay within the configured limit.

2. `after_tool_call` — Logs whether the protected file write succeeded or failed, giving you an audit trail in `gateway.log`.

3. `agent_end` — Checks if the session modified any protected files but never wrote to `memory/` or `MEMORY.md`. If so, it logs a warning. Regular file edits without memory writes are normal and don't trigger warnings.

Session state is tracked in-memory with a 2-hour TTL safety net, so crashed sessions won't leak memory.

## Scope

This plugin protects against accidental overwrites via OpenClaw's `write` and `edit` tools. It does not monitor `exec` commands — shell commands can modify files in ways that are impractical to detect reliably via string matching. If you need full file-system protection, use git auto-commit or filesystem snapshots.

## Default Protected Files

- `SOUL.md`, `AGENTS.md`, `openclaw.json`, `MEMORY.md`
- `IDENTITY.md`, `USER.md`, `HEARTBEAT.md`, `writing-prompt.txt`

## Configuration

```json
{
  "plugins": {
    "entries": {
      "safe-guard": {
        "enabled": true,
        "config": {
          "protectedFiles": ["cron/jobs.json", "my-config.yaml"],
          "maxBackups": 5
        }
      }
    }
  }
}
```

- `protectedFiles` — Extra file names or path suffixes to protect (merged with defaults, you can't remove defaults).
- `maxBackups` — Max backup copies per file (default: 5). Oldest are auto-deleted when exceeded.

## Install

```bash
openclaw plugins install github:wezuntanglang-create/openclaw-safe-guard
```

Or copy the directory to `~/.openclaw/extensions/safe-guard/` and enable in config.

## How Backups Work

When `SOUL.md` is about to be written:

```
SOUL.md  →  SOUL.bak-2026-03-22T18-30-00.md
```

Backups are created in the same directory via copy-to-tmp then atomic rename. When the backup count exceeds `maxBackups`, the oldest copies are deleted automatically.

## Logs

All activity goes to `gateway.log` with the `[safe-guard]` prefix:

```
[safe-guard] loaded v0.4.0 — protecting 8 pattern(s), max 5 backups each
[safe-guard] protected write detected: edit -> SOUL.md (session: abc123)
[safe-guard] backup: SOUL.md -> SOUL.bak-2026-03-22T18-30-00.md
[safe-guard] rotated old backup: SOUL.bak-2026-03-15T10-00-00.md
[safe-guard] protected write OK: SOUL.md
[safe-guard] session abc123 modified protected file(s) without writing memory: SOUL.md
```

## Design Decisions

- Never blocks writes — backup only. Fork and return `{ block: true }` from `before_tool_call` if you want blocking.
- No `exec` monitoring — shell command string matching gives false security. We're honest about what we cover.
- Backup rotation prevents `.bak-*` file accumulation.
- Memory warnings only fire when protected files are modified without memory updates. Regular file edits don't trigger warnings.
- Session state has a 2-hour TTL cleanup to prevent memory leaks from crashed sessions.

## License

MIT

tools