Archaeologist·Field Notes from openclaw/openclaw
Vol. I · Field Notes

openclawopenclaw

Multi-channel AI gateway with extensible messaging integrations

8 May 2026·a vast project
Reading Posture
From the Field
Over-engineered AI gateway that confuses complexity with capability.
Verdict:Pass
Reach for it when

You need a multi-channel AI assistant with deep plugin support and are willing to manage a 340k LOC beast.

Look elsewhere when

You want a simple, maintainable AI assistant or don't need the kitchen sink of integrations.

In context

It's like Home Assistant for AI but with 10x the code and half the polish.

Complexity●●●Heavy
Read time~30 minutes
Language
TypeScript
Runtime
Node.js >=22.16.0
Dependencies
84total
Frameworks
ExpressOpenAI SDKAnthropic SDK
Notable Dependencies
@agentclientprotocol/sdk@anthropic-ai/sdk@anthropic-ai/vertex-sdk@aws-sdk/client-bedrock@aws-sdk/client-bedrock-runtime@aws-sdk/credential-provider-node@aws/bedrock-token-generator@clack/core

What using it looks like

Drawn from the project's README

From the README
npm install -g openclaw@latest
# or: pnpm add -g openclaw@latest

openclaw onboard --install-daemon
Fig. 1 — example 1 of 5

What this is

As told for the tourist

What Is This?

OpenClaw is a personal AI assistant that lives on your own computer or server, not in someone else's cloud. It connects to all the messaging apps you already use—WhatsApp, Telegram, iMessage, Discord, and about 30 others—so you can talk to it wherever you already chat.

What Can You Do With It?

You could use this to have an AI assistant that answers you on any messaging app, without paying a monthly subscription or sending your data to a big company. For example:

- Send a WhatsApp message to your assistant asking "What's on my calendar today?" and get a reply right there.

- Ask it to summarize a long email thread through Telegram.

- Have it speak answers out loud on your iPhone or Android.

- Use the "live Canvas" feature to see it draw or write things in real time as it thinks.

The README shows you can install it with one command (npm install -g openclaw@latest) and start it up with openclaw gateway --port 18789. Then you can send messages like openclaw message send --target +1234567890 --message "Hello from OpenClaw" to test it out.

How It Works (No Jargon)

Think of OpenClaw as three simple parts working together:

1. The Gateway — like a mailroom for messages. When you send a message on WhatsApp, it arrives at the Gateway. The Gateway figures out who sent it, what channel it came from, and where to route it next. It's like a post office that sorts mail and sends it to the right department.

2. The Agent — like a personal assistant with a memory. Once your message is sorted, it goes to the "agent" (the AI brain). This agent remembers your past conversations, knows your preferences, and decides how to answer. It's like having a helper who keeps notes on everything you've discussed and can look things up instantly.

3. The Channels — like adapters for different phone lines. Each messaging app (WhatsApp, Telegram, etc.) has its own "channel" plugin. These plugins translate between OpenClaw's internal language and each app's specific format. It's like having a universal remote that works with every TV brand—each button press gets translated to whatever that TV understands.

What's Cool About It?

The coolest thing is that it's fully local and private. You run it on your own machine, so your conversations never leave your control. No company is reading your chats to train their AI.

Second, it's incredibly flexible about where you talk to it. Most AI assistants only work in their own app or website. OpenClaw lets you use whatever messaging app you already have open—you don't need to learn a new tool. It supports over 20 different messaging platforms, from mainstream ones like WhatsApp to niche ones like IRC and Nostr.

Who Should Care?

Reach for this if: You want a personal AI assistant that respects your privacy, you're comfortable running software on your own computer or server, and you want to talk to it from whatever messaging app you use daily. It's perfect for tinkerers, privacy-conscious folks, and anyone who wants AI help without the monthly fee.

Skip it if: You just want to use ChatGPT in a web browser and don't care about privacy or customization. Also skip it if you're not comfortable with command-line tools or running your own server—this isn't a click-and-install app for most people.

Start Here

A recommended reading path through the code

Start Here

A recommended reading path through the code

  1. 01

    This module is the gateway server's core, orchestrating inbound chat processing, session lifecycle management, agent exe.

  2. 02

    This module is the plugin lifecycle and integration backbone of the system.

  3. 03

    This module implements the Agent Client Protocol (ACP) control plane, managing session lifecycle through a core manager.

  4. 04
    src/entry.ts(Core & Misc)

    This module orchestrates the core operational logic of the OpenClaw system.

  5. 05

    This module, `plugin-sdk`, is the foundational toolkit for building OpenClaw plugins.

