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#

bash

# 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:

VariableDefaultDescriptionIDLE_SECONDS120Idle threshold (seconds)POLL_SECONDS10Polling interval (seconds)SESSIONS_DIR``~/.openclaw/agents/main/sessionsSession directoryLOG_FILE``~/.openclaw/logs/idle-shutdown.logLog file pathOPENCLAW_BIN``openclawopenclaw binary path

Uninstallation#

bash

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