Complete OpenClaw Installation Guide: From Environment Setup to First Run

Honestly, when I first heard about OpenClaw, I had my doubts. Another AI tool? Would the installation be a hassle? Would I need to mess with a bunch of environment configurations? Turns out, the whole process was way smoother than I expected.

This article is about sharing my installation experience with you, especially for those who, like me, aren’t super comfortable with command lines but still want to try something new. Whether you’re on Mac, Linux, or Windows, following this guide should help you avoid major pitfalls.

What Exactly is OpenClaw?

Before diving into the installation, let’s talk about what OpenClaw actually is. Simply put, it’s an open-source AI assistant platform that connects large language models like ChatGPT and Claude to your favorite messaging apps, such as Telegram or WhatsApp.

You might ask, why bother installing this locally? Isn’t the web version of AI good enough?

Well, each has its benefits. With a local installation, you can:

Control your data and privacy
Customize various features and skills
Integrate AI into your own workflow
If you’re willing to tinker, even use local models without relying on cloud services

For me, the most appealing aspect is connecting AI to Telegram, so I can invoke it directly while chatting without switching between apps.

Preparation: Check Your System

Honestly, OpenClaw’s system requirements are pretty friendly. But before we start, let’s confirm a few things.

Operating System Compatibility

OpenClaw natively supports macOS and Linux. If you’re on Windows, no problem, but you’ll need to install WSL2 (Windows Subsystem for Linux) first.

WSL2 is basically a lightweight Linux environment running inside Windows. Sounds complex, but Microsoft has made it quite simple. Open PowerShell and run a single command:

wsl --install

Remember to restart your computer after installation, then open PowerShell again and type wsl to enter the Linux environment.

Hardware Requirements

When it comes to hardware, OpenClaw really isn’t picky. The official recommendations are:

RAM: 8GB works, 16GB is better
Storage: At least 20GB of space (SSD recommended for better experience)

Basically, if your computer can run a browser smoothly, running OpenClaw shouldn’t be a problem. I use an old MacBook with 8GB RAM, and it runs just fine.

Node.js Environment

This is the most critical step. OpenClaw is built on Node.js, so you must install Node.js first. The version requirement is 22 or higher.

If you want to develop custom skills, the official recommendation is Node.js 24+, as newer versions support more advanced JavaScript features.

Installing Node.js on macOS

For Mac users, the easiest method is using Homebrew:

# If you don't have Homebrew yet, install it first
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Then install Node.js
brew install node

Installing Node.js on Linux

For Linux, I recommend using nvm (Node Version Manager), which makes it easy to switch between different Node.js versions:

# Install nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# After restarting the terminal, install Node.js 22
nvm install 22
nvm use 22

Installing Node.js on Windows (WSL2)

In WSL2, the method is the same as Linux—just use nvm.

After installation, verify the version:

node --version

As long as it shows v22.x.x or higher, you’re good to go.

Package Manager: npm or pnpm?

After installing Node.js, npm (Node Package Manager) comes bundled with it. OpenClaw works perfectly fine with npm.

However, if you’ve heard of pnpm, you can use that too. pnpm has several advantages over npm:

Faster installation speed
Less disk space usage
Stricter dependency management

For regular users, either one works. I personally prefer pnpm, but it’s totally a matter of preference.

To install pnpm:

npm install -g pnpm

Installing OpenClaw

Now that the prep work is done, we can officially begin. OpenClaw offers several installation methods, and I’ll explain them in order of recommendation.

Method 1: Official Installation Script (Most Recommended)

This is the simplest method—one command does it all:

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

This script will automatically:

Check your system environment
Install necessary dependencies
Download and install the OpenClaw CLI
Prompt you to run the initial configuration

The whole process takes about 1-2 minutes, depending on your internet speed. The first time I installed it, watching the logs scroll through the terminal was pretty satisfying.

Method 2: npm Global Installation

If you prefer using a package manager, you can use npm directly:

npm install -g openclaw@latest

The @latest ensures you’re installing the newest version. After installation, you can use the openclaw command directly in the terminal.

Method 3: pnpm Global Installation

If you’re using pnpm:

pnpm add -g openclaw@latest

The effect is the same as npm, just a different tool.

Method 4: Installing from Source (Advanced)

If you want to tinker or plan to contribute code to OpenClaw, you can clone the source from GitHub:

# Clone the repository
git clone https://github.com/openclaw/openclaw.git

# Navigate to the directory
cd openclaw

# Install dependencies
pnpm install

# Build
pnpm ui:build

This method is for developers; not recommended for regular users.

Initial Configuration: Getting OpenClaw Running

After installing OpenClaw, you can’t use it right away—you need to run the configuration wizard first. This step is important but also quite simple.

Running the Onboard Wizard

In the terminal, type:

openclaw onboard --install-daemon

This command launches an interactive configuration wizard. The --install-daemon parameter means OpenClaw will be installed as a system service, so it auto-starts on boot without manual intervention.

Next, the wizard will ask you several questions step by step:

1. Select Running Mode

Usually, selecting Local gateway is fine, unless you want to deploy to a remote server.

2. Configure AI Model

Here you need to choose which AI provider you want to use. Currently supported:

OpenAI (GPT-4, GPT-3.5, etc.)
Anthropic (Claude series)
Local models (requires additional configuration)

If you have an OpenAI or Anthropic API key, enter it here. If not, you can skip it and configure later.

How to get API keys:

OpenAI: Go to platform.openai.com, register an account, and generate a key on the API keys page
Anthropic: Go to console.anthropic.com, register, and generate in API settings

3. Set Working Directory

