$cd ../troubleshooting/
High⚡ Performance
Dreaming Orphaned Sessions — Disk Bloat & Slow Gateway Startup
// OpenClaw's memory 'dreaming' feature consolidates long-term context during idle periods. A known bug in several 2026 builds leaves behind temp session directories that are never garbage-collected — users report 5–50 GB under ~/.openclaw/agents/main/sessions/ and gateway startup times of 30+ seconds.
diagnose.sh
🔍 Is This Your Issue?
?du -sh ~/.openclaw/agents/main/sessions/ shows multiple GB (often 5–50 GB)
?Gateway restart or openclaw gateway status takes 15–60 seconds longer than fresh install
?Thousands of dream-temp-* or tmp-* directories with old mtimes and no active chat referencing them
measure_bloat.sh
✅ Fix 1 — Measure Session Directory Bloat
Baseline bloat — run before deleting anything
# Total size of session storage
du -sh ~/.openclaw/agents/main/sessions/
# Count all session-related dirs
find ~/.openclaw/agents/main/sessions/ -maxdepth 1 -type d | wc -l
# List largest dream-temp folders
find ~/.openclaw/agents/main/sessions/ -name 'dream-temp-*' -type d -exec du -sh {} \; | sort -hr | head -20cleanup_orphans.sh
✅ Fix 2 — Safely Remove Orphaned Temp Sessions
Quarantine first; rm quarantine after 48h if healthy
# Stop gateway first
openclaw gateway stop
# Preview orphan candidates (14+ days, dream-temp prefix)
find ~/.openclaw/agents/main/sessions/ \
-maxdepth 1 -type d -name 'dream-temp-*' -mtime +14 -print
# Move to quarantine (safer than rm)
mkdir -p ~/openclaw-session-quarantine
find ~/.openclaw/agents/main/sessions/ \
-maxdepth 1 -type d -name 'dream-temp-*' -mtime +14 \
-exec mv {} ~/openclaw-session-quarantine/ \;
openclaw gateway startopenclaw.json
✅ Fix 3 — Tune or Disable Dreaming
Tune retention — disable if disk is tight
# ~/.openclaw/openclaw.json
{
"agents": {
"defaults": {
"dreaming": {
"enabled": true,
"interval": "0 3 * * *",
"maxTempSessions": 50,
"retainTempDays": 3
}
}
}
}
# Or disable entirely:
# "dreaming": { "enabled": false }💡 Pro Tip: Schedule Weekly Cleanup
Add a cron job that deletes dream-temp-* folders older than 7 days. This keeps disk usage flat even if a future build regresses the GC logic. Always stop the gateway before bulk deletion.
🛡️ Prevention checklist
- • After enabling dreaming, check du -sh ~/.openclaw/agents/main/sessions/ weekly for the first month
- • Keep gateway on a recent patch — several 2026.3.x releases improved temp-session cleanup
- • Set agents.defaults.dreaming.maxTempSessions if your build supports it (cap orphan growth)
- • Back up active session JSON files before any bulk rm — never delete sess-* without checking mtime
- • Use a dedicated disk or quota for ~/.openclaw on VPS hosts so bloat cannot fill root /
❓ FAQ
Q1. What is 'dreaming' in OpenClaw?
Dreaming is a background memory consolidation pass. While the agent is idle, OpenClaw summarizes older conversation turns into compact memory files so future replies stay coherent without reloading the full transcript. It writes temporary working directories under agents/<id>/sessions/ during the pass. When cleanup fails, those temp dirs become orphans.
Q2. Is it safe to delete everything in the sessions folder?
No. Active sessions (often named sess-<uuid> with recent mtimes) hold live channel state. Only remove directories matching dream-temp-*, tmp-*, or .partial-* patterns, or folders with no corresponding entry in the agent's session index. When in doubt, move suspects to a quarantine folder first and restart the gateway — if channels reconnect fine, delete the quarantine after 48 hours.
Q3. Why does a huge sessions folder slow startup?
On gateway boot, OpenClaw scans session metadata to rebuild indexes and validate channel bindings. Ten thousand stale directories means tens of thousands of stat() calls and JSON parses before the first message can flow. Users on HDD-backed Mac Minis and Raspberry Pi SD cards feel this most — NVMe hosts still lag with 20k+ entries.
Q4. Will disabling dreaming break my agent's memory?
Dreaming improves long-horizon recall but is not required for day-to-day chat. Disabling it stops new temp dirs from accumulating; existing long-term memory files under agents/<id>/memory/ remain. You may notice slightly weaker references to conversations from weeks ago — acceptable trade-off on storage-constrained hosts.
Q5. How do I tell orphaned temps apart from real sessions?
Orphans usually have names like dream-temp-<timestamp>, .dream-work-<id>, or tmp-merge-* and have not been modified since the dreaming pass finished. Real sessions update mtime on every inbound message. Run find with -mtime +14 on dream-temp* paths — if the gateway has been up and chatting but those dirs are untouched for two weeks, they are orphans.
Q6. Should I open a GitHub issue after cleaning up?
Yes, if you are on an official build from github.com/openclaw/openclaw. Include openclaw --version, du -sh output, count from find … | wc -l, and your dreaming config snippet. Do not paste session contents — they may contain private messages. Community reports help prioritize GC fixes in upstream releases.