OpenClaw Setup Guide — From Zero to AI Assistant in 10 Minutes

What Is OpenClaw?

OpenClaw is an open-source AI gateway that turns large language models into practical, everyday assistants. It connects AI models (Claude, GPT, Gemini, DeepSeek, and others) to messaging platforms (Telegram, Discord, WhatsApp) and gives them skills — the ability to browse the web, run code, manage files, search the internet, and much more.

Think of it as the missing layer between raw AI APIs and a usable assistant. Without OpenClaw, using Claude or GPT means opening a web interface and typing into a chat box. With OpenClaw, you message your AI from Telegram while walking, ask it to research a topic in a Discord server meeting, or send it a voice note on WhatsApp and get a transcribed, intelligent response.

This guide walks you through setting up OpenClaw from scratch — from a blank server to a working AI assistant.

System Requirements

OpenClaw runs as a Docker container, which means it works on virtually any Linux server. Here's what you need:

• Operating System: Ubuntu 22.04+ (recommended), Debian 12+, or any Linux distro with Docker support. macOS and Windows work for local development but aren't recommended for production.
• Docker: Version 24+ with Docker Compose. Install with curl -fsSL https://get.docker.com | sh.
• Memory: Minimum 2GB RAM for the OpenClaw container. Budget 3GB+ if you plan to use memory-intensive skills like code execution.
• Storage: 10GB minimum. More if you'll be working with files, images, or persistent data.
• Network: Outbound HTTPS access (for AI API calls) and a public IP or domain if you want to use the web gateway.

A basic VPS from providers like Hetzner ($5-10/month) or DigitalOcean ($6/month) works perfectly.

Step 1: Install Docker

If Docker isn't already on your server, install it:

# Install Docker
curl -fsSL https://get.docker.com | sh

# Add your user to the docker group (avoids needing sudo)
sudo usermod -aG docker $USER

# Log out and back in for the group change to take effect
# Then verify:
docker --version

You should see something like Docker version 26.x.x. If Docker Compose isn't included, install it separately with sudo apt install docker-compose-plugin.

Step 2: Pull the OpenClaw Image

OpenClaw is distributed as a Docker image. Pull the latest stable version:

docker pull ghcr.io/openclaw/openclaw:latest

Important: Use the :latest tag for the stable release. The :main tag tracks the bleeding-edge development branch and may contain bugs. Unless you're testing specific features, stick with :latest.

Step 3: Create the Configuration

OpenClaw reads its configuration from a JSON file at ~/.openclaw/openclaw.json. Create the directory structure first:

# Create config directory
mkdir -p ~/.openclaw/credentials
chmod 777 ~/.openclaw
chmod 777 ~/.openclaw/credentials

The chmod 777 is necessary because the Docker container runs as the node user (uid 1000), and it needs write access to store session data, credentials, and pairing information. Without these permissions, channels like Telegram and WhatsApp will silently fail.

Now create the config file:

{
  "gateway": {
    "auth": {
      "token": "YOUR_RANDOM_TOKEN_HERE"
    },
    "controlUi": {
      "allowInsecureAuth": true
    }
  },
  "models": {
    "providers": {
      "openrouter": {
        "apiKey": "sk-or-v1-your-openrouter-key"
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "openrouter/anthropic/claude-sonnet-4"
      }
    }
  },
  "channels": {},
  "plugins": {
    "entries": {}
  }
}

Let's break down each section:

• gateway.auth.token — a secret token to access the web gateway. Generate a random one with uuidgen or openssl rand -hex 32. This must be an object ({"token": "..."}), not a plain string.
• gateway.controlUi.allowInsecureAuth — disables device-identity pairing for the web gateway, allowing token-only authentication. Without this, remote browser connections will fail with "pairing required" errors. Safe when behind HTTPS.
• models.providers — your AI model provider credentials. OpenRouter is recommended because it gives you access to dozens of models with a single API key.
• agents.defaults.model.primary — the default model for all conversations. Note the provider prefix: openrouter/anthropic/claude-sonnet-4, not just anthropic/claude-sonnet-4.

Step 4: Get an AI Model API Key

You need an API key from an AI model provider. OpenRouter is the easiest option because it aggregates multiple providers:

