How to Fix the OpenClaw "Gateway Not Reachable" Error [Complete 2026 Guide]

Introduction

If you have been working with OpenClaw and suddenly hit the dreaded "Gateway not reachable" message, you are not alone. This is one of the most frequently reported errors across OpenClaw's GitHub issues, Discord community, and developer forums. The good news is that it is almost always fixable, and in most cases, you can resolve it in under a minute.

This guide walks you through every known cause of the error, from the simplest token mismatch to more complex scenarios involving Docker containers, remote servers, and zombie processes. Each section is organized so you can jump straight to the fix that matches your setup.

Whether you are running OpenClaw on a local macOS machine, a Linux VPS, or inside Docker containers, the solutions here have been tested and confirmed by the community as of March 2026.

Skip the Setup Entirely with Entro

If you'd rather not deal with Gateway configuration, token management, Docker containers, or SSH tunnels at all, consider using Entro — a managed platform that runs OpenClaw for you. Entro handles the entire infrastructure behind the scenes: your AI agents run on fully managed containers with automatic provisioning, idle shutdown, and zero server maintenance. Unlike self-hosted setups where you need to worry about process crashes and service restarts, Entro keeps your agents up and running 24/7. You just create your agent team, connect your integrations (Gmail, Slack, Telegram, WhatsApp, Notion, and 19+ others), and start working. No Gateway tokens, no port conflicts, no zombie processes. There's a free 5-day trial with no credit card required, so you can see if it fits your workflow before committing to self-hosting.

1. What Does "Gateway Not Reachable" Actually Mean?

Before diving into fixes, it helps to understand what is happening behind the scenes when you see this error.

OpenClaw uses a hub-and-spoke architecture built around a single Gateway process. This Gateway is a WebSocket server that acts as the central control plane for everything: your messaging channels (WhatsApp, Telegram, Slack, Discord, and others), the AI agent runtime, the CLI tools you use in your terminal, the browser-based Control UI dashboard, and any companion apps on macOS, iOS, or Android.

When you see "Gateway not reachable," it means that whatever client you are using (the dashboard, CLI, or a messaging channel) cannot establish a WebSocket connection to the Gateway process. The default connection target is ws://127.0.0.1:18789, but this can vary depending on your configuration.

The underlying causes typically fall into one of four categories:

The Gateway is not running at all. The process may have crashed, was never started, or failed during startup.

Authentication failure. The Gateway is running, but your client is sending the wrong token (or no token), so the connection gets rejected with a 1008 WebSocket close code.

Port conflict or zombie process. Another process is occupying port 18789, preventing the Gateway from binding or causing clients to connect to the wrong process.

Network or binding issue. The Gateway is bound to an interface your client cannot reach, or an SSH tunnel or VPN is not configured correctly.

2. Quick Diagnosis: Identify Your Problem in 30 Seconds

Open a terminal and run these two commands. The output will tell you exactly which section of this guide to jump to.

openclaw gateway status
openclaw logs --follow

Here is how to read the output:

Pro Tip: The command openclaw status --all gives you a complete, credential-safe report of your entire configuration. It is safe to share when asking for help because it automatically redacts sensitive values.

3. The 60-Second Fix That Works for Most People

If you just want the fastest possible solution without reading the full guide, run this single command:

openclaw doctor --fix

This command runs a comprehensive health audit of your OpenClaw setup. It checks for service configuration drift, permission issues, missing directories, risky DM policies, and outdated settings. If it finds problems, it attempts to fix them automatically.

For many users, especially those who hit this error right after a fresh install or an update, this one command resolves everything. If it does not fix your situation, keep reading to identify and address the specific root cause.

4. Gateway Token Mismatch: The Most Common Root Cause

The single most common reason for the "Gateway not reachable" error is a mismatch between the authentication token stored in your configuration and the token the client is trying to use.

How Token Authentication Works

When your Gateway starts, it reads a token from the gateway.auth.token field in your configuration file (usually located at ~/.openclaw/openclaw.json). Every client that connects, whether it is the CLI, the browser dashboard, or a companion app, must present this same token during the WebSocket handshake. If the tokens do not match, the Gateway immediately closes the connection with a 1008 status code.

Step-by-Step Fix

First, generate a fresh cryptographic token and set the authentication mode:

openclaw config set gateway.auth.mode token
openclaw config set gateway.auth.token "$(openssl rand -hex 32)"

Next, make sure the remote token matches the auth token. This is the value your CLI and other clients use to connect:

openclaw config set gateway.remote.token "YOUR_NEW_TOKEN_HERE"

