Idle-shutdown

Monitors user session idleness and automatically stops the OpenClaw Gateway after a configurable idle period to save resources and costs.

Gateway Idle Shutdown

Monitors session activity between users and the bot, and automatically stops the OpenClaw Gateway when all sessions have been idle continuously beyond the configured threshold.

How It Works

• Polls session transcript files (~/.openclaw/agents/main/sessions/) every 10 seconds for their last modification time (mtime)
• Preferentially matches QQBot/channel/direct related session files
• When the latest mtime is older than the threshold (default 120 seconds), executes openclaw gateway stop
• Logs are written to ~/.openclaw/logs/idle-shutdown.log

Benefits

• Resource Savings — Automatically stops the Gateway when no one is using it, freeing CPU and memory that would otherwise be wasted during idle periods.
• Cost Reduction — On metered or cloud-hosted environments, shutting down idle services reduces compute costs by avoiding charges for unused uptime.
• Energy Efficiency — Reduces power consumption by ensuring services only run when actually needed, lowering your carbon footprint.
• Zero Manual Intervention — Once configured, the watcher runs autonomously with systemd; you never need to remember to shut down the Gateway manually.
• Seamless Lifecycle Integration — The systemd watcher is bound to the Gateway service (BindsTo + PartOf), so it starts and stops in lockstep — no orphaned watcher processes and no stale state.
• Configurable & Forgiving — Idle threshold, polling interval, session directory, and binary path are all controlled via environment variables; the watcher retries on failure instead of exiting abruptly.
• Lightweight Footprint — A simple bash script with sleep-based polling uses negligible system resources, making it suitable for low-power devices and headless servers alike.

Installation

# 1. Copy the script
cp scripts/idle-shutdown.sh ~/.openclaw/workspace/scripts/
chmod +x ~/.openclaw/workspace/scripts/idle-shutdown.sh

# 2. Create the systemd service file
mkdir -p ~/.config/systemd/user
cat > ~/.config/systemd/user/openclaw-idle-watch.service << 'EOF'
[Unit]
Description=OpenClaw idle gateway shutdown watcher
After=openclaw-gateway.service
BindsTo=openclaw-gateway.service
PartOf=openclaw-gateway.service

[Service]
Type=simple
ExecStart=%h/.openclaw/workspace/scripts/idle-shutdown.sh
Restart=on-failure
RestartSec=10s
Environment=HOME=%h
# Adjust this PATH if your openclaw binary lives elsewhere
Environment=PATH=%h/.local/bin:%h/bin:/usr/local/bin:/usr/bin:/bin
Environment=OPENCLAW_BIN=openclaw

[Install]
WantedBy=default.target
EOF

# 3. Enable and start the service
systemctl --user daemon-reload
systemctl --user enable openclaw-idle-watch.service
systemctl --user start openclaw-idle-watch.service

Configuration

Customize behavior via environment variables:

Variable	Default	Description
IDLE_SECONDS	120	Idle threshold (seconds)
POLL_SECONDS	10	Polling interval (seconds)
SESSIONS_DIR	~/.openclaw/agents/main/sessions	Session directory
LOG_FILE	~/.openclaw/logs/idle-shutdown.log	Log file path
OPENCLAW_BIN	openclaw	openclaw binary path

Uninstallation

systemctl --user stop openclaw-idle-watch.service
systemctl --user disable openclaw-idle-watch.service
rm ~/.config/systemd/user/openclaw-idle-watch.service
rm ~/.openclaw/workspace/scripts/idle-shutdown.sh

Service Lifecycle

• The watcher is bound to openclaw-gateway.service (BindsTo + PartOf)
• Gateway starts → Watcher starts automatically
• Gateway stops → Watcher stops automatically
• Watcher triggers on idle → Gateway is stopped → Watcher stops along with Gateway