How to Set Up OpenClaw: Complete Installation Guide 2026

A step-by-step guide to installing, configuring, and running OpenClaw on your own server. From a blank VPS to a working AI agent in about an hour.

OpenClaw is the most popular open-source AI agent framework in the world. Over 150,000 GitHub stars. Millions of installations. It connects to every major messaging platform (Telegram, Slack, Discord, WhatsApp), browses the web, executes code, sends emails, and handles multi-step workflows that would take a human hours. It turns an LLM into something that actually does work.

The problem is getting it running properly. The official docs cover the basics, but they leave out critical steps around security, configuration, and production readiness. Most tutorials get you to "it works" and stop there, which is how 42,665 OpenClaw instances ended up publicly exposed on the internet with no authentication.

This guide covers the full process: from provisioning a server to connecting your first messaging channel. We will also cover what most guides skip entirely, and why those missing steps matter more than the setup itself.

What You Will Need (Prerequisites)

Before starting, make sure you have the following ready:

Server Requirements

• A Linux VPS with at least 2 vCPU cores, 4GB RAM, and 40GB storage. If you plan to use browser automation (Playwright/Puppeteer), add another 2GB RAM. Any major VPS provider works.
• Ubuntu 22.04 LTS or 24.04 LTS recommended. Debian 12 also works. Other Linux distributions are compatible but may require adjusting package manager commands.
• Root or sudo access to the server.
• An SSH key pair for secure access. Password-based SSH login should be disabled after setup.

Software and Accounts

• Docker and Docker Compose will be installed during the guide.
• An AI model API key from OpenAI, Anthropic, or OpenRouter. OpenRouter is recommended because it supports budget caps and lets you switch between models without changing your configuration.
• A domain name (optional but recommended). You will need one for TLS/HTTPS. If you do not have a domain, you can still run OpenClaw locally and access it over SSH tunnels.
• Bot tokens for any messaging channels you want to connect (Telegram, Slack, Discord, etc.). We will cover how to get these in Step 5.

Total cost for a basic self-hosted setup: $5-25/mo for the VPS plus $10-100+/mo for AI model API usage, depending on how much your agent talks.

Step 1: Provision a VPS

Sign up with any Linux VPS provider and create a new server with the following specs:

• OS: Ubuntu 22.04 LTS or 24.04 LTS
• Plan: Minimum 2 vCPU, 4GB RAM, 40GB SSD (8GB RAM recommended for browser automation)
• Region: Choose a region close to where your users are located for lower latency
• Authentication: SSH key (not password)

Once the server is provisioned (usually 30-60 seconds), note down the public IP address. You will need it for SSH access.

Connect via SSH

ssh root@YOUR_SERVER_IP

If this is your first time connecting, your terminal will ask you to confirm the server's fingerprint. Type yes to continue.

Create a Non-Root User (Recommended)

Running everything as root is convenient but risky. Create a dedicated user for running OpenClaw:

# Create user and add to sudo group
adduser openclaw
usermod -aG sudo openclaw

# Copy your SSH key to the new user
mkdir -p /home/openclaw/.ssh
cp ~/.ssh/authorized_keys /home/openclaw/.ssh/
chown -R openclaw:openclaw /home/openclaw/.ssh
chmod 700 /home/openclaw/.ssh
chmod 600 /home/openclaw/.ssh/authorized_keys

# Switch to the new user
su - openclaw

From this point forward, run all commands as the openclaw user with sudo where needed.

Update the System

sudo apt update && sudo apt upgrade -y

This ensures your server has the latest security patches before you install anything else.

Step 2: Install Docker

OpenClaw runs as a set of Docker containers. You need both Docker Engine and Docker Compose.

Install Docker Engine

The official Docker installation for Ubuntu:

# Remove any old Docker versions
sudo apt remove docker docker-engine docker.io containerd runc 2>/dev/null

# Install prerequisites
sudo apt install -y ca-certificates curl gnupg

# Add Docker's official GPG key
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg

# Add the Docker repository
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
  $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# Install Docker
sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

Add Your User to the Docker Group

sudo usermod -aG docker $USER
newgrp docker

