Session Guardian — Never Lose a Conversation Again

Never lose a conversation again. Auto-backup, smart recovery, and health monitoring for OpenClaw sessions. Protects against gateway crashes, model disconnect...

Security Scan

The skill's purpose (local session backup and recovery) is coherent, but there are several mismatches and defaults that could cause unexpected data disclosure or hidden LLM/network activity — review config and install scripts before installing.

Purpose & Capability

The declared purpose (local backups, snapshots, health checks) matches the included scripts that read ~/.openclaw/agents/*/sessions and create local backups. However the repo also includes delivery/remote-sync/summary configuration (DELIVERY_ENABLED=true, REMOTE_SYNC_* options, SUMMARY_MODEL, KNOWLEDGE_EXTRACTION_ENABLED=true) that extend beyond pure local backups. SKILL.md claims "All backups stay local" and "Zero Token Cost", but config and scripts enable push/summary/extraction features that can call models or push data to external channels — this is an incoherence between claimed purpose and default capabilities.

Instruction Scope

SKILL.md instructs running install.sh which will configure cron jobs and run scripts that read all agent session files (~/.openclaw/agents/*/sessions). The instructions claim backups are local and non-networked, yet config.sh contains delivery and remote-sync settings and templates for SUMMARY_PROMPT_TEMPLATE and SUMMARY_MODEL (which imply LLM usage). The runtime instructions do not call out that daily summaries / knowledge extraction / delivery may send conversation data outside the machine if those features are enabled.

Install Mechanism

No external download/install spec is declared and scripts are included in the package (no network fetch of arbitrary code). install.sh (present in repo) will modify crontab/OpenClaw cron and create directories under ~/.openclaw/workspace/skills/session-guardian and Assets/SessionBackups. This is expected for a backup tool but you should inspect install.sh before running because it will create scheduled jobs that run frequently (every 5 minutes / hourly / daily).

Credentials

Registry metadata lists no required env vars or credentials, but config.sh defines many optional external integration fields (ALERT_WEBHOOK, REMOTE_RSYNC_HOST/USER/PATH, REMOTE_RCLONE_REMOTE, DELIVERY_CHANNEL/TARGET, GPG_KEY_ID, SUMMARY_MODEL). Defaults enable DELIVERY_ENABLED=true and KNOWLEDGE_EXTRACTION_ENABLED=true and set SUMMARY_MODEL to an external model name — meaning sensitive conversation content could be routed or summarized by external services if the defaults are left as-is. Additionally, scripts rely on tools (jq, rsync, gzip/pigz, find, cron) but the skill declares no required binaries — a mismatch that may cause failures or hidden behavior.

Persistence & Privilege

The skill does not request 'always: true' and uses standard cron for persistence; that is expected for a backup tool. It will gain ongoing presence via scheduled jobs and access to all agent session directories under the user's home, which is proportional to its stated goal but increases blast radius (frequent automated reads of all sessions).

Scan Findings in Context

[pre-scan-injection-none] expected: Static pre-scan reported no injection signals. This does not contradict the concerns above (which come from configuration and defaults, not regex-detected malicious patterns).

What to consider before installing

