Dr. Session Cleaner

What you get

• Automated sentinel (session_guard.py) that watches openclaw sessions --json and pings you when context usage crosses the threshold.
• A quick DM workflow: reply CLEAN <sessionId> if you want the agent to reset it, or run the included command yourself.
• A manual playbook for hard-resetting any bloated session plus prevention tips.

Super-short setup

clawhub install dr-session-cleaner
cd skills/dr-session-cleaner
SESSION_GUARD_TARGET="user:<discord_id>" ./scripts/install_guard.sh

That’s it — a cron entry is created (default every 15 min). Adjust threshold/interval with flags if needed. Details below if you ever want to run it manually or perform the hard reset yourself.

Instant run (most issues vanish here):

openclaw status && openclaw sessions cleanup --enforce

If the sluggish session disappears from openclaw sessions --json, have the user send a fresh message and you’re done. If it reappears or stays over ~80% of its context window, follow the steps below.

1. Spot the offender

1. openclaw status
   • In the Sessions table, find any key showing >80 % of its context window (e.g., 93%). Copy the session key such as agent:main:discord:direct:270548….
2. openclaw sessions --json
   • Locate the same key and note the sessionId (this is the transcript filename) plus the token totals.

2. Soft reset (preferred)

openclaw sessions cleanup --enforce

Re-run openclaw sessions --json. If the bloated key is gone, have the user send a new message to spin up a tiny session.

3. Hard reset (safely deleting one session)

⚠️ Double-check the key first. Always back up sessions.json.

1. Backup

   cp ~/.openclaw/agents/<agent>/sessions/sessions.json{,.bak}
   

2. Remove the entry (requires jq):

   jq 'del(."<session-key>")' \
     ~/.openclaw/agents/<agent>/sessions/sessions.json \
     > ~/.openclaw/agents/<agent>/sessions/sessions.json.tmp && \
   mv ~/.openclaw/agents/<agent>/sessions/sessions.json.tmp \
     ~/.openclaw/agents/<agent>/sessions/sessions.json
   

3. Delete the transcript + lock (use the sessionId):

   rm ~/.openclaw/agents/<agent>/sessions/<sessionId>.jsonl*
   

4. Verify

   openclaw sessions --json
   

   The key should be gone. Ask the user to send a message to confirm replies are instant again.

4. Keep it clean

• Run openclaw sessions cleanup --enforce on a schedule (daily cron or after big incidents).
• Lower agents.defaults.contextTokens (or per-agent overrides) so transcripts trim earlier (e.g., 120000 instead of 272000).
• Watch openclaw status; anything above ~80 % should be pruned the same day.
• Keep the .bak copy so you can restore a session if you removed the wrong one.

5. Automated monitoring

Path: scripts/session_guard.py (monitor) + scripts/install_guard.sh (one-line setup).

One-liner setup recap

SESSION_GUARD_TARGET="user:270548320366100480" \
./scripts/install_guard.sh

Customize with flags/env vars:

• --interval <minutes> (default 15)
• --threshold <ratio>
• --channel, --state, --log, --cooldown
• --dry-run to preview the cron block instead of installing it

Run manually (if you don’t want cron)

SESSION_GUARD_TARGET="user:<id>" SESSION_GUARD_THRESHOLD=0.8 python3 scripts/session_guard.py

Troubleshooting

• No jq? sudo apt install jq first.
• Permission errors deleting .jsonl? Make sure you’re the OpenClaw user or stop the agent briefly.
• Shared gateways: confirm the key belongs to your user before removing it (openclaw sessions --json --all-agents).

Use Dr. Session Cleaner whenever an agent gets stuck “typing,” replies take minutes, or you need an automated sentinel to warn when sessions creep toward their context caps.