Finally, restart the Gateway to apply the changes:

openclaw gateway restart

Watch Out for Legacy Config Keys: Older versions of OpenClaw used different configuration keys like gateway.token or gateway.auth.type. If these leftover keys are still present in your config file, they can confuse the Gateway. Run openclaw doctor --fix to clean them up automatically.

Verify the Fix

After restarting, confirm that the Gateway is healthy:

openclaw gateway status

You should see "Runtime: running" and "RPC probe: ok" in the output. If the dashboard is open in your browser, refresh it or open a new incognito window to clear any cached tokens.

5. Gateway Process Not Running or Stuck

Sometimes the problem is simply that the Gateway process never started, or it started but crashed shortly after.

Check the Current Status

openclaw gateway status

If the output shows "Runtime: stopped" or displays an exit code, the Gateway is not running.

Common Reasons the Gateway Fails to Start

Local mode not enabled. By default, the Gateway refuses to start unless gateway.mode is set to "local" in your configuration. If you missed this during setup, run:

openclaw configure

Or manually edit your configuration file and set gateway.mode to "local."

Service config mismatch. If you installed OpenClaw as a system service (via launchd on macOS or systemd on Linux), the service might be using a different configuration file than the one you are editing. Run this to check:

openclaw gateway status --deep

Look for the "Config (cli)" and "Config (service)" lines. If they show different paths, you are editing the wrong file. Fix this by reinstalling the service from the correct profile:

openclaw gateway install --force
openclaw gateway start

Restart Methods by Platform

On macOS, you can restart the Gateway from the OpenClaw menu bar app, or use the terminal:

openclaw gateway restart

On Linux with systemd:

systemctl --user restart openclaw-gateway

If neither works, try stopping the service completely and starting fresh:

openclaw gateway stop
openclaw gateway start

6. Zombie Processes and Port Conflicts

A zombie process is one that crashed but did not release its hold on port 18789. When this happens, a new Gateway instance may fail to start, or worse, clients may connect to the dead process and get rejected because it has stale authentication tokens.

How to Detect a Zombie Process

On macOS or Linux:

lsof -i :18789

On Windows:

netstat -ano | findstr :18789

If a process shows up while the Gateway is supposedly stopped, that is your zombie.

How to Kill It

On macOS or Linux, use the process ID from the previous command:

kill -9 <PID>

On Windows:

taskkill /PID <PID> /F

After killing the zombie, verify the port is free (the lsof or netstat command should return nothing), then start the Gateway cleanly:

openclaw gateway start

Quick Alternative: The Gateway's start command supports a --force flag that automatically kills any existing process on the configured port before starting. Use openclaw gateway start --force if you want to skip the manual steps.

7. Docker and Container-Specific Fixes

Running OpenClaw in Docker introduces an extra layer of complexity because of how environment variables interact with configuration files.

The Silent Override Problem

When you run OpenClaw in Docker, environment variables set in your docker-compose.yml or docker run command take priority over everything in the mounted configuration file. This means that even if your ~/.openclaw/openclaw.json has the correct gateway token, a stale OPENCLAW_GATEWAY_TOKEN environment variable from a previous deployment will override it.

The symptom is persistent "token mismatch" or "gateway not reachable" errors that resist all normal troubleshooting. The configuration files look correct, but the Gateway is reading a different value from the environment.

How to Diagnose

Check for environment variable overrides inside the running container:

docker exec <container_name> env | grep OPENCLAW

If OPENCLAW_GATEWAY_TOKEN appears in the output and its value differs from what is in your mounted config file, you have found the problem.

How to Fix

Set a fixed, explicit token in your docker-compose.yml so that both the Gateway and CLI containers share the same value:

services:

  openclaw-gateway:

    image: openclaw/gateway:latest

    environment:

      OPENCLAW_GATEWAY_TOKEN: "your-fixed-token-here"

    ports:

      - "18789:18789"

  openclaw-cli:

    image: openclaw/cli:latest

    environment:

      OPENCLAW_GATEWAY_TOKEN: "your-fixed-token-here"

      OPENCLAW_GATEWAY_URL: "ws://openclaw-gateway:18789"

The key point is that both containers must use exactly the same token. If the Gateway regenerates a random token on each restart and the CLI container has a cached old one, the connection will break every time you redeploy.

8. Remote Access and SSH Tunnel Troubleshooting

If you are running OpenClaw on a remote server (a VPS, for example) and accessing it from your laptop, the "Gateway not reachable" error often comes down to network configuration rather than authentication.

The Golden Rule

