OpenClaw: How to Set Up Your Own Self-Hosted AI Assistant on a Cloud VPS

What Is OpenClaw?

OpenClaw is an open-source, self-hosted AI gateway that connects your messaging apps — Telegram, WhatsApp, Discord, Slack, and more — to AI models like Claude, GPT-4, Gemini, or local Ollama instances. It went from a side project to 68,000+ GitHub stars in early 2026, making it the most popular self-hosted AI assistant platform of the year.

Think of it as the operating layer between your digital life and AI. You run a single Gateway process on your own hardware. Every message from every channel flows through it. Every tool call — shell commands, file reads, browser automation, scheduled tasks — executes through it. Your data stays on your machine. Your API keys stay in your config. You own everything.

We recently deployed OpenClaw on an Oracle Cloud ARM VPS and connected it to Telegram, Gmail, web search, browser automation, and a custom dashboard. This article walks through the entire process — what we did, why, and the hard-earned lessons from debugging along the way.

Why Self-Host an AI Assistant?

Cloud-hosted AI assistants are convenient, but they come with trade-offs: your conversations are stored on someone else's servers, you're locked into their pricing, and you can't customize the behavior deeply. With OpenClaw:

• Privacy — Session transcripts stay on disk. Nothing leaves unless you configure it.
• Cost control — Works with any API key from supported providers. No per-message markup on top of your provider costs.
• Update (April 2026): OpenClaw originally supported connecting directly to a Claude Max subscription, meaning you could run your AI assistant for a flat USD 200/month with no per-token fees. As of April 4, 2026, Anthropic discontinued this, blocking third-party tools like OpenClaw from using Claude subscriptions. You now need to use API keys with pay-per-token billing from whichever provider you choose.
• Full customization — Skills, plugins, hooks, webhooks. Write custom tools. Connect anything.
• Multi-channel — One gateway serves Telegram, Discord, web UI, and webhooks simultaneously. Same agent, different front doors.
• Extensibility — Browser automation, web search, email integration, scheduled tasks, and more.

Architecture Overview

OpenClaw's architecture is straightforward but powerful:

┌─────────────────┐     ┌──────────────────┐     ┌─────────────────┐
│   Channels       │────▶│    Gateway        │────▶│   AI Provider   │
│  (Telegram,     │     │  (Port 18789)    │     │  (Claude, GPT,  │
│   Discord, Web) │◀────│  localhost only   │◀────│   Fireworks)    │
└─────────────────┘     └──────────────────┘     └─────────────────┘
                              │
                        ┌─────┴─────┐
                        │   Tools    │
                        │  Browser   │
                        │  Search    │
                        │  Skills    │
                        │  Cron      │
                        └───────────┘

The Gateway is the execution boundary. The AI model never executes anything directly — the Gateway mediates every tool call, which is where you insert approval gates, cost controls, and custom logic. Channels (Telegram, web UI, etc.) are just front doors.

Setting Up OpenClaw on a Cloud VPS

Choosing Your Server

OpenClaw runs on anything with Node.js 24 (or 22.14+). For our deployment, we used an Oracle Cloud ARM instance — 4 OCPUs, 24 GB RAM, Ubuntu 24.04 on ARM64. Oracle's Always Free tier includes ARM instances, making it a cost-effective choice.

Any VPS provider works: DigitalOcean, Hetzner, Linode, AWS, etc. The key requirements are:

• SSH access to a Linux machine you control
• Node.js 24 or 22.14+
• At least 2 GB RAM (4+ recommended if using browser automation)

Security First

Before installing anything, harden the server. This is non-negotiable for any internet-facing machine:

# Enable UFW firewall — deny all inbound except SSH
sudo ufw default deny incoming
sudo ufw default allow outgoing
sudo ufw allow 22/tcp
sudo ufw enable

# Install fail2ban for brute-force protection
sudo apt install fail2ban -y

# Disable root SSH login
sudo sed -i 's/#PermitRootLogin yes/PermitRootLogin no/' /etc/ssh/sshd_config
sudo systemctl restart sshd

# Disable unnecessary services (rpcbind is a common attack surface)
sudo systemctl disable rpcbind --now
sudo systemctl mask rpcbind