This lets you run Docker commands without sudo. Log out and back in (or run newgrp docker) for this to take effect.

Verify the Installation

docker --version
docker compose version
docker run hello-world

You should see version numbers for both Docker and Docker Compose, and the hello-world container should print a success message. If any of these fail, check the Docker installation docs for troubleshooting.

Step 3: Set Up OpenClaw with Docker Compose

OpenClaw's recommended deployment method is Docker Compose. It manages the OpenClaw server, a browser automation container, and any supporting services in a single configuration file.

Create the Project Directory

mkdir -p ~/openclaw && cd ~/openclaw

Create the Docker Compose File

Create a file called docker-compose.yml in your project directory:

# ~/openclaw/docker-compose.yml
services:
  openclaw:
    image: openclaw/openclaw:latest
    container_name: openclaw
    restart: unless-stopped
    ports:
      - "18789:18789"
    volumes:
      - ./data:/data
      - ./config/openclaw.yaml:/app/config/openclaw.yaml:ro
    environment:
      - OPENCLAW_STATE_DIR=/data
    env_file:
      - .env

  browser:
    image: openclaw/browser:latest
    container_name: openclaw-browser
    restart: unless-stopped
    environment:
      - BROWSER_PORT=9222

This creates two containers:

• openclaw: The main agent server. It handles messaging channels, tool execution, and LLM communication.
• browser: A headless Chromium instance for web browsing and automation tasks.

Create the Environment File

Create a .env file for your sensitive configuration values:

# ~/openclaw/.env

# AI Model Provider (choose one)
OPENROUTER_API_KEY=your_openrouter_key_here
# OPENAI_API_KEY=your_openai_key_here
# ANTHROPIC_API_KEY=your_anthropic_key_here

# Gateway Authentication
OPENCLAW_AUTH_TOKEN=your_secure_token_here

# Generate a secure token with:
# openssl rand -hex 32

Important: never commit the .env file to version control. Add it to your .gitignore if you are tracking your configuration in git.

Create the OpenClaw Configuration File

# Create the config directory
mkdir -p ~/openclaw/config

Create config/openclaw.yaml:

# ~/openclaw/config/openclaw.yaml
gateway:
  bind: "loopback"
  auth:
    mode: "token"
  mDNS:
    enabled: false

agents:
  defaults:
    model: "openrouter/anthropic/claude-sonnet-4"
    sandbox:
      mode: "all"

browser:
  host: "openclaw-browser"
  port: 9222

Key configuration notes:

• gateway.bind: "loopback" restricts the API to local connections only. This is a critical security setting. Do not change it to listen on all interfaces unless you have a reverse proxy and firewall properly configured.
• gateway.auth.mode: "token" requires authentication for all API requests.
• gateway.mDNS.enabled: false prevents the instance from broadcasting its presence on the local network.
• agents.defaults.sandbox.mode: "all" sandboxes every tool execution in an isolated container.
• The model field specifies your default LLM. If you are using OpenRouter, prefix the model with openrouter/.

Create the Data Directory and Start Everything

# Create the data directory for persistent state
mkdir -p ~/openclaw/data

# Pull the images
docker compose pull

# Start the containers
docker compose up -d

# Check that everything is running
docker compose ps

You should see both the openclaw and openclaw-browser containers running. If either shows an error, check the logs:

# View logs for a specific container
docker compose logs openclaw
docker compose logs openclaw-browser

# Follow logs in real-time
docker compose logs -f openclaw

Common startup issues:

• Port conflict on 18789: Another service is already using the port. Change the port mapping in docker-compose.yml (e.g., "18790:18789").
• Permission denied on /data: The container user cannot write to the mounted volume. Run sudo chown -R 1000:1000 ~/openclaw/data to fix ownership.
• Invalid API key: Double-check the key in your .env file. Make sure there are no extra spaces or newline characters.

Step 4: Configure Your AI Model Provider

OpenClaw supports multiple AI model providers. You need at least one configured for the agent to function.

Option A: OpenRouter (Recommended)

OpenRouter is an API gateway that provides access to models from OpenAI, Anthropic, Google, Meta, and dozens of other providers through a single API key. It is the recommended option for several reasons:

• Budget controls. You can set a monthly spending limit on your API key. When the limit is reached, requests are rejected instead of continuing to accrue charges. This prevents the surprise $3,600 bills that make headlines.
• Model flexibility. Switch between Claude, GPT-4o, Gemini, Llama, and other models by changing a single configuration line. No need to manage separate API keys for each provider.
• Cost optimization. Route cheaper queries (simple lookups, formatting) to faster, cheaper models and expensive queries (complex reasoning, code generation) to frontier models.

To set up OpenRouter:

1. Create an account at openrouter.ai
2. Go to Keys and create a new API key
3. Set a monthly budget limit (recommended: start with $10-25 while testing)
4. Add the key to your .env file as OPENROUTER_API_KEY

Then update your OpenClaw configuration to use an OpenRouter model:

# In openclaw.yaml
agents:
  defaults:
    model: "openrouter/anthropic/claude-sonnet-4"
    # Other popular options:
    # model: "openrouter/openai/gpt-4o"
    # model: "openrouter/google/gemini-2.5-pro"
    # model: "openrouter/meta-llama/llama-4-maverick"

Option B: Direct API Keys

If you prefer to use a provider directly (without OpenRouter), add the API key to your .env file:

# For OpenAI
OPENAI_API_KEY=sk-...

# For Anthropic
ANTHROPIC_API_KEY=sk-ant-...

And set the model in your OpenClaw configuration:

# In openclaw.yaml
agents:
  defaults:
    model: "claude-sonnet-4"    # Anthropic
    # model: "gpt-4o"            # OpenAI

Warning about costs: Direct API keys have no built-in spending limits. A single runaway conversation can burn through hundreds of dollars in a day. OpenRouter's budget controls exist specifically to prevent this. If you use direct keys, monitor your usage dashboards closely and set up billing alerts with your provider.

There is a governance gap in the env var approach: every API key you inject becomes readable by anyone who can access the VPS, and there is no audit trail of which calls were made with which credential. ClawTrust uses a credential proxy instead. Your agent requests credentials through the proxy at call time, the raw secret never touches the VPS, every access is logged with a timestamp and tool context, and you can revoke any credential from the dashboard instantly without rotating the underlying password. A full server compromise cannot exfiltrate credentials that were never there.

Restart After Configuration Changes

After modifying any configuration file or environment variable, restart the containers for changes to take effect:

docker compose down && docker compose up -d

Step 5: Connect Messaging Channels

OpenClaw supports 15+ messaging channels out of the box. Here is how to set up the most popular ones.

Telegram

Telegram is the easiest channel to configure and is popular for personal and small business use cases.

1. Open Telegram and search for @BotFather
2. Send /newbot and follow the prompts to name your bot
3. BotFather will give you a bot token (looks like 123456789:ABCdefGHIjklMNOpqrsTUVwxyz)
4. Add the token to your .env file:

TELEGRAM_BOT_TOKEN=your_bot_token_here

5. Enable the Telegram channel in your openclaw.yaml:

channels:
  telegram:
    enabled: true
    dmPolicy: "pairing"   # Require approval before responding to new users

6. Restart the containers: docker compose down && docker compose up -d
7. Open your bot in Telegram and send it a message. It should respond using your configured LLM.

Slack

Slack integration requires creating a Slack App with the right OAuth scopes.

1. Go to api.slack.com/apps and click Create New App
2. Choose From scratch, name your app, and select your workspace
3. Under OAuth & Permissions, add these Bot Token Scopes:
   • chat:write, chat:write.customize (send messages with custom identity)
   • channels:history, groups:history, im:history (read messages)
   • files:read, files:write (handle file attachments)
   • app_mentions:read (respond to @mentions)
4. Install the app to your workspace and copy the Bot User OAuth Token
5. Under Event Subscriptions, enable events and set the request URL to your server's webhook endpoint
6. Add your Slack tokens to the .env file:

SLACK_BOT_TOKEN=xoxb-...
SLACK_SIGNING_SECRET=your_signing_secret

