Deploy OpenClaw on VPS: Complete Setup Guide

Dev.to by GeraldM April 4, 2026

What You'll Learn

This tutorial covers deploying OpenClaw, a self-hosted AI gateway connecting messaging apps to coding agents, on a remote VPS with security hardening. You'll configure a Telegram bot interface, secure SSH access via Tailscale VPN, integrate an AI model provider, and access the OpenClaw dashboard from your local machine.

Prerequisites

Before starting, verify you have the following:

A Virtual Private Server (VPS) or virtual machine with public IP access
Node.js 22.16 or later installed on the server
Git installed on the server
SSH client on your local machine (Git Bash, PowerShell, MobaXterm, or native terminal)
A Telegram account
An API key from an AI model provider (OpenRouter, OpenAI, or equivalent)
Administrator/sudo access on the VPS
Tailscale account for VPN networking (free tier sufficient)

Why This Matters

OpenClaw bridges a critical gap in the AI development ecosystem: enabling developers to interact with coding agents through existing communication platforms. Rather than building custom integrations for each messaging app, OpenClaw abstracts this layer, allowing you to deploy agentic workflows through Telegram, Discord, or WhatsApp. The VPS-based deployment pattern described here reflects production best practices—isolating potentially unsafe code execution in a sandboxed environment separate from your development machine.

Step 1: Provision Your Virtual Private Server

Choose a cloud provider offering Linux VPS instances (Azure, AWS, DigitalOcean, Linode, or Hetzner). Provision a server with at least 2GB RAM and 20GB storage. Ubuntu 22.04 LTS is recommended for compatibility. Note the server's public IP address and SSH credentials—you'll need these immediately.

Why VPS over local: OpenClaw executes arbitrary code via AI agents. Confining this to a remote, isolated machine prevents compromise of your personal files, credentials, and local network.

Step 2: Establish SSH Access and Initial Security Hardening

From your local terminal, connect to the VPS using SSH:

ssh username@your-vps-ip-address

When prompted, enter your server password. Verify Node.js and Git are installed:

node --version
git --version

If missing, install them using your system package manager (e.g., apt update && apt install nodejs git on Ubuntu).

Why this step matters: Direct SSH exposure to the public internet creates attack surface. You'll harden this next with Tailscale, but baseline connectivity must work first.

Step 3: Secure Your Server with Tailscale VPN

Tailscale creates a zero-trust private network, restricting SSH and OpenClaw access to authenticated devices only. This replaces firewall rules with cryptographic verification.

Install Tailscale on Your VPS

While still SSH'd into your server, run the official Tailscale installation:

curl -fsSL https://tailscale.com/install.sh | sh

Start the Tailscale service:

sudo tailscale up

You'll receive a URL. Open it in your browser, authenticate with your chosen identity provider (Google, GitHub, Microsoft), and authorize the VPS. Tailscale assigns your server a private IP (e.g., 100.x.x.x). Note this address.

Restrict SSH to Tailscale Only

Edit the SSH configuration file:

sudo nano /etc/ssh/sshd_config

Find the line ListenAddress 0.0.0.0 and replace it with your Tailscale IP:

ListenAddress 100.x.x.x

Save (Ctrl+O, Enter, Ctrl+X). Restart SSH:

sudo systemctl restart ssh

Create a dedicated non-root user for OpenClaw (improves security isolation):

sudo useradd -m -s /bin/bash openclaw-user
sudo usermod -aG sudo openclaw-user

Result: SSH now only accepts connections from the Tailscale network. Your VPS is invisible to the public internet.

Install Tailscale on Your Local Machine

Download Tailscale from tailscale.com for your OS (Windows, macOS, Linux). Install and launch it. Authenticate with the same account you used for the VPS. Your local machine joins the same private network.

Verify connectivity by SSH'ing to the Tailscale IP (no more direct IP needed):

ssh openclaw-user@100.x.x.x

Step 4: Install OpenClaw

SSH into your VPS as the OpenClaw user. Run the official installer:

bash -c "$(curl -fsSL https://raw.githubusercontent.com/OpenClawOrg/openclaw/main/install.sh)"

The interactive setup wizard will ask a series of configuration questions. Here's what to choose:

Gateway Configuration

