DEV Community

zac
zac

Posted on • Originally published at remoteopenclaw.com

OpenClaw Error: Config Validation Failed gateway.bind...

#claude #ai #productivity #tutorial

Originally published on Remote OpenClaw.

OpenClaw Error: Config Validation Failed gateway.bind Invalid Input — Fix

Marketplace

Free skills and AI personas for OpenClaw — browse the marketplace.

Browse the Marketplace →

Join the Community

Join 1k+ OpenClaw operators sharing deployment guides, security configs, and workflow automations.

Join the Community →

What Does This Error Mean?

The full error looks like this:

Error: Config Validation Failed
 → gateway.bind: Invalid input
Enter fullscreen mode Exit fullscreen mode

OpenClaw validates its configuration at startup. The gateway.bind field tells OpenClaw which network interface and port to listen on for incoming connections (web UI, API, webhook callbacks). If this field contains a value that does not match the expected IP:PORT format, the validation fails and OpenClaw refuses to start.

This is a strict validation — OpenClaw does not try to guess what you meant or fall back to a default. If the value is invalid, you get this error and the process exits.

The gateway is the HTTP server that powers the web UI, the REST API, and webhook endpoints. Without a valid bind address, it cannot start listening for connections, so OpenClaw halts entirely rather than running in a broken state.

What Is the Correct Format?

The gateway.bind value must be a valid IPv4 address followed by a colon and a port number. No protocol prefix, no hostname, no path.

Valid examples:

0.0.0.0:18789 ← Listen on all interfaces, port 18789 (default)
127.0.0.1:18789 ← Listen on localhost only, port 18789
0.0.0.0:8080 ← Listen on all interfaces, custom port 8080
192.168.1.50:3000 ← Listen on a specific interface, custom port
Enter fullscreen mode Exit fullscreen mode

Invalid examples that cause this error:

http://0.0.0.0:18789 ← Do not include the protocol
localhost:18789 ← Do not use a hostname
:18789 ← Must include the IP address
0.0.0.0 ← Must include the port
0.0.0.0:99999 ← Port must be 1-65535
0.0.0.0: 18789 ← No spaces allowed
Enter fullscreen mode Exit fullscreen mode

The default value is 0.0.0.0:18789. If you have never changed this setting and are getting the error, something in your environment is overriding the default.

What Are the Most Common Mistakes?

Including http:// or https://. This is the most common cause. People instinctively add a protocol prefix because it looks like a URL. The bind address is not a URL — it is a socket address. Remove the protocol.

Using a hostname instead of an IP. localhost:18789 or my-server:18789 will not work. Use the actual IP address. For localhost, use 127.0.0.1.

Trailing or leading spaces. Invisible whitespace is a frequent cause of validation errors. Check your .env file carefully. Some text editors add trailing spaces or invisible characters.

Quoting issues in docker-compose.yml. If you set the bind address in docker-compose.yml, YAML parsing can cause issues with certain characters. Use quotes around the value:

environment:
 GATEWAY_BIND: "0.0.0.0:18789"
Enter fullscreen mode Exit fullscreen mode

Port number out of range. Port must be between 1 and 65535. Ports below 1024 require root privileges. The default 18789 is a safe high-numbered port that works without elevated permissions.

Legacy variable names. If upgrading from MoltBot or ClawdBot, the old variable might be MOLTBOT_GATEWAY_BIND or CLAWDBOT_GATEWAY_BIND. OpenClaw 3.22 only recognizes GATEWAY_BIND.

Marketplace

Free skills and AI personas for OpenClaw — browse the marketplace.

Browse the Marketplace →

Stats: IP:PORT Correct Format; 18789 Default Port; 0.0.0.0 Docker Bind; No http:// Common Mistake

Key numbers to know

How Do You Fix It Step by Step?

Follow these steps in order:

Step 1: Find where gateway.bind is set.

Check three locations, in order of precedence:

  1. Environment variables (GATEWAY_BIND in your shell, .env file, or docker-compose.yml)
  2. Config file (gateway.bind in config.json or config.yaml)
  3. Command-line flags (--gateway-bind if passed directly)

The environment variable overrides the config file, and the command-line flag overrides both.

Step 2: Check the .env file.

# Look for the GATEWAY_BIND variable
grep -i gateway .env
Enter fullscreen mode Exit fullscreen mode

If you find it, verify the format is exactly IP:PORT with no extra characters.

Step 3: Check docker-compose.yml.

Look under the environment section of your OpenClaw service for any GATEWAY_BIND entry. Also check for legacy names like MOLTBOT_GATEWAY_BIND or CLAWDBOT_GATEWAY_BIND.

Step 4: Check config.json.

If you have a config.json file mounted into the container, look for:

{
 "gateway": {
 "bind": "0.0.0.0:18789"
 }
}
Enter fullscreen mode Exit fullscreen mode

Ensure the value follows the correct format.

Step 5: Fix and restart.

Correct the value to a valid IP:PORT format and restart:

docker compose down && docker compose up -d
Enter fullscreen mode Exit fullscreen mode

Check the logs to confirm the error is gone:

docker compose logs openclaw | head -20
Enter fullscreen mode Exit fullscreen mode

How Does Bind Address Work in Docker vs Bare Metal?

In Docker: Use 0.0.0.0:18789. This tells OpenClaw to listen on all network interfaces inside the container. Docker handles port mapping from the container to the host via the ports directive in docker-compose.yml. Using 127.0.0.1 inside Docker means the gateway only accepts connections from inside the container — nothing external can reach it, including your browser.

services:
 openclaw:
 ports:
 - "18789:18789" # host:container
 environment:
 GATEWAY_BIND: "0.0.0.0:18789"
Enter fullscreen mode Exit fullscreen mode

On bare metal: You have more flexibility. Use 127.0.0.1:18789 if you are running a reverse proxy (Nginx, Caddy) on the same machine and want the gateway to only accept local connections. Use 0.0.0.0:18789 if you want the gateway to be directly accessible from external machines.

If you are behind a reverse proxy, the common pattern is:

Internet → Reverse Proxy (443) → OpenClaw (127.0.0.1:18789)
Enter fullscreen mode Exit fullscreen mode

This keeps the gateway off the public internet while the proxy handles TLS termination and access control.

How Do You Prevent This in the Future?

A few practices to avoid config validation errors:

  • Use the default. Unless you have a specific reason to change the bind address, leave it at the default 0.0.0.0:18789. Do not set GATEWAY_BIND at all, and the default will be used.
  • Validate before restarting. OpenClaw 3.22+ includes a config validation command: openclaw config validate. Run this before restarting to catch errors early.
  • Keep your .env clean. Only set variables you actually need to change. Every unnecessary variable is a potential source of errors. Comment out old values instead of leaving them active.
  • Use quotes in YAML. When setting environment variables in docker-compose.yml, always quote values that contain colons to avoid YAML parsing issues.
  • Version control your config. Keep your .env and docker-compose.yml in a Git repository (with sensitive values in a .gitignore'd .env.local). This lets you track changes and revert if something breaks.

Top comments (0)