Environment:Openclaw Openclaw Gateway Network Ports
| Knowledge Sources | |
|---|---|
| Domains | Infrastructure, Networking |
| Last Updated | 2026-02-06 12:00 GMT |
Overview
Network port allocation scheme for the OpenClaw Gateway, spanning ports 18789-18899 for gateway, bridge, browser control, canvas host, and CDP automation.
Description
The OpenClaw Gateway uses a derived port allocation scheme anchored on a configurable base gateway port (default: 18789). Additional service ports are computed as offsets from the base port: bridge (+1), browser control (+2), canvas host (+4), and browser CDP range (+11 to +110). All ports can be overridden individually via environment variables or configuration. The gateway defaults to loopback binding (127.0.0.1) for security; LAN binding must be explicitly enabled.
Usage
This environment must be satisfied for Gateway server startup, node pairing, browser automation, and canvas rendering. Firewall rules and container port mappings must expose the required ports.
System Requirements
| Category | Requirement | Notes |
|---|---|---|
| Gateway Port | 18789 (default) | HTTP/WebSocket; override via `OPENCLAW_GATEWAY_PORT` |
| Bridge Port | 18790 (gateway + 1) | Agent communication; override via config |
| Browser Control | 18791 (gateway + 2) | Browser automation control; override via config |
| Canvas Host | 18793 (gateway + 4) | Canvas rendering server; override via `OPENCLAW_CANVAS_HOST_PORT` |
| CDP Port Range | 18800-18899 | Playwright browser CDP connections (100 ports) |
| Bind Mode | loopback (default) | Set `--bind lan` or `OPENCLAW_GATEWAY_BIND=lan` for external access |
Dependencies
No system package dependencies. Port availability on the host is the only requirement.
Credentials
When binding to LAN (non-loopback), one of:
- `OPENCLAW_GATEWAY_TOKEN`: Bearer token for gateway access
- `OPENCLAW_GATEWAY_PASSWORD`: Password-based authentication
Quick Install
# Start gateway on default port (18789, loopback)
openclaw gateway run
# Start gateway on custom port, LAN-bound
openclaw gateway run --port 8080 --bind lan
# Verify port is listening
ss -ltnp | grep 18789
Code Evidence
Default port constants from `src/config/port-defaults.ts:15-19`:
export const DEFAULT_BRIDGE_PORT = 18790;
export const DEFAULT_BROWSER_CONTROL_PORT = 18791;
export const DEFAULT_CANVAS_HOST_PORT = 18793;
export const DEFAULT_BROWSER_CDP_PORT_RANGE_START = 18800;
export const DEFAULT_BROWSER_CDP_PORT_RANGE_END = 18899;
Gateway port from `src/config/paths.ts:196`:
export const DEFAULT_GATEWAY_PORT = 18789;
Port derivation logic from `src/config/port-defaults.ts:21-31`:
export function deriveDefaultBridgePort(gatewayPort: number): number {
return derivePort(gatewayPort, 1, DEFAULT_BRIDGE_PORT);
}
export function deriveDefaultBrowserControlPort(gatewayPort: number): number {
return derivePort(gatewayPort, 2, DEFAULT_BROWSER_CONTROL_PORT);
}
export function deriveDefaultCanvasHostPort(gatewayPort: number): number {
return derivePort(gatewayPort, 4, DEFAULT_CANVAS_HOST_PORT);
}
Port resolution cascade from `src/config/paths.ts:236-254`:
export function resolveGatewayPort(
cfg?: OpenClawConfig,
env: NodeJS.ProcessEnv = process.env,
): number {
const envRaw = env.OPENCLAW_GATEWAY_PORT?.trim() || env.CLAWDBOT_GATEWAY_PORT?.trim();
if (envRaw) {
const parsed = Number.parseInt(envRaw, 10);
if (Number.isFinite(parsed) && parsed > 0) {
return parsed;
}
}
const configPort = cfg?.gateway?.port;
if (typeof configPort === "number" && Number.isFinite(configPort)) {
if (configPort > 0) {
return configPort;
}
}
return DEFAULT_GATEWAY_PORT;
}
Common Errors
| Error Message | Cause | Solution |
|---|---|---|
| `EADDRINUSE: address already in use` | Port 18789 already occupied | Kill existing gateway or change port via `--port` |
| Gateway not reachable from other devices | Default loopback binding | Use `--bind lan` and set gateway token/password |
| Browser automation fails | CDP ports blocked | Ensure ports 18800-18899 are available |
Compatibility Notes
- Fly.io: Internal port is remapped to 3000; Fly proxy handles HTTPS termination.
- Docker: Port mapping required in docker-compose.yml or `docker run -p`.
- Render: Default port overridden to 8080 via `PORT` env var.
- Multiple gateways: Use different base ports to run multiple isolated instances on the same host.