This guide explains how to set up monitoring and logging for your OpenClaw installation to ensure optimal performance, troubleshoot issues, and maintain security.
Effective monitoring and logging are crucial for maintaining a healthy OpenClaw deployment. This guide covers setting up logging, metrics collection, alerting, and visualization.
OpenClaw logs to both stdout and file. Configure logging via the gateway command:
# Start gateway with verbose logging
openclaw gateway --port 18789 --verbose
# Or set log level via environment
export OPENCLAW_LOG_LEVEL=debug
openclaw gateway --port 18789
| Level | Description |
|---|---|
error |
Only errors |
warn |
Warnings and errors |
info |
General information (default) |
debug |
Detailed debugging information |
verbose |
Very detailed output |
Logs are stored in:
~/.openclaw/logs/gateway.log
In Docker setups, logs are also available via:
docker compose logs -f openclaw-gateway
Create a log rotation configuration to prevent logs from filling up disk space:
cat > /etc/logrotate.d/openclaw << 'EOF'
~/.openclaw/logs/*.log {
daily
rotate 30
compress
delaycompress
missingok
notifempty
create 0640 node node
}
EOF
Or use a custom script:
cat > scripts/log_rotate.sh << 'EOF'
#!/bin/bash
# Log rotation script for OpenClaw
LOG_DIR="${HOME}/.openclaw/logs"
RETENTION_DAYS=30
# Rotate logs
if [ -d "$LOG_DIR" ]; then
# Compress old logs
find $LOG_DIR -name "*.log" -mtime +7 -exec gzip {} \;
# Delete old compressed logs
find $LOG_DIR -name "*.log.gz" -mtime +$RETENTION_DAYS -delete
echo "$(date): Log rotation completed"
fi
EOF
chmod +x scripts/log_rotate.sh
# Add to crontab (run daily)
(crontab -l 2>/dev/null; echo "0 2 * * * $(pwd)/scripts/log_rotate.sh") | crontab -
Create a Prometheus configuration file:
mkdir -p monitoring/prometheus
cat > monitoring/prometheus/prometheus.yml << 'EOF'
global:
scrape_interval: 15s
evaluation_interval: 15s
scrape_configs:
- job_name: 'prometheus'
static_configs:
- targets: ['localhost:9090']
- job_name: 'node-exporter'
static_configs:
- targets: ['node-exporter:9100']
EOF
Create a Docker Compose file for Prometheus:
version: '3.8'
services:
prometheus:
image: prom/prometheus:latest
container_name: prometheus
ports:
- "9090:9090"
volumes:
- ./prometheus/prometheus.yml:/etc/prometheus/prometheus.yml
- prometheus_data:/prometheus
command:
- '--config.file=/etc/prometheus/prometheus.yml'
- '--storage.tsdb.path=/prometheus'
- '--storage.tsdb.retention.time=200h'
- '--web.enable-lifecycle'
networks:
- monitoring-net
grafana:
image: grafana/grafana-enterprise
container_name: grafana
ports:
- "3000:3000"
volumes:
- grafana_storage:/var/lib/grafana
environment:
- GF_SECURITY_ADMIN_PASSWORD=admin
- GF_USERS_ALLOW_SIGN_UP=false
depends_on:
- prometheus
networks:
- monitoring-net
node-exporter:
image: prom/node-exporter:latest
container_name: node-exporter
ports:
- "9100:9100"
volumes:
- /proc:/host/proc:ro
- /sys:/host/sys:ro
- /:/rootfs:ro
command:
- '--path.procfs=/host/proc'
- '--path.rootfs=/rootfs'
- '--path.sysfs=/host/sys'
- '--collector.filesystem.mount-points-exclude=^/(sys|proc|dev|host|etc)($$|/)'
networks:
- monitoring-net
volumes:
prometheus_data:
grafana_storage:
networks:
monitoring-net:
driver: bridge
For Docker deployments, use built-in Docker monitoring:
# Real-time resource usage
docker stats openclaw-gateway openclaw-cli
# One-time snapshot
docker stats --no-stream openclaw-gateway
# Detailed container inspection
docker inspect openclaw-gateway
Create a health check script:
cat > scripts/health_check.sh << 'EOF'
#!/bin/bash
# Health check script for OpenClaw
HEALTH_ENDPOINT="http://localhost:18789"
TIMEOUT=10
MAX_RETRIES=3
check_health() {
local attempt=1
while [ $attempt -le $MAX_RETRIES ]; do
if curl -f --max-time $TIMEOUT $HEALTH_ENDPOINT > /dev/null 2>&1; then
echo "$(date): OpenClaw is healthy"
return 0
else
echo "$(date): Health check failed (attempt $attempt/$MAX_RETRIES)"
sleep 5
((attempt++))
fi
done
echo "$(date): OpenClaw is unhealthy after $MAX_RETRIES attempts"
return 1
}
# Run the health check
if ! check_health; then
echo "$(date): Attempting recovery..."
# Add recovery commands here if needed
exit 1
else
exit 0
fi
EOF
chmod +x scripts/health_check.sh
Add to crontab for regular checks:
# Add to crontab (run every 5 minutes)
(crontab -l 2>/dev/null; echo "*/5 * * * * $(pwd)/scripts/health_check.sh") | crontab -
# Check gateway status
openclaw gateway status
# Check version
openclaw -v
# View running processes
ps aux | grep openclaw
# List configured channels
openclaw channels list
# Check channel connectivity
openclaw channels status
# List pending device pairings
openclaw devices list
# View active sessions
openclaw sessions list
# Check disk usage
du -sh ~/.openclaw/*
# Check memory database sizes
ls -lh ~/.openclaw/memory/*.sqlite
# Monitor log file sizes
du -sh ~/.openclaw/logs/*
Create alert rules for Prometheus:
cat > monitoring/prometheus/alerts.yml << 'EOF'
groups:
- name: openclaw_alerts
rules:
- alert: OpenClawDown
expr: up{job="openclaw"} == 0
for: 5m
labels:
severity: critical
annotations:
summary: "OpenClaw gateway is down"
description: "OpenClaw gateway has been down for more than 5 minutes."
- alert: HighMemoryUsage
expr: container_memory_usage_bytes{container="openclaw-gateway"} > 2147483648
for: 10m
labels:
severity: warning
annotations:
summary: "High memory usage detected"
description: "OpenClaw gateway is using more than 2GB of memory."
- alert: HighErrorRate
expr: rate(http_requests_total{status=~"5.."}[5m]) > 0.1
for: 5m
labels:
severity: warning
annotations:
summary: "High error rate detected"
description: "More than 10% of requests are failing."
EOF
Once services are running:
http://your-server:3000 (default login: admin/admin)http://your-server:9090http://your-server:9100/metricsImport a dashboard for OpenClaw metrics:
http://your-server:3000# Check memory usage
docker stats openclaw-gateway --no-stream
# View memory-intensive processes
docker top openclaw-gateway
# Consider increasing Docker memory limits or using a smaller model
# Check log sizes
du -sh ~/.openclaw/logs/*
# Manually rotate logs
logrotate -f /etc/logrotate.d/openclaw
# Clear old logs (be careful)
find ~/.openclaw/logs -name "*.log.gz" -delete
# Check container status
docker compose ps
# View logs
docker compose logs openclaw-gateway
# Restart gateway
docker compose restart openclaw-gateway
# Check for port conflicts
sudo lsof -i :18789
# Check memory database files
ls -lh ~/.openclaw/memory/
# View SQLite database integrity
sqlite3 ~/.openclaw/memory/<agentId>.sqlite "PRAGMA integrity_check;"
~/.openclaw/~/.openclaw/memory/Any questions?
Feel free to contact us. Find all contact information on our contact page.