<!-- source: https://deepwiki.com/openclaw/openclaw/2-gateway -->

# Gateway

- docs/automation/hooks.md
- docs/reference/AGENTS.default.md
- docs/reference/templates/AGENTS.md
- scripts/build-all.mjs
- scripts/lib/static-extension-assets.mjs
- scripts/runtime-postbuild.mjs
- skills/model-usage/SKILL.md
- src/agents/embedded-agent-runner/run/attempt-system-prompt.test.ts
- src/agents/embedded-agent-runner/run/attempt.cwd-split.test.ts
- src/cli/gateway-cli/lifecycle.runtime.ts
- src/cli/gateway-cli/run-loop.test.ts
- src/cli/gateway-cli/run-loop.ts
- src/gateway/gateway-cli-backend.connect.test.ts
- src/gateway/gateway-cli-backend.live-helpers.test.ts
- src/gateway/gateway-cli-backend.live-helpers.ts
- src/gateway/gateway-cli-backend.live-probe-helpers.test.ts
- src/gateway/gateway-cli-backend.live-probe-helpers.ts
- src/gateway/live-agent-probes.test.ts
- src/gateway/live-agent-probes.ts
- src/gateway/method-scopes.test.ts
- src/gateway/method-scopes.ts
- src/gateway/methods/core-descriptors.ts
- src/gateway/methods/descriptor.ts
- src/gateway/methods/registry.test.ts
- src/gateway/methods/registry.ts
- src/gateway/minimal-gateway.test-helpers.ts
- src/gateway/probe.close-drain.test.ts
- src/gateway/probe.test.ts
- src/gateway/probe.ts
- src/gateway/server-close.test.ts
- src/gateway/server-close.ts
- src/gateway/server-methods-list.test.ts
- src/gateway/server-methods-list.ts
- src/gateway/server-methods.ts
- src/gateway/server-methods/models-auth-status.test.ts
- src/gateway/server-methods/models-auth-status.ts
- src/gateway/server-methods/subagent-followup.test-helpers.ts
- src/gateway/server-reload-handlers.test.ts
- src/gateway/server-reload-handlers.ts
- src/gateway/server-startup-post-attach.test.ts
- src/gateway/server-startup-post-attach.ts
- src/gateway/server.impl.ts
- src/gateway/server.silent-scope-upgrade-reconnect.poc.test.ts
- src/infra/exec-wrapper-trust-plan.test.ts
- src/infra/infra-runtime.test.ts
- src/infra/restart.deferral-timeout.test.ts
- src/infra/restart.ts
- test/scripts/build-all.test.ts
- test/scripts/runtime-postbuild.test.ts

