DEV Community

Miso
Miso

Posted on

Self-Hosting OpenClaw: Complete Guide

#openclaw #devops #docker #tutorial

Self-Hosting OpenClaw: Complete Guide

Deploy your own AI agent infrastructure in under an hour — no vendor lock-in, full control.

If you've been following the AI agent space, you've probably noticed a pattern: most platforms want you on their cloud, on their terms, at their price. OpenClaw breaks that pattern. It's open-source, self-hostable, and gives you full control over your AI agent team.

This guide walks you through deploying OpenClaw from scratch on your own server. We'll cover prerequisites, installation, configuration, and getting your first agent online.

What Is OpenClaw?

OpenClaw is an AI agent orchestration framework that lets you run a team of autonomous agents — each with its own role, memory, and tool access — on your own infrastructure. Agents communicate via the A2A (Agent-to-Agent) protocol, collaborate on tasks, and report back to you.

Key concepts:

  • Agents: Individual AI workers with defined roles (Developer, Marketer, QA, DevOps, etc.)
  • Rooms: Messaging channels between agents
  • Gateway: The central NATS-based message broker
  • Admin API: REST API for managing agents, rooms, and messages
  • Skills: Packaged capability modules agents can use (browser, code runner, file system, etc.)

Prerequisites

Before you start, make sure you have:

  • A Linux server (Ubuntu 22.04+ recommended, 2 vCPU / 4GB RAM minimum)
  • Docker and Docker Compose installed
  • A domain name (optional but recommended for TLS)
  • An Anthropic API key (or compatible LLM provider key)
  • Basic familiarity with the terminal

Step 1: Install Docker (if not already) 

# Update package index
sudo apt update

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

# Add Docker's 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

# Add 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-compose-plugin

# Add your user to docker group
sudo usermod -aG docker $USER
newgrp docker
Enter fullscreen mode Exit fullscreen mode

Verify installation:

docker --version
docker compose version
Enter fullscreen mode Exit fullscreen mode

Step 2: Clone the OpenClaw Repository 

git clone https://github.com/openclaw/openclaw.git
cd openclaw
Enter fullscreen mode Exit fullscreen mode

Note: If you don't have git installed: sudo apt install -y git

Step 3: Configure Environment Variables

Copy the example environment file and edit it:

cp .env.example .env
nano .env
Enter fullscreen mode Exit fullscreen mode

Key variables to configure:

# LLM Provider (required)
ANTHROPIC_API_KEY=sk-ant-...

# Or use OpenAI-compatible provider
# OPENAI_API_KEY=sk-...
# OPENAI_BASE_URL=https://api.openai.com/v1

# Gateway settings
GATEWAY_HOST=0.0.0.0
GATEWAY_PORT=4222

# Admin API
ADMIN_API_PORT=3000
ADMIN_API_SECRET=your-secure-secret-here

# Agent defaults
DEFAULT_MODEL=anthropic/claude-sonnet-4-5
Enter fullscreen mode Exit fullscreen mode

Security tip: Generate a strong secret with openssl rand -hex 32

Step 4: Launch the Stack

OpenClaw uses Docker Compose to orchestrate all its services:

docker compose up -d
Enter fullscreen mode Exit fullscreen mode

This starts:

  • NATS server — message broker for agent communication
  • Admin API — REST API for management
  • Web UI — browser-based admin panel
  • Traefik (optional) — reverse proxy with automatic TLS

Check that all services are running:

docker compose ps
Enter fullscreen mode Exit fullscreen mode

You should see all services with status running.

Step 5: Access the Admin Panel

Open your browser and navigate to:

  • http://your-server-ip:8080 (local/no TLS)
  • https://your-domain.com (if you configured a domain with TLS)

Default credentials are set during first-run setup. You'll be prompted to create an admin account.

Step 6: Create Your First Agent

Via the Admin Panel:

  1. Click "New Agent"
  2. Fill in:
    • Name: e.g., Alex
    • Role: e.g., Full-Stack Developer
    • Model: anthropic/claude-sonnet-4-5 (or your preferred model)
    • System prompt: Define the agent's personality and responsibilities
  3. Click "Deploy Agent"

The agent spins up as an isolated Docker container within seconds.

Alternatively, via the CLI:

openclaw agent create \
  --name "Alex" \
  --role "Developer" \
  --model "anthropic/claude-sonnet-4-5"
Enter fullscreen mode Exit fullscreen mode

Step 7: Set Up Agent-to-Agent Communication

Agents communicate through "rooms." Create a room between agents:

# Via API
curl -X POST http://localhost:3000/api/rooms \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Dev Team", "type": "group", "agents": ["alex", "qa-agent"]}'
Enter fullscreen mode Exit fullscreen mode

Or use the Admin Panel's Rooms section to create and manage rooms visually.

Step 8: Configure Skills

Skills extend what agents can do. Enable them in each agent's configuration:

# agent-config.yaml
skills:
  - filesystem     # Read/write files in /workspace
  - browser        # Headless browser automation
  - code-runner    # Execute code in sandboxed environment
  - github         # GitHub API integration
  - web-search     # Brave Search API
Enter fullscreen mode Exit fullscreen mode

Each skill requires its own API keys configured in .env.

Step 9: Enable Persistent Memory

Agents can have persistent memory across sessions via the memory skill:

# In .env
MEMORY_BACKEND=sqlite   # Options: sqlite, postgres, redis
MEMORY_PATH=/data/memory
Enter fullscreen mode Exit fullscreen mode

This allows agents to remember past decisions, context, and learned preferences — making them more effective over time.

Step 10: Set Up Monitoring

For production deployments, enable the built-in monitoring stack:

docker compose --profile monitoring up -d
Enter fullscreen mode Exit fullscreen mode

This adds:

  • Prometheus — metrics collection
  • Grafana — dashboards at http://your-server:3001
  • Loki — log aggregation

Key metrics to watch:

  • Agent response latency
  • LLM token usage per agent
  • Message throughput on NATS
  • Container resource usage

Production Hardening Tips

Before going to production, review these:

1. Use TLS everywhere

# Let's Encrypt via Traefik (automatic)
ACME_EMAIL=you@yourdomain.com
DOMAIN=agents.yourdomain.com
Enter fullscreen mode Exit fullscreen mode

2. Set resource limits per agent

# docker-compose.override.yml
services:
  agent-alex:
    deploy:
      resources:
        limits:
          cpus: '0.5'
          memory: 512M
Enter fullscreen mode Exit fullscreen mode

3. Enable audit logging

AUDIT_LOG_ENABLED=true
AUDIT_LOG_PATH=/var/log/openclaw/audit.log
Enter fullscreen mode Exit fullscreen mode

4. Restrict network access
Each agent container runs in an isolated network by default. Agents can only reach the Gateway and explicitly allowed external services.

5. Regular backups

# Backup script (add to cron)
#!/bin/bash
docker compose exec postgres \
  pg_dump -U openclaw openclaw > \
  /backups/openclaw-$(date +%Y%m%d).sql
Enter fullscreen mode Exit fullscreen mode

Troubleshooting Common Issues

Agent won't start:

docker compose logs agent-alex --tail=50
Enter fullscreen mode Exit fullscreen mode

Most common cause: missing or invalid API key in .env.

Agents not communicating:

# Check NATS connectivity
docker compose exec nats nats server check
Enter fullscreen mode Exit fullscreen mode

High memory usage:

  • Reduce context_window in agent config
  • Enable message pruning: MESSAGE_RETENTION_DAYS=7

Web UI not loading:

docker compose restart web-ui
# Check if port 8080 is blocked by firewall
sudo ufw allow 8080/tcp
Enter fullscreen mode Exit fullscreen mode

What's Next?

Once you have OpenClaw running, you can:

  • Add more agents — build your full team (Marketer, DevOps, Security, QA)
  • Create automation workflows — trigger agents on schedules or webhooks
  • Connect external tools — Slack, GitHub Actions, Jira, Linear
  • Build custom skills — extend agent capabilities for your specific stack

Don't Want to Self-Host?

Self-hosting gives you full control, but it requires infrastructure management. If you'd rather skip the setup and get straight to building with AI agents, ClawPod.cloud offers the full OpenClaw stack as a managed service — your first AI agent team, ready in 60 seconds.

Both paths are valid. The ecosystem is open.

Have questions about your self-hosted setup? Drop them in the comments — happy to help.

Top comments (0)