Keep the Gateway bound to loopback (127.0.0.1) and access it through a secure tunnel. Never expose port 18789 directly to the public internet unless you fully understand the security implications. An exposed Gateway means an AI agent with system access is reachable by anyone who finds your server's IP address.

Setting Up an SSH Tunnel

From your local machine, forward port 18789 through SSH:

ssh -L 18789:127.0.0.1:18789 user@your-server-ip

Once the tunnel is active, you can access the Gateway at ws://127.0.0.1:18789 on your local machine, just as if it were running locally.

For a more permanent setup, consider using Tailscale. OpenClaw supports Tailscale natively, and you can configure it so the Gateway is accessible across your tailnet without any manual tunneling.

Common Remote Access Mistakes

Binding to 0.0.0.0. Some tutorials show this configuration for convenience, but it exposes your Gateway (and the AI agent with system access) to the entire internet. Always prefer loopback plus a tunnel.

Forgetting auth on non-loopback binds. If you do bind to a LAN or tailnet interface, the Gateway requires authentication. Without gateway.auth.token configured, it will refuse to start as a safety measure.

Stale SSH tunnel. If your SSH session dropped and the tunnel is no longer active, your local client will try to connect to a port that no longer forwards anywhere. Reestablish the tunnel before troubleshooting further.

9. Full Reset: The Nuclear Option

If you have tried everything above and the error persists, a complete reset of the Gateway's authentication state will give you a clean starting point.

openclaw gateway stop
openclaw gateway token reset
openclaw gateway install --force
openclaw gateway start

After running these commands, all previously connected devices will need to re-authenticate. Open the Dashboard in an incognito browser window so it does not try to use a cached token from your previous session.

Important: A token reset disconnects every connected client and device. If you have companion apps on macOS, iOS, or Android connected to this Gateway, they will all need to reconnect with the new credentials.

Once the Gateway is back up, verify its health:

openclaw gateway status
openclaw doctor

Both commands should report a clean, healthy state with no warnings.

10. Prevention: Stop This Error From Coming Back

Now that you have resolved the immediate problem, here are a few habits that will keep your OpenClaw Gateway stable over time.

Run openclaw doctor after every update. Updates can introduce new configuration keys or deprecate old ones. The doctor command catches these changes before they cause problems.

Pin your token in Docker deployments. Never rely on auto-generated tokens in containerized setups. Set OPENCLAW_GATEWAY_TOKEN explicitly in your Docker configuration so it survives container rebuilds.

Use a process manager for production. Install OpenClaw as a system service (openclaw gateway install) so it starts automatically on boot and restarts on crashes. Running it in the foreground is fine for development, but unreliable for long-term use.

Keep one Gateway per host. Unless you are intentionally running isolated profiles, multiple Gateway instances on the same host will fight over the default port and cause confusing errors.

Monitor your logs. A quick openclaw logs --follow after any configuration change will immediately surface problems before they become mysterious failures hours later.

11. Frequently Asked Questions

1. Do I need to regenerate the token every time I restart the Gateway?

No. The token is stored in your configuration file and persists across restarts. You only need to regenerate it if you want to rotate it for security reasons, or if you somehow lost the original value.

2. Can multiple browsers or devices use the same token?

Yes. Token-based authentication uses a single shared secret. Anyone who has the token can connect to the Gateway. For setups where you need individual credentials per user, consider using password authentication or setting up device pairing through the Control UI.

3. I am on Windows. Do I need WSL?

The OpenClaw team strongly recommends running the Gateway inside WSL2 (Ubuntu is the preferred distribution) rather than natively on Windows. Native Windows has known compatibility issues with some channel providers and tools, particularly WhatsApp and Telegram. If you are experiencing gateway errors on Windows, switching to WSL2 is often the simplest path to a stable setup.

4. The dashboard loads, but chat messages hang forever. Is that the same error?

It is closely related. If the dashboard HTML loads but the WebSocket connection is rejected with a 1008 error, the root cause is almost always the token mismatch described in Section 4. Generate a new token, then either use a tokenized dashboard URL (openclaw dashboard --no-open) or paste the token into the Control UI settings.

5. I fixed the error, but it comes back after every Gateway restart.

This usually points to one of two issues. The first is an environment variable silently overriding your config file, which is common in Docker setups (covered in Section 7). The second is that the system service is running from a different configuration file than the one you are editing. Run openclaw gateway status --deep and compare the "Config (cli)" and "Config (service)" paths to catch this.

6. I upgraded OpenClaw and now the Gateway will not start. What happened?

