How to install OpenClaw on a VPS with Docker

OpenClaw needs a persistent, always-on environment to stay connected to your messaging platforms and AI provider. Running it inside a Docker container on a VPS gives you isolated storage, automatic restarts on failure and a repeatable setup you can rebuild at any time.

This guide walks you through creating the directory structure, writing the environment and Compose files, completing first-run onboarding and keeping OpenClaw up to date. It also covers building from source if an official image is not available for your architecture.

Create the project directory

Keeping all OpenClaw files in a single directory makes backups, upgrades and troubleshooting easier. Create the directory and move into it before writing any configuration files.

1. Create and enter the project directory.
   Run the following to create the directory and navigate into it:

mkdir -p /opt/openclaw
cd /opt/openclaw

Configure environment variables

OpenClaw reads all sensitive credentials from a .env file rather than baking them into the Compose configuration. Create this file first and restrict its permissions so only root can read it.

1. Create the environment file.
   Open a new file at /opt/openclaw/.env in your editor:

nano /opt/openclaw/.env

2. Add your credentials.
   Paste the template below, uncomment the lines that match your AI provider and messaging platform, and replace the placeholder values with your actual credentials. Comment out any lines you are not using by adding a # at the start.

# AI Provider - uncomment one
ANTHROPIC_API_KEY=your_anthropic_api_key
# OPENAI_API_KEY=your_openai_api_key

# Messaging platform - uncomment whichever you are using
TELEGRAM_BOT_TOKEN=your_telegram_bot_token
# DISCORD_BOT_TOKEN=your_discord_bot_token
# SLACK_BOT_TOKEN=your_slack_bot_token

# Timezone
TZ=Europe/London

3. Restrict file permissions.
   This prevents other users on the system from reading your API keys:

chmod 600 /opt/openclaw/.env

Write the Docker Compose file

The Compose file defines the container, tells Docker where to find your credentials and mounts a named volume so OpenClaw’s memory, skills and configuration survive container restarts and upgrades.

1. Create the Compose file.
   Open a new file at /opt/openclaw/docker-compose.yml:

nano /opt/openclaw/docker-compose.yml

2. Paste the service definition.
   The restart: unless-stopped policy means Docker restarts the container automatically after a crash or a VPS reboot, unless you explicitly stop it yourself.

services:
  openclaw:
    image: ghcr.io/openclaw/openclaw:latest
    container_name: openclaw
    restart: unless-stopped
    env_file:
      - .env
    volumes:
      - openclaw_data:/home/node/.openclaw
    environment:
      - NODE_ENV=production

volumes:
  openclaw_data:
    driver: local

OpenClaw is an actively developed project. Check the OpenClaw GitHub repository for the current recommended image tag before deploying. If an official image is not available for your architecture, see the Building from source section below.

Start OpenClaw and complete onboarding

The first time OpenClaw runs, it requires an interactive onboarding step to configure your persona and connect your integrations. Start the container, then run onboarding inside it before leaving it to run in the background.

1. Start the container.
   From /opt/openclaw, bring the service up in detached mode:

cd /opt/openclaw
docker compose up -d

2. Run the onboarding wizard.
   Execute the onboarding command inside the running container. Follow the prompts to connect your AI provider and messaging platforms. Your choices are saved to the persistent volume, so you will not need to repeat this step after upgrades.

docker compose exec openclaw openclaw onboard

3. Restart the container.
   After onboarding completes, restart the container to begin normal operation:

docker compose restart openclaw

4. Check the logs.
   Tail the container logs to confirm OpenClaw is running and connecting to your messaging platforms. Press Ctrl+C to stop following:

docker compose logs -f openclaw

OpenClaw is now running as a persistent background service. The named volume protects your data across restarts.

Building from source

If an official image is not available for your architecture or the current version, you can build the image directly from the GitHub repository. This replaces the image: line in your Compose file with a local build.

1. Clone the repository.
   Download the source into a src subdirectory inside your project folder:

cd /opt/openclaw
git clone https://github.com/openclaw/openclaw.git src

2. Create a Dockerfile.
   Create the following file at /opt/openclaw/Dockerfile. It installs production dependencies and starts the compiled entry point:

FROM node:20-alpine
WORKDIR /app
COPY src/ .
RUN npm install --production --no-fund --no-audit
RUN npm run build 2>/dev/null || true
EXPOSE 3000
CMD ["node", "dist/index.js"]

3. Update docker-compose.yml to build locally.
   Replace the image: line with build: . so Docker Compose builds from your Dockerfile instead of pulling a remote image:

services:
  openclaw:
    build: .
    container_name: openclaw
    restart: unless-stopped
    env_file:
      - .env
    volumes:
      - openclaw_data:/home/node/.openclaw
    environment:
      - NODE_ENV=production

volumes:
  openclaw_data:
    driver: local

4. Build and start.
   The --build flag forces Docker Compose to build the image before starting the container:

docker compose up -d --build

Return to the onboarding step above to complete your first-run configuration.

Useful management commands

The following commands cover the most common day-to-day tasks. Run them from /opt/openclaw unless noted otherwise.

# View live logs
docker compose logs -f openclaw

# Stop OpenClaw
docker compose down

# Restart
docker compose restart openclaw

# Open a shell inside the container
docker compose exec openclaw sh

# Run a one-off OpenClaw command
docker compose exec openclaw openclaw --help

Back up your OpenClaw data

OpenClaw stores its memory, skills and configuration in the openclaw_data named volume. Backing up this volume regularly means you can restore a working installation without repeating onboarding.

Run the following to create a compressed archive in /opt/openclaw/backups:

docker run --rm \
  -v openclaw_data:/data \
  -v /opt/openclaw/backups:/backup \
  alpine tar czf /backup/openclaw-$(date +%Y%m%d).tar.gz -C /data .

To run this automatically each night, add a cron job. Open the crontab editor with crontab -e and add the following line, which runs the backup at 03:00 daily:

0 3 * * * docker run --rm -v openclaw_data:/data -v /opt/openclaw/backups:/backup alpine tar czf /backup/openclaw-$(date +\%Y\%m\%d).tar.gz -C /data . 2>/dev/null

Upgrade OpenClaw

OpenClaw releases new features and integrations frequently. Upgrading pulls the latest image or source code while leaving your data volume untouched.

For official image installs, run the following from /opt/openclaw:

docker compose pull
docker compose up -d

For source builds, pull the latest code first, then rebuild:

cd /opt/openclaw/src
git pull
cd /opt/openclaw
docker compose up -d --build

Troubleshooting

Container exits immediately after starting

If the container stops seconds after docker compose up -d, a missing or malformed environment variable is the most common cause. Check the logs for the specific error:

docker compose logs openclaw

• Confirm your .env file is in /opt/openclaw and contains valid credentials.
• Check that the API key you uncommented matches the provider you intend to use.
• Verify the image name in docker-compose.yml is correct and the tag exists on the registry.

Build fails with “Killed” or exit code 137

Exit code 137 means the process was killed by the operating system, almost always because the VPS ran out of memory during the build. The npm install and build steps are memory-intensive.

• Upgrade to a VPS plan with more RAM. See our VPS hosting options.
• As a temporary measure, add a swap file to your VPS. See our guide on securing and configuring your VPS for general VPS setup steps.
• Use the official pre-built image instead of building from source, if one is available for your architecture.

Onboarding command not found inside the container

If docker compose exec openclaw openclaw onboard returns a “command not found” error, the container may not have started correctly or the binary path differs in your build.

• Confirm the container is running with docker compose ps.
• Open a shell inside the container with docker compose exec openclaw sh and check what is available in /usr/local/bin or dist/.
• For source builds, confirm the build step completed without errors before running onboarding.

Wrapping up

You have installed OpenClaw on a VPS using Docker Compose, completed first-run onboarding and set up automated daily backups. Your configuration and data persist in a named volume, so upgrades and restarts do not affect your setup.

Now that OpenClaw is running, consider reviewing your VPS firewall rules to confirm the container is not exposing unnecessary ports. Our guides on opening ports in UFW and securing your VPS cover the key steps. For Node.js version management inside your containers, see our guide on managing Node.js versions with NVM.

Our VPS hosting plans give you the root access, RAM and persistent storage that a production OpenClaw deployment needs.