In This Article
Introduction
The OpenClaw Gateway typically runs on 127.0.0.1:18789. 127.0.0.1 is localhost — the machine itself. The Gateway only listens on this interface by default, meaning it's not accessible from the network. This is a security feature: only processes on the same machine can connect. Exposing the Gateway to 0.0.0.0 or a public IP was a major cause of the 135K exposed instances discovered in early 2026.
Understanding this binding is critical for both security and getting it running. New users sometimes wonder why they can't reach their agent from another device — the answer is deliberate: the Gateway is designed to be local-only. Messaging platforms (Telegram, WhatsApp, Slack) reach OpenClaw through their own APIs and webhooks, not through direct Gateway access. This article explains the architecture, the security rationale, and when (if ever) you might need to change it.
Default Binding
127.0.0.1 is the IPv4 loopback address. Traffic to 127.0.0.1 never leaves the machine — it's routed internally by the operating system. Any service bound to 127.0.0.1 is invisible to the network. Other computers cannot connect to it. Only processes running on the same host can reach it.
18789 is the default port for the OpenClaw Gateway's WebSocket server. The Gateway uses WebSocket for real-time communication between its components — the channel adapters, the agent runtime, and any local clients. The port number is somewhat arbitrary (it doesn't correspond to a well-known service) but has become the standard in OpenClaw configurations.
Together: 127.0.0.1:18789 means "listen only on localhost, port 18789." The Gateway accepts connections from localhost only. This is the secure default in OpenClaw 2026.2.17 and later.
How Messaging Reaches the Gateway
A common misconception: "If the Gateway is on localhost, how does Telegram reach it?" The answer: Telegram doesn't connect to the Gateway directly. Here's the flow:
- You send a message to your OpenClaw bot on Telegram.
- Telegram's servers receive the message and forward it to your webhook URL — a URL you configured when setting up the bot (e.g.,
https://your-server.com/webhook/telegram). - Your web server (or a reverse proxy like Nginx/Caddy) receives the webhook request and forwards it to the OpenClaw process. This forwarding happens locally — the web server and OpenClaw run on the same machine.
- The OpenClaw Gateway, listening on 127.0.0.1:18789, receives the message through its internal channel adapters. The adapters may use HTTP callbacks, long polling, or other mechanisms — but they all communicate with the Gateway over localhost.
The key insight: the Gateway never needs to be exposed to the internet. External traffic hits your web server (on port 443). The web server proxies to localhost:18789. The Gateway stays local. See Gateway architecture for the full picture.
Security: Why Localhost Matters
Never bind the Gateway to 0.0.0.0 (all interfaces) unless you're behind a firewall, VPN, or private network with strict access controls. Never expose port 18789 to the public internet. The 21K→135K exposed instances incident was caused by users binding the Gateway to 0.0.0.0 or a public IP with no authentication. Anyone on the internet could send commands to those agents. See exposed instances.
When the Gateway is on 127.0.0.1, an attacker would need to already have access to your machine (via SSH, malware, or physical access) to reach it. That's a much higher bar than "anyone on the internet." The default localhost binding is a critical defense-in-depth measure.
If you need remote access — for example, to manage the agent from a different machine — use SSH port forwarding: ssh -L 18789:127.0.0.1:18789 user@your-openclaw-server. This creates a secure tunnel. Your local machine can then connect to localhost:18789, and the traffic is forwarded over SSH. No need to expose the Gateway.
When You Might Change the Binding
In rare cases, you might bind to a different address:
- Docker networking: If OpenClaw runs in a Docker container and another container needs to reach it, use the Docker network. The Gateway can bind to 0.0.0.0 inside the container — the container's network is isolated. The host still doesn't expose 18789.
- Private VLAN: In a tightly controlled private network (e.g., a Kubernetes cluster with no public ingress to the Gateway), binding to a private IP might be acceptable. Document the decision and ensure the network is restricted.
- Custom port: You can change the port (e.g., 18790) if 18789 conflicts with another service. The host should still be 127.0.0.1.
When in doubt, keep 127.0.0.1. See OpenClaw security for full guidance.
Troubleshooting
"I can't connect to the Gateway from my browser on another machine." That's by design. Use SSH port forwarding or a reverse proxy with authentication. The Gateway is not meant for direct remote access.
"My reverse proxy can't reach the Gateway." If the proxy runs on the same machine as OpenClaw, it should connect to 127.0.0.1:18789. If the proxy runs in a different container, ensure Docker networking is configured so the proxy can reach the OpenClaw container's port.
"Connection refused on 127.0.0.1:18789." The Gateway isn't running, or it's bound to a different port. Check config.yaml for the gateway host and port. Verify the OpenClaw process is running.
Wrapping Up
127.0.0.1:18789 is the secure default for the OpenClaw Gateway. Keep it that way. Messaging platforms reach your agent through webhooks and local adapters — the Gateway never needs to be exposed. See Gateway architecture and security best practices.