# How to Install OpenClaw: Best Methods to Run Your AI Agent

This guide explains the best OpenClaw installation methods so you can choose the right setup, avoid common mistakes, and start running real AI agent workflows faster.

## What Is OpenClaw?

OpenClaw is an AI agent framework that helps you run agents for tasks, tools, channels, and automation workflows. It is not just a chatbot sitting there waiting for prompts like a bored intern. It can connect with your setup and help with real workflows such as reminders, research, file organization, meeting notes, calendar tasks, and messaging automation.

OpenClaw runs through a Gateway and browser-based Control UI. The official documentation says the Control UI can be opened locally from the gateway host, and the gateway commonly uses local access such as 127.0.0.1:18789 for browser control.

## Before You Install OpenClaw

Decide where you want to run OpenClaw: local machine, [VPS](/blog/install-openclaw-on-vps), source setup, or [managed hosting](/blog/best-openclaw-managed-hostings).

Use local setup if you only want to test OpenClaw before using it seriously.

Use a [VPS](/blog/install-openclaw-on-vps) if you want more control and a 24/7 self-hosted setup.

Use [source install](/blog/openclaw-custom-skill) if you are a developer and want to customize or contribute.

Use [managed hosting](/blog/best-openclaw-managed-hostings) if you want the easiest way to keep OpenClaw online without server work.

Make sure you have a stable internet connection before starting the setup.

Keep your model provider or API key ready, because OpenClaw needs a model to power the agent.

Prepare secure access details like gateway token, login credentials, or environment variables.

Plan where OpenClaw will store state, workspace files, and connected tool data.

Start with one simple workflow first, then add more tools and channels after the setup works.

## Best Methods to Install OpenClaw

Use this section to compare the practical OpenClaw install methods before explaining each one. The reference article covers four useful paths: CLI install, npm/pnpm install, [Docker](/blog/openclaw-on-docker)/[Docker](/blog/openclaw-on-docker) Compose, and cloud/[VPS](/blog/install-openclaw-on-vps) setup. It also highlights onboarding, gateway status, dashboard access, doctor checks, channel connection, troubleshooting, and security.

| Method | Best For | Difficulty | 24/7 Ready | Main Value |
| --- | --- | --- | --- | --- |
| CLI install | Beginners testing OpenClaw | Easy | No | Fast local setup |
| npm/pnpm install | Node users and developers | Medium | No | More control over packages |
| [Docker](/blog/openclaw-on-docker) install | Safer isolated setup | Medium | Yes, if hosted | Cleaner environment |
| [VPS](/blog/install-openclaw-on-vps)/cloud install | Production and always-on use | Hard | Yes | Full server control |
| [Managed hosting](/blog/best-openclaw-managed-hostings) | Fastest production setup | Easy | Yes | No server maintenance |

## Method 1: Install OpenClaw With [Managed Hosting](/blog/best-openclaw-managed-hostings)

[Managed hosting](/blog/best-openclaw-managed-hostings) is the easiest way to run OpenClaw if you want to avoid server setup, [Docker](/blog/openclaw-on-docker) configuration, ports, SSL, logs, updates, and uptime monitoring.

This method is best for:

Beginners

Founders

Marketers

Teams

Non-technical users

Anyone who wants OpenClaw running faster

### Basic Setup Flow

~~~bash
# No terminal command required for managed hosting.
# Use the hosting dashboard to deploy OpenClaw.
~~~

### Steps

Create your account on Ampere.sh.

Deploy your OpenClaw environment from the Ampere.sh dashboard.

Open the OpenClaw Control UI after deployment.

Complete the onboarding setup.

Connect your model provider or API key.

Create your first OpenClaw agent.

Connect one message channel, such as Telegram, WhatsApp, Slack, or Discord.

Add one simple workflow, such as reminders, task follow-ups, or meeting notes.

Test the workflow with a small task before adding more tools.

Keep your setup always online so OpenClaw can handle chats, tasks, and automations without running on your laptop.

### Best For

