OpenClaw Gateway: Configuration & Binding Options

Introduction

The OpenClaw Gateway is configured through a combination of CLI flags, environment variables, and a JSON configuration file. Understanding the precedence rules and binding modes is critical for deploying the Gateway securely in different network environments. This lesson covers the config file format, port resolution order, and how binding modes control network exposure.

Key Concepts

• Config File (openclaw.json): The primary configuration file located at ~/.openclaw/openclaw.json that defines Gateway behavior.
• Port Resolution Precedence: The order in which the Gateway determines its listening port: --port flag, then environment variable, then config file, then default 18789.
• Binding Modes: Controls which network interfaces the Gateway listens on: loopback (default), lan, tailnet, or custom.
• Loopback Binding: Restricts the Gateway to localhost only, meaning no external machines can connect.

Real World Context

Port resolution precedence follows the same convention used by tools like Docker, PostgreSQL, and Redis: CLI flags override environment variables, which override config files, which override hardcoded defaults. This layered approach lets you define a base configuration in the config file, override it per-environment using env vars, and override it per-invocation using CLI flags. Binding modes mirror the concept of listen addresses in web servers like Nginx (listen 127.0.0.1:80 vs listen 0.0.0.0:80), where the choice of interface determines who can reach the service.

Deep Dive

The Gateway reads its configuration from ~/.openclaw/openclaw.json. Here is a minimal configuration file:

json
{
  "gateway": {
    "port": 18789,
    "binding": "loopback"
  }
}

This file tells the Gateway to listen on port 18789 and bind to the loopback interface only. The gateway key is the top-level namespace for all Gateway-related settings.

Let us walk through the port resolution precedence with a concrete example. Suppose your config file sets port 18789, but you have an environment variable setting a different port, and you also pass a CLI flag:

bash
# Config file says 18789
# Environment variable overrides to 9000
export OPENCLAW_PORT=9000

# CLI flag overrides everything to 7777
openclaw gateway --port 7777

In this scenario, the Gateway listens on port 7777 because the CLI flag has the highest precedence. If you remove the --port flag, it falls back to the environment variable (9000). If you also unset the env var, it falls back to the config file (18789). If the config file does not specify a port, the hardcoded default of 18789 is used.

The resolution order is:

1. --port CLI flag (highest priority)
2. Environment variable (OPENCLAW_PORT)
3. Config file (~/.openclaw/openclaw.json)
4. Default value: 18789 (lowest priority)

Binding modes control which network interfaces the Gateway listens on. There are four options:

json
{
  "gateway": {
    "binding": "loopback"
  }
}

The above binds to 127.0.0.1 only. No machine on your local network can reach the Gateway. This is the default and the safest option for local development.

json
{
  "gateway": {
    "binding": "lan"
  }
}

This binds to all local network interfaces (0.0.0.0), making the Gateway accessible to other devices on the same network. This requires authentication to be configured – the Gateway will reject startup if you use a non-loopback binding without authentication enabled.

json
{
  "gateway": {
    "binding": "tailnet"
  }
}

This binds specifically to a Tailscale network interface, making the Gateway accessible only to machines in your Tailscale network. Authentication is still required.

Finally, custom allows you to specify an exact interface or IP address for advanced use cases.

A critical safety rule: non-loopback binding without authentication is rejected. The Gateway enforces this at startup to prevent accidental exposure of your AI infrastructure to the network without access controls.

Common Pitfalls

• Editing the wrong config file: The Gateway only reads from ~/.openclaw/openclaw.json. Placing a config file in your project directory or another location will have no effect unless explicitly specified.
• Forgetting precedence when debugging port issues: If the Gateway is listening on an unexpected port, check CLI flags first, then env vars, then the config file. Developers often forget about an exported env var that silently overrides their config.
• Using lan binding without authentication: The Gateway will refuse to start. This is intentional, but the error message can be confusing if you do not know about the fail-closed security model.

Best Practices

• Start with loopback binding during development and only switch to lan or tailnet when you have authentication configured.
• Use environment variables for port overrides in CI/CD or container environments rather than modifying the config file.
• Keep your openclaw.json under version control (minus any secrets) so your team shares a consistent baseline configuration.

Concept deep dive: For a full overview of the Gateway architecture, message pipeline, and deployment patterns, see the OpenClaw Gateway Architecture concept page.

Summary

• The Gateway config file lives at ~/.openclaw/openclaw.json under the gateway key.
• Port resolution follows a strict precedence: --port flag > environment variable > config file > default 18789.
• Binding modes control network exposure: loopback (default, localhost only), lan (all interfaces), tailnet (Tailscale only), and custom.
• Non-loopback binding without authentication is rejected at startup as a security measure.
• Environment variables are the preferred override mechanism for deployment-specific settings.