What to check before installing: 1) Inspect scripts/install.sh and scripts/*.sh yourself (or with a trusted admin) before running — install.sh will add cron jobs that run frequently and will read all session files under ~/.openclaw/agents. 2) Open and edit config.sh defaults before deployment: - Set DELIVERY_ENABLED=false (default is true) if you do not want any automatic push of summaries/backups to chat channels or external endpoints. - Ensure REMOTE_SYNC_ENABLED=false unless you deliberately want to sync backups to a remote host; if you do, provide and verify credentials securely. - If you want backups encrypted, set ENCRYPTION_ENABLED=true and configure GPG_KEY_ID before running. - If you do not want token/LLM usage, disable KNOWLEDGE_EXTRACTION_ENABLED and any SUMMARY_MODEL settings (SKILL.md's "zero token cost" claim is inconsistent with these enabled defaults). 3) Confirm required system tools are present (jq, rsync or rclone, gzip/pigz, cron) — the package scripts use jq and rsync-like behavior but the skill metadata declares no required binaries. 4) Run installation in a safe environment or test account first (to confirm behavior and verify no unintended pushes or remote syncs occur). 5) Audit the backup directory permissions (~/.openclaw/workspace/Assets/SessionBackups) and logs after a test run; verify backups are stored where you expect and not transmitted externally. 6) If you need stronger guarantees, ask the maintainer for minimal configuration examples that explicitly disable delivery/remote sync and LLM calls, and for a signed release or repository URL to verify provenance.

Session Guardian 🛡️

Never lose a conversation again.

  Without Guardian                    With Guardian
┌──────────────────┐            ┌──────────────────────────┐
│ Gateway crashes  │            │  Auto-backup every 5 min │
│ → conversation   │            │  Hourly snapshots        │
│   gone forever   │            │  Health monitoring       │
│                  │            │  One-command recovery    │
│ Token overflow   │            │                          │
│ → agent frozen   │            │  Gateway crash?          │
│                  │            │  → Restore in seconds    │
│ No way back. 😱  │            │                          │
└──────────────────┘            │  Token overflow?         │
                                │  → Auto-detected + alert │
                                │                          │
                                │  Always protected. 🛡️    │
                                └──────────────────────────┘

The Problem

Your OpenClaw conversations live in session files. When things go wrong — and they will — you lose everything:

• 🔴 Gateway restart → entire conversation history gone
• 🔴 Model disconnection → mid-task context wiped out
• 🔴 Token overflow → session too large, agent slows down or crashes
• 🔴 Disk issues → session files corrupted or lost

No built-in backup. No recovery. No warning before it's too late.

The Fix

clawhub install session-guardian
bash ~/.openclaw/workspace/skills/session-guardian/scripts/install.sh

That's it. Five layers of protection, running automatically.

How It Works

Layer 1: Incremental Backup    → Every 5 min   → New conversations saved
Layer 2: Hourly Snapshot       → Every hour     → Full session snapshots
Layer 3: Health Check          → Every 6 hours  → Detect problems early
Layer 4: Smart Summary         → Daily          → Key info extracted
Layer 5: Knowledge Extraction  → Daily          → Best practices saved

All automatic. All in the background. Zero manual work.

Quick Start

# Install
clawhub install session-guardian

# Deploy (sets up all cron jobs automatically)
cd ~/.openclaw/workspace/skills/session-guardian
bash scripts/install.sh

# Check status
bash scripts/status.sh

What You Get

• ✅ Auto-backup every 5 minutes — never lose more than 5 min of conversation
• ✅ Hourly snapshots — full point-in-time recovery
• ✅ Health monitoring — warns before token overflow crashes your agent
• ✅ One-command recovery — restore any session from any backup
• ✅ Multi-agent support — protects all your agents, not just main
• ✅ Collaboration tracking — see task flow across agents (King → Lead → Members)
• ✅ Knowledge extraction — auto-saves best practices from conversations
• ✅ Minimal overhead — ~10-15k tokens/day, ~1-2MB/agent/month

Usage

Check Status

bash ~/.openclaw/workspace/skills/session-guardian/scripts/status.sh

Shows: backup count, last backup time, snapshot count, cron jobs, disk usage.

Run Health Check

bash ~/.openclaw/workspace/skills/session-guardian/scripts/health-check.sh

Detects: oversized sessions, missing configs, disk space issues, gateway problems.

Restore a Session

# List available backups
bash ~/.openclaw/workspace/skills/session-guardian/scripts/restore.sh list

# Restore specific agent
bash ~/.openclaw/workspace/skills/session-guardian/scripts/restore.sh restore --agent main

View Collaboration Health (Multi-Agent)

bash ~/.openclaw/workspace/skills/session-guardian/scripts/collaboration-health.sh report

Track Task Flow

bash ~/.openclaw/workspace/skills/session-guardian/scripts/collaboration-tracker.sh trace "task name"

Cron Jobs (Auto-Configured)

After install.sh, these run automatically:

Schedule	Task	What it does
Every 5 min	Incremental backup	Save new conversations
Every hour	Snapshot	Full session archive
Every 6 hours	Health check	Detect problems
Daily 2am	Smart summary	Extract key info

File Structure

Assets/SessionBackups/
├── incremental/     # Every-5-min backups
├── hourly/          # Hourly snapshots
├── collaboration/   # Task flow records
└── Knowledge/       # Extracted best practices

All backups stay local. Nothing leaves your machine.

Who Is This For

Solo Agent User

✅ Protect your main conversation from crashes ✅ Get warned before token overflow kills your agent ✅ Recover in seconds, not hours of re-explaining

Multi-Agent Team

✅ Protect all agents (King + team leads + members) ✅ Track collaboration: who assigned what, who finished what ✅ Health scoring: monitor team communication quality ✅ Knowledge extraction: auto-save best practices from every agent

Troubleshooting

Problem	Fix
Backups not running	Check crontab -l | grep session-guardian
Agent slow/timing out	Run health-check — likely token overflow
Can't restore	Run restore.sh list to see available backups
Disk filling up	Check config retention settings (default: 7 days incremental, 30 days snapshots)

Configuration

Edit scripts/config.sh to customize:

BACKUP_DIR         # Where backups go (default: Assets/SessionBackups)
INCREMENTAL_KEEP   # Days to keep incremental backups (default: 7)
SNAPSHOT_KEEP      # Days to keep snapshots (default: 30)
MAX_SESSION_SIZE   # Alert threshold for session size (default: 5MB)

Security

• All data stays local — no external services, no network requests
• No API keys required
• Backups are excluded from git (add to .gitignore)
• Does not modify your session files — only reads and copies

Performance

Operation	Tokens	Storage
Incremental backup	~100/run	~10KB/session/day
Hourly snapshot	~500/run	~100KB/session/day
Health check	~200/run	~2KB/report
Daily summary	~5k/run	~5KB/day
Total	~10-15k/day	~1-2MB/agent/month

Feedback

• Star: clawhub star session-guardian
• Update: clawhub update session-guardian

---

🇨🇳 中文说明

Session Guardian 🛡️ — 再也不丢对话

你的 OpenClaw 对话存在 session 文件里。Gateway 一重启、模型一断连、token 一溢出——对话就没了。没有备份，没有恢复，没有预警。

痛点

• 🔴 Gateway 重启 → 整个对话历史消失
• 🔴 模型断连 → 做到一半的任务上下文全丢
• 🔴 Token 溢出 → session 太大，Agent 变慢甚至崩溃
• 🔴 磁盘问题 → session 文件损坏或丢失

解决方案

clawhub install session-guardian
bash ~/.openclaw/workspace/skills/session-guardian/scripts/install.sh

五层自动防护，后台运行，零手动操作。

五层防护

层级	频率	作用
增量备份	每 5 分钟	保存新对话，最多丢 5 分钟
快照备份	每小时	完整 session 存档，支持回滚
健康检查	每 6 小时	提前发现问题（token 溢出、磁盘不足）
智能总结	每天	提取关键信息到 MEMORY.md
知识沉淀	每天	自动保存最佳实践

你会得到

• ✅ 自动备份 — 每 5 分钟一次，最多丢 5 分钟对话
• ✅ 一键恢复 — 从任意备份点恢复 session
• ✅ 健康监控 — 在 token 溢出前预警
• ✅ 多 Agent 支持 — 保护所有 Agent，不只是 main
• ✅ 协作追踪 — 可视化任务流转（King → 团长 → 成员）
• ✅ 知识沉淀 — 自动从对话中提取最佳实践
• ✅ 极低开销 — 每天约 10-15k tokens，每月约 1-2MB/Agent

常用命令

# 查看状态
bash scripts/status.sh

# 健康检查
bash scripts/health-check.sh

# 恢复 session
bash scripts/restore.sh list
bash scripts/restore.sh restore --agent main

# 协作健康度（多 Agent）
bash scripts/collaboration-health.sh report

适用场景

个人用户：保护主对话不丢失，token 溢出前预警，秒级恢复

多 Agent 团队：保护所有 Agent，追踪协作链路，自动沉淀知识

安全性

• 所有数据本地存储，不联网，不需要 API Key
• 不修改 session 文件，只读取和复制
• 备份文件已排除 git 追踪