Fix: Gateway Not Running

The symptom

You try to use your Telegram or WhatsApp bot, but it does not reply. When you check your server, the OpenClaw Gateway is no longer running. Alternatively, when you try to start it, it crashes immediately with an error stack trace.

Quick diagnosis flow

The first step is figuring out why it stopped. The fix depends entirely on the error message.

Check 1: Did it stop when you closed your laptop?

If you started OpenClaw by running npx openclaw start and then closed your terminal or laptop, the process died. When you disconnect from an SSH session, Linux kills any programs running in that session.

The Fix: You need a process manager like PM2 to run the Gateway in the background. See the Run OpenClaw After Logout guide.

Check 2: Run it manually to see the error

If PM2 says the process is stopped or “errored”, stop PM2 and run the Gateway manually in the foreground. This forces the error to print directly to your screen.

Watch the output closely. Compare what you see against the common failures below.

Common crash errors

1. “EADDRINUSE: address already in use :::18789”

Meaning: The Gateway cannot start because another program (or a duplicate/zombie Gateway process) is already listening on port 18789.

Diagnosis: Find out what is using the port:

The Fix: Kill the process holding the port. If the ss command shows pid=1234, run:

Then try starting the Gateway again.

2. “SyntaxError” or “Unexpected token” immediately on boot

Meaning: Your Node.js version is too old. OpenClaw requires modern JavaScript features.

Diagnosis: Check your Node version:

The Fix: If the output is v18 or lower, you must upgrade. Do not use Ubuntu’s default apt package manager for this. Follow Step 1 in the Install Guide to install the latest LTS version using nvm.

3. “EACCES: permission denied” on .env or database.sqlite

Meaning: The Gateway does not have the correct file permissions to read its configuration or write to its database. This almost always happens because you previously ran commands using sudo or as the root user.

The Fix: Change the ownership of your entire workspace back to your normal user:

4. Silent crash after channel config change

Meaning: If you recently edited your .env file (e.g., adding a Telegram token or WhatsApp number) and the Gateway crashes silently, you may have introduced a syntax error in the .env file.

The Fix:

• Check for missing quotes around values with spaces.
• Check for accidental line breaks in the middle of a token.
• Ensure there are no spaces immediately before or after the = sign (e.g., TELEGRAM_TOKEN=123..., not TELEGRAM_TOKEN = 123...).

Safe restart path

Once you have identified and fixed the issue, verify the Gateway runs properly in the foreground:

If it boots without errors and shows Listening on 127.0.0.1:18789, stop it with Ctrl+C, and restart it using PM2:

Prevention checklist

• I am running Node.js v20 LTS or higher.
• I am using PM2 to keep the Gateway running in the background.
• I never use sudo to run npm or openclaw commands.
• My .env file is properly formatted.

When to ask for help

If the Gateway crashes with an obscure database error, a Node module missing error, or a channel API failure, you may need community assistance.

Request help via the Setup Help service or community forum. Redaction Warning: When sharing crash logs, read through them carefully. The stack trace might contain your bot token, API keys, or VPS IP address. Redact these (replace with XXX) before posting the log. Never share your raw .env file.