Getting Started with OpenClaw: A Guide to the Open-Source Personal AI Assistant

2026-02-01 · Alpha · Post Comment

What is OpenClaw?

OpenClaw (formerly Clawdbot/Moltbot) is an open-source, cross-platform AI agent gateway. It acts as a bridge, connecting popular instant messaging platforms (like WhatsApp, Telegram, Discord) with backend large language models (such as OpenAI GPT, Anthropic Claude, etc.), allowing you to use a personal AI assistant within your everyday chat tools.

Core Architecture & Features

OpenClaw uses a centralized gateway architecture. Its main components include:

Gateway: The core backend service responsible for managing all channel connections, message routing, session states, and tool invocation.
Dashboard: A web-based graphical interface for monitoring status, configuring agents, managing sessions, and viewing logs.
Multi-Channel Support: Can simultaneously connect to multiple platforms like WhatsApp, Telegram, Discord, Google Chat, Mattermost, Signal, and iMessage.
Multi-Agent & Routing: Supports configuring multiple AI agents and can route messages to different agents based on contact, group, or content.
Sandbox & Security: Provides session isolation, tool execution sandboxing, and a private conversation pairing approval mechanism for enhanced security.
Skills & Tools: Supports extended skills (like web search, code execution, voice calls) and can be enhanced via a plugin system.

Quick Start Guide

Using the official CLI tool for quick deployment and configuration is the most convenient way to get started.

Environment Preparation

Ensure your system meets these requirements:

Node.js: Version 22 or higher.
Package Manager: pnpm is recommended (if building from source).
Operating System: macOS, Linux, or Windows (strongly recommended via WSL2 on Windows).
Model API Key: Have a usable AI model API key ready, e.g., from OpenAI, Anthropic, or Moonshot.

Install CLI & Run the Wizard

1. Install the OpenClaw CLI:

curl -fsSL https://openclaw.bot/install.sh | bash

2. Run the interactive configuration wizard, which will guide you through core setup:

openclaw onboard --install-daemon

The wizard guides you through these steps:

Choose Authentication: Configure OpenAI OAuth, Anthropic API key, or other model provider credentials.
Setup Gateway: Configure port, bind address, and authentication token.
Add Communication Channels: Configure WhatsApp (QR code login), Telegram (Bot Token), etc.
Install Background Service: Automatically installs as a LaunchAgent (macOS) or systemd user service (Linux/WSL2) to ensure the gateway runs persistently.
Bootstrap Workspace: Creates the initial workspace directory containing startup files needed by agents.

Start Gateway & Verify

If the wizard successfully installed the service, the gateway should have started automatically. You can manually check its status:

openclaw gateway status
openclaw health

Once started, the dashboard is accessible by default at http://127.0.0.1:18789/. You can open this in your browser and converse with the AI assistant without first configuring any chat channels.

Connect Your First Chat Channel

For example, to connect WhatsApp, run in the terminal:

openclaw channels login

Use the WhatsApp mobile app to scan the displayed QR code to complete the link. For Telegram or Discord, you need to provide a Bot Token during the wizard setup.

Pairing & Security Approval

By default, private messages (DMs) from new contacts trigger a pairing flow. The assistant replies with a short code, which you must manually approve before messages are processed:

openclaw pairing list whatsapp
openclaw pairing approve whatsapp <received_short_code>

This mechanism prevents unauthorized access.

Advanced Configuration & Management

Configuration Files & Workspace

Your personalized configuration and data are managed separately for easier updates and backups:

Main Config: ~/.openclaw/openclaw.json stores gateway, channel, and agent routing settings.
Workspace: ~/.openclaw/workspace/ holds agent skills, prompts, memory, etc. It's recommended to initialize this as a private Git repository.
Credentials: OAuth tokens are stored in ~/.openclaw/credentials/. API keys are in ~/.openclaw/agents/<agent_id>/agent/auth-profiles.json.

Use the openclaw configure command to interactively modify specific configuration sections.

Add More AI Agents

You can create multiple independent agents, each with its own workspace, sessions, and authentication:

openclaw agents add <agent_name>

You can then specify in routing rules which agent handles messages from specific contacts or groups.

Skills & Tools

OpenClaw supports a rich set of built-in skills and tools, such as web search, code execution, and voice calls. The configuration wizard recommends installing some common skills. You can manage them in the workspace's skills/ directory.

Troubleshooting & Maintenance

Gateway Not Running: Check service status with openclaw gateway status, or start manually with openclaw gateway --verbose.
Assistant Not Responding: First run openclaw health and openclaw status --all for a detailed status report. A common cause is missing or failed model authentication.
Channel Connection Failed: Check the channel configuration (e.g., if the Token is correct) and review error logs in /tmp/openclaw/.
Keeping the Service Running: The background service installed by the CLI wizard typically ensures persistence. On Linux, if the gateway stops after logout, you may need to enable lingering: sudo loginctl enable-linger $USER.
Updates: Update the CLI using npm update -g openclaw. Your configuration and data (~/.openclaw/) are preserved during updates.

Summary

OpenClaw provides an enterprise-grade, extensible open-source framework for building and managing your personal AI assistant. Using the CLI wizard, you can deploy a working assistant from scratch in minutes. Its clear architectural separation (gateway, configuration, workspace) and powerful features (multi-channel, multi-agent, sandbox security, skill extensions) make it suitable for both simple quick-start needs and complex, customized application scenarios.