Use managed hosting if your goal is to run OpenClaw quickly and keep it online without maintaining infrastructure yourself.

### Not Best For

Avoid managed hosting if you need full server control, custom networking, private infrastructure rules, or source-level modification.

## Method 2: Install OpenClaw With the Official CLI Script

The CLI script is one of the simplest ways to install OpenClaw locally on macOS, Linux, or Windows with WSL. The official docs list the macOS/Linux command as a curl installer and Windows PowerShell as a separate installer command.

### For macOS or Linux

~~~bash
curl -fsSL https://openclaw.ai/install-cli.sh | bash
~~~

After installation, run onboarding:

~~~bash
openclaw onboard
~~~

Start the gateway:

~~~bash
openclaw gateway
~~~

Open the Control UI in your browser:

~~~bash
http://127.0.0.1:18789
~~~

### For Windows PowerShell

~~~bash
& ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1)))
~~~

If you want to install without launching onboarding immediately:

~~~bash
& ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -NoOnboard
~~~

Then run:

~~~bash
openclaw onboard
~~~

### Best For

Testing OpenClaw locally

Learning the Control UI

Trying OpenClaw before hosting it

Users who want the fastest local setup

### Important Note

[Local install](/blog/openclaw-beginner-setup) is not ideal for 24/7 automation. If your laptop sleeps or shuts down, OpenClaw stops. Computers, like humans, love failing at the exact wrong moment.

## Method 3: Install OpenClaw With npm, pnpm, or bun

This method is useful if you already manage JavaScript tools manually. OpenClaw’s install docs mention npm, pnpm, and bun as package-manager install options.

### Check Node Version

OpenClaw documentation currently recommends Node 24 or Node 22.19+ for package-based installs.

~~~bash
node -v
~~~

If Node is missing or outdated, install Node first.

### Install With npm

~~~bash
npm install -g openclaw@latest
~~~

Then run onboarding:

~~~bash
openclaw onboard
~~~

Start the gateway:

~~~bash
openclaw gateway
~~~

### Install With pnpm

~~~bash
pnpm add -g openclaw@latest
~~~

If pnpm asks for build approval, approve required packages:

~~~bash
pnpm approve-builds -g
~~~

Then run:

~~~bash
openclaw onboard
openclaw gateway
~~~

### Install With bun

~~~bash
bun install -g openclaw@latest
~~~

Then run:

~~~bash
openclaw onboard
openclaw gateway
~~~

### If openclaw Command Is Not Found

Check your global npm path:

~~~bash
npm prefix -g
~~~

Add the global bin path to your shell config.

For zsh:

~~~bash
echo 'export PATH="$(npm prefix -g)/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
~~~

For bash:

~~~bash
echo 'export PATH="$(npm prefix -g)/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
~~~

The official docs also mention adding $(npm prefix -g)/bin to your shell startup file if the command is not in your PATH.

### Best For

Node.js users

Developers

Users who want package-level control

Local testing

### Not Best For

Avoid this method if you are not comfortable fixing Node, PATH, or package-manager errors. Tiny package issues can waste entire afternoons, because modern tooling was apparently designed by people who enjoy riddles.

## Method 4: Install OpenClaw With [Docker](/blog/openclaw-on-docker)

[Docker](/blog/openclaw-on-docker) is useful if you want a cleaner, isolated OpenClaw setup. The official [Docker](/blog/openclaw-on-docker) docs describe [Docker](/blog/openclaw-on-docker) as a containerized deployment path and mention persistent config/workspace mounts, gateway checks, and [Docker](/blog/openclaw-on-docker) Compose usage.

### Basic [Docker](/blog/openclaw-on-docker) Setup

Create a project folder:

~~~bash
mkdir openclaw-docker
cd openclaw-docker
~~~

Create an .env file:

~~~bash
nano .env
~~~

Add this:

~~~bash
OPENCLAW_GATEWAY_TOKEN=change-this-to-a-strong-random-token
OPENCLAW_GATEWAY_PORT=8080
OPENCLAW_STATE_DIR=/data/.openclaw
OPENCLAW_WORKSPACE_DIR=/data/workspace
~~~

