Lesson 1. How OpenClaw Works Inside#

Why you need this#

You already know how to use OpenClaw — send messages, connect channels, configure the assistant. But to solve non-standard problems and understand why something isn’t working, it’s helpful to know how the system works “under the hood.” It’s like understanding what a car is made of — not to become a mechanic, but to understand what’s happening.

Main components#

OpenClaw consists of several parts that work together:

1. Gateway#

Gateway is the “brain” of the system. It’s a program that constantly runs on your computer or server.

What Gateway does:

• Maintains connections with all messengers (Telegram, WhatsApp, Discord, etc.)
• Receives your messages and sends them to the AI model
• Manages sessions (conversation history)
• Assigns tasks to helper devices (nodes)

Gateway is the only process you need to start. Everything else connects to it.

Starting Gateway:
openclaw gateway

By default, it listens on port 18789 — this is like a door number that everyone uses to enter.

2. WebSocket — the communication method#

WebSocket (WS) is a technology for continuous two-way communication. Imagine a phone call: you don’t hang up after every sentence — you talk continuously.

All parts of OpenClaw communicate with Gateway through WebSocket:

• The Mac application
• The command line (CLI)
• The web interface (WebChat)
• Devices (nodes)

Communication happens in JSON format — a text format for transmitting data, similar to a “key-value” list.

3. Clients#

A client is any program that connects to Gateway:

• macOS application — graphical interface in the menu bar
• CLI (Command Line Interface) — text commands in the terminal
• WebChat — chat in the browser
• Control UI — control panel in the browser

Each client opens one WebSocket connection to Gateway.

4. Nodes#

Nodes are helper devices: phone, tablet, Raspberry Pi. They also connect to Gateway through WebSocket, but marked as “I’m a node.”

Nodes can:

• Take photos (camera)
• Record the screen
• Determine location
• Show notifications

5. Canvas#

Canvas is a web page that the assistant can create and edit during operation. It’s displayed at the Gateway address on the same port 18789.

How everything works together#

Here’s what happens when you send a message:

You (Telegram) → Gateway → AI model → Gateway → Response in Telegram

In detail:

1. You write a message in Telegram
2. Gateway receives it through the Telegram bot
3. Gateway sends the text to the AI model (e.g., Claude)
4. The model decides what to do — it may call tools (read a file, search the internet)
5. If a device is needed — Gateway contacts a node via WebSocket
6. The finished response is sent by Gateway back to Telegram

Connection lifecycle#

When a client connects to Gateway, a “handshake” occurs:

1. The client sends a connect request (the first message must always be this)
2. Gateway checks the authorization token (if configured)
3. Gateway responds “ok” and sends the current status
4. After that, the client can send requests, and Gateway can send events

If the first message isn’t connect, Gateway drops the connection.

Authorization and trust#

• Every client and node has a device identity
• New devices require pairing approval
• Connections from the same computer (localhost) can be auto-approved
• Remote connections require explicit confirmation

Health check#

To make sure Gateway is running:

openclaw health
openclaw status --deep

Lesson summary#

• Gateway is the central program that manages everything
• All parts of the system communicate through WebSocket (persistent connection)
• Clients (apps, CLI, web) connect to Gateway for control
• Nodes (devices) connect as helpers with camera, screen, etc.
• The first message on connection is always connect with authorization
• One Gateway = one host. It’s the single control point for all channels