Tools
Filesafe
By Zero-friction file protection for OpenClaw workspaces. One command tool to keep your local files safe while AI agents work. Web dashboard included (EN/中文).
Install
npm install openclaw-filesafeREADME
# 🛡️ OpenClaw-filesafe
**Zero-friction file safety layer for AI agents.** Automatic snapshots, protected trash, vault mode, skill monitoring — one command to set up, zero friction to use.
---
## What filesafe does
filesafe adds three layers of file protection to your OpenClaw workspace:
```
Layer 1: Isolation (分区隔离)
Your files live in a "safe zone" that OpenClaw cannot see.
Sensitive files are transferred through a vault push/pull workflow
with diff review — OpenClaw never touches the originals.
Layer 2: Version Control (版本控制)
Every file change is automatically snapshotted.
Full version history, one-command rollback.
Like an invisible Git that commits on every save.
Layer 3: Recycle Bin (回收站)
Deleted files go to a protected trash — not the OS trash
that OpenClaw can empty. Password-protected permanent deletion.
Nothing is ever truly lost.
```
On top of these three hard layers, filesafe also generates a `SAFETY.md` that tells OpenClaw *how to behave* — risk-level rules, modification confirmations, skill installation restrictions. The LLM mostly follows these rules, but even when it doesn't, the three hard layers catch it.
Everything is visible through a **bilingual web dashboard** (English / 简体中文) at `http://127.0.0.1:9090` — run `filesafe ui` to open it.
---
## Quick Start
```bash
# Install
npm install openclaw-filesafe
# Initialize (one-time setup)
npx filesafe init
# Protect a project folder
npx filesafe project ~/my-app
# Want to go back? Roll back:
npx filesafe rollback ~/my-app/src/main.ts
# File was deleted? Restore:
npx filesafe trash restore main.ts
# Check status anytime:
npx filesafe status
# Or open the web dashboard:
npx filesafe ui
```
<details>
<summary>Install from source (if interested)</summary>
```bash
git clone https://github.com/griffithfly/OpenClaw-filesafe.git
cd OpenClaw-filesafe
npm install
npm run build
```
</details>
---
## Features
### 📊 Web Dashboard
Visual status dashboard at `http://127.0.0.1:9090`. Bilingual (EN/中文). Works offline.
```bash
filesafe ui
```
### 🔄 Auto Snapshots & Rollback
Every file change is captured automatically. View history, roll back to any version.
```bash
filesafe history <file>
filesafe rollback <file> [--to <version>]
```
### 🗑️ Protected Trash
Deleted files go to filesafe's own trash (outside OpenClaw's reach). Restore anytime.
```bash
filesafe trash list
filesafe trash restore <file>
```
### 🔐 Vault Mode
Sensitive files (SSH keys, credentials) stay isolated. Push copies to OpenClaw, pull back with diff review.
```bash
filesafe vault add ~/.ssh
filesafe push ~/.ssh/config # copy to inbox (password required)
filesafe pull config --to ~/.ssh/config # review diff, confirm, write back
```
### 🔍 Skill Monitoring
Detects when OpenClaw silently installs third-party skills. Alerts you to review.
```bash
filesafe skill alerts
filesafe skill ack <name>
```
### 📋 Audit Log
Every operation logged with risk levels (CRITICAL/HIGH/MEDIUM/LOW). Sensitive info auto-redacted.
```bash
filesafe audit --risk high --last 1h
```
### 🩺 Security Check
Scans OpenClaw's config for common misconfigurations. Gives recommendations, never modifies.
```bash
filesafe check
```
---
## Architecture
```
┌─────────────────────────────────────┐
│ Your Workspace │
├─────────────────────────────────────┤
│ │
│ Soft Layer SAFETY.md rules │ ← AI agent reads and (mostly) follows
│ │
├─────────────────────────────────────┤
│ │
│ Hard Layer 1 Vault Isolation │ ← Sensitive files physically separated
│ Hard Layer 2 Auto Snapshots │ ← Every change captured, rollback anytime
│ Hard Layer 3 Protected Trash │ ← Deleted files recoverable
│ │
├─────────────────────────────────────┤
│ SQLite + Watcher + Supervisor │ ← Background daemon, auto-restart
└─────────────────────────────────────┘
```
OpenClaw's native security handles **prevention**. filesafe handles **recovery**.
Together they form complete protection.
---
## All Commands
| Command | Description |
|---------|-------------|
| `filesafe init` | Initialize protection + SAFETY.md + security check |
| `filesafe project <path>` | Register and protect a project |
| `filesafe project list` | List protected projects |
| `filesafe start` / `stop` | Start/stop background watcher |
| `filesafe status` | Show protection status |
| `filesafe status --json` | Machine-readable status |
| `filesafe history <file>` | File version history |
| `filesafe rollback <file>` | Restore previous version |
| `filesafe trash list` / `restore` | View/restore deleted files |
| `filesafe vault add` / `list` / `remove` | Manage vault paths |
| `filesafe push <file>` | Copy vault file to inbox |
| `filesafe pull <file> --to <dest>` | Review diff and write back |
| `filesafe password set` / `clear` / `status` | Vault password management |
| `filesafe skill list` / `alerts` / `ack` | Skill monitoring |
| `filesafe audit [filters]` | Operation audit log |
| `filesafe safety generate` | Generate/regenerate SAFETY.md |
| `filesafe check` | OpenClaw security configuration check |
| `filesafe ui` | Web dashboard (port 9090) |
---
## Roadmap
**Completed**: Snapshots, trash, rollback, background watcher with auto-restart, SAFETY.md, audit log (sanitization + risk levels + anomaly detection), vault mode, skill monitoring, security check, web dashboard.
**Planned**: Delta compression for snapshots, configurable ignore patterns (.filesafeignore), actor detection (OpenClaw vs user), deeper OpenClaw integration, smarter anomaly rules, multi-project dashboards.
---
## License
MIT
tools
Comments
Sign in to leave a comment