Core Components
Gateway
The Gateway is OpenClaw's central service component that handles all communication and routing between your AI agents and messaging platforms.
In Simple Terms
Gateway = Background Service. It works like a "translator" between your chat apps and AI. As long as the Gateway is running, you can talk to AI.
Default Port
The Gateway runs on port 18789 by default. You can start it with openclaw gateway or openclaw gateway --port 18789.
Key commands:
openclaw gateway- Start the gateway in foreground modeopenclaw gateway --daemon- Run as a background service
Control UI
The Control UI is OpenClaw's built-in web-based management interface. It provides the fastest way to start chatting without configuring any external channels.
Access URL: http://127.0.0.1:18789/
Quick Start
The Control UI is the easiest way to test your OpenClaw installation. No external accounts required.
Channels
Channels are integrations that connect OpenClaw to external messaging platforms. Each channel requires its own authentication setup.
In Simple Terms
Channel = Messaging Platform. These are the apps you use to chat, like WhatsApp, Telegram, or Discord. OpenClaw connects to these apps through Channels.
- WhatsApp - QR code scan
- Telegram - Bot Token
- Discord - Bot Token
- Mattermost - Plugin integration
Related command: openclaw channels login
Pairing
Pairing is OpenClaw's security mechanism for verifying new direct message (DM) connections.
In Simple Terms
Pairing = Device Authorization. When someone messages your bot for the first time, you need to approve them before they can use it. This prevents strangers from using your AI.
How Pairing Works
When an unknown user sends a DM to your OpenClaw bot, they receive a pairing code instead of a normal response.
Approve the Connection
You must approve the pairing request using the CLI:
openclaw pairing approve whatsapp ABC123
Replace whatsapp with your channel type and ABC123 with the actual pairing code shown to the user.
Connection Established
Once approved, the user can communicate normally with your OpenClaw agents.
Security Note
Never approve pairing requests from unknown sources. This mechanism protects your agents from unauthorized access.
Runtime Concepts
Sandbox
The Sandbox is an isolation mode for running agents securely. It restricts what actions an agent can perform on your system.
In Simple Terms
Sandbox = Secure Isolation Mode. It runs AI in a protected environment, limiting what it can do to prevent accidental changes to your computer.
Sandbox modes:
"non-main"(default) - Group and channel sessions use sandbox isolation"off"- Disable sandbox for a specific agent (use with caution)
Workspace
The Workspace is the default working directory for OpenClaw agents.
Default location: ~/.openclaw/workspace
All file operations performed by agents are scoped to this directory unless explicitly configured otherwise.
Auth Profiles
Auth Profiles store OAuth tokens and API keys for external services that your agents need to access.
Location: ~/.openclaw/agents/<agentId>/agent/auth-profiles.json
Keep Secure
Never share or commit auth-profiles.json files. They contain sensitive credentials.
Essential Commands
openclaw onboard- Run the setup wizardopenclaw dashboard- Open the web dashboardopenclaw status- Check system statusopenclaw health- Verify gateway healthopenclaw security audit --deep- Run a deep security auditopenclaw channels login- Connect to messaging platforms
System Requirements
Node.js
OpenClaw requires Node.js version 22 or higher.
node --version
Should output: v22.x.x or higher
Runtime Compatibility
Bun runtime has known compatibility issues with WhatsApp and Telegram integrations. Use Node.js for best results.
WSL2 (Windows Users)
Windows users should run OpenClaw inside WSL2 (Windows Subsystem for Linux) for full compatibility.
Next Steps
Now that you understand the terminology:
- Start Here - Begin your OpenClaw journey
- Install OpenClaw - Platform-specific installation guides
- Connect Channels - Set up messaging integrations
Official Documentation
For the most up-to-date and detailed information, visit the official OpenClaw documentation.