Installing OpenClaw on a VPS

Overview

• System used: Debian 12 64-bit
• User account: I am performing all actions as ‘root’
• Duration: approx. 20 minutes
• Difficulty: Easy. Just copy the code 😉
• Special features:
• This guide is based on the following instructions: Installing Traefik reverse proxy on a VPS
  These instructions must be followed first.
• Installation of Docker / Docker Compose is required here.
• You will need an API key for an AI system, as OpenClaw is entirely dependent on the AI

1. Installing OpenClaw

1.1 Introduction

OpenClaw is a relatively new open-source project that has attracted a great deal of attention since its release. Broadly speaking, it allows you to run an AI agent that chats with you via integrations and performs tasks using connected AI models (e.g. generating text, triggering simple workflows).

Important: OpenClaw is entirely dependent on an AI model. Without an AI backend, it does not ‘think’ for itself, and as every response is generated via an external AI, every request incurs usage-based costs with the respective AI provider.

In our specific setup, the aim is to deploy OpenClaw via Traefik. We are using Google Gemini as our AI provider and also want to integrate Telegram so that we can interact with OpenClaw conveniently via Telegram chat.

1.2 Information on YML files

With YML files, it is very important that all lines are correctly indented. Lines MUST always be indented using the space bar. They must NOT contain any tabs. You can always have the following code ‘checked’ online. Most errors are caused by incorrect formatting. One service for checking is, for example: https://codebeautify.org/yaml-validator

1.3 Preparation

These instructions are based on the current Debian 12 operating system. We will set up OpenClaw using Docker. This will allow us to perform very quick updates and a rapid installation later on.

To run OpenClaw alongside other services on our server, we’ll be using the Traefik reverse proxy. You can find the guide for this here:  Installing Traefik reverse proxy on a VPS

1.3.1 Create a directory

We will create a new directory in which we will later store all OpenClaw data. To do this, enter the following in the console:

mkdir -p /opt/containers/openclaw

You can also use a different directory here. However, you will then need to adapt the entire guide accordingly.

1.3.2 Create docker-compose.yml

Now we can begin the actual “installation” of OpenClaw. To do this, open the following file:

nano /opt/containers/openclaw/docker-compose.yml

Now copy the following code into the file. This code is our blueprint for our OpenClaw container.

services:
 openclaw-gateway:
   image: ${OPENCLAW_IMAGE}
   environment:
     HOME: /home/node
     TERM: xterm-256color
     OPENCLAW_GATEWAY_TOKEN: ${OPENCLAW_GATEWAY_TOKEN}
   volumes:
     - ./config:/home/node/.openclaw
     - ./workspace:/home/node/.openclaw/workspace
   env_file:
     - .env
   init: true
   restart: unless-stopped
   command:
     [
       "node",
       "dist/index.js",
       "gateway",
       "--allow-unconfigured",
       "--bind",
       "${OPENCLAW_GATEWAY_BIND:-0.0.0.0}",
       "--port",
       "18789",
     ]
   healthcheck:
     test:
       [
         "CMD",
         "node",
         "-e",
         "fetch('http://127.0.0.1:18789/healthz').then((r)=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))",
       ]
     interval: 30s
     timeout: 5s
     retries: 5
     start_period: 20s
   labels:
     - "traefik.enable=true"
     - "traefik.http.routers.openclaw.entrypoints=http"
     - "traefik.http.routers.openclaw.rule=Host(`openclaw.euredomain.de`)"
     - "traefik.http.middlewares.openclaw-https-redirect.redirectscheme.scheme=https"
     - "traefik.http.routers.openclaw.middlewares=openclaw-https-redirect"
     - "traefik.http.routers.openclaw-secure.entrypoints=https"
     - "traefik.http.routers.openclaw-secure.rule=Host(`openclaw.euredomain.de`)"
     - "traefik.http.routers.openclaw-secure.tls=true"
     - "traefik.http.routers.openclaw-secure.tls.certresolver=http"
     - "traefik.http.routers.openclaw-secure.service=openclaw"
     - "traefik.http.services.openclaw.loadbalancer.server.port=18789"
     - "traefik.docker.network=proxy"
     - "traefik.http.routers.openclaw-secure.middlewares=secHeaders@file,openclaw-auth"
     - "traefik.http.middlewares.openclaw-auth.basicauth.users="
   networks:
     - proxy

 openclaw-cli:
   image: ${OPENCLAW_IMAGE}
   env_file:
     - .env
   network_mode: "service:openclaw-gateway"
   cap_drop:
     - NET_RAW
     - NET_ADMIN
   security_opt:
     - no-new-privileges:true
   environment:
     HOME: /home/node
     TERM: xterm-256color
     OPENCLAW_GATEWAY_TOKEN: ${OPENCLAW_GATEWAY_TOKEN:-}
     BROWSER: echo
   volumes:
     - ./config:/home/node/.openclaw
     - ./workspace:/home/node/.openclaw/workspace
   stdin_open: true
   tty: true
   init: true
   entrypoint: ["node", "dist/index.js"]
   depends_on:
     - openclaw-gateway

