Core Concepts & Terminology

+15 Mana ✨
OpenClaw Core Concepts(DOCUMENTATION)OpenClaw Agents Guide(DOCUMENTATION)

Introduction

OpenClaw is built around a small set of well-defined concepts that work together to form a complete messaging pipeline. Understanding these concepts and their relationships is critical before you start building with OpenClaw. This lesson defines each core term and shows how they connect.

Key Concepts

  • Gateway: The single central process that orchestrates all message routing, channel management, and agent dispatching
  • Channel: A bidirectional connection to a specific chat platform (WhatsApp, Telegram, Discord, Slack, iMessage, Signal, IRC, Google Chat, WebChat, and plugin channels like Teams, Matrix, LINE)
  • Agent: An AI persona configured with a model, system prompt, tools, and memory that processes incoming messages
  • Session: A conversation context that tracks state, history, and metadata across multiple messages between a user and an agent
  • Node: A device peripheral or hardware integration point that extends the Gateway's capabilities into the physical world
  • Workspace: A logical grouping that isolates channels, agents, and sessions for multi-tenant or multi-project deployments

Real World Context

A freelance developer uses OpenClaw to run a personal AI assistant. They connect their WhatsApp (Channel) and Telegram (Channel) to a single Gateway. They configure one Agent for coding help and another for general questions. When they message on WhatsApp, the Gateway creates a Session that remembers their conversation. If they later ask the same question on Telegram, a separate Session is created for that channel, keeping conversations isolated by default.

Deep Dive

Let us walk through each concept in detail and see how they are represented in configuration.

Gateway

The Gateway is the heart of OpenClaw. It is a single Node.js process that you start on your infrastructure. Everything else -- channels, agents, sessions -- lives inside the Gateway.

json
{
  "gateway": {
    "port": 18789
  }
}

This configuration block sets the Gateway to listen on port 18789. The Gateway does not store data externally by default; everything runs in-process.

Channels

Channels are the bridges between chat platforms and your Gateway. Each channel has an adapter that translates platform-specific message formats into a normalized structure.

json
{
  "channels": {
    "whatsapp": {
      "enabled": true,
      "phoneNumberId": "${WHATSAPP_PHONE_ID}",
      "accessToken": "${WHATSAPP_ACCESS_TOKEN}"
    },
    "telegram": {
      "enabled": true,
      "token": "${TELEGRAM_BOT_TOKEN}"
    },
    "discord": {
      "enabled": true,
      "token": "${DISCORD_BOT_TOKEN}"
    },
    "slack": {
      "enabled": false
    }
  }
}

This configuration enables three channels (WhatsApp, Telegram, Discord) and explicitly disables Slack. Each channel requires its own platform-specific credentials, stored as environment variables. When a channel is enabled, the Gateway registers webhooks or opens socket connections to start receiving messages.

Agents

Agents are the AI personas that respond to messages. Each agent has a model, a system prompt, optional tools, and memory configuration.

json
{
  "agents": {
    "list": [
      {
        "id": "coder",
        "model": "anthropic:claude-sonnet-4-20250514",
        "workspace": "~/.openclaw/agents/coder/workspace",
        "agentDir": "~/.openclaw/agents/coder/agent"
      },
      {
        "id": "support",
        "model": "openai:gpt-4o",
        "workspace": "~/.openclaw/agents/support/workspace",
        "agentDir": "~/.openclaw/agents/support/agent"
      }
    ]
  }
}

This defines two agents: a coder agent using Claude Sonnet and a support agent using GPT-4o. Each agent has its own isolated workspace and agent directory for sessions, auth profiles, and persona configuration.

Sessions

A Session is created automatically when a user starts a conversation. It tracks the message history, the active agent, and any metadata needed for context.

Sessions are scoped to a user-channel-agent combination. If the same user talks to the same agent on two different channels, they get two separate sessions.

Nodes

Nodes represent device peripherals or hardware integrations. For example, a Node could be a camera, microphone, or IoT sensor connected to the Gateway. Nodes extend OpenClaw beyond text-based chat into the physical world.

Workspaces

Workspaces provide logical isolation. In a multi-tenant setup, each tenant gets their own workspace with separate channels, agents, and sessions. This prevents data leakage between tenants.

json
{
  "workspaces": {
    "team-alpha": {
      "channels": ["discord"],
      "agents": ["coder"]
    },
    "team-beta": {
      "channels": ["slack"],
      "agents": ["support"]
    }
  }
}

This configuration creates two workspaces. Team Alpha uses Discord with the coder agent, while Team Beta uses Slack with the support agent. Each workspace operates independently within the same Gateway process.

Common Pitfalls

  • Confusing Channels with Agents: A Channel is a connection to a platform. An Agent is the AI that responds. They are separate concerns that the Gateway connects.
  • Assuming sessions are shared across channels: By default, sessions are scoped per user-channel-agent. A WhatsApp session and a Telegram session for the same user are independent.
  • Ignoring Workspaces in multi-team setups: Without workspaces, all channels and agents are shared globally. This can lead to unintended message routing in multi-team environments.

Best Practices

  • Name agents by their role: Use descriptive names like coder, support, or onboarding instead of generic names like agent1.
  • Start with a single workspace: Only introduce workspaces when you need tenant or project isolation. Premature partitioning adds unnecessary complexity.
  • Document your concept mappings: Keep a simple diagram showing which channels route to which agents in which workspaces.

Summary

  • The Gateway is the single central process that orchestrates everything in OpenClaw
  • Channels connect the Gateway to chat platforms like WhatsApp, Telegram, and Discord
  • Agents are AI personas with models, prompts, tools, and memory that process messages
  • Sessions maintain conversation state scoped to a user-channel-agent combination
  • Nodes extend the Gateway into physical devices and peripherals
  • Workspaces provide logical isolation for multi-tenant or multi-project deployments
✓ Completed