What's inside

15 sections of the codebase

Read Next

Where to go from here

📰
Article2024

What is an AI Gateway?

Simon Willison

A plain-English introduction to the concept of routing AI requests through a central gateway, which is the core idea behind OpenClaw.

📺
Video2024

Home Assistant for AI: Building a Personal Assistant

NetworkChuck

Shows how to build a multi-platform AI assistant at home, giving context for why OpenClaw exists and what it aims to replace.

📰
Article2023

ReAct: The AI Pattern That Lets LLMs Use Tools

LangChain Blog

Explains the ReAct loop (Reasoning + Acting) in simple terms, which is the agent architecture OpenClaw uses for tool execution.

📰
Article2024

Self-Hosted AI: Why You Might Want to Run Your Own Models

Ars Technica

Discusses the privacy and control benefits of self-hosting AI, which is the main motivation behind OpenClaw's design.

Sibling Projects

Codebases that occupy adjacent space

Related Expeditions
openclaw🌐litellm🔀n8n💬Open WebUI🧩Dify🤖Chatbot UI
 

Export & Share

Take the field notes with you

Words You'll Hear

Hover the dotted terms above for definitions in context

async writer queuing

pattern

A technique where write operations are collected and processed later in the background, so the program doesn't have to wait for each save to finish.

channel adapter

pattern

A component that translates messages from a specific platform (like Discord or Telegram) into a standard format the system can understand.

context window management

concept

The technique of controlling how much conversation history is fed to the AI model, often by summarizing or trimming old messages to stay within memory limits.

cooldown tracking

concept

A mechanism that temporarily marks a failed model as unavailable for a set period, preventing repeated attempts to use it immediately after an error.

dependency inversion layer

pattern

A technique where high-level modules don't directly depend on low-level modules; instead, both depend on abstractions, making the system more flexible.

exclusive locks

concept

A mechanism that prevents multiple parts of a program from accessing the same file at the same time, avoiding data corruption.

failover

pattern

A system's ability to automatically switch to a backup model or service when the primary one fails, ensuring the conversation continues without interruption.

hexagonal architecture

pattern

A design pattern that isolates the core logic from external systems using ports and adapters, making it easy to swap out databases or APIs without changing the core.

hook system

pattern

A mechanism that lets plugins run custom code at specific moments in the program's lifecycle, like before a message is processed or after a model responds.

LRU cache

tool

A storage system that keeps recently used data in memory and automatically discards the least recently used items when space runs out.

pipeline-based execution model

pattern

A design where data flows through a series of steps (functions) in a fixed order, each step transforming the data before passing it to the next.

plugin registry

tool

A central list that keeps track of all available plugins and their capabilities, acting as the single source of truth for what the system can do.

plugin-core architecture

pattern

A design where the main system is built around a central core, and additional features are added through plugins that extend but cannot replace core parts.

ReAct agent loop

pattern

A pattern where an AI model repeatedly decides which tool to use, executes it, and uses the result to decide the next step until a final answer is reached.

sandboxed subprocess

concept

A separate, isolated process that runs code with restricted permissions so it cannot harm the main system or access sensitive data.

schema validation

concept

The process of checking that data matches a predefined structure or format, ensuring messages are correctly formed before processing.

session store

tool

A component that saves conversation data to disk using files instead of a database, with features like async writing and locks to prevent conflicts.

skill discovery

pattern

A system that automatically finds and loads available tools or skills from specific folders, making them available for the AI to use.

streaming transport layer

concept

A communication method that sends data in chunks as it becomes available, allowing the AI's response to appear gradually rather than all at once.

subagent registry

tool

A central list that manages the lifecycle of smaller, specialized AI agents that can be spawned and controlled by the main agent.

summarization

concept

The process of condensing a long conversation into a shorter version that keeps the important information, so the AI can continue without exceeding its memory limit.

token limits

concept

The maximum number of words or pieces of text an AI model can process in one go, beyond which the conversation must be shortened or summarized.

TTL-based refresh

pattern

A strategy where cached data is automatically updated after a set amount of time (Time To Live) to ensure it stays current.

webhook

concept

A way for one service to send real-time data to another service via a URL, often used to receive messages from chat platforms.