OpenClaw Stuck on Starting — How to Fix It

Why OpenClaw Gets Stuck on Starting

When you deploy OpenClaw, it needs to initialize the gateway, connect to your AI model provider (like OpenRouter, OpenAI, or Gemini), and start any channel plugins you've configured (Telegram, Discord, etc.). If any of these steps fails, the instance can appear stuck on “Starting” indefinitely.

This can happen whether you're self-hosting OpenClaw with Docker or using a managed platform like OpenClaw Launch. The good news is that most causes are straightforward to diagnose and fix.

Quick Fixes (Try These First)

Before diving into detailed troubleshooting, try these quick fixes that resolve most “OpenClaw not starting” issues:

1. Wait 60–90 seconds — The first deployment takes longer than subsequent starts because OpenClaw needs to initialize its gateway, load plugins, and establish connections to AI model APIs. Give it at least 90 seconds before assuming something is wrong.
2. Restart the instance from your dashboard — If you're using OpenClaw Launch, go to your dashboard, find the stuck instance, and click Restart. For self-hosted setups, run docker restart openclaw.
3. Check your instance logs for specific error messages — Logs almost always reveal the exact reason for the failure. See the “How to Read Instance Logs” section below.

Common Causes and Solutions

1. Insufficient Memory

OpenClaw needs at least 2GB of RAM to run properly. If the container runs out of memory during startup, it will either crash silently or hang indefinitely. This is one of the most common reasons for an OpenClaw deployment failure.

• Self-hosting: Increase your container memory allocation. Use --memory=2g --memory-swap=3g in your Docker run command. Containers with only 512MB will almost certainly OOM (out of memory) during startup.
• Check current limits: Run docker stats openclaw --no-stream to see memory usage vs. limit.
• On OpenClaw Launch: Memory is pre-configured with adequate resources, so this shouldn't happen. If you see memory-related errors in your logs, contact support.

# Run OpenClaw with proper memory allocation
docker run -d \
  --name openclaw \
  --memory=2g \
  --memory-swap=3g \
  -p 18789:18789 \
  -v ~/.openclaw:/home/node/.openclaw \
  ghcr.io/openclaw/openclaw:latest \
  node openclaw.mjs gateway --allow-unconfigured

2. Invalid Configuration

A misconfigured openclaw.json file is another frequent cause of OpenClaw getting stuck on starting. The gateway will fail to initialize if any required configuration is missing or malformed.

• AI model API key: Verify your API key is valid and has not expired. Test it directly with the provider's API to confirm it works.
• Bot token (Telegram/Discord): Double-check that your bot token is correct. An invalid token will cause the channel plugin to fail at startup.
• Missing plugin entries: Both channels.telegram.enabled: true AND plugins.entries.telegram.enabled: true are required for a channel to start. Channel config alone is not enough.
• Gateway auth format: The gateway auth must be an object: { "token": "your-token" }, NOT a plain string like "auth": "your-token". Using the wrong format will prevent the gateway from starting.

# Verify your config is valid JSON
cat ~/.openclaw/openclaw.json | python3 -m json.tool

# Check inside a Docker container
docker exec openclaw cat /home/node/.openclaw/openclaw.json

3. Port Conflicts (Self-Hosting)

If another service is already using the OpenClaw gateway port (18789), the container will start but the gateway cannot bind to the port, causing it to appear stuck.

• Check if the port is in use: docker ps or ss -tlnp | grep 18789
• If another container is using port 18789, stop it or change the port mapping in your Docker run command (e.g., -p 18790:18789)
• If you're running multiple OpenClaw instances, each one needs a unique host port

# Check what's using port 18789
docker ps --format "table {{.Names}}	{{.Ports}}" | grep 18789

# Or check at the system level
ss -tlnp | grep 18789

4. Docker Image Issues (Self-Hosting)

An outdated or corrupted Docker image can cause OpenClaw to fail during startup. Always use the :latest tag for stable releases.

• Pull the latest image: docker pull ghcr.io/openclaw/openclaw:latest
• Avoid the :main tag — It's the bleeding-edge development version and may contain bugs that cause startup failures.
• Clear the stuck container and redeploy:

# Remove the stuck container
docker stop openclaw && docker rm openclaw

# Pull the latest stable image
docker pull ghcr.io/openclaw/openclaw:latest

# Redeploy
docker run -d \
  --name openclaw \
  --memory=2g \
  --memory-swap=3g \
  -p 18789:18789 \
  -v ~/.openclaw:/home/node/.openclaw \
  ghcr.io/openclaw/openclaw:latest \
  node openclaw.mjs gateway --allow-unconfigured

5. Network/Firewall Issues (Self-Hosting)

OpenClaw needs outbound internet access to connect to AI model provider APIs (OpenRouter, OpenAI, Anthropic, Google, etc.). If your server's firewall blocks outgoing HTTPS traffic, OpenClaw will hang during startup while trying to validate the API connection.

• Ensure outbound HTTPS (port 443) is allowed in your firewall rules
• If you're behind a corporate firewall or proxy, configure your Docker container to use the proxy
• If using a reverse proxy (Nginx, Caddy), make sure trustedProxies in the OpenClaw config uses exact IPs, not CIDR ranges. OpenClaw does strict === comparison on proxy addresses.

# Test outbound connectivity from the container
docker exec openclaw curl -s https://api.openai.com

# Check firewall rules on Ubuntu
sudo ufw status

# Verify trustedProxies uses exact IPs (not CIDR)
# Correct:   "trustedProxies": ["172.17.0.1"]
# Incorrect: "trustedProxies": ["172.17.0.0/16"]

How to Read Instance Logs

Instance logs are the fastest way to diagnose why OpenClaw is stuck on starting. They contain specific error messages that point directly to the problem.

On OpenClaw Launch

Go to your dashboard, click on the stuck instance, and click the “Logs” button. The most recent log entries will show what happened during startup.

Self-Hosting with Docker

# View the last 100 lines of logs
docker logs openclaw --tail 100

# Follow logs in real time
docker logs openclaw -f

# Check if the container is restarting in a loop
docker ps -a | grep openclaw

What to Look For

• Error or FATAL — Critical errors that prevented startup
• plugin not available — A channel plugin (Telegram, Discord) failed to load, usually due to a missing or invalid bot token
• ECONNREFUSED — Cannot connect to an external service (API provider, database, etc.)
• OOMKilled or out of memory — Container ran out of RAM, needs more memory
• EADDRINUSE — Port 18789 is already in use by another process
• invalid token or authentication failed — API key or bot token is incorrect

The Easy Fix: Use OpenClaw Launch

All of the issues above — memory limits, configuration formatting, port conflicts, Docker image versions, firewall rules — are things you never have to worry about with OpenClaw Launch.

OpenClaw Launch handles all configuration, memory allocation, networking, and Docker setup automatically. Deploy your AI agent in under 10 seconds, starting at $3/mo. No terminal, no Docker, no debugging stuck containers.

Frequently Asked Questions

Why is my OpenClaw stuck on “Starting”?

OpenClaw can get stuck on starting due to insufficient memory (needs at least 2GB RAM), invalid configuration (wrong API key, bad bot token, missing plugin entries), port conflicts, outdated Docker images, or network/firewall issues blocking outbound HTTPS. Check your instance logs for the specific error message.

How long should OpenClaw take to start?

A fresh OpenClaw deployment typically takes 60–90 seconds for the first start. Subsequent restarts are faster (10–30 seconds). If your instance has been starting for more than 2 minutes, something is likely wrong — check the logs for errors.

My OpenClaw container keeps restarting. What should I do?

A container restart loop usually indicates either an out-of-memory crash or a fatal configuration error. Check docker logs openclaw --tail 50 for the error, ensure you're using --memory=2g --memory-swap=3g, and verify your openclaw.json is valid JSON with correct API keys and bot tokens.

Related Guides

• OpenClaw Docker Setup Guide — Complete Docker deployment walkthrough
• OpenClaw Gateway Token Setup — Configure your gateway authentication
• OpenClaw Telegram Bot Setup — Connect your AI agent to Telegram
• OpenClaw Discord Bot Setup — Connect your AI agent to Discord
• OpenClaw Hosting Guide — Choose the best hosting for OpenClaw