When you update OpenClaw, the config key format sometimes changes between versions. For example, the key gateway.token was renamed to gateway.auth.token in recent releases, and the old key no longer works. Running openclaw doctor --fix after every update will automatically catch and migrate these renamed or deprecated keys. It is the single most important post-update habit you can build.

7. What is the "pairing required" error, and how is it different from "gateway not reachable"?

The "pairing required" error means the Gateway is running and reachable, but it does not recognize your device. This is actually a security feature, not a bug. Every new browser or device that connects to OpenClaw needs to be approved before it can interact with the agent. You can approve pending devices through the dashboard settings, or use the CLI with openclaw pairing list followed by openclaw pairing approve with the appropriate channel and code.

8. My config file looks correct, but I still get token errors. What else could be wrong?

There is a subtle issue that catches a lot of people. On macOS, your terminal session has the OPENCLAW_GATEWAY_TOKEN environment variable loaded, but the LaunchAgent that runs the Gateway service does not inherit your shell environment. So even if the env variable looks right in your terminal, the actual Gateway process might be reading a completely different value (or none at all). The safest approach is to set the token directly in the config file rather than relying on environment variables for macOS LaunchAgent setups.

9. Can I change the default Gateway port from 18789?

Yes. You can change it using the config command:

openclaw config set gateway.port 19000

After changing the port, reinstall the service with openclaw gateway install --force and restart. Keep in mind that if you change the port, you also need to update any clients, SSH tunnels, or reverse proxy configurations that reference the old port number. Do not edit the JSON config file directly for port changes if you can avoid it, since there are related settings that need to stay consistent.

10. The Gateway starts but crashes immediately with a 1006 WebSocket error. What does that mean?

A 1006 close code means the connection was terminated abnormally without a proper close frame. This is different from 1008 (which is a deliberate rejection). A 1006 right after startup usually points to a plugin or extension that is crashing during load. The fix is to temporarily disable non-core plugins in your configuration, confirm the Gateway stays stable on its own, and then re-enable plugins one by one until you find the problematic one.

11. How long does the Gateway take to fully start in Docker?

In containerized environments, the Gateway can take approximately 30 to 40 seconds to fully initialize. The log line that says "Starting OpenClaw gateway" does not mean the Gateway is ready to accept connections. You need to wait until you see the "listening on" log line before sending any requests. If you are using health checks or startup scripts, make sure they wait for that specific log output rather than just checking if the process is alive.

12. Do I need to set up authentication if I am only running OpenClaw locally on my own machine?

If your Gateway is bound to loopback (127.0.0.1), which is the default, then only processes on your own machine can reach it. As of version 2026.2.19, OpenClaw will auto-generate and persist a gateway.auth.token at startup if you have not set one yourself, so the Control UI and clients can connect without manual setup. You can also explicitly set gateway.auth.mode to "none" for local-only loopback setups if you prefer to skip authentication entirely.

13. I am running OpenClaw behind Nginx or Caddy. Could that be causing the problem?

Yes, reverse proxies are a common source of gateway connectivity issues. The most frequent problem is that the proxy is not forwarding WebSocket connections properly. Make sure your proxy configuration includes WebSocket upgrade headers. Also, if your proxy sits between the client and the Gateway, you need to add the proxy's IP address to gateway.trustedProxies in your config so the Gateway recognizes it and reads the real client IP from the forwarded headers. Without this, the Gateway may treat all connections as coming from an unknown remote source and enforce stricter pairing requirements.

14. What is the minimum system requirement to run the OpenClaw Gateway?

The Gateway needs at least 256MB of available RAM to run reliably. It also requires Node.js 22 or newer. If you are running on a memory-constrained VPS or container, make sure you have enough headroom. When the system is low on memory, the Gateway can behave unpredictably, sometimes starting but then failing to complete WebSocket handshakes, which produces error messages that look like authentication failures but are actually resource problems.

15. I migrated from Clawdbot (the old name) to OpenClaw. Could leftover files be causing this?

Absolutely. The installer does a solid job of migrating your old .clawdbot directory to .openclaw and even creates a symlink for backward compatibility. However, there is a known issue where the old clawdbot-gateway.service sometimes keeps running in the background after the migration. When both the old and new Gateway processes try to use port 18789 at the same time, you get a restart loop where the new Gateway repeatedly fails with "another gateway instance is already listening." Check for and stop any old Clawdbot services before starting the new OpenClaw Gateway. On Linux, run systemctl --user list-units and look for anything with "clawdbot" in the name.

16. The Gateway is running and healthy, but my WhatsApp or Telegram bot is not responding to messages. What is going on?