Create storage folders:

~~~bash
mkdir -p data/.openclaw data/workspace
~~~

Create a docker-compose.yml file:

~~~bash
nano docker-compose.yml
~~~

Add a basic Compose structure:

~~~bash
services:
 openclaw-gateway:
   image: ghcr.io/openclaw/openclaw:latest
   container_name: openclaw-gateway
   restart: unless-stopped
   env_file:
     - .env
   ports:
     - "8080:8080"
   volumes:
     - ./data/.openclaw:/data/.openclaw
     - ./data/workspace:/data/workspace
~~~

Start OpenClaw:

~~~bash
docker compose up -d
~~~

Check running containers:

~~~bash
docker compose ps
~~~

View logs:

~~~bash
docker compose logs -f openclaw-gateway
~~~

Run a health check if your Docker image exposes the gateway command:

~~~bash
docker compose exec openclaw-gateway node dist/index.js health --token "$OPENCLAW_GATEWAY_TOKEN"
~~~

The [Docker](/blog/openclaw-on-docker) docs mention gateway health checks using docker compose exec openclaw-gateway node dist/index.js health --token "$OPENCLAW_GATEWAY_TOKEN".

### Connect a Channel From [Docker](/blog/openclaw-on-docker)

For example, to add [Telegram](/blog/openclaw-on-telegram):

~~~bash
docker compose run --rm openclaw-cli channels add --channel telegram --token "<TELEGRAM_BOT_TOKEN>"
~~~

OpenClaw Docker docs show this pattern for running channel commands through the openclaw-cli service.

### Best For

Developers

Self-hosters

Users who want isolated setup

Users who want persistent storage

Server deployments

### Important Docker Warning

Do not skip persistent volumes. If you rebuild containers without proper mounts, your setup data can disappear like it got a better job.

## Method 5: Install OpenClaw on a VPS or Cloud Server

A VPS install is best when you want OpenClaw running 24/7 with full control. OpenClaw docs list VPS/cloud deployment as an install path, and Docker is commonly used for server-based deployments.

### Step 1: Update the Server

For Ubuntu/Debian:

~~~bash
sudo apt update && sudo apt upgrade -y
~~~

Install basic tools:

~~~bash
sudo apt install -y curl git ufw nano
~~~

### Step 2: Install Docker

~~~bash
curl -fsSL https://get.docker.com | sh
~~~

Add your user to the [Docker](/blog/openclaw-on-docker) group:

~~~bash
sudo usermod -aG docker $USER
~~~

Apply group changes:

~~~bash
newgrp docker
~~~

Check [Docker](/blog/openclaw-on-docker):

~~~bash
docker --version
docker compose version
~~~

### Step 3: Create OpenClaw Directory

~~~bash
mkdir -p ~/openclaw
cd ~/openclaw
~~~

Create folders:

~~~bash
mkdir -p data/.openclaw data/workspace
~~~

### Step 4: Create Environment File

~~~bash
nano .env
~~~

Add:

~~~bash
OPENCLAW_GATEWAY_TOKEN=replace-with-a-strong-token
OPENCLAW_GATEWAY_PORT=8080
OPENCLAW_STATE_DIR=/data/.openclaw
OPENCLAW_WORKSPACE_DIR=/data/workspace
~~~

### Step 5: Create Docker Compose File

~~~bash
nano docker-compose.yml
~~~

Add:

~~~bash
services:
 openclaw-gateway:
   image: ghcr.io/openclaw/openclaw:latest
   container_name: openclaw-gateway
   restart: unless-stopped
   env_file:
     - .env
   ports:
     - "8080:8080"
   volumes:
     - ./data/.openclaw:/data/.openclaw
     - ./data/workspace:/data/workspace
~~~

### Step 6: Start OpenClaw

~~~bash
docker compose up -d
~~~

Check logs:

~~~bash
docker compose logs -f
~~~

### Step 7: Configure Firewall

Allow SSH:

~~~bash
sudo ufw allow OpenSSH
~~~

