OpenClaw Stability Tools

Stability improvements and automation tools for OpenClaw deployments.

🎯 What This Solves

Problem 1: "No conversation found" Errors

When Claude CLI experiences a watchdog timeout (typically after 16 minutes of no output), the process restarts with a fresh session ID. However, OpenClaw's session store still references the old session ID, causing Telegram messages to fail with:

Embedded agent failed before reply: No conversation found with session ID: xxx-yyy-zzz

Problem 2: Chromium Memory Leaks

OpenClaw's Browser Automation agent can leave orphaned Chromium processes running, especially after gateway restarts. These processes accumulate and consume significant memory (observed: 24 processes = 4GB RAM).

✅ Solutions Provided

1. Session Recovery Script

clear-stale-sessions.py - Automatically clears stale Claude CLI session IDs from OpenClaw's session store while preserving the OpenClaw session itself. This allows the next message to create a fresh CLI session automatically.

• Auto-discovers all agent session directories
• Preserves OpenClaw session metadata (Telegram chat mapping, labels, etc.)
• Safe to run multiple times (idempotent)

2. Chromium Cleanup Automation

cleanup-chromium.sh - Terminates orphaned Chromium processes to reclaim memory. Browser Automation tasks will start fresh Chromium instances as needed.

• Safe to run via cron
• Verbose and dry-run modes for testing
• Logging support

📦 Installation

Quick Install

git clone https://github.com/yourusername/openclaw-stability.git
cd openclaw-stability
chmod +x install.sh
./install.sh

The installer will:

1. ✅ Verify OpenClaw installation
2. ✅ Install scripts to ~/.openclaw/stability-tools/
3. ✅ Add ExecStartPre to openclaw-gateway.service (optional)
4. ✅ Add Chromium cleanup cron job (optional)

Manual Installation

# 1. Copy scripts
mkdir -p ~/.openclaw/stability-tools
cp scripts/* ~/.openclaw/stability-tools/
chmod +x ~/.openclaw/stability-tools/*.{py,sh}

# 2. Add to systemd (optional)
# Edit ~/.config/systemd/user/openclaw-gateway.service
# Add before ExecStart:
ExecStartPre=/usr/bin/python3 /home/YOUR_USER/.openclaw/stability-tools/clear-stale-sessions.py

# Reload systemd
systemctl --user daemon-reload

# 3. Add cron job (optional)
crontab -e
# Add:
0 */2 * * * ~/.openclaw/stability-tools/cleanup-chromium.sh >> /tmp/chromium-cleanup.log 2>&1

🚀 Usage

Session Recovery

Automatic (via systemd ExecStartPre):

# Runs automatically before every gateway restart
systemctl --user restart openclaw-gateway

Manual:

# Run manually
~/.openclaw/stability-tools/clear-stale-sessions.py

# Verbose output
~/.openclaw/stability-tools/clear-stale-sessions.py --verbose

# Custom OpenClaw directory
~/.openclaw/stability-tools/clear-stale-sessions.py --openclaw-dir /custom/path

Chromium Cleanup

Automatic (via cron):

# Runs every 2 hours automatically (if configured during installation)
# Check crontab
crontab -l | grep chromium

Manual:

# Run cleanup
~/.openclaw/stability-tools/cleanup-chromium.sh

# Dry run (see what would be killed)
~/.openclaw/stability-tools/cleanup-chromium.sh --dry-run

# Verbose output
~/.openclaw/stability-tools/cleanup-chromium.sh --verbose

📊 Monitoring

Check Session Recovery

# View systemd logs
journalctl --user -u openclaw-gateway --no-pager | grep "clear-stale"

# Or check ExecStartPre status
systemctl --user status openclaw-gateway | grep ExecStartPre

Check Chromium Cleanup

# View cleanup log
tail -f /tmp/chromium-cleanup.log

# Check current Chromium processes
pgrep -af chromium | wc -l

🔧 Configuration

Environment Variables

• OPENCLAW_HOME: Override default OpenClaw directory (default: ~/.openclaw)
• LOG_FILE: Path for Chromium cleanup logs (used by cron job)

Systemd Service Example

[Service]
# Clear stale sessions before starting gateway
ExecStartPre=/usr/bin/python3 /home/user/.openclaw/stability-tools/clear-stale-sessions.py
ExecStart=/usr/bin/node /path/to/openclaw/dist/index.js gateway

Cron Schedule Options

# Every 2 hours (default)
0 */2 * * * ~/.openclaw/stability-tools/cleanup-chromium.sh

# Every hour
0 * * * * ~/.openclaw/stability-tools/cleanup-chromium.sh

# Daily at midnight
0 0 * * * ~/.openclaw/stability-tools/cleanup-chromium.sh

🐛 Troubleshooting

See docs/TROUBLESHOOTING.md for common issues and solutions.

📖 Documentation

• Installation Guide
• Architecture & How It Works
• Troubleshooting

🤝 Contributing

Contributions welcome! Please:

1. Test on your OpenClaw deployment
2. Document any new features
3. Follow existing code style

📝 License

MIT License - feel free to use in your own projects.

🙏 Acknowledgments

• Built for the OpenClaw community
• Tested on Ubuntu 24.04 with OpenClaw v2026.2.6-3
• Based on real-world production deployment experience

📧 Support

• Issues: Open a GitHub issue
• Discussions: Use GitHub Discussions for questions
• Security: Report security issues privately

---

Made with ❤️ for the OpenClaw community