This is a different problem from "gateway not reachable," but it looks almost identical from the outside. When the Gateway is running fine but your messaging channels stay silent, the issue is usually one of three things. First, check whether DM pairing is blocking the message. OpenClaw ships with a safety-first default where unknown contacts are not processed until you manually approve them. Run openclaw pairing list whatsapp (or replace whatsapp with telegram) to see if there are pending pairing requests, and approve them with openclaw pairing approve followed by the channel name and code. Second, make sure your AI provider credentials are valid. Run openclaw models status to check whether your Anthropic or OpenAI key is active and authenticated. If the key expired or ran out of credits, the agent will accept messages but never produce a response, which makes it look like the Gateway is broken when it is actually just the model layer that is failing. Third, for Telegram specifically, make sure you are using Node.js and not Bun to run the Gateway. The official documentation warns that Bun has known issues with WhatsApp and Telegram channel adapters.

17. I edited my openclaw.json config file, but the changes do not seem to take effect. Do I always need to restart?

It depends on what you changed. Some settings are picked up through hot reload without a restart. These include most timeout and interval values, model parameters within already-configured providers, and certain channel toggles. However, some changes absolutely require a full Gateway restart before they take effect. These include adding or removing model providers, changing port or bind settings, modifying the agent structure or routing, and any authentication profile changes. If you made a change and the behavior seems stale, restart the Gateway before spending time debugging further. The safest approach is to always run openclaw gateway restart after making config edits, especially if you are unsure whether the specific setting supports hot reload.

18. My Gateway starts, but the browser dashboard says "device identity required." How do I fix that?

This error is different from the regular token mismatch issue. It happens when you open the Control UI dashboard over plain HTTP (not HTTPS) on a non-loopback address. For example, if you access the dashboard at http://192.168.1.50:18789 or http://your-tailscale-ip:18789, the browser runs in a non-secure context. In that environment, the WebCrypto API is blocked, and the dashboard cannot generate the device identity it needs to complete the authentication handshake. There are two ways to fix this. The first and simplest is to access the dashboard through localhost (http://127.0.0.1:18789), which browsers always treat as a secure context even over HTTP. If you are accessing the dashboard from a different machine, set up an SSH tunnel or use Tailscale Serve to put HTTPS in front of the Gateway. The second option is to use the terminal-based interface instead. Run openclaw chat or openclaw tui to interact with your agent directly from the command line, bypassing the browser entirely.

19. Can I run multiple OpenClaw Gateway instances on the same machine?

You can, but only if you do it intentionally with isolated profiles. Each Gateway instance needs its own port, its own configuration directory, and its own state directory. If two instances share any of these, you will get token collisions, port conflicts, and intermittent errors that are extremely difficult to debug. Most users should stick with a single Gateway per machine. The multi-gateway setup is designed for advanced use cases, like running a separate "rescue bot" alongside your primary agent, or keeping work and personal assistants completely isolated. If you just need to route different channels to different personas, you do not need multiple Gateways. OpenClaw supports multi-agent routing within a single Gateway, where you can route specific channels or accounts to isolated agents, each with their own workspace and session history.

20. Where are the OpenClaw log files stored, and how do I enable verbose logging for deeper troubleshooting?

Live logs are the fastest way to see what is happening in real time. Run openclaw logs --follow to stream them directly in your terminal. For persistent log files that you can review later, check the path /tmp/openclaw-<uid>/openclaw-YYYY-MM-DD.log on Linux, or the equivalent temp directory on macOS. The exact path shows up in the output of openclaw gateway status under the "File logs" line. If you need more detail than the default logs provide, start the Gateway with the verbose flag by running openclaw gateway --verbose in the foreground. You can also set the verboseLevel in your configuration file if you want verbose logging to persist across restarts without having to pass the flag every time. Verbose mode adds timestamps, severity levels, and detailed context about each operation, which is especially useful when you need to share diagnostic output with the community or when filing a bug report on GitHub.

Final Thoughts

The "Gateway not reachable" error in OpenClaw is one of those problems that looks intimidating the first time you see it, but almost always has a straightforward solution. In the vast majority of cases, running openclaw doctor --fix or regenerating your gateway token will get you back up and running in under a minute.

For more complex setups involving Docker, remote servers, or multi-device configurations, the key is understanding that the Gateway is a single WebSocket server with token-based authentication, and that every client connecting to it must present the exact same token. Once you internalize that mental model, diagnosing and fixing connection issues becomes second nature.

If you found this guide helpful, consider bookmarking it. OpenClaw is evolving rapidly, and the troubleshooting steps here reflect the latest best practices from the community and official documentation as of March 2026.