Gateway Deep Troubleshooting Guide

Overview

OpenClaw Gateway is the critical component connecting clients to core services. When the Gateway has issues, message processing across all channels is affected. This article systematically covers Gateway troubleshooting methods.

First Step: Run Doctor

openclaw doctor

Based on Doctor's output, identify the specific problem category.

Network Troubleshooting

Port in Use

lsof -i :3000
netstat -tlnp | grep 3000

Solution: Change the Gateway port or terminate the conflicting process:

{
  "gateway": {
    "port": 3001
  }
}

Firewall Blocking

sudo ufw status
sudo ufw allow 3000/tcp

DNS Resolution Failure

nslookup api.openai.com
dig api.openai.com

SSL/TLS Issues

openssl s_client -connect api.openai.com:443
curl -vI https://api.openai.com

Common SSL errors:

UNABLE_TO_GET_ISSUER_CERT: Install a CA certificate bundle
CERT_HAS_EXPIRED: Update system time
SELF_SIGNED_CERT: Set NODE_TLS_REJECT_UNAUTHORIZED=0 (development only)

Configuration Troubleshooting

Config File Syntax Errors

openclaw configure --validate

Common syntax issues: trailing commas in JSON, unquoted string values, incorrect nesting.

Environment Variables Not Set

openclaw doctor --check-env
openclaw secrets list

Model Configuration Errors

openclaw doctor --provider openai --model gpt-4o

Runtime Troubleshooting

Memory Leaks

ps aux | grep openclaw
watch -n 5 "ps -o pid,rss,vsz,comm -p $(pgrep -f openclaw)"

High Latency

Enable detailed logging to identify the bottleneck:

{
  "gateway": {
    "logLevel": "debug",
    "logTimings": true
  }
}

Frequent Restarts

Check process manager logs:

pm2 logs openclaw --lines 100
journalctl -u openclaw -n 100

Common restart causes: OOM kills, uncaught exceptions, abnormal provider responses.

Channel Connection Issues

Webhook Unreachable

curl -X POST https://your-domain.com/webhook/telegram \
  -H "Content-Type: application/json" \
  -d '{"test": true}'

WebSocket Disconnections

grep "websocket" ~/.openclaw/logs/gateway.log | tail -20

Log Analysis

openclaw logs --follow
openclaw logs --level error --since "1h"
openclaw logs --since "24h" --output gateway-debug.log

Recovery Steps

When the issue is severe enough to require a reset:

openclaw stop
openclaw cache clear
openclaw configure --validate
openclaw start

Summary

The core approach to Gateway troubleshooting: use the Doctor command first for quick problem categorization, then dive deeper with logs and targeted checks. Keeping the log level at info or above helps with post-hoc analysis; setting up monitoring alerts ensures you are notified the moment an issue occurs.