Implementation:Openclaw Openclaw StartGatewayServer

Knowledge Sources	OpenClaw
Domains	Deployment, Docker
Last Updated	2026-02-06 12:00 GMT

Overview

Concrete tool for starting the OpenClaw WebSocket gateway server provided by the startGatewayServer function in the gateway server implementation module.

Description

The startGatewayServer function is the main entry point for the OpenClaw gateway process. It orchestrates the entire server lifecycle: loading and validating configuration, resolving runtime parameters (bind host, port, TLS, authentication), initializing channel managers for all messaging platforms, setting up WebSocket handlers, starting health monitoring, configuring Tailscale exposure, loading plugins, and establishing a config file watcher for hot-reload.

The function sets process.env.OPENCLAW_GATEWAY_PORT to ensure all subsystems (browser control, canvas host) use the correct port. It handles legacy config migration, auto-enables plugins, and creates the full runtime state including HTTP servers, WebSocket server, node registry, subscription management, cron service, and exec-approval system.

The returned GatewayServer object exposes a close method that performs orderly shutdown, stopping diagnostics, clearing timers, unsubscribing event listeners, and closing all network connections.

Usage

This function is called by the openclaw gateway CLI command. In Docker, the Dockerfile CMD or Compose command invokes node dist/index.js gateway, which ultimately calls startGatewayServer. The function is also used in integration tests with test-specific option overrides.

Code Reference

Source Location

Repository: openclaw
File: src/gateway/server.impl.ts (lines 155-638)

Signature

export async function startGatewayServer(
  port: number = 18789,
  opts: GatewayServerOptions = {},
): Promise<GatewayServer>

Types

export type GatewayServer = {
  close: (opts?: {
    reason?: string;
    restartExpectedMs?: number | null;
  }) => Promise<void>;
};

export type GatewayServerOptions = {
  bind?: "loopback" | "lan" | "tailnet" | "auto";
  host?: string;
  controlUiEnabled?: boolean;
  openAiChatCompletionsEnabled?: boolean;
  openResponsesEnabled?: boolean;
  auth?: GatewayAuthConfig;
  tailscale?: GatewayTailscaleConfig;
  allowCanvasHostInTests?: boolean;
  wizardRunner?: (
    opts: OnboardOptions,
    runtime: RuntimeEnv,
    prompter: WizardPrompter,
  ) => Promise<void>;
};

Import

import { startGatewayServer } from "../gateway/server.impl.js";
import type { GatewayServer, GatewayServerOptions } from "../gateway/server.impl.js";

I/O Contract

Inputs

Name	Type	Required	Description
port	`number`	No	TCP port for the gateway HTTP/WebSocket server. Defaults to `18789`.
opts.bind	"lan" \| "tailnet" \| "auto"	No	Network bind mode. `"loopback"` binds to 127.0.0.1, `"lan"` binds to 0.0.0.0, `"tailnet"` binds to the Tailscale IP. Config file value is used if not provided.
opts.host	`string`	No	Advanced override for the bind host address, bypassing bind resolution.
opts.controlUiEnabled	`boolean`	No	Whether to serve the browser-based Control UI. Defaults to config value or `true`.
opts.openAiChatCompletionsEnabled	`boolean`	No	Whether to serve the `POST /v1/chat/completions` endpoint.
opts.openResponsesEnabled	`boolean`	No	Whether to serve the `POST /v1/responses` (OpenResponses) endpoint.
opts.auth	`GatewayAuthConfig`	No	Override gateway authentication configuration. Merges with config file values.
opts.tailscale	`GatewayTailscaleConfig`	No	Override Tailscale exposure configuration.

Outputs

Name	Type	Description
(return value)	`Promise<GatewayServer>`	The running gateway server handle with a `close()` method for graceful shutdown.

Usage Examples

Basic Usage

import { startGatewayServer } from "../gateway/server.impl.js";

// Start with default settings (loopback, port 18789)
const server = await startGatewayServer();

// Start for Docker deployment (LAN bind, custom port)
const dockerServer = await startGatewayServer(3000, {
  bind: "lan",
});

// Graceful shutdown
await server.close({ reason: "maintenance" });

Docker CMD / Compose Command

# Dockerfile default CMD (loopback bind)
CMD ["node", "dist/index.js", "gateway", "--allow-unconfigured"]

# Docker Compose override (LAN bind on port 18789)
command: ["node", "dist/index.js", "gateway", "--bind", "lan", "--port", "18789"]

# Fly.io process (LAN bind on port 3000)
app = "node dist/index.js gateway --allow-unconfigured --port 3000 --bind lan"

Related Pages

Implements Principle

Principle:Openclaw_Openclaw_Gateway_Server_Startup

Requires Environment

Uses Heuristic

Heuristic:Openclaw_Openclaw_Warning_Suppression_For_Known_Deprecations

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment