← Blog

Guide

OpenClaw Architecture: How It Works Under the Hood

OpenClaw architecture explained: gateway, sessions, skills system, node connections, provider routing, and how a command flows from user to response.

Mar 30, 2026 ·7 min read

OpenClaw Architecture: How It Works Under the Hood

OpenClaw looks simple from the outside — you send a message, an agent responds, things happen. Under the hood, there's a layered architecture that handles provider routing, session management, skill dispatch, and multi-channel delivery. Understanding how it's built matters when you're debugging, extending, or deploying at scale.

This is a technical walkthrough of the core components and how they connect.

High-Level Overview

The OpenClaw runtime has five major layers:

Gateway — the always-on daemon that listens for input
Sessions — isolated agent contexts with their own history and state
Skills — the extensibility layer that gives agents new capabilities
Provider routing — how requests get sent to LLMs
Tool execution — how agents take actions in the real world

Every user interaction flows through all five layers. Let's trace that path.

The Gateway

The gateway is the entry point for everything. It's a persistent Node.js daemon that:

Listens on channel adapters (Telegram, Discord, CLI, HTTP)
Authenticates incoming messages
Routes them to the correct session
Returns responses back through the originating channel

Start it with:

openclaw gateway start

The gateway binds to a port (default 3000) for HTTP/API access and simultaneously maintains persistent connections to any configured messaging channels. It's not stateless — it holds active session references in memory and persists session metadata to disk.

Channel Adapters

Each integration is a channel adapter that normalizes incoming messages into a standard internal format. A Telegram message and a Discord message both become the same internal AgentMessage object by the time they reach the session layer. This is how OpenClaw can support multiple channels without duplicating core logic.

The adapters handle:

Authentication (bot tokens, user ID allowlists)
Message formatting (stripping platform-specific markup)
Attachment handling (files, images, voice notes)
Delivery of responses back to the correct platform/user

The gateway config lives in ~/.openclaw/config.yaml under the channels key.

Sessions

A session is an isolated agent context. Each user or thread gets its own session, which contains:

Message history — the conversation context sent to the LLM
Active tools — what capabilities the agent has in this session
Working directory — the filesystem scope the agent operates in
Session state — metadata about the session (created at, last active, model, etc.)

Sessions persist between gateway restarts. History is serialized to disk, so an agent in a long-running session picks up where it left off.

Session Isolation

Session isolation means one user's context doesn't bleed into another's. This matters if you're running OpenClaw for multiple people or multiple projects. A session running a coding task for Project A won't see the message history or workspace files from Project B.

You can inspect active sessions:

openclaw sessions list

And view session history for a specific session:

openclaw sessions history <session-id>

Subagents

Sessions can spawn subagents — child sessions that handle a delegated task and report results back to the parent. Subagents run in parallel and are isolated from each other. The parent session orchestrates; subagents execute.

This is how OpenClaw handles parallelism. A top-level agent can spawn three subagents to work on three different files simultaneously, then synthesize their outputs when all three complete.

The Skills System

Skills are OpenClaw's extensibility primitive. A skill is a directory containing a SKILL.md file that provides natural-language instructions telling the agent how and when to use a particular tool or capability.

When the agent receives a request, it scans available skill descriptions to determine if any skill clearly applies. If one matches, it reads the full SKILL.md before proceeding. The skill file can reference scripts, config files, and external documentation that the agent uses during execution.

Example skill directory structure:

skills/
  my-skill/
    SKILL.md          # Natural language instructions
    scripts/
      do-thing.sh     # Script the agent can invoke
    references/
      api-docs.md     # Reference material the agent reads

The skill system is what allows OpenClaw to be extended without modifying core code. Adding a new capability is creating a directory with a SKILL.md — no framework code, no class registration.

For a deeper look at building and installing skills, see How OpenClaw Skills Work.

ClawHub

Skills are distributable. ClawHub is the registry for community skills — install published skills directly:

openclaw skills install <skill-name>

Provider Routing

Provider routing is how OpenClaw decides which LLM gets the request and how it formats that request.

The routing layer:

Reads the session's configured model (e.g., anthropic/claude-sonnet-4-6)
Selects the appropriate provider adapter (Anthropic, OpenAI, Google)
Formats the message history into the provider's expected format
Handles streaming responses back to the session
Tracks token usage

Provider Adapters

Each LLM provider has a different API format, authentication method, and capability set. OpenClaw normalizes this behind a common interface. The session layer never talks directly to Anthropic or OpenAI — it talks to the provider adapter, which handles the translation.

This is why you can switch models in config without changing anything else:

providers:
  anthropic:
    apiKey: sk-ant-...
    defaultModel: anthropic/claude-sonnet-4-6

Change defaultModel to openai/gpt-4o and the same sessions, skills, and tools work with OpenAI's API instead.

Model Selection

Different sessions can use different models. A background cron task might use a cheaper/faster model like anthropic/claude-haiku-4-5, while your primary interactive session uses Sonnet. Set model at the session level or default it globally in config.

Tool Execution

When an LLM decides to use a tool, the tool execution layer handles it. Tools are the concrete actions an agent can take:

read — read file contents
write — write files
edit — make targeted file edits
exec — run shell commands
web_search — search the web
web_fetch — fetch URL content
browser — control a browser
message — send messages to channels

The agent generates a tool call (structured JSON with the tool name and parameters), the execution layer validates it, runs the action, and returns the result back to the LLM as a tool result. The LLM then decides what to do next — call another tool, return a response, or ask for clarification.

Tool Security

Tool execution happens in the context of the process running the OpenClaw gateway. The exec tool runs shell commands with the same permissions as the gateway process. This is powerful and means you should run the gateway with appropriate permissions — not as root in production.

The gateway supports an ask mode for sensitive tool calls that requires human approval before execution. Configure this in your session settings for use cases where you want a human in the loop on destructive operations.

How a Command Flows End-to-End

Here's the complete path for "what files are in my project directory?":

User sends message via Telegram
Telegram adapter receives it, authenticates the user ID against the allowlist, normalizes it to AgentMessage
Gateway routes it to the user's active session
Session adds the message to history, checks available skills, finds no matching skill
Provider router formats the history + system prompt + tool definitions, sends to Anthropic API
Anthropic returns a tool call: read { path: "/path/to/project" }
Tool execution layer runs the read tool, returns directory listing
Session sends the tool result back to Anthropic as a follow-up
Anthropic returns a text response describing the files
Session stores the exchange in history
Telegram adapter formats the response and delivers it to the user

Total latency: 1–3 seconds for a simple tool call, depending on LLM response time.

Node Connections

OpenClaw supports connecting remote nodes — additional machines that the agent can run tools on. This is how you run an OpenClaw agent on a central server but have it execute commands on a different machine (say, a Raspberry Pi or a remote VPS).

Node connections are configured in config.yaml under the nodes key. Once connected, the agent can target a specific node for exec calls, file operations, and browser control.

This architecture lets one OpenClaw instance orchestrate work across multiple machines — useful for homelab setups, multi-server deployments, or keeping the AI off the machine that actually runs your production workloads.

Deployment Options

The architecture supports several deployment patterns:

Local install — gateway runs on your laptop or desktop. Good for development, personal use.

Dedicated server — gateway runs on a VPS or home server. Always-on, accessible from anywhere via Telegram/Discord. This is the most common production setup.

Docker — containerized deployment with managed lifecycle. Covered in OpenClaw Docker Setup.

Managed hosting can reduce setup time, but you should still understand the underlying architecture and operational tradeoffs.

Build On Top of It

OpenClaw's architecture is designed to be extended — new channels, new skills, new provider adapters. The OpenClaw GitHub repo has documentation on contributing and the internal APIs.

If you are running OpenClaw in production, make sure your setup includes monitoring, backups, process management, and a clear rollback path.