networks:
 proxy:
   external: true 

1.3.3 Creating an env file

Now let’s create a file containing our settings. To do this, enter the following:

nano /opt/containers/openclaw/.env 

Inhalt:

# ----------------------------------------------------------------------------- 
# Gateway auth + Image 
# ----------------------------------------------------------------------------- 
OPENCLAW_GATEWAY_TOKEN=change-me-to-a-long-random-token 
OPENCLAW_IMAGE=ghcr.io/openclaw/openclaw:latest 
OPENCLAW_CONFIG_DIR=./config 
OPENCLAW_WORKSPACE_DIR=./workspace 

You can customise the OPENCLAW_IMAGE parameter as you wish. However, in this case we are using the official OpenClaw image.

1.3.4 First configuration script

To save a bit of work, we’ll create a script that assigns our domain, username and password, ensuring that OpenClaw is accessible and secure.

 nano /opt/containers/openclaw/setup.sh 

Content:

#!/bin/bash 
 
if ! command -v htpasswd &> /dev/null; then 
    echo "htpasswd is not installed. Install apache2-utils..." 
    sudo apt-get update && sudo apt-get install -y apache2-utils 
fi 
 
read -p "Please enter your desired domain (e.g. openclaw.mydomain.co.uk): " USER_DOMAIN 
 
sed -i "s/Host(\`openclaw.yourdomain.co.uk\`)/Host(\`$USER_DOMAIN\`)/g" docker-compose.yml 
echo "The domain has been updated to $USER_DOMAIN in docker-compose.yml." 
 
NEW_TOKEN=$(openssl rand -hex 32) 
sed -i "s/^OPENCLAW_GATEWAY_TOKEN=change-me-to-a-long-random-token/OPENCLAW_GATEWAY_TOKEN=$NEW_TOKEN/g" .env 
echo "A secure gateway token has been generated and stored in the .env file." 
 
echo "---" 
echo "Setting up the OpenClaw login" 
read -p "Please enter a username for the dashboard: " AUTH_USER 
read -s -p "Please enter a secure password: " AUTH_PASS 
echo "" 
 
AUTH_STRING=$(htpasswd -nb "$AUTH_USER" "$AUTH_PASS" | sed -e s/\\$/\\$\\$/g) 
 
sed -i "s|^      - \"traefik.http.middlewares.openclaw-auth.basicauth.users=\".*|      - \"traefik.http.middlewares.openclaw-auth.basicauth.users=$AUTH_STRING\"|g" docker-compose.yml 
 
echo "Basic Auth credentials have been successfully stored in docker-compose.yml." 
echo "Setup complete!" 

Now let’s make the script executable and run it:

chmod +x /opt/containers/openclaw/setup.sh 
cd /opt/containers/openclaw/ 
./setup.sh 

1.3.5 Download the official setup script

Now let’s download the official OpenClaw configuration script.

cd /opt/containers/openclaw 
wget -O docker-setup.sh https://raw.githubusercontent.com/openclaw/openclaw/main/docker-setup.sh 
chmod +x docker-setup.sh 

2. Generate an AI API key

OpenClaw offers a wide range of supported AI systems. Here is an overview:

Later on, you’ll need to enter an API key for an AI system in order to use OpenClaw. In this example, we’re using Google Gemini. To do this, go to the following URL: https://aistudio.google.com/

Register there and you will then be able to view your API key. You will also see the costs you will incur for requests to Gemini.

3. Add a communication gateway (optional)

OpenClaw offers a wide range of gateways through which it can communicate.

Essentially, OpenClaw provides a website, so you don’t need any additional gateway. In this example, we’re using Telegram, as it’s free and very easy to set up.

First, create a Telegram account or log in to your existing account.

Then search for the following contact: “@BotFather”.

It’s important to make sure you use the service with the ‘blue tick’, as there are many fake services out there.

Type “/start” to see an overview of all parameters.

Select “/newbot” here and give your bot a name. You can search for the bot using this name later. It is important that the name ends with “bot”.

If everything was correct, you should receive a confirmation message containing an HTTP API token. We will need this later for OpenClaw.

4. Start the OpenClaw setup

Important note:
OpenClaw takes a long time to load at several points. It is important that you simply wait a few minutes here until the dialogue continues. In this guide, the images always show you which dialogues or outputs you need to wait for before you can continue.

