Key Concepts

Quick reference. Terms are listed in the order you'll encounter them. For a full explanation of what OpenClaw is and how it compares to alternatives, see What is OpenClaw?.

┌─────────────────────────────────────────────────────┐
│                    Gateway                          │
│              (port 18789, always on)                │
│                                                     │
│  ┌──────────────┐      ┌──────────────────────────┐ │
│  │   Channels   │      │         Agent            │ │
│  │              │◄────►│  SOUL.md + USER.md +     │ │
│  │  Telegram    │      │  MEMORY.md + AI model    │ │
│  │  Slack       │      │                          │ │
│  │  WhatsApp    │      │  ┌────────┐ ┌─────────┐  │ │
│  │  iMessage    │      │  │ Skills │ │  Tools  │  │ │
│  │  WebChat...  │      │  └────────┘ └─────────┘  │ │
│  └──────────────┘      └──────────────────────────┘ │
│                                                     │
│  ┌──────────────────────────────────────────────┐   │
│  │  Cron Jobs  (run on schedule, no user input) │   │
│  └──────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────┘

Core components

Gateway — The central process that runs on your machine. An HTTP + WebSocket server listening on port 18789. Manages all channels, runs automations, routes messages to your AI provider, hosts canvas interfaces, serves OpenAI-compatible API endpoints (/v1/models, /v1/chat/completions, /v1/responses, /v1/embeddings), and handles device pairing. Explicit model overrides are forwarded through /v1/chat/completions and /v1/responses for broader client and RAG compatibility. Everything flows through the Gateway.

In practice: When you send a message on Telegram, it arrives at the Gateway first. The Gateway routes it to your AI model and sends the response back.

Agent — Your configured AI assistant. The combination of Gateway + your SOUL.md + your AI provider model. The "agent" is not a separate process — it's the Gateway acting under your configuration.

In practice: The same Claude model gives wildly different results depending on your SOUL.md. The "agent" is the model shaped by your config.

Channel — A messaging platform your agent can send and receive messages through. Telegram, WhatsApp, Slack, Discord, iMessage, email, and WebChat are all channels.

In practice: You might read replies in Telegram but send daily alerts to Slack — same agent, two channels.

Skill — A purpose-built integration for a specific service (Gmail, Calendar, GitHub, etc.). Gives your agent structured access to that service's API. Installed from ClawHub or configured manually. Bundled skills (coding-agent, gh-issues, openai-whisper-api, session-logs, tmux, trello, weather) include one-click install recipes so the CLI and Control UI can offer dependency installation when requirements are missing.

In practice: Add the Gmail skill and your agent can read, send, and search your email on demand.

Tool — A general-purpose built-in capability. web_fetch, web_search, read, write, edit, apply_patch, and exec are core tools. Additional tools include browser, message, canvas, nodes, cron, gateway, image, image_generate, sessions_*, and agents_list. Tools are organized into profiles (full, coding, messaging, minimal) and can be grouped for easier management. Enabled in config, not installed separately. The /tools endpoint and openclaw tools list show only the tools the current agent can actually use right now.

In practice: web_search lets your agent look up current information; exec lets it run shell commands on your machine.

Config files

openclaw.json — Main configuration file at ~/.openclaw/openclaw.json. Contains provider config, channel config, tools, skills, and automations.

SOUL.md — Plain text file at ~/.openclaw/SOUL.md. Defines your agent's personality, communication style, and behavioral rules. Read every session.

In practice: "Always respond in under 3 sentences unless I ask for more" goes here.

USER.md — Plain text file at ~/.openclaw/USER.md. Describes you — your role, projects, preferences. Read every session.

MEMORY.md — Growing file at ~/.openclaw/workspace/MEMORY.md. Accumulates notes from past sessions. Your agent reads it at startup and can write to it during sessions.

In practice: After you tell your agent you're working on a new project, it writes a note to MEMORY.md so it remembers next session.

