Common issues and their solutions for clincher deployments.
| Symptom | Diagnostic | Fix |
|---|---|---|
Sandbox fails: docker command was not found in PATH |
docker exec openclaw which docker |
Add - /usr/bin/docker:/usr/bin/docker:ro to openclaw volumes in docker-compose.yml, then docker compose up -d openclaw |
| Sandbox fails: socket proxy errors | docker logs openclaw-docker-proxy |
Verify EXEC=1, check socket proxy is reachable on openclaw-net |
| Gateway unreachable | docker compose logs openclaw |
Confirm gateway.bind "lan", check trustedProxies includes proxy-net subnet |
| Gateway auth rejected | docker exec openclaw openclaw config get gateway.auth.mode |
Re-run Step 5 auth section; verify Authorization: Bearer <token> header |
| Agents can’t reach LLM APIs | docker exec openclaw wget -qO- http://openclaw-litellm:4000/health/liveliness |
Verify LiteLLM is healthy, check agents.defaults.apiBase points to http://openclaw-litellm:4000, check ANTHROPIC_API_KEY in /opt/openclaw/.env |
| LiteLLM can’t reach providers | docker exec openclaw-litellm curl -x http://openclaw-egress:4750 -I https://api.anthropic.com |
Check smokescreen-acl.yaml whitelist, verify HTTP_PROXY env var |
| Memory index fails | docker exec openclaw openclaw memory index --verify |
Verify Voyage AI key, check *.voyageai.com in smokescreen-acl.yaml |
| Telegram crashes / drops messages | docker compose logs openclaw --tail 100 \| grep -i telegram |
Check channel token and pairing status. If upgrading from 2026.2.17, the streaming race condition was fixed in 2026.2.19 — remove legacy streamMode "off" if present |
| Channel not connecting | docker exec openclaw openclaw doctor |
Check channel token, verify dmPolicy, check pairing status |
| Container keeps restarting | docker compose logs <service> --tail 100 |
Check resource limits (docker stats), verify config files are readable |
| Egress proxy blocks legitimate traffic | docker logs openclaw-egress |
Check smokescreen-acl.yaml allowed_domains, verify domain glob pattern matches (e.g., *.anthropic.com) |
| Container OOM-killed | dmesg \| grep -i oom, docker inspect <container> --format '' |
Check docker stats — verify the OOM’d container’s memory limit. On 64 GB host, individual container limits are the constraint, not total host memory. Increase the specific container’s limit or reduce concurrent sandbox count |
| High swap usage | free -h, vmstat 1 5 |
If swap > 1 GB consistently, reduce agents.defaults.sandbox.docker.memoryLimit or lower openclaw memory limit to 3G |
| Config error after update | docker exec openclaw openclaw doctor --repair |
Restore from backup: docker exec openclaw cp /root/.openclaw/config.json.bak /root/.openclaw/config.json and restart. See Step 5 backup note |
| Redis unreachable / LiteLLM cache errors | docker exec openclaw-redis redis-cli ping, docker logs openclaw-litellm --tail 50 \| grep -i redis |
Verify redis container is healthy, check REDIS_HOST env var in LiteLLM, verify both are on openclaw-net. LiteLLM falls back to no-cache if Redis is unavailable — service continues, just without caching |
| Low cache hit rate | docker exec openclaw-redis redis-cli dbsize, check Prometheus litellm_cache_hit_metric_total on monitoring VPS |
Normal for first 24 hours. If persistently < 5%, lower similarity_threshold from 0.8 to 0.7 in litellm-config.yaml and restart LiteLLM |
# Overall service health
docker compose ps
# Full security audit
docker exec $(docker ps -q -f "name=openclaw") openclaw security audit --deep
# Doctor check (covers channels, config, connectivity)
docker exec openclaw openclaw doctor
# Sandbox status
docker exec $(docker ps -q -f "name=openclaw") openclaw sandbox explain
# Resource usage across all containers
docker stats --no-stream
# Check egress proxy connectivity
docker exec $(docker ps -q -f "name=openclaw") \
curl -x http://openclaw-egress:4750 -I https://api.anthropic.com
# View recent logs for a specific service
docker compose logs <service> --tail 100
For full deployment and configuration details, see the deployment guide.