🦞 MoltyClaw.ai
Launch Agent

The Complete Guide to Setting Up OpenClaw Manually

OpenClaw is rapidly becoming the gold standard for open-source AI assistants. Its ability to execute code, browse the web securely, and manage files on a server natively is unmatched.

But as any developer who has tried to run a 24/7 background process knows, getting the software to run locally on your laptop is very different from deploying it to a production server that you can access anywhere via Telegram.

In this guide, we'll walk through the manual process of setting up a private OpenClaw instance on a fresh Linux VPS (Virtual Private Server), the environment variables you need to configure, and the common pitfalls you'll likely encounter along the way.

Prerequisites

Before you start, you'll need:

  • A fresh Linux VPS (Ubuntu 24.04 or Debian 12 is recommended). You'll need at least 2 vCPUs and 4GB of RAM. OpenClaw relies heavily on Docker and Headless Chromium, which are resource-hungry.
  • A domain name pointing to your VPS IP address (optional, but highly recommended for secure WebSocket connections).
  • A Telegram Bot Token (obtained from the @BotFather on Telegram).
  • An API Key from your preferred LLM provider (OpenAI, Google Gemini, Anthropic, etc.).

Step 1: Provisioning the Environment

First, SSH into your server. Update your package lists and install the core dependencies: Node.js (v22+ is strictly required) and Docker.

# Update packages
sudo apt update && sudo apt upgrade -y

# Install dependencies (curl, git, build-essential)
sudo apt install -y curl git build-essential

# Install Docker (required for the Sandbox feature)
sudo apt-get install -y ca-certificates curl gnupg
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg

Pitfall Warning: Ensure your user is added to the docker group. If you run OpenClaw as a standard user (which you should, never run it as root), the agent will fail to spawn secure sandboxes if it can't interact with the Docker daemon.

sudo usermod -aG docker $USER
newgrp docker

Step 2: Installing OpenClaw

Clone the official repository and run the setup scripts.

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

# Install dependencies using npm
npm ci

Common Issue: Node.js version mismatches. OpenClaw uses specific native bindings for capabilities like desktop automation or secure cryptography. If you try to run npm ci on Node 18, it will fail to compile certain binaries. Stick to Node 22 LTS.

Step 3: Configuration (The .env File)

OpenClaw requires several environment variables to function correctly. Copy the example configuration file:

cp .env.example .env
nano .env

You'll need to set the following critical variables:

  • OPENCLAW_TELEGRAM_TOKEN: Your BotFather token.
  • OPENCLAW_API_KEY: Your LLM provider key (e.g., GEMINI_API_KEY).
  • OPENCLAW_MODEL_DEFAULT: Set this to your preferred model (e.g., google/gemini-3.1-pro-preview).
  • OPENCLAW_WORKSPACE_DIR: Where the agent will store its memory, files, and downloaded media. Ensure this directory exists and has write permissions.

Step 4: Running the Gateway

Finally, start the OpenClaw gateway daemon. For production, you shouldn't just run npm start in a tmux session. You should set up a systemd service or use pm2 so the agent restarts automatically if the server reboots or the process crashes.

Using pm2:

npm install -g pm2
pm2 start npm --name "openclaw" -- start
pm2 save
pm2 startup

The "Day 2" Operations

Congratulations, your agent is live! You can message your bot on Telegram and it will respond. However, "Day 2" operations are where things get tricky:

  • Browser Management: OpenClaw uses Playwright/Puppeteer for web browsing. Over time, zombie Chromium processes can eat up your server's memory, eventually crashing the instance. You'll need a script to periodically prune dead browsers.
  • Updates: The open-source project moves fast. Updating involves pulling new code, rebuilding binaries, and restarting the gateway—all of which can introduce breaking changes to your local configuration.
  • Security: Since the agent can execute code on your server, ensuring your Docker sandbox configuration is perfectly isolated is critical to prevent accidental host machine damage.

The Alternative: Managed Hosting

If deploying Linux packages, managing Docker daemon permissions, and debugging PM2 startup scripts sounds like an enjoyable afternoon, the manual setup is extremely rewarding. You gain total control over the host environment.

However, if your goal is just to use the AI assistant without the burden of maintaining infrastructure, keeping it updated, and securing it against memory leaks, you might want to look into managed hosting solutions like MoltyClaw.

With a managed instance, you provide your API key and Telegram token, and the service provisions a dedicated, private, pre-configured server in under 5 minutes. You get all the power of OpenClaw with none of the dependency hell.

← Back to blog