HEARTBEAT.md — Standing instructions at ~/.openclaw/workspace/HEARTBEAT.md. Things your agent should always track or be aware of. Unlike MEMORY.md, it's curated and doesn't grow automatically.

MESSAGING.md — Routing rules at ~/.openclaw/MESSAGING.md. Defines which content goes to which channel and cross-channel identity mapping.

Messaging concepts

DM policy — Controls who can send direct messages to your agent on a channel. Options: pairing (approve on first contact), allowlist (explicit user IDs only), open (anyone), disabled.

In practice: Use pairing when sharing your agent with someone new; use allowlist once you know the user IDs.

Pairing — The process of approving a new user on a pairing DM policy channel. The user sends /start, you run openclaw channels pair and approve.

Allowlist — An explicit list of user IDs permitted to message the agent. More secure than pairing for long-term setups.

Session — A single conversation thread. The agent maintains context within a session. MEMORY.md persists context across sessions.

Owner-enforced commands — When enforceOwnerForCommands is true in your config, commands designated as owner-only require the sender to be a verified owner: either a match against commands.ownerAllowFrom (your explicit owner identity list) or the internal operator.admin role. A permissive allowFrom wildcard or an empty commands.ownerAllowFrom list is not sufficient — those do not grant owner identity. This prevents non-owner users from reaching privileged commands through overly broad channel allowlists.

In practice: If you set enforceOwnerForCommands: true, make sure commands.ownerAllowFrom explicitly lists your identity on each channel (e.g., "telegram:123456789"). See the troubleshooting guide if commands stop responding after upgrading to v2026.4.21.

Automation concepts

Automation — A scheduled task. Defined with a cron schedule, a prompt, and a target channel. Runs automatically without user input.

In practice: "Every morning at 7am, send me a weather + email summary" is a single automation — no user trigger needed.

Cron schedule — A 5-field expression defining when an automation runs: minute hour day month weekday. Example: 0 7 * * 1-5 = 7am on weekdays. Test expressions at crontab.guru.

Hook — A command that runs in response to an event. session_end hook runs after each conversation. Used for automatic memory writes and post-session summaries. The before_dispatch hook fires before message dispatch with canonical inbound metadata, and routes handled replies through the normal final-delivery path (preserving TTS and routed delivery semantics).

In practice: A session_end hook that writes key decisions to MEMORY.md runs automatically every time you finish a conversation. A before_dispatch hook can inspect or transform inbound messages before the agent processes them.

Sub-agent — A separate agent instance your main agent can delegate tasks to. Useful for parallel research, specialized roles, or isolating tool permissions.

Technical terms

WebChat — The built-in browser interface at http://localhost:18789. Always available when the Gateway is running. No setup required. Open it with openclaw dashboard.

Socket Mode — Slack's connection method that uses a persistent WebSocket instead of requiring a public webhook URL. OpenClaw uses this for Slack integration.

Talk Mode — Voice interface for OpenClaw. Uses Deepgram (or Whisper as a fallback) for speech-to-text (STT) and ElevenLabs or system TTS for text-to-speech. Implemented as a plugin-based voice feature, activated with a wake key or wake word.

Daemon — A background process that starts automatically on boot. OpenClaw can install itself as a daemon so the Gateway is always running without manual start.

ClawHub — The community skill directory at clawhub.ai. Browse and install skills for specific services.

Workspace — The directory at ~/.openclaw/workspace/. The agent's read/write sandbox. MEMORY.md, task files, and any files the agent creates live here.

Model Auth Status — A monitoring card in the Control UI Overview (added in v2026.4.15) that shows OAuth token health and provider rate-limit pressure at a glance. The card surfaces attention callouts when OAuth tokens for configured providers are expiring soon or have already expired, so you can re-authenticate before requests start failing. Powered by the models.authStatus gateway method, which strips all credential material before returning status data and caches results for 60 seconds to avoid hammering provider endpoints.