Allow your OpenClaw port only if needed:

~~~bash
sudo ufw allow 8080/tcp
~~~

Enable firewall:

~~~bash
sudo ufw enable
~~~

Check status:

~~~bash
sudo ufw status
~~~

### Step 8: Open the Control UI

Use your VPS IP:

~~~bash
http://YOUR_SERVER_IP:8080
~~~

If you use a domain and reverse proxy, connect through your domain instead.

### Step 9: Restart or Update OpenClaw

Restart:

~~~bash
docker compose restart
~~~

Update image:

~~~bash
docker compose pull
docker compose up -d
~~~

Check logs after update:

~~~bash
docker compose logs -f openclaw-gateway
~~~

### Best For

24/7 OpenClaw hosting

Full control

Advanced users

Production workflows

Users comfortable with server maintenance

### Not Best For

Avoid VPS if you do not want to manage firewalls, logs, updates, SSL, backups, and random server nonsense. The cloud is just someone else’s computer, plus your invoice.

## Method 6: Install OpenClaw From Source

Source install is for developers, contributors, or advanced users who want to customize OpenClaw. Current docs and indexed docs show a source-style flow using git clone, pnpm install, pnpm build, pnpm ui:build, and pnpm link --global.

### Step 1: Install Requirements

Check Node:

~~~bash
node -v
~~~

Check pnpm:

~~~bash
pnpm -v
~~~

If pnpm is missing:

~~~bash
npm install -g pnpm
~~~

### Step 2: Clone OpenClaw

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

### Step 3: Install Dependencies

~~~bash
pnpm install
~~~

If pnpm asks for approval:

~~~bash
pnpm approve-builds
~~~

### Step 4: Build OpenClaw

~~~bash
pnpm build
pnpm ui:build
~~~

### Step 5: Link OpenClaw Globally

~~~bash
pnpm link --global
~~~

### Step 6: Run Onboarding

~~~bash
openclaw onboard
~~~

For daemon setup:

~~~bash
openclaw onboard --install-daemon
~~~

The OpenClaw quickstart docs mention openclaw onboard --install-daemon and say onboarding walks through model provider, API key, and Gateway configuration.

### Step 7: Start Gateway

~~~bash
openclaw gateway
~~~

Open the UI:

~~~bash
http://127.0.0.1:18789
~~~

### Best For

Developers

Contributors

Custom builds

Testing new changes

Debugging internals

### Not Best For

Do not use source install if your goal is just to run OpenClaw. Use managed hosting, CLI install, Docker, or VPS instead. Source setup is power plus pain, because apparently developers needed a personality test in installation form.

## Which OpenClaw Install Method Should You Choose?

| User Goal | Best Install Method | Difficulty | Best For | Main Tradeoff |
| --- | --- | --- | --- | --- |
| Fastest way to run OpenClaw | Managed hosting | Easy | Beginners, teams, founders, non-technical users | Less infrastructure control |
| Test OpenClaw on your laptop | Local install | Medium | Learning, testing, demos, small experiments | Not reliable for 24/7 workflows |
| Manage OpenClaw with packages | npm, pnpm, or bun install | Medium | Node.js users and developers | Can create dependency or PATH issues |
| Run OpenClaw in an isolated setup | Docker install | Medium | Developers, self-hosters, repeatable deployments | Needs Docker knowledge and volume setup |
| Run OpenClaw 24/7 with full control | VPS install | Hard | Technical users, self-hosters, production control | Requires server, security, updates, logs, and backups |
| Customize or contribute to OpenClaw | Source install | Hard | Developers and contributors | Not beginner-friendly and needs debugging |

Run OpenClaw without server setup, Docker, ports, logs, updates, or uptime work. Use Ampere.sh to deploy OpenClaw faster and start your first AI workflow

### CTA Button:

Run OpenClaw on Ampere.sh

## Common OpenClaw Installation Mistakes

### 1. Problem: Choosing the Wrong Install Method