Workspace Directory: Accept the default (typically ~/.openclaw)
Gateway Port: Keep default (18789)
Gateway Bind Address: Keep default (127.0.0.1 for local-only access)
Gateway Auth: Select "token" for API key protection
Tailscale Exposure: Leave "off" (you'll tunnel via SSH instead)
Generate Token: Select "generate/store plaintext token" and leave blank to auto-generate

Select an AI Model Provider

OpenClaw supports multiple providers: OpenAI, Claude (Anthropic), Gemini, and OpenRouter (which offers free open-source models). For cost-effective setup, choose OpenRouter:

Visit openrouter.ai and create an account
Copy your API key from settings
In the OpenClaw installer, paste this key when prompted
Select a model (e.g., StepFun 3.5 Flash, Mistral 7B, or LLaMA 2) from the scrollable list

Cost note: OpenRouter's free tier supports limited requests. For production, consider paid API keys or self-hosted models like Ollama.

Step 5: Configure Telegram Bot Integration

OpenClaw can interface with multiple messaging platforms. Telegram is recommended for ease of setup.

Create a Telegram Bot Token

Open Telegram and search for "BotFather" (the official Telegram bot management account)
Start a chat and type /newbot
Choose a display name (e.g., "MyOpenClawBot")
Choose a username ending in "bot" (e.g., "myopenclaw_bot")
BotFather returns an API token (e.g., 123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11)

Connect Bot to OpenClaw

During the OpenClaw installer, when prompted for "Channel status," select "Yes" and choose "Telegram." Paste your bot token. When asked to select a channel, scroll to "finished" (the last option).

For DM access policies, select "Yes" to allow direct messages. The installer will approve the pairing.

Activate the Bot

BotFather provides a Telegram link to your new bot. Click it to open a chat. Type /start. Your OpenClaw agent will respond with a pairing code.

Back in your VPS terminal, run:

~/.openclaw/bin/openclaw pairing approve telegram

If "command not found" appears, navigate to the OpenClaw bin directory first:

cd ~/.openclaw/bin
./openclaw pairing approve telegram

Result: You can now chat with your AI agent directly via Telegram.

Step 6: Configure Web Dashboard Access

OpenClaw includes a web UI for configuration and monitoring. Since the gateway binds to localhost (127.0.0.1), you'll tunnel it through SSH.

Create an SSH Tunnel from Your Local Machine

From your local terminal (not SSH'd into the VPS), run:

ssh -N -L 18789:127.0.0.1:18789 openclaw-user@100.x.x.x

This command:

-N: No remote commands (tunnel only)
-L 18789:127.0.0.1:18789: Maps local port 18789 to the VPS's port 18789
openclaw-user@100.x.x.x: Connects via Tailscale IP

Leave this terminal open while using the dashboard.

Access the Dashboard

On your local machine, open a browser and navigate to http://localhost:18789. You'll see a Tailscale authentication prompt. Log in using your Tailscale account credentials. This cryptographically verifies your device before granting access.

If this fails, you may need to retrieve the dashboard token. SSH into the VPS and run:

~/.openclaw/bin/openclaw dashboard --no-open

This outputs a full URL with an embedded authentication token. Copy this URL into your browser.

Step 7: Define Your Agent's Personality

OpenClaw stores agent configuration in three markdown files in your workspace:

BOOTSTRAP.md

Defines the agent's core identity (name, role, initial system prompt). Edit via the web dashboard or SSH into the VPS and edit directly:

nano ~/.openclaw/BOOTSTRAP.md

Example:

# Agent: CodeAssistant
You are an expert software developer with 10 years of experience in Python and TypeScript.

USER.md

Tells the agent about you (name, role, preferences, constraints). Example:

# User Profile
Name: Alex
Role: Software Engineer
Preferences: Concise, technical explanations
Constraints: Do not suggest using paid services without justification

SOUL.md

Adds personality and behavioral traits:

# Personality
Tone: Friendly but professional
Communication style: Clear and structured
Quirks: Use relevant emoji occasionally

Edit these files via the web dashboard under "Configuration" or directly on the VPS. Changes take effect on the agent's next message.

Step 8: Add Skills (Optional but Recommended)

Skills are plugins that grant agents capabilities beyond conversation. OpenClaw ships with default skills (web search, file operations). To add custom skills:

In the web dashboard, navigate to "Skills"
Select "Add Skill" and choose from templates (web search, code execution, API calls)
Configure the skill's parameters (e.g., search engine API key, execution sandbox)
Test the skill by prompting the agent to use it

Example: If you add a "GitHub" skill, the agent can query repositories, create issues, and post comments on your behalf.

Troubleshooting

SSH Hangs or Times Out

Symptom: ssh openclaw-user@100.x.x.x never connects or takes 30+ seconds. Cause: Tailscale not running on VPS or local machine. Fix: Verify Tailscale status on both machines: sudo tailscale status. Both should show "Connected." Restart if needed: sudo tailscale down && sudo tailscale up.

"Command not found: openclaw"

Symptom: Running openclaw returns command not found. Cause: OpenClaw binary not in PATH. Fix: Navigate to the binary directly: cd ~/.openclaw/bin && ./openclaw [command]. Or add to PATH: echo 'export PATH="$PATH:$HOME/.openclaw/bin"' >> ~/.bashrc && source ~/.bashrc.

Telegram Bot Doesn't Respond

Symptom: Messages sent to the bot don't get a response. Cause: Pairing incomplete or OpenClaw gateway not running. Fix: Verify the gateway is active: ps aux | grep openclaw. Check pairing status in the web dashboard ("Channels" section). Re-approve if needed: ~/.openclaw/bin/openclaw pairing approve telegram.

Web Dashboard Returns "Unauthorized"

Symptom: Accessing localhost:18789 shows an auth error after Tailscale login. Cause: Token mismatch or corrupted session. Fix: Clear browser cookies and retry. If persistent, regenerate the dashboard token: ~/.openclaw/bin/openclaw dashboard --reset-auth.

AI Model Returns Errors or Quota Exceeded

Symptom: Agent messages fail with "Rate limit exceeded" or "Invalid API key." Cause: API key expired, quota consumed, or incorrect model selected. Fix: Check your model provider's dashboard (OpenRouter, OpenAI, etc.). Verify remaining credits. Update the API key in ~/.openclaw/config.json via the web dashboard (Settings > AI Provider).

Best Practices

Security

Rotate Telegram Bot Token Periodically: In BotFather, use /revoke to invalidate old tokens and /newbot to create fresh ones. Update OpenClaw immediately.
Use Strong SSH Keys: Replace password authentication with public key authentication. SSH into your VPS and disable passwords: Edit /etc/ssh/sshd_config, set PasswordAuthentication no, restart SSH.
Monitor OpenClaw Logs: Check ~/.openclaw/logs/ regularly for errors or unusual activity. Log execution requests and API calls.
Isolate the VPS Network: Avoid exposing OpenClaw's port (18789) directly. Always use SSH tunneling or Tailscale. Never open port 18789 in firewall rules.

Performance & Cost

Choose Efficient Models: StepFun 3.5 Flash, Mistral 7B, and LLaMA 2 offer good speed/accuracy balance at low cost on OpenRouter. Avoid large models (70B+) for simple tasks.
Set API Rate Limits: Configure OpenRouter to limit requests/hour to avoid runaway costs. Test skills thoroughly before production.
Monitor VPS Resource Usage: OpenClaw plus a language model can consume 1-2GB RAM. Use free -h and top to track memory. Upgrade VPS if consistently above 80% utilization.

Operational

Version Control Agent Config: Commit BOOTSTRAP.md, USER.md, and SOUL.md to a private Git repo. This enables rollback and audit trails.
Set Up Systemd Service: During installation, enable systemd lingering so OpenClaw restarts automatically after VPS reboots. Verify: sudo systemctl status openclaw-gateway.
Document Your Setup: Keep a README noting your model choice, skills enabled, and critical API keys (encrypted). Future troubleshooting becomes faster.
Test Skills in Isolation: Before enabling a skill for production use, test it with dummy data in the web dashboard's "Playground" feature.

Next Steps

With OpenClaw running and accessible, consider these extensions:

Add More Channels: Integrate Discord or WhatsApp alongside Telegram. Repeat Step 5 for each platform. The same agent instance can manage multiple channels.
Deploy Custom Skills: Write JavaScript/Python functions that the agent can invoke. Examples: fetch data from APIs, trigger webhooks, control IoT devices. Reference OpenClaw's skill SDK in the official documentation.
Set Up Alerts & Monitoring: Configure OpenClaw to send you Slack or email notifications when specific events occur (e.g., task completion, errors). Integrate openclaw-events webhooks with Zapier or n8n.
Scale to Multiple Agents: Deploy separate OpenClaw instances for different use cases (coding, content generation, DevOps). Use Tailscale for inter-agent networking.
Evaluate Self-Hosted Models: Consider running Ollama on your VPS to eliminate API costs and latency. OpenClaw supports local inference through the Ollama provider.

Summary

You've successfully deployed OpenClaw on a secure, isolated VPS—connecting your AI agent to Telegram, configuring an open-source model via OpenRouter, and accessing both a CLI and web interface. The layered security approach (Tailscale VPN + SSH key auth + firewall restrictions) ensures your agent executes safely without exposing your personal infrastructure.

OpenClaw's strength lies in its abstraction of messaging platforms, freeing you from building custom integrations. By investing time in agent personality (BOOTSTRAP.md, USER.md, SOUL.md) and skills, you unlock automation patterns far beyond simple chatbots—from code review assistants to DevOps orchestrators.

The foundation is now in place. Your next focus should be defining and testing skills tailored to your workflow. Start small: enable one skill, validate its output, then iterate. Each skill you add multiplies the agent's utility while increasing the risk surface, so test rigorously in staging before production use.

Read original