openclaw - 💡(How to fix) Fix [Feature]: `openclaw caches` command to inspect and prune unbounded `~/.openclaw/` cache dirs (plugin-runtime-deps, browser, tools, orphan transcripts) [1 comments, 2 participants]

Summary

Add an openclaw caches command (or openclaw doctor --prune-caches) that lists cache-class directories under ~/.openclaw/ with their sizes and what populates them, and lets the user prune safely (stale plugin-runtime-deps version dirs, orphan agent transcripts, unused browser/tools downloads).

Problem to solve

~/.openclaw/ grows unbounded with no first-class way to slim it. On a single Mac install at 2026.4.29, after ~6 weeks of regular use:

Pre-bundled-runtime-deps versions of the same install were ~180 MB. The growth is almost entirely caches the user can't trim:

1. Stale plugin-runtime-deps/openclaw-<old-version>-<hash>/ directories. Each openclaw update stages a new version dir but never removes the old ones. Today my install had 2026.4.24, 2026.4.25, 2026.4.26, and 2026.4.29 side by side, totalling 4.5 GB; only 2026.4.29 was active. This same accumulation is also a known crash-loop cause in #73520. doctor --fix does not prune these.
2. Orphan agent transcripts. ~/.openclaw/agents/main/sessions/*.jsonl and *.trajectory.jsonl files persist after their session is removed from sessions.json. Each cron run produces 2 new files; there is no GC. Doctor offers a one-shot archive (*.deleted.<ts>) interactively, but no scheduled or scriptable cleanup.
3. Browser/tools/memory caches. Playwright Chromium, local model weights, and tools stage large blobs that are re-downloadable but have no --prune path; users either keep them or rm -rf blindly.

The user-visible symptom is "why is my ~/.openclaw 4+ GB when my Pi snapshot was 180 MB" with no answer in the docs and no command that returns a useful breakdown. Today's debugging session is a representative example.

Proposed solution

openclaw caches list — print a table of cache-class directories with size, last-modified, and a one-line description of what populates them. Distinguish cache (regenerable) from data (user-owned) explicitly. Example:

PATH                                        SIZE    CLASS         NOTES
plugin-runtime-deps/openclaw-2026.4.29-...  2.2GB   cache:active  current version's bundled-plugin npm deps
plugin-runtime-deps/openclaw-2026.4.26-...  858MB   cache:stale   prior version, regenerable
plugin-runtime-deps/openclaw-2026.4.25-...  855MB   cache:stale   prior version, regenerable
plugin-runtime-deps/openclaw-2026.4.24-...  589MB   cache:stale   prior version, regenerable
browser/                                    268MB   cache         Playwright Chromium; redownload on next launch
tools/                                      189MB   cache         Bundled CLI tools
memory/                                     235MB   data:cache    local llama-cpp model + embeddings (regenerable but slow)
agents/main/sessions/<orphans>              ~50MB   cache:stale   120 orphan transcripts, no sessions.json entry
agents/main/sessions/<active>               ~18MB   data          referenced by sessions.json
workspace/                                  218MB   data          user-owned, never pruned

openclaw caches prune [--dry-run] [--include=<class>] [--keep-versions=N] — remove cache:stale entries by default, with flags to also prune cache (browser/tools, regenerable) or to keep N most-recent plugin-runtime-deps version dirs (default 1). Dry-run first.

Specific defaults (the safe --prune baseline):

• plugin-runtime-deps/openclaw-<version>-* where <version> is not the current installed openclaw version → remove.
• agents/main/sessions/*.jsonl and *.trajectory.jsonl whose UUID is not referenced in sessions.json and whose mtime is > N days old (configurable, default 7) → archive (rename to .deleted.<ts>) or remove.
• Never touch workspace/, credentials/, cron/, delivery-queue/, active version's plugin-runtime-deps, memory/ (unless --include=memory is passed).

openclaw doctor --fix integration: after the existing "archive orphan transcripts" prompt, add an "also prune N stale plugin-runtime-deps dirs (~M GB)" prompt with the same opt-in flow.

Alternatives considered

• Manual rm -rf. What people do today, but has no safety: a wrong path can wipe workspace/ or credentials/. Today's debugging session involved a manual prune of three stale plugin-runtime-deps dirs — fine for an experienced user with the tree memorized, but not something to recommend to non-engineers running openclaw on a personal Mac.
• Time-based npm cache eviction. Doesn't help — the issue is multiple full version dirs side by side, each populated by its own npm install, not stale entries within one cache.
• Auto-prune on openclaw update. Tempting but riskier than an explicit command: today update's post-install path is fragile (see #73520, #75296 for recent crash-loop / partial-install bugs). Adding deletion to that path multiplies blast radius. An explicit caches prune is safer first; auto-prune-on-update can come later behind a config flag once the command is proven.
• Doctor-only. doctor --fix already has a half-finished cleanup path (the orphan-transcript archive prompt) but no pruning of other cache classes. Could extend doctor instead of a new top-level command — that's fine if maintainers prefer it; the API surface is what matters.

Impact

• Affected users: anyone running openclaw on a long-lived install (especially desktop Mac/Linux, where cron sessions add transcripts daily and updates leave version dirs around). The issue is silent — users notice only when they hit a disk-pressure threshold or run du.
• Severity: annoying-to-blocking, depending on disk pressure. On laptops with constrained SSDs, multi-GB unbounded growth is a real problem. It also causes known crashes — see #73520 where stale plugin-runtime-deps version dirs caused a 5-hour crash-loop.
• Frequency: continuous. Every openclaw update adds ~600MB–2.2GB of stale plugin-runtime-deps. Every cron run leaves 2 orphan jsonl files.
• Practical consequence today: new contributors and end-users have no way to answer "why is ~/.openclaw huge" without reading source. The mitigation lives in support threads / Discord, not in the CLI.

Related issues

• #73520 — stale plugin-runtime-deps version dirs cause gateway crash-loop after update. A caches prune command with --keep-versions=1 would have prevented this entirely.
• #75032 — feature to disable bundled-runtime-deps install at all (installBundledRuntimeDeps: false). Complementary; this issue addresses cleanup of what is installed rather than gating the install.
• #74963 — multi-instance hash mismatch in plugin-runtime-deps. Same staging dir, different concern.
• #75296 — silent partial install on ETIMEDOUT (filed today). Would benefit from caches list showing whether the active version dir is complete vs. partial.
• #50248 — sessions cleanup --fix-missing over-prunes fresh cron sessions. Suggests the orphan-transcript pruning logic needs the same care; caches prune should not call into that buggy path.

AI-assisted: this issue was drafted by Claude after a debugging session today on the user's Mac install (2026.4.29). The sizes and orphan counts are from real du/jq output on that install. Session log can be shared on request.