Many users install OpenClaw locally and expect it to run 24/7. Local setup is fine for testing, but it can stop when your laptop sleeps, restarts, or loses internet. Naturally, the machine does not care about your automation dreams.

### Solution:

Use local install only for testing.

Use Ampere.sh managed hosting for the easiest always-on setup.

Use a VPS if you want full control and can manage the server yourself.

Use source install only if you are a developer or contributor.

### 2. Problem: OpenClaw Command Not Found

After installation, users may get a command not found error when running openclaw. This usually means the global package path is not added to the system PATH.

### Solution:

Check if OpenClaw is available:

~~~bash
openclaw --version
~~~

Check your global npm path:

~~~bash
npm prefix -g
~~~

Add the global npm bin path.

For zsh:

~~~bash
echo 'export PATH="$(npm prefix -g)/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
~~~

For bash:

~~~bash
echo 'export PATH="$(npm prefix -g)/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
~~~

Test again:

~~~bash
openclaw --version
~~~

### 3. Problem: Skipping Onboarding

Some users install OpenClaw but do not run onboarding. Without onboarding, the model provider, gateway, workspace, and channels may not be configured properly.

### Solution:

Run onboarding:

~~~bash
openclaw onboard
~~~

During onboarding, configure:

Model provider

API key

Gateway settings

Workspace path

Optional channels

Then start OpenClaw:

~~~bash
openclaw gateway
~~~

### 4. Problem: OpenClaw Control UI Not Opening

The Control UI may not open if the gateway is not running, the wrong port is used, or [Docker](/blog/openclaw-on-docker)/[VPS](/blog/install-openclaw-on-vps) port mapping is incorrect. Classic “it works but nothing opens” nonsense.

### Solution:

Start the gateway:

~~~bash
openclaw gateway
~~~

Open the local Control UI:

~~~bash
http://127.0.0.1:18789
~~~

For [Docker](/blog/openclaw-on-docker), check containers and logs:

~~~bash
docker compose ps
docker compose logs -f
~~~

For VPS, check if the port is allowed:

~~~bash
sudo ufw status
~~~

If needed, allow the gateway port:

~~~bash
sudo ufw allow 8080/tcp
~~~

### 5. Problem: Node Version or Dependency Issue

If you install OpenClaw with npm, pnpm, bun, or from source, an old Node.js version or broken dependency setup can cause install errors.

### Solution:

Check Node version:

~~~bash
node -v
~~~

Install or switch to a newer LTS version using nvm:

~~~bash
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
source ~/.bashrc
nvm install --lts
nvm use --lts
~~~

Then install OpenClaw again:

~~~bash
npm install -g openclaw@latest
~~~

Check installation:

~~~bash
openclaw --version
~~~

### 6. Problem: No Persistent Storage in Docker or VPS Setup

Some users run OpenClaw in Docker or on a server without persistent storage. After restart, rebuild, or redeploy, config and workspace data may disappear. Storage vanishing after not being stored: humanity’s finest mystery.

### Solution:

Use persistent volumes in docker-compose.yml:

~~~bash
services:
 openclaw-gateway:
   image: ghcr.io/openclaw/openclaw:latest
   restart: unless-stopped
   env_file:
     - .env
   ports:
     - "8080:8080"
   volumes:
     - ./data/.openclaw:/data/.openclaw
     - ./data/workspace:/data/workspace
~~~

Create the folders:

~~~bash
mkdir -p data/.openclaw data/workspace
~~~

Restart Docker:

~~~bash
docker compose up -d
~~~

### 7. Problem: Weak Gateway Token or Exposed Access

A weak token or publicly exposed gateway can create serious security problems, especially when OpenClaw connects with tools, channels, files, or workflows.

### Solution:

Set a strong token in your .env file:

~~~bash
OPENCLAW_GATEWAY_TOKEN=replace-with-a-strong-random-token
~~~

Protect your .env file:

~~~bash
chmod 600 .env
~~~

Also follow these basics:

Do not share your gateway token.

Do not expose the gateway publicly without protection.

Use HTTPS and restricted access for production.

Review third-party skills before installing them.

