Session Storage Management

Analyze and clean up OpenClaw session storage files. Use when the user wants to manage session files, clean up old sessions, delete cron/heartbeat, or organi...

Security Scan

The skill's instructions match the stated purpose (scanning and deleting session files) but they rely on filesystem access and shell tools while the registry metadata declares no required paths or binaries — an incoherence worth investigating before install.

Purpose & Capability

The name and description match the instructions: analyzing and deleting OpenClaw session files. However, the skill's metadata declares no required config paths or binaries, yet the SKILL.md explicitly references a sessions directory (~/.openclaw/agents/main/sessions/) and file operations. The missing declaration of config paths is an inconsistency.

Instruction Scope

SKILL.md instructs scanning session files, parsing their contents, and deleting files after confirmation — all within the claimed purpose. But it also assumes access to 'session context' / 'system prompt' and uses shell commands (bash, head, jq, grep) without declaring those requirements. File deletion is inherently sensitive; the instructions correctly require explicit confirmation, but the scope of file access is broader than the declared metadata.

Install Mechanism

This is an instruction-only skill with no install spec or code files, which minimizes installation risk. No artifacts are downloaded or written by an installer.

Credentials

The skill requests no environment variables or credentials (appropriate). However, it implicitly requires access to agent/session filesystem paths and relies on command-line tools (jq, grep, head). Those accesses are not declared in requires.configPaths or required binaries, creating a proportionality gap between declared and actual needs.

Persistence & Privilege

The skill is not always-enabled and does not request persistent elevated privileges. It doesn't declare behavior that would modify other skills or system-wide settings.

What to consider before installing

This skill performs file-system operations (scanning and deleting OpenClaw session files) and expects to read from a sessions directory and use shell tools like jq/grep. Before installing: 1) Confirm you are comfortable granting the agent access to the sessions folder (e.g., ~/.openclaw/agents/...); 2) Ensure required command-line tools (jq, grep, head, bash) are available or ask the publisher to declare them; 3) Backup sessions if you may need them later; 4) Ask the publisher why requires.configPaths and required binaries are empty despite the SKILL.md referencing specific paths and shell utilities. If you proceed, carefully verify deletion candidates and rely on the explicit confirmation prompts the skill describes.

Overview

This skill helps analyze and clean up OpenClaw session files stored in the agents sessions directory. It categorizes sessions by type (cron, chat, deleted, reset, heartbeat), presents them to the user for review, and handles safe deletion while protecting the current active session.

Workflow

Step 1: Analyze Session Files

Scan the sessions directory and categorize all session files:

1. Active .jsonl files - Current session files

   • Cron sessions (isolated cron job runs)
   • Heartbeat sessions
   • Chat sessions (direct conversations)
   • Supergroup/other test sessions

2. .deleted.<timestamp> files - Previously deleted sessions

3. .reset.<timestamp> files - Sessions from /new or /reset commands

Step 2: Identify Current Session

Always identify and exclude the current session from deletion candidates:

# Get current session ID from session context
# It will be in the system prompt or can be extracted from the current session file

The current session should NEVER be deleted without explicit user confirmation in a separate step.

Step 3: Present Categories to User

Show summary statistics:

📊 Session Analysis Summary:
├── Active .jsonl files: N total
│   ├── Cron sessions: N
│   ├── Heartbeat sessions: N
│   ├── Chat sessions: N
│   └── Other sessions: N
├── .deleted files: N
└── .reset files: N

✅ Current session (protected): <session-id>

Then ask the user:

"Would you like me to:

1. Show the full detailed list of all sessions with descriptions
2. Delete specific categories (e.g., 'delete all cron and .deleted files')
3. Delete everything except the current session"

Step 4: Handle Current Session Warning

If the current session appears in any deletion category (it shouldn't, but check anyway), display a prominent warning:

⚠️  WARNING: Your current session was found in the deletion list!
   Session: <session-id>
   
This is the session you're currently using. Deleting it will not affect
your current conversation, but the session file will be removed.

Do you want to delete your current session file as well? (yes/no)

Step 5: Execute Deletion

After user confirmation:

1. Delete confirmed files
2. Report count and types of deleted files
3. Show remaining files
4. Estimate disk space freed

Categorization Logic

Analyze session content to determine type:

# Example analysis
content=$(head -10 "$file" | jq -r '.message.content[]? | select(.type=="text") | .text' 2>/dev/null | head -5)

if echo "$content" | grep -qiE "cron.*[a-f0-9-]{36}"; then
    type="cron"
elif echo "$content" | grep -qiE "heartbeat|HEARTBEAT"; then
    type="heartbeat"
elif echo "$content" | grep -qiE "new session|Session Startup"; then
    type="chat"
else
    type="other"
fi

Safety Rules

1. Never delete without explicit confirmation - Always show what will be deleted and wait for "yes"
2. Protect current session - Exclude it from bulk deletion, ask separately if user wants it deleted
3. Preserve last chat session - If multiple chat sessions exist, keep at least the most recent one unless user explicitly says otherwise
4. Report everything - Show full list of files being deleted with their sizes

Example Session Analysis Output

╔══════════════════════════════════════════════════════════════╗
║ SESSION ANALYSIS                                             ║
╚══════════════════════════════════════════════════════════════╝

📁 Location: ~/.openclaw/agents/main/sessions/

Category Breakdown:
  🕐 Cron sessions: 13 (isolated job runs)
  💓 Heartbeat sessions: 1  
  💬 Chat sessions: 2
  🗑️  .deleted files: 14
  🔄 .reset files: 23

Total files: 56
Estimated size: 12 MB

✅ Protected: <current-session-id> (current conversation)