1. Sign up at openrouter.ai.
2. Add credits to your account (you can start with $5).
3. Go to Keys and create a new API key.
4. Copy the key (starts with sk-or-v1-) into your config file.

OpenRouter supports Claude (Anthropic), GPT (OpenAI), Gemini (Google), DeepSeek, Llama (Meta), Mistral, and many more — all through one key. You can switch models anytime by changing the agents.defaults.model.primary value.

Step 5: Connect Your First Channel

Now add a messaging channel. We'll use Telegram as the example (see our Telegram-specific guide for more detail, or our Discord guide for Discord setup):

1. Message @BotFather on Telegram and use /newbot to create a bot.
2. Copy the bot token.
3. Add to your config:

{
  "channels": {
    "telegram": {
      "enabled": true,
      "botToken": "YOUR_TELEGRAM_BOT_TOKEN",
      "dmPolicy": "pairing"
    }
  },
  "plugins": {
    "entries": {
      "telegram": {
        "enabled": true
      }
    }
  }
}

Remember: both channels.telegram.enabled and plugins.entries.telegram.enabled must be true. The channel config tells OpenClaw how to connect; the plugin entry tells it to actually start the connection.

Step 6: Run OpenClaw

Start the container:

docker run -d \
  --name openclaw \
  --restart unless-stopped \
  -p 18789:18789 \
  -v ~/.openclaw:/home/node/.openclaw \
  --memory=2g \
  --memory-swap=3g \
  ghcr.io/openclaw/openclaw:latest \
  node openclaw.mjs gateway --allow-unconfigured

Breaking down the flags:

• -d — runs in the background.
• --restart unless-stopped — auto-restarts on crash or server reboot.
• -p 18789:18789 — exposes the web gateway port.
• -v ~/.openclaw:/home/node/.openclaw — bind-mounts your config directory into the container.
• --memory=2g --memory-swap=3g — resource limits. OpenClaw needs at least 2GB; less causes out-of-memory crashes.

Check that it's running:

docker logs openclaw --tail 50

You should see the gateway starting up, loading plugins, and connecting to your configured channels. If Telegram is configured, you'll see a message about the Telegram bot connecting.

Step 7: Have Your First Conversation

Open Telegram and find your bot by its username. Send it a message. If you're using pairing mode, you'll first need to pair through the web gateway:

1. The bot responds with a pairing code.
2. Open http://your-server-ip:18789 in your browser.
3. Log in with your gateway token.
4. Enter the pairing code.
5. Go back to Telegram and send another message — this time you'll get an AI response.

Try a few things:

• "What can you do?" — the AI will describe its capabilities based on enabled skills.
• "What's the weather like in Tokyo?" — if web search is enabled, it'll look it up.
• "Write a Python script that generates a random password." — tests code generation.
• "Summarize this article: [paste URL]" — if web browse is enabled, it'll read and summarize the page.

Self-Hosting vs. OpenClaw Launch

You've just gone through about 10 minutes of setup — and that's the streamlined version. In practice, self-hosting also means:

• Server maintenance: Keeping Ubuntu updated, Docker patched, and the server secure.
• Monitoring: Checking that the container is running, channels are connected, and API keys haven't expired.
• Scaling: If you want multiple bots or higher availability, you need to manage multiple containers.
• SSL certificates: Setting up HTTPS for the web gateway (essential for device pairing).
• Backups: Backing up your config, credentials, and conversation data.
• Updates: Pulling new OpenClaw versions and testing that nothing breaks.

Self-hosting gives you full control, and for power users who want to customize every aspect of their setup, it's the right choice.

But if you just want a working AI assistant without managing infrastructure, OpenClaw Launch does everything above for you. The entire process — from signup to a working bot — takes about 60 seconds:

1. Sign up at openclawlaunch.com.
2. Paste your bot token (Telegram, Discord, or WhatsApp).
3. Pick your model and skills.
4. Click Deploy.

No VPS, no Docker, no config files, no SSL, no monitoring. OpenClaw Launch handles deployment, health checks, automatic restarts, security configuration, and updates. You get a dashboard to manage everything and logs to see exactly what's happening.

Plans start at $3/month for the first month, $6/month after. Get started here and skip straight to the part where your AI assistant is working.