Use human approval for risky workflows.

### 8. Problem: OpenClaw Stops After Closing Terminal

If you start OpenClaw manually over SSH and close the terminal, the process may stop. The terminal is not a production hosting platform, shocking as that may be.

### Solution:

For quick testing, use tmux:

~~~bash
sudo apt install -y tmux
tmux new -s openclaw
openclaw gateway
~~~

Detach from tmux:

~~~bash
Ctrl + B, then D
~~~

Reopen later:

~~~bash
tmux attach -t openclaw
~~~

For a better production setup, use Docker Compose:

~~~bash
docker compose up -d
~~~

## Final Verdict

The best way to install OpenClaw depends on what you want to do next.

Use [managed hosting](/blog/best-openclaw-managed-hostings) if you want the easiest way to run OpenClaw without handling infrastructure. Use a [local install](/blog/openclaw-beginner-setup) if you only want to test it. Use [VPS](/blog/install-openclaw-on-vps) install if you want full control and 24/7 self-hosting. Use [source install](/blog/openclaw-custom-skill) if you are a developer or contributor.

If your goal is to run OpenClaw for real workflows, choose an always-on setup and start with one useful automation. Installation is only the first step. The real value starts when OpenClaw is connected to your tools, channels, and daily tasks.

## FAQs

### Is OpenClaw free to install?

Yes, OpenClaw can be installed as an open-source AI agent framework. However, you may still need to pay for hosting, [managed hosting](/blog/best-openclaw-managed-hostings), a [VPS](/blog/install-openclaw-on-vps), or model/API usage depending on how you run it.

### How long does OpenClaw installation take?

OpenClaw installation time depends on the setup method. A managed setup with [Ampere.sh](https://www.ampere.sh/setup) is usually faster because you skip manual server work. Local setup can take a few minutes if your system is ready, while [Docker](/blog/openclaw-on-docker) or [VPS](/blog/install-openclaw-on-vps) setup can take longer because you need to configure storage, ports, tokens, and security.

### Will updating OpenClaw delete my data?

Updating OpenClaw should not delete your data if persistent storage is configured correctly. Before updating, back up your state files, workspace files, environment variables, and important configuration. Tiny ritual, huge regret prevention.

### Why is OpenClaw not working after installation?

OpenClaw may fail because of missing onboarding, wrong Node version, broken PATH, missing API key, gateway not running, blocked firewall, wrong port, or no persistent storage. Start by checking onboarding, gateway status, and logs.

### What port does OpenClaw use?

OpenClaw commonly uses the Gateway and Control UI through the same gateway port. 18789 is often used locally, while [Docker](/blog/openclaw-on-docker) or [VPS](/blog/install-openclaw-on-vps) setups may use a configured port like 8080. Always check your environment settings.

### Is [managed hosting](/blog/best-openclaw-managed-hostings) better than installing OpenClaw manually?

[Managed hosting](/blog/best-openclaw-managed-hostings) is better if you want the easiest setup without servers, [Docker](/blog/openclaw-on-docker), ports, logs, updates, or uptime work. Manual install is better for full control. For beginners and teams, [Ampere.sh](https://www.ampere.sh/setup) keeps the focus on workflows, not setup maintenance.

### Which OpenClaw install method is best for beginners?

[Managed hosting](/blog/best-openclaw-managed-hostings) is usually best for beginners because it removes most of the technical setup. [Local install](/blog/openclaw-beginner-setup) is fine for testing, but [managed hosting](/blog/best-openclaw-managed-hostings) is better if you want OpenClaw running online and available for real workflows.

### Which OpenClaw install method is best for advanced users?

Advanced users can choose [Docker](/blog/openclaw-on-docker), [VPS](/blog/install-openclaw-on-vps), or [source install](/blog/openclaw-custom-skill). [Docker](/blog/openclaw-on-docker) is good for isolated deployment, [VPS](/blog/install-openclaw-on-vps) is best for full server control, and [source install](/blog/openclaw-custom-skill) is best for developers who want to customize or contribute to OpenClaw.