Now let’s start setting up OpenClaw. To do this, we need the API keys created earlier.

cd /opt/containers/openclaw 
set -a && source .env && set +a && ./docker-setup.sh 

In the first step, select “yes”:

Here, we select ‘Manual’ so that we can configure all the settings:

You can simply confirm the Workspace Directory:

Now you can choose your AI system. In our case, it’s Google.

Here, we select ‘Google Gemini API key’:

Now we select the option to paste the API key directly (“Paste API key now”):

Now we can choose our model. This affects both the price and the quality of the responses. Gemini 3.1 Pro is currently the most powerful of Google’s AI models.

You can easily check the gateway port:

Now select “LAN (0.0.0.0)” to ensure that communication with Traefik works later:

Communication is to be secured using tokens. We have already had these set up.

We do not choose Tailscale:

Now let’s select ‘Generate/store plaintext token’:

Confirm the preselected token by pressing ENTER.

Here you can now choose whether you want to use a channel/gateway, or whether you simply want to use OpenClaw via the website. We select “Yes” so that we can integrate Telegram.

We’re choosing Telegram because we want to link it to that.

It will now take a few minutes before you are prompted to enter your Telegram API credentials:

Now let’s select ‘Finished’, as we don’t want to connect any further services:

During pairing, we select ‘no’, as this mode suits us.

Now let’s select a search provider. We’ll go with Google, as we already have an API key for it:

You can now select the various skills you want to install for OpenClaw:

We’ll skip this step by clicking ‘Skip for now’.

You can now enter additional API keys. However, we’ll skip this step.

You can now define hooks. We’ll skip this as well:

Finally, we’ll install the zsh shell:

OpenClaw is now set up and is running the configuration. This will take several minutes. Please wait until you see the following:

5. OpenClaw customisations for Traefik

Now we run another script that makes adjustments to OpenClaw for Traefik:

nano /opt/containers/openclaw/setup2.sh 

Content:

#!/bin/bash 
set -e 
 
echo "Reading configuration..." 
 
if ! TOKEN=$(grep "^OPENCLAW_GATEWAY_TOKEN=" .env | cut -d '=' -f 2); then 
    echo "Error: OPENCLAW_GATEWAY_TOKEN not found in .env." 
    exit 1 
fi 
 
if ! DOMAIN=$(grep -oP 'Host\(`\K[^`]+' docker-compose.yml | head -1); then 
    echo "Error: Could not find a domain (host) in docker-compose.yml." 
    exit 1 
fi 
 
echo "Token found: $TOKEN" 
echo "Domain found: $DOMAIN" 
echo "---" 
 
echo "Disabling Device Auth..." 
docker compose run --rm openclaw-cli config set gateway.controlUi.dangerouslyDisableDeviceAuth true 
 
echo "Allowing domain in Control UI..." 
docker compose run --rm openclaw-cli config set gateway.controlUi.allowedOrigins "[\"https://$DOMAIN\"]" --strict-json 
 
echo "---" 
# 5. Restart the container so that the configuration takes effect 
echo "Restarting container..." 
docker compose down 
docker compose up -d 
 
echo "---" 
echo "✅ Setup completed successfully!" 
echo "" 
echo "The dashboard will be available in a few minutes at the following URL:" 
echo "https://$DOMAIN/#token=$TOKEN" 
echo "" 

We will now run this script:

chmod +x /opt/containers/openclaw/setup2.sh 
cd /opt/containers/openclaw/ 
./setup2.sh 

The script will take several minutes to run. Please wait until you see the following:

6. Launch OpenClaw

Now copy the link displayed and paste it into your browser. Again, it will take several minutes for OpenClaw to finish starting up.

You should then see this message:

Enter the username and password from step 1.3.4 here.

You are now on the OpenClaw interface, where you can configure further settings or execute commands.

7. Connect Telegram to OpenClaw

Now find the Telegram bot you created in step 3.

When you enter the command "/start", you should see the following:

Now copy this pairing code. Then run the following command on your server:

docker compose run --rm openclaw-cli pairing approve telegram PAIRING-CODE 

In my case, that would be:

docker compose run --rm openclaw-cli pairing approve telegram T4VAY9AN 

Once the command has been successfully processed on your server, enter “/status” in Telegram. You should now see the following:

8. OpenClaw versions

New Docker images for OpenClaw are currently released every few days, which is why some menus may look different. Users have also reported in forums that on some days an image may contain an error, which may then be fixed in the next image released a few days later.

9. Running OpenClaw commands

You can now do this via Telegram:

How to run commands via the website:

In the settings, you can also see how many requests OpenClaw has already sent and the approximate costs incurred. However, to be on the safe side, you should always check this on the AI provider’s platform as well.