OpenClaw Setup Guide: Deploy Your First AI Agent (2026)
OpenClaw is impressively close to "one docker run and you have an AI agent". It is also true that the first deployment will trip you up on at least one of four things: the LLM API key wiring, the Control UI device pairing, the gateway token, or the reverse-proxy hostname. We have walked dozens of first-time deployments through these. This guide is the boring, accurate version of the setup process — including the gotchas — for both DIY self-hosters and people taking the managed OpenClaw hosting shortcut. By the end you will have a running OpenClaw instance, an LLM connected, and an agent that responds to its first message.
A first OpenClaw deployment takes roughly an hour: provision a 2 vCPU / 4 GB VPS, install Docker, run the OpenClaw container behind Caddy with SSL, set OPENCLAW_LLM_API_KEY, complete the one-time device pairing in the Control UI, and create your first agent. The four common pitfalls are LLM key formatting, device pairing without a working public hostname, the gateway token mismatch, and forgetting to remove data/openclaw.json after a config change. Or skip all of this with managed OpenClaw hosting — the same end state in five minutes.
What You Need Before You Start
A VPS with at least 2 vCPU, 4 GB RAM, 40 GB SSD, and Ubuntu 22.04 or 24.04. Hetzner CX22 and BearHost BearHost VPS Hosting both qualify. Blogs How To Set Up Vps Beginners 2026 covers first-time VPS basics if this part is new.
A subdomain you control. OpenClaw needs HTTPS, which needs a real hostname. Something like agents.example.com is fine. Point an A record at your VPS IP before you start the container so Let's Encrypt can issue the cert on first boot.
An LLM API key. OpenAI sk-... or Anthropic sk-ant-... both work. If you do not have one, OpenAI accounts can be created in five minutes; Anthropic accounts sometimes need a day for approval. You can also use Ollama for local models — see Blogs What Is Openclaw Ai Agent Platform 2026 for the trade-offs.
About an hour. Less if you have done docker-on-a-VPS work before, more if everything is new. Skip this if you would rather have it done in five minutes — managed OpenClaw hosting handles every step in this guide for you from £14.15/mo.
Step 1: Prepare the Server
SSH in as root or as a sudoer. Update the package index and install Docker — these are stable enough to copy verbatim.
apt update && apt upgrade -y
curl -fsSL https://get.docker.com | sh
systemctl enable --now docker
apt install -y ufw
ufw allow OpenSSH && ufw allow 80/tcp && ufw allow 443/tcp && ufw --force enableThat gives you a working Docker host with only SSH, HTTP, and HTTPS exposed. If you are running on a provider that does not give you a real public IPv4 (some shared-rdp "VPSs" do not), stop and switch to a real KVM VPS — OpenClaw cannot complete device pairing without a routable hostname. Blogs Cheap Vps Hosting 2026 explains how to spot the fake-VPS pattern.
Step 2: Configure Your Environment
Create a directory for OpenClaw and a .env file with the four variables that matter. Use printf rather than a heredoc — VirtFusion and several other VPS providers add leading spaces to heredocs that silently break the file.
mkdir -p /opt/openclaw/data && cd /opt/openclaw
printf 'OPENCLAW_HOSTNAME=agents.example.com\nOPENCLAW_LLM_PROVIDER=openai\nOPENCLAW_LLM_API_KEY=sk-your-real-key\nGATEWAY_TOKEN=$(openssl rand -hex 32)\n' > .env
cat .env # double check everything is present and correctly formattedPitfall one: the LLM API key. OpenAI keys start sk- and Anthropic keys start sk-ant-. Do not paste in the project ID, the org ID, or a key with a trailing newline. About one in three first-time deploys fails here and the error messages — "401 unauthorized", "missing scope" — are not always obvious.
Step 3: Run OpenClaw with Caddy
Caddy issues SSL certificates automatically and reverse-proxies to the OpenClaw container. The compose file below is the minimum that works in production.
services:
openclaw:
image: ghcr.io/openclaw/openclaw:latest
restart: unless-stopped
env_file: .env
volumes:
- ./data:/app/data
networks: [internal]
caddy:
image: caddy:2
restart: unless-stopped
ports: ["80:80", "443:443"]
volumes:
- ./Caddyfile:/etc/caddy/Caddyfile
- caddy_data:/data
networks: [internal]
volumes:
caddy_data:
networks:
internal:And the Caddyfile — note the gateway.bind must be lan rather than loopback or Caddy will not be able to reach the OpenClaw container over the Docker network. This is the second common pitfall.
agents.example.com {
reverse_proxy openclaw:8080
}Bring it up with docker compose up -d. Watch the logs for sixty seconds — Caddy needs to reach Let's Encrypt over port 80, and OpenClaw needs to validate the LLM key.
Step 4: Complete Device Pairing in the Control UI
Visit https://agents.example.com in a browser. The first time you load the Control UI, OpenClaw asks you to "pair" your browser as a trusted device. This is not optional and you cannot skip it by setting dangerouslyDisableDeviceAuth=true (you can technically, but the Control UI will then be missing the scopes it needs to install skills). Pitfall three: device pairing only works over HTTPS on the real hostname, not on http://your-ip. Make sure DNS is propagated and Caddy has a green padlock before you try to pair.
Pairing flow: the Control UI shows a six-character code. SSH into your server, run docker exec openclaw openclawctl pair --code ABC123, and the browser flips to a logged-in dashboard. From here on, the device cookie is what authenticates you.
Step 5: Wire the Gateway Token
The gateway is OpenClaw's JSON-RPC API. Anything that wants to invoke an agent from outside — n8n, Zapier, your own backend, a webhook — calls https://agents.example.com/gateway/rpc with the GATEWAY_TOKEN you generated in step 2. Pitfall four: people forget that GATEWAY_TOKEN must match exactly between the .env file and whatever caller is hitting the gateway. If you regenerate the .env after first boot, you also need to docker compose restart openclaw to pick up the new value.
Test the gateway from your laptop: curl -H "Authorization: Bearer your-token" https://agents.example.com/gateway/rpc/health. A 200 with {"status":"ok"} means the gateway is healthy and ready to receive RPC calls. If you also run n8n, Blogs What Is Managed N8n Hosting Guide 2026 covers how to wire OpenClaw into a workflow.
Step 6: Create Your First Agent
In the Control UI, go to Agents → New. The minimum viable agent is three fields: a name, a system prompt, and a list of allowed tools. Start with the built-in chat tool and the http_request tool — they are the most useful and the least likely to misbehave on day one.
A reasonable first system prompt: "You are a helpful research assistant. Use the http_request tool to fetch web pages when the user asks about something current. Always cite the URL you used. If you are unsure, say so." Save the agent, click "Try it", and send a message. You should see the model think for a few seconds, fetch a URL, and reply with a cited answer.
For agent ideas with concrete API choices and outcomes, Blogs Best Openclaw Ai Agent Use Cases 2026 catalogues the patterns that work in production — customer support, lead scoring, data extraction, browser-based RPA, and more.
Pitfalls Recap
- LLM API key formatting: no trailing whitespace, correct prefix (sk- for OpenAI, sk-ant- for Anthropic), correct provider value in OPENCLAW_LLM_PROVIDER
- Device pairing: only works on the real HTTPS hostname, not raw IP — DNS must be propagated and SSL must be valid before you click Pair
- Gateway token mismatch: regenerate the token, then restart the container before any external system tries to use the new value
- Stale config: after a meaningful config change, remove data/openclaw.json before restarting (rm data/openclaw.json && docker compose restart openclaw) or the old config will silently win
- gateway.bind: must be lan, not loopback, for Caddy to reach OpenClaw across the Docker network
- Wrong port: the OpenClaw container exposes 8080 internally, not 80 — your reverse proxy must target openclaw:8080
- IPv6 only VPS: a few cheap providers ship IPv6-only servers; Caddy can issue an IPv6 cert but device pairing assumes you have IPv4 connectivity. Use a VPS with both A and AAAA records
The Five-Minute Alternative: Managed Hosting
Every step above happens automatically on BearHost OpenClaw hosting. You sign up, choose a plan, and within three to five minutes you receive an email with your https://yourname.openclaw.bearhost.com URL, your admin credentials, and the gateway token already wired into the .env. The container is running, Caddy has issued the cert, the firewall is configured, daily backups are scheduled, and the device pairing flow works on first try because the hostname is correct.
You still need to bring your own LLM API key — paste it into the Control UI under Settings → LLM Provider and you have a working agent. If you outgrow the Cub plan, upgrade to Bear or Grizzly with no migration; the data lives on the VPS and the upgrade scales the resources behind it. Blogs Self Hosted Vs Managed Openclaw Hosting Cost 2026 has the full cost comparison if you are weighing the two paths.
Frequently Asked Questions
Conclusion
OpenClaw deployment is one of those tasks that is genuinely easy in the happy path and genuinely annoying when one of the four pitfalls fires. With the LLM key formatted correctly, the hostname pointed at the VPS before first boot, the gateway token consistent across .env and callers, and the gateway.bind set to lan, you have a running agent in under an hour. If you would rather not learn this list of edge cases, managed OpenClaw hosting on BearHost handles every one of them and gets you to the same end state in five minutes. For the bigger picture, Blogs What Is Openclaw Ai Agent Platform 2026 explains what OpenClaw actually is, Blogs Self Hosted Vs Managed Openclaw Hosting Cost 2026 compares the cost of both paths, and Blogs Best Openclaw Ai Agent Use Cases 2026 catalogues real agents you can build now that the platform is up.
