OpenClaw — Operations Workbook
OpenClaw WhatsApp gateway running on IONOS VPS (vps-i1). Provides WhatsApp connectivity for the fleet platform. Distinct from WAHA (vps-h1 DE number) — OpenClaw handles a separate account/session.
Architecture
IONOS VPS (217.154.82.162)
└── Container: openclaw-openclaw-gateway-1
├── port 18789 OpenClaw API (internal)
├── port 18790 OpenClaw secondary port (internal)
└── proxied via Caddy → openclaw.vps-i1.infra.zintegrowana.online (HTTPS)
Public URL: https://openclaw.vps-i1.infra.zintegrowana.online
Health endpoint: https://openclaw.vps-i1.infra.zintegrowana.online/healthz (public, no auth)Caddy routing: defined in monitoring/Caddyfile — reverse_proxy to localhost:18789.
Compose file on server: /opt/p24-infra/openclaw/docker-compose.yml
Compose file in repo: openclaw/docker-compose.yml
OpenClaw runs as a separate Docker Compose stack from the monitoring stack, co-located on vps-i1.
Config Management
| File | In repo? | Notes |
|---|---|---|
openclaw/docker-compose.yml | Yes | Container definition, port mapping, env refs |
monitoring/Caddyfile | Yes | Caddy reverse proxy rule for openclaw |
.env (openclaw) | No | API key and session config — on server only |
Config change workflow
# On vps-i1
cd /opt/p24-infra
git pull
# If Caddy config changed (new route, auth rule):
docker compose -f monitoring/docker-compose.yml exec caddy caddy reload --config /etc/caddy/Caddyfile
# If openclaw compose changed:
cd openclaw
docker compose up -d --force-recreateDeployment
Fresh install
# On vps-i1
cd /opt/p24-infra/openclaw
# Ensure .env is populated with API key / session config
docker compose up -d
# Verify container is running
docker compose ps
docker compose logs --tail=30Re-authenticate WhatsApp session
OpenClaw holds WhatsApp session state. If session is lost (container wiped, volume deleted, session expired):
# 1. Stop and clear session
docker compose -f /opt/p24-infra/openclaw/docker-compose.yml stop
# Clear session volume if needed (see compose volume name)
docker volume rm openclaw_session_data # adjust name to match compose
# 2. Start fresh
docker compose -f /opt/p24-infra/openclaw/docker-compose.yml up -d
# 3. Follow OpenClaw re-auth procedure (QR scan or pairing code via API)
# Refer to OpenClaw vendor docs for the specific auth endpoint
curl https://openclaw.vps-i1.infra.zintegrowana.online/healthzBackup
| Data | Method | Schedule | Destination |
|---|---|---|---|
| Config (compose + Caddyfile) | Git repo | On every push | GitHub radieu/p24-infra |
| WhatsApp session data | Docker volume — not backed up | — | Re-auth required after loss (5 min) |
| API key / secrets | GH Secrets + .env.local on local workstation | — | Not committed to repo |
Backup = stateless after re-auth. Session loss requires a QR scan or pairing code re-auth; no persistent business data is stored in the container. Backup status: yes (stateless by design).
Restore
Scenario 1: Container crash (session volume intact)
cd /opt/p24-infra/openclaw
docker compose up -d
# Session resumes automatically if volume is intact
curl https://openclaw.vps-i1.infra.zintegrowana.online/healthz
# Expected: HTTP 200Scenario 2: Session volume lost
# 1. Start container (fresh session)
cd /opt/p24-infra/openclaw
docker compose up -d
# 2. Re-authenticate WhatsApp (QR scan or pairing code)
# See vendor docs for auth endpoint
# 3. Verify /healthz returns 200
curl https://openclaw.vps-i1.infra.zintegrowana.online/healthzEstimated RTO: ~5 minutes (container start + re-auth).
Scenario 3: Full vps-i1 rebuild
# After Ansible provisioning + git clone (see vps-i1-operations.md):
cd /opt/p24-infra/openclaw
cp /path/to/.env.local .env # restore from local workstation
docker compose up -d
# Then re-authenticate WhatsApp sessionHealthcheck / Monitoring
| Check | Method | Interval | Alert |
|---|---|---|---|
/healthz probe | Blackbox exporter HTTP probe | 30s | EndpointDown alert if non-200 |
| Container resource usage | cAdvisor scrape (if cadvisor running on vps-i1) | 15s | ContainerCrashLooping |
| Container restart count | Prometheus container_restart_count from cAdvisor | — | ContainerCrashLooping rule |
Manual health check:
# Public endpoint
curl -o /dev/null -s -w "%{http_code}" \
https://openclaw.vps-i1.infra.zintegrowana.online/healthz
# Expected: 200
# Container status on vps-i1
ssh -i C:\Users\konar\.ssh\id_ed25519 root@217.154.82.162 \
"docker inspect openclaw-openclaw-gateway-1 --format '{{.State.Status}}'"Blackbox probe config: monitoring/prometheus/blackbox.yml — module http_2xx, target https://openclaw.vps-i1.infra.zintegrowana.online/healthz.
Password Rotation
| Credential | Location | Rotation frequency | Procedure |
|---|---|---|---|
| OpenClaw API key | /opt/p24-infra/openclaw/.env + GH Secret (if applicable) | On demand / 180d | See below |
| WhatsApp session auth | Managed by WhatsApp — expires on device logout or session revoke | On event | Re-auth QR scan |
Rotate OpenClaw API key
# 1. Generate new key
NEW_KEY=$(openssl rand -hex 32)
# 2. Update .env on vps-i1
ssh root@217.154.82.162 "sed -i 's/OPENCLAW_API_KEY=.*/OPENCLAW_API_KEY=${NEW_KEY}/' /opt/p24-infra/openclaw/.env"
# 3. Restart container to pick up new key
ssh root@217.154.82.162 "cd /opt/p24-infra/openclaw && docker compose restart"
# 4. Update .env.local on local workstation
# 5. Update GH Secret if used by any workflow
gh secret set OPENCLAW_API_KEY -b "${NEW_KEY}" -R radieu/p24-infra
# 6. Update any consumers (n8n workflows, scripts) that send the API key
# 7. Log rotation in docs/secrets-rotation-log.mdTroubleshooting
| Symptom | Likely cause | Fix |
|---|---|---|
/healthz returns non-200 | Container not running or session broken | docker compose -f /opt/p24-infra/openclaw/docker-compose.yml up -d; check logs |
| Caddy 502 for openclaw domain | Container crashed or wrong port | docker compose ps; verify port 18789 is bound |
| WhatsApp messages not delivered | Session expired or disconnected | Re-auth QR scan procedure above |
| Container OOM | Memory limit too low | Increase mem_limit in compose; check docker stats |
| API calls return 401 | API key mismatch | Verify key in .env matches caller |