session-cleanup

Original source / Raw SKILL.md

---
name: session-cleanup
description: Clean orphan .jsonl files and stale sessions in OpenClaw session storage with safe confirmation flow. 适用于会话列表杂乱、历史会话堆积、需要释放存储空间场景；默认保护 72 小时内会话，删除前必须用户确认。
user-invocable: true
metadata:
  { "openclaw": { "emoji": "🧹", "requires": { "bins": ["bash", "node"] } }, "version": "0.3", "updatedAt": "2026-03-06 20:47 Asia/Shanghai" }
---

# Session Cleanup

清理 OpenClaw 会话目录中的孤儿文件与过期会话，优先安全、可审计。

## 使用方式

先扫描，再确认，再执行：

1. 扫描（只读）
2. 生成清理计划
3. 用户确认
4. 执行清理并回报结果

## 关键文件

- 扫描脚本：`scripts/scan_sessions.sh`
- 清理策略：`references/policy.md`

## 扫描命令（必做）

```bash
./skills/session-cleanup/scripts/scan_sessions.sh scan
```

返回 JSON 包含：
- `orphanFiles`：磁盘存在但 `sessions.json` 未登记的 `.jsonl`
- `staleSessions`：超过 72 小时且非受保护会话
- `protectedSessions`：当前会话 + 72 小时保护窗口内会话

## 执行规则

- 必须先扫描并展示摘要
- 必须询问用户确认后才清理
- 默认不删除受保护会话
- 永不删除 `agent:main:main`

## 清理建议

### A. 先处理孤儿文件（优先）

在用户确认后删除孤儿文件：

```bash
rm ~/.openclaw/agents/main/sessions/<orphan>.jsonl
```

### B. 再处理过期会话（谨慎）

仅在用户明确确认后执行，删除对应 `.jsonl`，并更新 `sessions.json` 去除条目。

## 输出模板

```markdown
🧹 会话清理扫描完成

- 注册会话：X
- 磁盘 jsonl：Y
- 孤儿文件：A
- 过期会话：B
- 受保护会话：C

预计可释放：N MB

是否按上述计划执行清理？
```

## 发布前自检

```bash
# 1) 脚本可执行
./skills/session-cleanup/scripts/scan_sessions.sh scan >/tmp/session-cleanup-report.json

# 2) 输出为有效 JSON
node -e "JSON.parse(require('fs').readFileSync('/tmp/session-cleanup-report.json','utf8')); console.log('OK')"
```


---

## Referenced Files

> The following files are referenced in this skill and included for context.

### scripts/scan_sessions.sh

```bash
#!/usr/bin/env bash
set -euo pipefail

MODE="${1:-scan}"
STATE_DIR="${OPENCLAW_STATE_DIR:-$HOME/.openclaw}"
AGENT_ID="${OPENCLAW_AGENT_ID:-main}"
SESSIONS_DIR="$STATE_DIR/agents/$AGENT_ID/sessions"
SESSIONS_JSON="$SESSIONS_DIR/sessions.json"
NOW_MS=$(node -e 'console.log(Date.now())')
PROTECT_MS=$((72*60*60*1000))

if [[ ! -f "$SESSIONS_JSON" ]]; then
  echo "ERROR: sessions.json not found: $SESSIONS_JSON" >&2
  exit 1
fi

node - "$SESSIONS_JSON" "$SESSIONS_DIR" "$NOW_MS" "$PROTECT_MS" "$MODE" <<'NODE'
const fs = require('fs');
const path = require('path');
const [sessionsJsonPath, sessionsDir, nowMsRaw, protectMsRaw, mode] = process.argv.slice(2);
const nowMs = Number(nowMsRaw);
const protectMs = Number(protectMsRaw);
const sessions = JSON.parse(fs.readFileSync(sessionsJsonPath, 'utf8'));

const registeredFiles = new Set();
const registeredRows = [];
for (const [key, meta] of Object.entries(sessions)) {
  const sf = meta?.sessionFile ? path.basename(meta.sessionFile) : null;
  if (sf) registeredFiles.add(sf);
  const updatedAt = Number(meta?.updatedAt || 0);
  const ageMs = updatedAt ? nowMs - updatedAt : Number.MAX_SAFE_INTEGER;
  const isProtected = key === 'agent:main:main' || ageMs < protectMs;
  registeredRows.push({
    key,
    sessionFile: sf,
    updatedAt,
    ageHours: updatedAt ? Math.round(ageMs / 36e5) : null,
    isProtected,
  });
}

const diskFiles = fs.readdirSync(sessionsDir)
  .filter((f) => f.endsWith('.jsonl'))
  .sort();

const orphans = diskFiles.filter((f) => !registeredFiles.has(f));

const stale = registeredRows
  .filter((r) => !r.isProtected)
  .sort((a, b) => (b.ageHours || 0) - (a.ageHours || 0));

const orphanSizeBytes = orphans.reduce((sum, f) => {
  const st = fs.statSync(path.join(sessionsDir, f));
  return sum + st.size;
}, 0);

const summary = {
  mode,
  sessionsDir,
  sessionsJsonPath,
  protectHours: 72,
  totals: {
    registered: registeredRows.length,
    onDiskJsonl: diskFiles.length,
    orphanCount: orphans.length,
    staleCount: stale.length,
    reclaimBytesOrphans: orphanSizeBytes,
  },
  orphanFiles: orphans,
  staleSessions: stale.map((r) => ({
    key: r.key,
    sessionFile: r.sessionFile,
    updatedAt: r.updatedAt,
    ageHours: r.ageHours,
  })),
  protectedSessions: registeredRows.filter((r) => r.isProtected).map((r) => ({
    key: r.key,
    sessionFile: r.sessionFile,
    updatedAt: r.updatedAt,
    ageHours: r.ageHours,
  })),
};

console.log(JSON.stringify(summary, null, 2));
NODE
```

### references/policy.md

```markdown
# 会话清理策略

## 安全原则

- 永远不删除当前主会话（`agent:main:main`）。
- 默认保护窗口：以 `updatedAt` 为准，72 小时内会话受保护。
- 必须先执行 `scan` 并展示报告，再进入清理。
- 清理前必须获得用户明确确认。

## 清理优先级

1. 孤儿 `.jsonl` 文件（磁盘存在但 `sessions.json` 无映射）
2. 超过保护窗口的过期会话

## 删除策略

- 默认优先归档/移动，而不是永久删除。
- 若用户要求硬删除，必须二次确认后执行。

## 建议交互流程

1. 扫描
2. 展示摘要（孤儿/过期/受保护）
3. 请求确认
4. 执行清理
5. 回报释放空间与清理结果

```



---

## Skill Companion Files

> Additional files collected from the skill directory layout.

### _meta.json

```json
{
  "owner": "irideas",
  "slug": "session-cleanup-pro",
  "displayName": "Session Cleanup Pro",
  "latest": {
    "version": "0.3.0",
    "publishedAt": 1772801322026,
    "commit": "https://github.com/openclaw/skills/commit/685d18d61fc5c66b73e8cddcc92cfdd52a8d2b35"
  },
  "history": []
}

```