The wizard will ask where to store OpenClaw’s configuration and data. The default is ~/.openclaw/, and usually, you can just press Enter to use the default.

4. Connect Messaging Channels

This step is about choosing which chat platform you want to use to interact with the AI. Currently supported:

Telegram: You need to find @BotFather in Telegram first, create a bot, and get the token
WhatsApp: A QR code will be generated for you to scan with your phone’s WhatsApp to link
Skip: If you only want to use the Web interface, you can skip this for now

I chose Telegram myself, and the setup process is straightforward:

Search for @BotFather in Telegram
Send the /newbot command
Follow the prompts to name your bot
Copy the generated token
Paste it into OpenClaw’s configuration

5. Install Daemon

Finally, the wizard will ask if you want to install the daemon. If you say yes, OpenClaw will run continuously in the background, unaffected by closing the terminal.

The whole configuration process takes about 5-10 minutes, mostly spent on getting API keys and configuring chat channels.

Manual Configuration (Optional)

If you want to fine-tune the configuration, you can edit the config file:

nano ~/.openclaw/openclaw.json

This file is in JSON format and contains all configuration items. However, for most users, the wizard configuration is sufficient—no need to edit manually.

First Run: Verify Everything Works

After configuration is complete, you can start OpenClaw.

Start the Gateway

If you didn’t install the daemon earlier, you’ll need to start it manually:

openclaw gateway --port 18789

18789 is the default port; you can change it to something else. If it starts successfully, you’ll see output like this:

✓ OpenClaw Gateway started on http://localhost:18789

Access the Web Interface

Open your browser and visit:

http://localhost:18789

You should see OpenClaw’s control interface. The interface is clean, with several main sections:

Chat: Chat testing area
Agents: Manage your AI agents
Skills: Configure various skill plugins
Settings: System settings

Test the Conversation

On the Chat page, try sending a message, like “Hello” or “Introduce yourself.”

If everything is configured correctly, the AI should respond. The first time I saw a reply, I was pretty excited—this is your own self-hosted AI assistant!

Troubleshooting Common Issues

When installing software, you’re bound to encounter some minor issues. I’ve listed common pitfalls for you to troubleshoot.

Incorrect Node.js Version

Symptom: Running the openclaw command throws an error about incompatible Node version

Solution: Check the Node.js version, ensure it’s 22+

node --version

If the version is too old, reinstall or upgrade Node.js.

WSL2 Configuration Issues (Windows Users)

Symptom: Various errors during installation on Windows

Solution: Confirm WSL2 is correctly installed and updated to the latest version

wsl --update

Invalid API Key

Symptom: Configured the API key, but AI doesn’t respond or throws errors

Solution:

Check if the key is correctly copied (no extra spaces before or after)
Confirm the API account has balance (both OpenAI and Anthropic require credits)
Try regenerating the key

Port Already in Use

Symptom: Starting the Gateway shows port 18789 is already occupied

Solution: Switch to a different port, or find and close the process using the port

# See what's using port 18789
lsof -i :18789

# Start with a different port
openclaw gateway --port 18790

Permission Issues

Symptom: Installation prompts insufficient permissions

Solution: Linux/Mac users may need to use sudo, or check directory permissions

# Ensure write permissions
chmod -R 755 ~/.openclaw

Security Reminders

After setting up OpenClaw, there are a few security considerations:

Don’t Expose the Port: Port 18789 defaults to listening on localhost only. Never expose it to the public internet, or anyone can access your AI
Protect API Keys: API keys in the config file are sensitive. Don’t share them with others or commit them to Git repositories
Use SSH Tunnels for Remote Access: If you want to access from other devices, use SSH tunneling instead of directly opening the port

# Access from another computer via SSH
ssh -L 18789:localhost:18789 user@your-server

Final Thoughts

Alright, by now you should have successfully installed OpenClaw. Let’s recap the process:

OpenClaw Quick Installation

Steps to install and setup OpenClaw from scratch

⏱️ Estimated time: 10 min

1
Step1: Prepare Environment
Install Node.js 22+ (Brew for Mac, nvm for Linux/Windows). Confirm system requirements.
2
Step2: Install Core
Run the official recommended script:
curl -fsSL https://openclaw.ai/install.sh | bash
3
Step3: Initial Setup
Execute onboard wizard to configure API and channels:
openclaw onboard --install-daemon
4
Step4: Start Service
Start manually if daemon is not installed:
openclaw gateway
Visit http://localhost:18789 to verify.

Next steps you can take:

Explore the Skills feature to add various capabilities to your AI
Try connecting Telegram or WhatsApp to invoke AI within messaging apps
If interested, look into developing custom skills
Check out the official documentation for more advanced features

Honestly, even though OpenClaw is an open-source project, the experience is already quite polished. If you encounter any issues during installation, check the GitHub Issues page—the community is pretty active.

One last reminder: the first time working with these tools might feel a bit complex, but after installing once, you’ll realize it’s not that big a deal. Take your time, search when you hit problems, and most things can be resolved.

Have fun!

References:

FAQ

What if Node.js version is incorrect?

Check with node -v, must be 22+. Recommended to use nvm:
nvm install 22
nvm use 22

Errors installing on Windows?

Ensure WSL2 is installed (wsl --install) and updated.
Run commands inside the WSL terminal (Ubuntu, etc.), not CMD/PowerShell.

API Key not working?

1. Check for unexpected whitespace
2. Verify account balance (OpenClaw is free, but model providers charge)
3. Try regenerating the key

Port 18789 already in use?

Check process with lsof -i :18789
Or specify a different port: openclaw gateway --port 18790

9 min read · Published on: Feb 5, 2026 · Modified on: Feb 5, 2026

Easton

AI & Intelligence