The Gateway is the central control plane for OpenClaw, responsible for managing WebSocket connections, dispatching RPC methods, coordinating messaging channels, orchestrating agent runs, and maintaining system state. It runs as a single multiplexed process serving protocol clients (CLI, native apps, Control UI) and channel providers simultaneously. [src/gateway/server.impl.ts165-166](https://github.com/openclaw/openclaw/blob/fbdf5937/src/gateway/server.impl.ts#L165-L166)

For details on specific Gateway subsystems, see:

- WebSocket Protocol & RPC - Document the Gateway protocol v3, including ConnectFrame , RequestFrame , ResponseFrame , and EventFrame . src/gateway/server-methods/types.ts 1-20
- Authentication & Authorization - Explain Gateway authentication modes (token/password/none), scope-based authorization, and device pairing. src/gateway/server.impl.ts 55-59
- Configuration System - Overview of openclaw.json , models.json , auth-profiles.json , and Zod schema validation. src/gateway/server.impl.ts 12-24
- Session & State Management - Document session scoping, JSONL transcript storage, and session lifecycle events. src/gateway/server.impl.ts 80-86
- Multi-Agent Routing - Explain agent bindings and how channels route to specific agents. src/gateway/server.impl.ts 62-65
- Service Lifecycle & Diagnostics - Cover health checks, the status command, and the doctor command for auto-repair. src/gateway/server.impl.ts 101-108
- Control UI & WebChat - Document the browser-based dashboard served by the Gateway for chat and management. src/gateway/server.impl.ts 84
- HTTP APIs - Document the Gateway's HTTP surfaces including OpenAI-compatible endpoints and MCP bridge. src/gateway/server.impl.ts 46-48
- Client SDK - Document the TypeScript SDK that wraps the WebSocket protocol for external integrations.

## Gateway Role in the System

The Gateway acts as the single source of truth for:

- Protocol connections : WebSocket clients connect to the Gateway for RPC and events. src/gateway/server.impl.ts 112
- Channel routing : Inbound messages from Telegram, Discord, etc., are normalized and routed to agents. src/gateway/server.impl.ts 4-9
- Agent orchestration : The Gateway invokes agent runs and streams results, managing the execution pipeline. src/gateway/server.impl.ts 3-4
- Configuration : Runtime config is loaded, validated, and hot-reloaded. src/gateway/server.impl.ts 12-19
- Model Auth Warming : Pre-warms model provider authentication states at startup to reduce latency during agent execution. src/gateway/server-startup-post-attach.ts 188-191

### Gateway Architecture Overview

```

```

Sources: [src/gateway/server.impl.ts58-112](https://github.com/openclaw/openclaw/blob/fbdf5937/src/gateway/server.impl.ts#L58-L112) [src/gateway/server-startup-post-attach.ts188-191](https://github.com/openclaw/openclaw/blob/fbdf5937/src/gateway/server-startup-post-attach.ts#L188-L191) [src/gateway/server.impl.ts85](https://github.com/openclaw/openclaw/blob/fbdf5937/src/gateway/server.impl.ts#L85-L85)

## Core Responsibilities

### 1. WebSocket Protocol Handling

The Gateway implements a JSON-based RPC protocol over WebSockets. Each client must perform a handshake and authorize scopes. [src/gateway/server.impl.ts110-112](https://github.com/openclaw/openclaw/blob/fbdf5937/src/gateway/server.impl.ts#L110-L112)

**Key protocol components:**

- Handshake : Managed via attachGatewayWsHandlers which handles the initial connection state and ConnectParams . src/gateway/server.impl.ts 112
- RPC Requests : Clients issue method calls which are organized in GATEWAY_EVENTS . src/gateway/server-methods-list.ts 88
- Events : Async notifications like GATEWAY_EVENT_UPDATE_AVAILABLE are pushed to connected clients. src/gateway/server-startup-post-attach.ts 20-22

Sources: [src/gateway/server.impl.ts112](https://github.com/openclaw/openclaw/blob/fbdf5937/src/gateway/server.impl.ts#L112-L112) [src/gateway/server-methods-list.ts88](https://github.com/openclaw/openclaw/blob/fbdf5937/src/gateway/server-methods-list.ts#L88-L88) [src/gateway/server-startup-post-attach.ts20-22](https://github.com/openclaw/openclaw/blob/fbdf5937/src/gateway/server-startup-post-attach.ts#L20-L22)

### 2. RPC Method Dispatch

The Gateway exposes method families organized by domain. Method handlers are registered in `createGatewayMethodRegistry` and supplemented by plugin-provided handlers. [src/gateway/methods/registry.ts65-69](https://github.com/openclaw/openclaw/blob/fbdf5937/src/gateway/methods/registry.ts#L65-L69)

**Method categories and Scopes:**

- operator.read : Status, health, logs, and list methods. src/gateway/methods/core-descriptors.ts 21-22
- operator.write : Actions that modify state or send messages. src/gateway/methods/core-descriptors.ts 25-29
- operator.admin : High-privilege actions like configuration changes, restricted via ADMIN_SCOPE . src/gateway/server.impl.ts 57

Sources: [src/gateway/methods/core-descriptors.ts20-50](https://github.com/openclaw/openclaw/blob/fbdf5937/src/gateway/methods/core-descriptors.ts#L20-L50) [src/gateway/methods/registry.ts63-69](https://github.com/openclaw/openclaw/blob/fbdf5937/src/gateway/methods/registry.ts#L63-L69)

### 3. Model Auth Pre-warming

To ensure low latency for agent responses, the Gateway pre-warms authentication states for configured model providers at startup and upon configuration reload. [src/gateway/server-startup-post-attach.ts188-191](https://github.com/openclaw/openclaw/blob/fbdf5937/src/gateway/server-startup-post-attach.ts#L188-L191)

- Warming Logic : warmCurrentProviderAuthStateOffMainThread probes external CLIs and plugins to cache available credentials. src/gateway/server-startup-post-attach.ts 190-191
- Hot Reload : The cache is cleared and re-warmed during hot-reload to ensure credentials remain fresh. src/gateway/server-reload-handlers.ts 93-97

Sources: [src/gateway/server-startup-post-attach.ts188-191](https://github.com/openclaw/openclaw/blob/fbdf5937/src/gateway/server-startup-post-attach.ts#L188-L191) [src/gateway/server-reload-handlers.ts93-97](https://github.com/openclaw/openclaw/blob/fbdf5937/src/gateway/server-reload-handlers.ts#L93-L97)

## Gateway Server Implementation

### Server Startup and Lifecycle

The Gateway startup is a multi-stage process involving early runtime initialization, plugin discovery, and post-ready maintenance tasks. [src/gateway/server-startup-post-attach.ts109-115](https://github.com/openclaw/openclaw/blob/fbdf5937/src/gateway/server-startup-post-attach.ts#L109-L115)

```

```

Sources: [src/gateway/server-startup-post-attach.ts109-115](https://github.com/openclaw/openclaw/blob/fbdf5937/src/gateway/server-startup-post-attach.ts#L109-L115) [src/gateway/server.impl.ts161-166](https://github.com/openclaw/openclaw/blob/fbdf5937/src/gateway/server.impl.ts#L161-L166) [src/cli/gateway-cli/run-loop.ts99-108](https://github.com/openclaw/openclaw/blob/fbdf5937/src/cli/gateway-cli/run-loop.ts#L99-L108)

### Restart and Recovery

The Gateway handles graceful shutdowns and state recovery during restarts, particularly for agent runs that were interrupted.

- Drain and Abort : During shutdown, the Gateway attempts to drain pending tasks and abort active embedded agent runs. src/cli/gateway-cli/run-loop.ts 19-21
- Session Recovery : The Gateway manages handoff state during restarts to preserve traces and session context. src/gateway/server.impl.ts 34-35
- Handoff Management : resumeGatewayRestartTraceFromHandoff ensures that diagnostics continue across process boundaries. src/gateway/server.impl.ts 81

```

```

Sources: [src/gateway/server.impl.ts34-83](https://github.com/openclaw/openclaw/blob/fbdf5937/src/gateway/server.impl.ts#L34-L83) [src/cli/gateway-cli/run-loop.ts18-23](https://github.com/openclaw/openclaw/blob/fbdf5937/src/cli/gateway-cli/run-loop.ts#L18-L23)

### Session and Store Management

The Gateway maintains session state with specific scoping and persistence rules. [src/gateway/server.impl.ts22](https://github.com/openclaw/openclaw/blob/fbdf5937/src/gateway/server.impl.ts#L22-L22)

- Store Management : Session data is persisted to the state directory, with the Gateway coordinating concurrent access. src/gateway/server-startup-post-attach.ts 36
- Persistence : Shared gateway session generations are enforced for configuration writes to maintain security. src/gateway/server.impl.ts 94-97
- State Organization : State is organized under a dedicated directory resolved at runtime. src/gateway/server-startup-post-attach.ts 7

Sources: [src/gateway/server.impl.ts22-97](https://github.com/openclaw/openclaw/blob/fbdf5937/src/gateway/server.impl.ts#L22-L97) [src/gateway/server-startup-post-attach.ts7-36](https://github.com/openclaw/openclaw/blob/fbdf5937/src/gateway/server-startup-post-attach.ts#L7-L36)

## Summary

The Gateway is the orchestration layer for OpenClaw. It:

- Implements the WebSocket protocol for all clients. src/gateway/server.impl.ts 112
- Dispatches RPC methods with scope-based authorization. src/gateway/methods/registry.ts 65-69
- Manages the lifecycle of agent runs and pre-warms model authentication. src/gateway/server-startup-post-attach.ts 188-191
- Coordinates session persistence and hot-reloading of configuration. src/gateway/server-reload-handlers.ts 93-97

For operational details, see [Service Lifecycle & Diagnostics](/openclaw/openclaw/2.6-service-lifecycle-and-diagnostics).