Critical: If your cloud provider has a separate network firewall (like Oracle's Security Lists or AWS Security Groups), restrict SSH access to your IP address there too. Defense in depth — don't rely on UFW alone.

Installing OpenClaw

The install is a single command:

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

After installation, run the onboarding wizard:

openclaw onboard --install-daemon

This walks you through authentication, gateway configuration, channel setup, and service installation. For a headless Linux server, you'll want to initialize in local mode and bind the gateway to loopback only:

# The gateway should NEVER be exposed to the public internet
# Bind to loopback only
openclaw config set gateway.host 127.0.0.1
openclaw config set gateway.port 18789

Set up the gateway as a user-level systemd service so it auto-starts on boot:

# Enable lingering so the user service runs without an active login session
loginctl enable-linger $USER

# Start and enable the gateway service
systemctl --user enable openclaw-gateway
systemctl --user start openclaw-gateway

Accessing the Dashboard Securely

Since the gateway only listens on localhost, you access it through an SSH tunnel from your local machine. This is the secure way — no need to open port 18789 in your firewall.

# From your local machine (Windows, Mac, or Linux):
ssh -N -L 18789:127.0.0.1:18789 -i your-key.pem user@your-server-ip

Then open http://127.0.0.1:18789/ in your browser. The dashboard shows active sessions, connected channels, and lets you chat directly with your AI agent.

Automating the Tunnel (Windows Example)

We created a batch file that automates the entire process — fetches the current gateway token, copies it to the clipboard, starts the SSH tunnel, and opens the browser. Here's the pattern:

@echo off
set SSH_EXE=C:\Windows\System32\OpenSSH\ssh.exe
set KEY_FILE=path\to\your-key.pem
set SSH_HOST=user@your-server-ip
set LOCAL_PORT=18789

REM Fetch the dashboard URL (includes token)
REM Start the SSH tunnel in a new window
start "OpenClaw SSH Tunnel" "%SSH_EXE%" -N -L %LOCAL_PORT%:127.0.0.1:%LOCAL_PORT% -i "%KEY_FILE%" %SSH_HOST%

REM Wait for tunnel to establish, then open browser
timeout /t 3 /nobreak >nul
start "" "http://127.0.0.1:18789/"

echo Keep the "OpenClaw SSH Tunnel" window open while using the UI.

Connecting AI Providers

OpenClaw supports multiple AI providers out of the box: Anthropic (Claude), OpenAI, Google (Gemini), and any OpenAI-compatible API. We chose Fireworks AI with the Kimi K2.5 router for cost efficiency and quality.

Configuration is done through the CLI:

# Add a custom OpenAI-compatible provider
openclaw config set providers.fireworks.type openai-compatible
openclaw config set providers.fireworks.baseUrl https://api.fireworks.ai/inference/v1

# Set the default model
openclaw config set agents.defaults.model fireworks/your-model-name

# Store the API key securely as an environment variable reference
# (not plaintext in the config file)
openclaw config set providers.fireworks.apiKey env:FIREWORKS_API_KEY

Important: Always use env:SECRET_NAME references instead of pasting API keys directly into the config. Store the actual keys in your systemd service override file with restrictive permissions (0600).

Setting Up Telegram

Telegram is one of OpenClaw's best-supported channels. The setup is straightforward:

1. Create a bot via @BotFather on Telegram
2. Get the bot token
3. Add it to OpenClaw (using env SecretRef, not plaintext):

openclaw config set channels.telegram.enabled true
openclaw config set channels.telegram.botToken env:TELEGRAM_BOT_TOKEN
openclaw config set channels.telegram.dmPolicy pairing
openclaw config set channels.telegram.groups.*.requireMention true

The dmPolicy: pairing setting means new users must be approved before they can chat with the bot — a good security practice. The requireMention setting for groups means the bot only responds when directly mentioned, preventing it from hijacking every conversation.

Browser Automation on a Headless Server

One of OpenClaw's most powerful features is browser automation — your AI agent can actually browse the web, fill forms, take screenshots, and interact with web pages. But getting it working on a headless VPS requires specific configuration.

First, install a Chromium-based browser. We used Brave Browser because it provides official ARM64 Linux packages (Chrome does not):

# Install Brave Browser (arm64 Linux)
sudo curl -fsSLo /usr/share/keyrings/brave-browser-archive-keyring.gpg \
  https://brave-browser-apt-release.s3.brave.com/brave-browser-archive-keyring.gpg
echo "deb [arch=arm64 signed-by=/usr/share/keyrings/brave-browser-archive-keyring.gpg] \
  https://brave-browser-apt-release.s3.brave.com/ stable main" | \
  sudo tee /etc/apt/sources.list.d/brave-browser-release.list
sudo apt update && sudo apt install brave-browser -y

Then install Playwright for browser automation:

npm install -g playwright
npx playwright install chromium

Finally, configure OpenClaw for headless operation — this is the critical step that many people miss:

openclaw config set browser.enabled true
openclaw config set browser.headless true
openclaw config set browser.noSandbox true
openclaw config set tools.profile full
openclaw config validate
systemctl --user restart openclaw-gateway

Without browser.headless = true and browser.noSandbox = true, the browser will crash with "Missing X server or $DISPLAY" errors on a headless VPS. Without tools.profile = full, the AI agent won't have access to browser tools even if the browser service is running.

Gmail Integration via Webhooks

We connected Gmail to OpenClaw so the AI agent receives and can respond to emails. The architecture uses Google Cloud Pub/Sub to push Gmail notifications to the server through a Tailscale Funnel — a secure, publicly-reachable endpoint without opening ports in the firewall.

The pipeline looks like this:

Gmail → Google Pub/Sub → Tailscale Funnel → gog watch serve → OpenClaw webhook

This setup requires:

• gog — a CLI tool for Google Workspace APIs
• A Google Cloud project with Gmail API and Pub/Sub enabled
• Tailscale installed with Funnel configured

OpenClaw provides a single command that wires everything together:

openclaw webhooks gmail setup --account [email protected] --project your-gcp-project

For outgoing email from custom domains, we used himalaya — a Rust-based CLI email client — configured with AWS SES SMTP credentials. This lets the AI send email as [email protected] without a full mail server.

Lessons Learned the Hard Way

Setting up OpenClaw on a production VPS isn't plug-and-play. Here are the real issues we ran into and how we solved them:

1. The Gateway Crashed from an Invalid Config Key

An unsupported config key (gateway.tokenServer) was written during a pairing experiment. The gateway refused to start, SSH tunnels showed "Connection refused," and it looked like a network problem. Lesson: Always run openclaw config validate after any config change. If the gateway won't start, check the logs first — it's probably a config issue, not a network issue.

2. Browser "Works" but Agent Can't Use It

The browser service can be healthy while the AI agent still doesn't have browser tools available. These are different layers. The backend browser being up doesn't mean the agent's tool policy includes browser actions. Fix: Set tools.profile = full and start a fresh session after restarting the gateway.

3. Credential Storage Matters

Never paste API keys directly into OpenClaw's config JSON. Use environment variable references (env:SECRET_NAME) and store the actual values in your systemd service override file with 0600 permissions. This keeps secrets out of config files that might be backed up or shared.

4. "Error Changed" Doesn't Mean "Error Fixed"

During debugging, a CLI patch changed an error from "pairing required" to "missing scope: operator.write." It looked like progress, but it was actually worse — the auth path had been bypassed entirely. Lesson: A different error message doesn't mean you're closer to a fix. Understand why the error changed before celebrating.

5. Headless VPS Browser Config Is Non-Negotiable

On a server without a display, you must set browser.headless = true and browser.noSandbox = true. This isn't optional. Installing Brave and Playwright isn't enough — the browser launch itself will fail without these settings.

Security Hardening Checklist

Running an AI agent with tool access on a VPS demands serious security. Here's what we implemented:

• UFW firewall — deny all inbound except SSH (and HTTPS if needed)
• fail2ban — automatic IP banning after failed SSH attempts
• Gateway on loopback only — never expose port 18789 to the internet
• SSH tunnel for dashboard access — no public web exposure
• Token-based gateway auth — rotate tokens after setup
• ClamAV + rkhunter — daily malware and rootkit scanning
• Real-time file scanner — inotifywait monitors key directories
• Unattended security upgrades — automatic OS patching
• OCI Security List IP restriction — SSH only from known IPs
• Credential isolation — API keys in systemd env vars, not config files

The Final Stack

After all the setup and troubleshooting, here's what our production OpenClaw deployment looks like:

• Server: Oracle Cloud ARM64, Ubuntu 24.04, 4 OCPU, 24 GB RAM
• AI Model: Fireworks AI (Kimi K2.5 router) via OpenAI-compatible API
• Channels: Telegram bot, Web UI (via SSH tunnel)
• Email: Gmail incoming (via Pub/Sub + Tailscale Funnel), AWS SES outgoing (via himalaya)
• Search: Brave Search API
• Browser: Brave Browser + Playwright (headless)
• Extraction: Firecrawl plugin for web scraping
• Dashboard: Custom Python FastAPI app behind Cloudflare + Nginx
• Security: UFW, fail2ban, ClamAV, rkhunter, Lynis audits, real-time file scanning

The whole thing runs 24/7, auto-starts on reboot, and costs nothing beyond the AI provider API fees.

Is It Worth It?

Absolutely — if you want control over your AI assistant. OpenClaw isn't for everyone. If you just want to chat with ChatGPT, use ChatGPT. But if you want an AI that can read your emails, search the web, automate browser tasks, respond on Telegram, run scheduled jobs, and do it all on your hardware with your data — OpenClaw is the best tool for the job in 2026.

The setup takes a few hours (or a day if you hit the browser automation gotchas). But once it's running, you have something no hosted service can offer: a fully customizable, private AI assistant that you control completely.

Resources

• OpenClaw on GitHub (68K+ stars, MIT license)
• Official Documentation
• Quick Install Script