openclaw - 💡(How to fix) Fix acpx: completed sessions accumulate indefinitely — no auto-cleanup or TTL mechanism [1 participants]

Bug type

Bug / Resource Leak

OpenClaw version

OpenClaw 2026.4.2 (d74a122)

OS and install method

Linux 6.8.0-106-generic (x64), Node.js v24.14.1, npm global, systemd user service.

Summary

ACP acpx sessions accumulate across gateway restarts and are not automatically cleaned up. Even after sessions_spawn with mode: "run" (one-shot), session files persist on disk. A manual cleanup script found 81 dead sessions on a ~3-week-old instance. Session file growth is unbounded unless an external cleanup job is manually scheduled.

Steps to reproduce

1. Run acpx sessions on any instance that has been running for a few days
2. Observe all completed mode: "run" sessions remain listed indefinitely
3. Count files in the acpx sessions directory (typically under ~/.openclaw/) — it grows monotonically
4. Restart the gateway — sessions survive the restart

Expected behavior

Completed one-shot sessions (mode: "run") should be cleaned up automatically after a configurable TTL, or at least be archived/compressed rather than left as active session files indefinitely. The acpx sessions list should default to showing only active or recently completed sessions.

Actual behavior

Session files persist indefinitely. A clean 3-week-old instance had 81+ dead sessions (most [closed]), many from one-shot coding agent spawns that completed days ago. Gateway restarts do not trigger any cleanup.

Logs and evidence

Live instance evidence (April 4, 2026):

$ acpx sessions | grep '\[closed\]' | wc -l
70+ closed sessions from regression tests, audit tasks, and daily work

A custom cleanup script (acpx-sessions-cleanup.sh) removed 81 dead sessions freeing no critical space, but demonstrating the accumulation rate is ~3-4 sessions per day with moderate ACP usage.

Impact

• Disk space: Each session file is small (~few KB) but hundreds of sessions over months will accumulate
• Session bloat: acpx sessions output becomes noise-filled with closed sessions from weeks ago
• Debugging difficulty: Operators cannot easily distinguish active sessions from historical noise
• No automatic lifecycle management: The acpx protocol has no TTL or auto-expiry for completed sessions

Root cause analysis

The acpx session store (under ~/.openclaw/) is append-only. Session files are created on spawn and persisted after completion, with no garbage collection. The mode: "run" (one-shot) designation does not imply "auto-delete after completion" — the session file remains until manually cleaned.

Gateway restarts preserve the session store because it lives in the config directory, not the runtime state directory.

Proposed fix

1. Add an autoCleanup flag or ttlMs field to sessions_spawn so completed mode: "run" sessions are automatically deleted after a configurable period (default: 24h)
2. Add acpx sessions --active-only flag to show only running or recently completed sessions
3. Add a built-in acpx cleanup --stale [ttl] command so operators don't need custom scripts
4. Consider a deleteAfterRun: true option (already exists for cron jobs — extend to acpx sessions)

Related

• #59555 — sessions_spawn loopback pairing fix (landed in v2026.4.2)
• #33069 — acpx docs audit (documented session management patterns)