Slack's event-based architecture requires your server to be reachable from the internet for webhook delivery. If your gateway is bound to loopback (as it should be), you will need a reverse proxy or tunnel to route Slack's webhooks to your local instance.

Discord

1. Go to the Discord Developer Portal and create a new application
2. Under Bot, create a bot and copy the token
3. Enable Message Content Intent under Privileged Gateway Intents
4. Generate an invite URL under OAuth2 > URL Generator with the bot scope and appropriate permissions
5. Add the token to your .env:

DISCORD_BOT_TOKEN=your_discord_token

WhatsApp

WhatsApp integration uses the WhatsApp Business API through Meta's Cloud API.

1. Create a Meta Business account and set up a WhatsApp Business App in the Meta Developer Portal
2. Configure a phone number for your business
3. Obtain a permanent access token (the temporary one expires after 24 hours)
4. Configure the webhook URL for incoming messages
5. Add credentials to your .env:

WHATSAPP_ACCESS_TOKEN=your_access_token
WHATSAPP_PHONE_NUMBER_ID=your_phone_number_id
WHATSAPP_VERIFY_TOKEN=your_webhook_verify_token

WhatsApp is the most complex channel to set up due to Meta's verification requirements. Expect the business verification process to take several days.

Other Channels

OpenClaw also supports Microsoft Teams, Google Chat, Line, Matrix, Signal, and more. Each follows a similar pattern: create an app or bot on the platform, obtain API credentials, add them to your configuration, and enable the channel in openclaw.yaml. The OpenClaw channel documentation covers each in detail.

Step 6: Basic Security Configuration

If you have followed this guide, you already have two of the most important security settings in place: the gateway bound to loopback and token authentication enabled. Here are additional steps to lock down your installation.

Configure the Firewall (UFW)

# Set default policies
sudo ufw default deny incoming
sudo ufw default allow outgoing

# Allow SSH (restrict to your IP if possible)
sudo ufw allow ssh
# Or restrict to a specific IP:
# sudo ufw allow from YOUR_IP to any port 22

# Enable the firewall
sudo ufw enable

# Verify the rules
sudo ufw status verbose

Since the gateway is bound to loopback, port 18789 is not externally accessible even without a firewall rule. But defense in depth matters: if a configuration change accidentally re-binds the gateway, the firewall is your safety net.

Disable SSH Password Authentication

# Edit SSH config
sudo nano /etc/ssh/sshd_config

# Set these values:
# PasswordAuthentication no
# PubkeyAuthentication yes
# PermitRootLogin no

# Restart SSH
sudo systemctl restart sshd

Important: Make sure your SSH key is working before disabling password authentication. If you lock yourself out, you will need to use your VPS provider's console access to recover.

Set Up DM Pairing

DM pairing prevents unauthorized users from interacting with your agent on messaging channels. With pairing enabled, each new user must be explicitly approved before the agent responds to them.

# In openclaw.yaml
channels:
  telegram:
    dmPolicy: "pairing"
  discord:
    dmPolicy: "pairing"
  slack:
    dmPolicy: "pairing"

Without this setting, anyone who discovers your bot can send it commands. With sensitive channels like email or CRM integrations connected, an unauthorized user could access your business data or trigger actions on your behalf.

Enable Tool Sandboxing

Tool sandboxing runs every tool execution (shell commands, code execution, file operations) inside an isolated container rather than directly on the host system.

# In openclaw.yaml
agents:
  defaults:
    sandbox:
      mode: "all"

This is already in our configuration from Step 3, but it is worth highlighting. Without sandboxing, a prompt injection attack or a malicious skill could execute arbitrary commands on your server. With sandboxing enabled, tool calls run in an isolated environment with limited access to the host.

What this checklist does not cover is runtime detection. A hardened configuration reduces your attack surface, but it does not tell you when something unexpected happens after the agent is running. ClawTrust ships with EDR built in: a tool policy engine that monitors every tool call against 33 behavioral rules across 11 MITRE ATT&CK categories, file integrity monitoring that flags unexpected writes, and Falco-based process monitoring that catches suspicious activity in real time. You get full capability with full visibility.

Verify Your Configuration

After making security changes, restart and verify:

# Restart containers
docker compose down && docker compose up -d

# Verify gateway is only listening on loopback
ss -tlnp | grep 18789
# Expected output should show 127.0.0.1:18789, NOT 0.0.0.0:18789

# Verify authentication is working
curl http://localhost:18789/health
# Should return 401 Unauthorized without a valid token

# Test with your token
curl -H "Authorization: Bearer YOUR_TOKEN" http://localhost:18789/health
# Should return 200 OK

Step 7: Test Your Agent

With everything configured and running, it is time to verify that your agent works end-to-end.

Test via the API

# Send a test message
curl -X POST http://localhost:18789/v1/chat/completions \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {"role": "user", "content": "Hello! What can you do?"}
    ]
  }'

You should get a response from your configured LLM. If you see an error about the model or API key, double-check your .env file and OpenClaw configuration.

Test via Messaging Channel

If you connected Telegram (the easiest to test):

1. Open your bot in Telegram
2. Send a message: "Hello, what can you help me with?"
3. The agent should respond within a few seconds

If the agent does not respond, check the logs:

docker compose logs -f openclaw

Look for error messages related to the channel connection or API key validation.

Test Browser Automation

Ask your agent to perform a web browsing task to verify the browser container is connected:

# Via the API
curl -X POST http://localhost:18789/v1/chat/completions \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {"role": "user", "content": "Go to example.com and tell me what the page says."}
    ]
  }'

If browser automation fails, check that the openclaw-browser container is running and that the browser.host setting in your OpenClaw config matches the container name in your Docker Compose file.

What Most Guides Skip

If you have followed every step so far, you have a functional OpenClaw instance. It can chat, browse the web, execute code, and communicate through messaging channels. It has basic security in place: loopback gateway binding, token authentication, firewall rules, and DM pairing.

That covers about 60% of what a production deployment needs. Here is the other 40% that most setup guides leave out entirely.

Container Hardening

The default Docker configuration gives containers more privileges than they need. A production deployment should restrict privilege escalation, cap resource usage (CPU and memory), and run the browser container with a read-only filesystem. Without these restrictions, a compromised container can consume all server resources or escalate to host-level access.

Disk Encryption

OpenClaw stores agent state, conversation logs, and cached data on disk. Without encryption at rest, anyone with physical or infrastructure-level access to the server (a decommissioned disk, a backup snapshot, a hypervisor compromise) can read all of it. LUKS2 full-disk encryption on the data volume addresses this, but it must be configured before OpenClaw is installed. Retrofitting encryption onto an existing deployment requires data migration.

Credential Management

Right now, your API keys and bot tokens live in a .env file on the server. If the server is compromised, those credentials are immediately exposed. A proper production deployment moves credentials to a dedicated secrets manager (HashiCorp Vault, Doppler, or a similar tool) and retrieves them at runtime. The agent should never have direct access to your most sensitive credentials.

TLS/HTTPS

If you need to access the OpenClaw API remotely (not just from the local machine), you need a reverse proxy with TLS termination in front of it. Nginx or Caddy with a Let's Encrypt certificate is the standard approach. Without TLS, API tokens and conversation data are transmitted in plaintext.

Monitoring and Alerting

Your agent is running, but how do you know if it stops? Or if it is being attacked? A production deployment needs health checks on a regular interval, log monitoring for error spikes and authentication failures, resource monitoring for CPU and memory, and a patching schedule for OpenClaw updates and security advisories.

Automated Updates

OpenClaw had three CVEs disclosed in a single week in early 2026, including one (CVE-2026-25253) that allowed one-click remote code execution. Self-hosted instances do not auto-update. If you are running your own server, you need a process for discovering, testing, and deploying patches quickly.

The Time Investment

Steps 1 through 7 of this guide take about an hour. You will have a working agent with basic security.

The full hardening process (container restrictions, disk encryption, credential management, monitoring, TLS, patching) takes 3 to 19 more hours, depending on your experience with Linux server administration, Docker, and secrets management. The wide range reflects the gap between someone who has done this before and someone learning as they go.

We wrote a complete guide to the full hardening process: OpenClaw Security Hardening: The Complete Guide for 2026. It covers all seven security layers with step-by-step instructions and time estimates.

