Guide to installing OpenClaw AI on VPS

Deploying OpenClaw AI Agent on VPS: Step-by-Step Guide with Scripts

OpenClaw is an open-source AI agent for managing your VPS via Telegram. Full stack: docker-compose, bash tool scripts, context configs. Clone the repo, set up .env with API keys, run deploy.sh — system ready in 10 minutes. The agent monitors containers, runs SQL queries, restarts services, and checks heartbeats.

System Architecture

OpenClaw runs in a Docker container ghcr.io/openclaw/openclaw with mounts for /var/run/docker.sock, /var/www/projects, and /var/log/nginx. Context from workspace/SOUL.md defines behavior: PostgreSQL container list, projects table, security rules.

Scripts in /tools/ are triggered by requests:

• docker-status.sh, docker-logs.sh, docker-restart.sh
• db-discover.sh, db-query.sh for PostgreSQL
• health-check.sh for HTTP site monitoring
• system-stats.sh, security-check.sh

The agent handles natural language: “auth service logs” → docker-logs.sh auth-container.

Minimum Requirements

• Ubuntu 20.04+ or Linux with Docker Compose V2 (docker compose version)
• 2 GB RAM (agent ~300–500 MB)
• OpenRouter API key (openrouter.ai/keys) for GPT-4o, Claude models
• Telegram bot token from @BotFather

Step 1: Repo Setup

ssh user@your-server
git clone https://github.com/ShyDamn/openclaw-devops-kit.git /tmp/openclaw-setup
cd /tmp/openclaw-setup

Structure:

openclaw-devops-kit/
├── docker-compose.yml
├── .env.example
├── deploy.sh
├── config/openclaw.json
├── workspace/SOUL.md, USER.md, HEARTBEAT.md
└── tools/ (14 scripts: docker-*.sh, db-*.sh, health-check.sh, etc.)

Step 2: Telegram Bot and .env

• @BotFather → /newbot → token 123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11
• @userinfobot → your ID 778921250

cp .env.example .env
nano .env

TELEGRAM_BOT_TOKEN=123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11
OPENROUTER_API_KEY=sk-or-v1-xxxxxxxxxxxxxxxxxxxxxxxx
YOUTRACK_TOKEN=perm:your-token-here  # optional

In config/openclaw.json:

"allowFrom": [
  "tg:778921250"
]

Step 3: Context Setup in workspace/

SOUL.md — Core Behavior

List your PostgreSQL containers and projects:

## PostgreSQL Containers: db1, db2, db3

| Path | Project | Stack |
|------|---------|-------|
| /projects/my-app/ | SaaS | Next.js + PostgreSQL |
| /projects/api/ | Backend | NestJS |

Rules: read without confirmation, edits with double-check.

USER.md — Your Profile

Time zone, tech stack, key projects.

HEARTBEAT.md — Hourly Checklist

Resource monitoring, container status, HTTP sites.

Step 4: Site Monitoring

In tools/health-check.sh:

SITES=(
  "mysite.com|mysite-frontend|mysite"
  "api.mysite.com|mysite-api|mysite"
)

Format: domain|container|project. On 5xx/timeout — auto-restart, notify on failure.

Step 5: Deploy and Launch

bash deploy.sh

Automation:

• Check Docker Compose V2
• Create /var/www/openclaw/
• Set .env permissions (chmod 600)
• Pull image
• Start container

Telegram pairing:

cd /var/www/openclaw
docker compose run --rm --profile cli openclaw-cli pairing approve telegram <CODE>

Key Scripts Breakdown

docker-logs.sh

#!/bin/bash
CONTAINER="${1:?Usage: docker-logs.sh <container_name> [lines]}"
LINES="${2:-50}"
docker logs --tail "$LINES" "$CONTAINER" 2>&1

Auto-detects container from SOUL.md.

system-stats.sh

#!/bin/bash
echo "=== RAM ==="
free -h
echo ""
echo "=== DISK ==="
df -h / | tail -1
# ... CPU, docker stats

Comprehensive output for heartbeat.

db-discover.sh — Database Discovery

#!/bin/bash
for c in $(docker ps --format '{{.Names}}' | grep -i postgres); do
  echo "=== $c ==="
  DB_USER=$(docker exec "$c" printenv POSTGRES_USER 2>/dev/null)
  # ...
  docker exec "$c" psql -U "$DB_USER" -d "$DB_NAME" -c "\dt"
done

Auto-finds all PostgreSQL instances, pulls POSTGRES_USER/POSTGRES_DB, lists tables.

db-query.sh

Executes SQL with container params.

Key Takeaways

• SOUL.md context is critical: Without projects/containers table, agent asks for details.
• Whitelist in openclaw.json: Telegram ID-only access, no leaks.
• Health-check.sh with auto-restart: 5xx → restart → verify → notify.
• MIT license: Full control over scripts/configs.
• OpenRouter: Model rotation (GPT-4o, Claude) on failures, single API.

— Editorial Team