The bottom line: getting OpenClaw running is the easy part. Keeping it secure, monitored, and patched is the actual work.

The Managed Alternative

If you just read through 3,000 words of setup instructions and thought "that is a lot of work," you are not wrong.

Between provisioning a server, installing Docker, configuring OpenClaw, setting up messaging channels, hardening containers, encrypting disks, managing credentials, configuring TLS, setting up monitoring, and establishing a patching schedule, a proper production deployment is a significant investment. And it is not a one-time investment. Servers need maintenance. CVEs need patches. Monitoring needs attention.

ClawTrust handles all of this. Every deployment gets:

• A dedicated VPS provisioned and configured automatically
• Full security hardening including loopback gateway binding, token auth, container restrictions, and disk encryption
• AI budget controls through OpenRouter with configurable spending limits. No surprise bills.
• All messaging channels pre-configured and ready to connect
• Automated health monitoring with checks every 15 minutes and auto-remediation for common issues
• Fleet-wide security patching so you never have to manually apply CVE fixes
• Credential isolation where your API keys and passwords are stored in an encrypted vault, separate from the agent's server

Setup time: under 5 minutes. No SSH. No Docker. No YAML files. Pick a plan, connect your channels, and start working with your agent.

Plans start at $79/mo (all-inclusive with AI credits). Compare that to the hourly cost of doing it yourself, and the monthly maintenance cost of keeping it running.

Frequently Asked Questions

What are the minimum server requirements for OpenClaw?

OpenClaw requires at least 2 vCPU cores, 4GB RAM, and 40GB storage. If you plan to use browser automation, add another 2GB RAM (6GB total). Docker must be installed. For production workloads with multiple channels and heavy browser use, 4 vCPU and 8GB RAM is recommended.

How long does it take to install OpenClaw?

Basic installation takes about an hour: 10-15 minutes for VPS provisioning and Docker, 15-20 minutes for OpenClaw configuration, and 15-30 minutes for channel setup and testing. Full security hardening adds another 3-19 hours depending on your experience level.

Can I run OpenClaw on my local machine?

Yes. OpenClaw runs on any machine with Docker installed, including macOS and Windows (via Docker Desktop). Local installations are great for development and testing but are not suitable for production use because your machine needs to stay running 24/7, messaging webhooks need a publicly accessible URL, and there is no redundancy if your machine goes offline.

Which AI model should I use with OpenClaw?

For general-purpose agents, Claude Sonnet 4 (via OpenRouter or Anthropic directly) offers the best balance of capability and cost. GPT-4o is a strong alternative. For budget-sensitive deployments, Llama 4 Maverick through OpenRouter provides good performance at a lower price point. You can change models at any time by updating your configuration.

How do I update OpenClaw to the latest version?

Pull the latest Docker images and restart:

docker compose pull
docker compose down && docker compose up -d

Check the OpenClaw changelog before updating to review breaking changes. For critical security patches, update within 24 hours of disclosure.

Why is my OpenClaw agent not responding to messages?

Common causes: the container is not running (docker compose ps to check), the API key is invalid or has hit its spending limit, the messaging channel token is incorrect, or the gateway is not accessible from the channel's webhook delivery service. Check docker compose logs openclaw for specific error messages.

How much does it cost to run OpenClaw per month?

Self-hosted: $5-25/mo for a VPS plus $10-100+/mo for AI model API usage with no spending cap. The API cost is the wildcard. Without budget controls, a single agent can burn through hundreds of dollars in a day. Managed hosting (like ClawTrust) starts at $79/mo all-inclusive with AI credits and spending limits built in.

Can I run multiple OpenClaw agents on one server?

Technically yes, using separate Docker Compose stacks with different ports and data directories. However, this means all agents share the same security boundary. If one agent is compromised, the attacker has access to the same server running your other agents. For production use with sensitive data, each agent should run on its own dedicated server.

---

Chris DiYanni is the founder of ClawTrust. Previously at Palo Alto Networks, SentinelOne, and PagerDuty. He builds security infrastructure so businesses can trust their AI agents with real work.