Back to Tutorials

Complete OpenClaw Getting Started Guide

Step-by-step guide to install and run OpenClaw, no programming experience required

Beginner30 min
beginnerinstallationenvironmentserver

Complete OpenClaw Getting Started Guide

🎯 Goal: Even if you've never written code before, you can get OpenClaw running in 30 minutes by following this tutorial.

Who Is This Tutorial For?

  • βœ… Complete beginners who have never coded
  • βœ… People who want an AI assistant to auto-reply messages
  • βœ… Users who want AI in WeChat/Telegram/Feishu
  • βœ… Privacy-conscious users who don't want data sent to third parties

πŸ“– Learning Path

This tutorial is your first step with OpenClaw. After completing it, we recommend:

  1. Installation Guide - Deep dive into installation methods and troubleshooting
  2. Configuration - Detailed AI model and platform connection setup
  3. Pricing Guide - Understand OpenClaw's usage costs

Before You Start: Choose Your Deployment Method

OpenClaw has two main deployment options:

| Method | Pros | Cons | Best For | |--------|------|------|----------| | Local Deployment | Free, data stays local, full control | Computer must stay on | Have a computer, occasional use | | Cloud Server | 24/7 online, access anywhere | Costs money (~$10-15/year) | Need always-on service |

Method 1: Local Deployment (Mac/Windows)

System Requirements

Before starting, make sure your computer meets these requirements:

| Requirement | Minimum | Recommended | |-------------|---------|-------------| | OS | macOS 12+ / Windows 10+ | macOS 14+ / Windows 11 | | RAM | 4GB | 8GB or more | | Disk Space | 10GB | 20GB+ |

⚠️ Windows Users Note: Windows MUST use WSL2 (Linux Subsystem). Direct Windows installation is not supported.

Step 1: Install Node.js

⏱️ Estimated Time: 5-10 minutes

Node.js is the runtime environment for OpenClaw, just like a car needs fuel.

Why Node.js v22+ is Required

OpenClaw uses some modern JavaScript features that are only available in Node.js 22 and above:

  • Better performance and memory management
  • Native TypeScript transformation support
  • More stable long-connection handling

If your system has an older version of Node.js, you must upgrade to v22 or higher.

For Mac Users

  1. Open Terminal (Press Command + Space, type Terminal, press Enter)

  2. Check if Node.js is installed:

    node --version
    • If it shows v22.x.x or higher, skip to Step 2
    • If version is lower than v22, or shows command not found, continue below

  3. Install Homebrew (Mac package manager):

    /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

    Follow the prompts, you may need to enter your password

  4. Install Node.js:

    brew install node@22

  5. Verify installation:

    node --version

    Should show v22.x.x

For Windows Users

Windows users need to install WSL2 (Windows Subsystem for Linux) first - this is a requirement.

  1. Enable WSL2:

    • Right-click Start menu, select "Terminal (Admin)" or "Windows PowerShell (Admin)"
    • Enter this command and press Enter:
    wsl --install
    • Wait for installation to complete, then restart your computer

  2. Set up Ubuntu:

    • After restart, Ubuntu window will open automatically
    • Follow prompts to set username and password (password won't show while typing, just type and press Enter)

  3. Install Node.js in Ubuntu:

    # Install nvm (Node.js version manager)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash

# Reload configuration
source ~/.bashrc

# Install Node.js 22
nvm install 22

# Verify
node --version

Step 2: Install OpenClaw

⏱️ Estimated Time: 3-5 minutes

Now that Node.js is ready, let's install OpenClaw itself.

Method A: One-Line Install (Recommended)

Run in Terminal (Mac) or Ubuntu (Windows WSL2):

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

The script will automatically:

  • Detect your system environment
  • Install missing dependencies
  • Configure OpenClaw
  • Start the setup wizard

Method B: npm Install

If the one-line script has issues, install manually:

# Install OpenClaw
npm install -g openclaw@latest

# Start configuration wizard
openclaw onboard --install-daemon

Common Installation Issues

Issue: openclaw: command not found

This means npm's global directory isn't in your system PATH. Fix:

# Find npm global directory
npm prefix -g

# Add to PATH (Mac users)
echo 'export PATH="$(npm prefix -g)/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

# Add to PATH (Linux/WSL2 users)
echo 'export PATH="$(npm prefix -g)/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Issue: Sharp module installation failed

SHARP_IGNORE_GLOBAL_LIBVIPS=1 npm install -g openclaw@latest

Step 3: Configure AI Model

⏱️ Estimated Time: 5 minutes

OpenClaw doesn't provide AI capabilities itself - it needs to connect to an AI service (like Claude, ChatGPT, etc.).

πŸ’‘ Tip: Want to compare models and costs? Check out our Pricing Guide

Get an API Key

You can choose any of these AI services:

| Provider | Price | Features | Rating | |----------|-------|----------|--------| | Google Gemini | Free tier | Free quota, good for testing | ⭐⭐⭐⭐⭐ | | DeepSeek | $0.14/M tokens | Very affordable | ⭐⭐⭐⭐⭐ | | Claude | $3/M tokens | High intelligence | ⭐⭐⭐⭐ | | ChatGPT | $2.5/M tokens | Great ecosystem | ⭐⭐⭐⭐ | | Qwen | Free tier | Alibaba Cloud model | ⭐⭐⭐⭐ | | Moonshot Kimi | Free tier | Great for long context | ⭐⭐⭐⭐ | | Zhipu GLM | Free tier | High cost-performance | ⭐⭐⭐⭐ | | Groq | Free tier | Ultra-fast response | ⭐⭐⭐⭐ |

πŸ’‘ Two Payment Options

OpenClaw supports two payment methods for AI models:

| Method | Description | Best For | |--------|-------------|----------| | Pay-as-you-go (API) | Pay per token consumed | Light users, trial phase | | Subscription (Code Plan) | Fixed monthly fee, unlimited use | Heavy users, predictable costs |

πŸ“– For detailed cost comparison, see Pricing Guide

Option 1: Pay-as-you-go (API Key)

Best for light users or trial phase. Pay only for what you use.

πŸ”Ή Google Gemini (Recommended for Beginners, Free Tier)

  1. Visit Google AI Studio
  2. Sign in with your Google account
  3. Click "Create API Key"
  4. Copy the generated API Key

πŸ“– Official Docs: Gemini API Quickstart

πŸ”Ή DeepSeek (Best Value, Lowest Price)

  1. Visit DeepSeek Platform
  2. Register and sign in (supports phone registration)
  3. Go to "API Keys" page
  4. Click "Create API Key"
  5. Copy the generated API Key

πŸ“– Official Docs: DeepSeek API Documentation

πŸ”Ή Qwen / Tongyi Qianwen (Alibaba Cloud, Free Tier)

  1. Visit Alibaba Cloud Bailian
  2. Sign in with Alibaba Cloud account
  3. Enable "Model Service Lingji"
  4. Go to "API-KEY Management" to create a key

πŸ“– Official Docs: Qwen API Documentation

πŸ”Ή Moonshot Kimi (Long Context, Free Tier)

  1. Visit Moonshot Platform
  2. Register and sign in
  3. Go to "API Key Management"
  4. Click "Create New API Key"

πŸ“– Official Docs: Moonshot API Documentation

πŸ”Ή Zhipu GLM (Tsinghua Tech, Free Tier)

  1. Visit Zhipu Open Platform
  2. Register and sign in
  3. Go to "API Keys" page
  4. Click "Add API Key"

πŸ“– Official Docs: GLM API Documentation

πŸ”Ή Groq (Ultra-Fast, Free Tier)

  1. Visit Groq Console
  2. Sign in with Google/GitHub account
  3. Go to "API Keys" page
  4. Click "Create API Key"

πŸ“– Official Docs: Groq API Documentation

πŸ”Ή Claude (High Intelligence)

  1. Visit Anthropic Console
  2. Register and sign in
  3. Go to "API Keys" page
  4. Click "Create Key"

πŸ“– Official Docs: Claude API Documentation

πŸ”Ή ChatGPT / OpenAI (Great Ecosystem)

  1. Visit OpenAI Platform
  2. Register and sign in
  3. Go to "API keys" page
  4. Click "Create new secret key"

πŸ“– Official Docs: OpenAI API Documentation

Option 2: Subscription Plans (Code Plan)

Best for heavy users. Fixed monthly fee for predictable costs.

πŸ”Ή Claude Max / Anthropic Subscription

| Plan | Monthly Fee | Includes | |------|-------------|----------| | Claude Pro | $20/month | Unlimited Claude.ai web chat | | Claude Max | $100-200/month | API credits + priority access |

πŸ“– Official Info: Claude Pricing

πŸ”Ή ChatGPT Plus / Pro / Team

| Plan | Monthly Fee | Includes | |------|-------------|----------| | ChatGPT Plus | $20/month | Unlimited GPT-4 chat | | ChatGPT Pro | $200/month | GPT-4 + o1 unlimited | | ChatGPT Team | $25-30/month/user | Team collaboration + admin features |

πŸ“– Official Info: ChatGPT Pricing

πŸ”Ή Google One AI Premium

| Plan | Monthly Fee | Includes | |------|-------------|----------| | AI Premium | $19.99/month | Gemini Advanced + 2TB cloud storage |

πŸ“– Official Info: Google One AI Premium

πŸ”Ή Cursor Pro (AI Code Editor, supports OpenClaw)

| Plan | Monthly Fee | Includes | |------|-------------|----------| | Pro | $20/month | Unlimited AI completions + fast models |

πŸ“– Official Info: Cursor Pricing

Configure Your API Key

Run the configuration wizard:

openclaw onboard

Follow the prompts to select your AI provider and enter your API Key.

πŸ’° Money-Saving Tips

  1. Start with free tiers: Google Gemini, Qwen, Moonshot, and Zhipu GLM all offer free quotas
  2. Best value: DeepSeek has the lowest price ($0.14/M tokens)
  3. Heavy users: ChatGPT Plus/Claude Pro fixed monthly fees are more cost-effective
  4. Need speed: Groq offers ultra-fast responses, great for real-time chat
  5. Long documents: Moonshot Kimi supports 200K token context

πŸ“– For detailed cost comparison and recommendations, see Pricing Guide

Step 4: Verify Installation

⏱️ Estimated Time: 2 minutes

Run the health check:

openclaw doctor

Understanding Health Check Results

openclaw doctor checks the following items:

| Check Item | Meaning | If Failed | |------------|---------|-----------| | βœ… Node.js Version | Is Node.js β‰₯22 | Reinstall Node.js v22+ | | βœ… OpenClaw CLI | Is CLI working properly | Re-run installation command | | βœ… Config File | Does config file exist | Run openclaw onboard | | βœ… API Key | Is API key valid | Check if key is configured correctly | | βœ… Network | Is network connection working | Check network or proxy settings |

If all checks show βœ…, installation was successful!

Auto-Fix Issues

If any check fails, try auto-fix:

openclaw doctor --fix

Access the dashboard:

openclaw start

Then open http://localhost:18789 in your browser. You should see OpenClaw's management interface.

Method 2: Cloud Server Deployment

⏱️ Estimated Time: 15-20 minutes

If you need OpenClaw running 24/7 (like for a Telegram Bot), use a cloud server.

Server Requirements

| Spec | Minimum | Recommended | |------|---------|-------------| | CPU | 1 core | 2 cores | | RAM | 2GB | 4GB | | Storage | 20GB SSD | 40GB SSD | | OS | Ubuntu 22.04 | Ubuntu 24.04 | | Bandwidth | 1Mbps | 5Mbps+ |

πŸ’‘ Tip: If you need browser automation features, choose 4GB RAM or higher.

Recommended Budget Servers

International Users

| Provider | Specs | Price | Features | Link | |----------|-------|-------|----------|------| | Vultr | 1 core, 1GB | $2.5/mo | $100 credit for new users | Sign Up | | DigitalOcean | 1 core, 1GB | $4/mo | Very stable | Website | | BandwagonHost | 1 core, 1GB | $49.99/yr | CN2 route | Website |

China Users

| Provider | Specs | Price | Features | Link | |----------|-------|-------|----------|------| | Alibaba Cloud | 2 cores, 2GB | Β₯99/yr | Pre-installed OpenClaw image | Promo | | Tencent Cloud | 2 cores, 2GB | Β₯99/yr | Renewal discounts | Promo | | Huawei Cloud | 2 cores, 4GB | ~Β₯100/yr | Enterprise-friendly | Promo |

Alibaba Cloud One-Click Deploy (Easiest):

  1. Visit Alibaba Cloud Lightweight Server
  2. Select "Application Image" β†’ "OpenClaw"
  3. Choose 2 cores 2GB or higher
  4. Click purchase, wait 3-5 minutes for automatic deployment

Server Deployment Steps

1. Connect to Server

ssh root@your-server-ip

2. Install Docker

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

3. Deploy OpenClaw

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

# Run deployment script
./docker-setup.sh

4. Security Configuration (Important!)

On a cloud server, you MUST set up user whitelist:

# Edit ~/.openclaw/config.yaml
channels:
  telegram:
    allowed_users:
      - "your-telegram-user-id"

⚠️ Security Warning: Without a whitelist, anyone can use your Bot and consume your API credits!

πŸŽ‰ Congratulations!

You've successfully installed OpenClaw! Next steps:

  1. Configuration Guide - Learn more about model options
  2. Connect Telegram - Easiest messaging platform to set up
  3. Connect Feishu - Great for users in China
  4. Pricing Guide - Calculate your OpenClaw usage costs

FAQ

Q: Is OpenClaw free?

A: OpenClaw itself is completely free and open source. However, you need to pay for AI model API calls:

  • Google Gemini has free tier
  • DeepSeek ~$0.14/million tokens
  • Claude/ChatGPT ~$2-3/million tokens

πŸ“– For detailed cost comparison, see our Pricing Guide

Q: Is 4GB RAM enough?

A:

  • Yes: If you only use AI chat features, no browser automation
  • No: If you frequently use browser features, get 8GB

Q: Why must Windows use WSL2?

A: OpenClaw depends on many Linux system libraries that Windows native environment can't provide. WSL2 gives you a complete Linux environment for best compatibility.

Q: Installation failed, what should I do?

A: Common causes and solutions:

| Error Message | Cause | Solution | |--------------|-------|----------| | EACCES permission denied | Insufficient permissions | Use sudo npm install -g openclaw | | network timeout | Network issues | Switch npm registry or use proxy | | sharp module not found | Missing dependency | Run SHARP_IGNORE_GLOBAL_LIBVIPS=1 npm install -g openclaw@latest | | node-gyp rebuild failed | Missing build tools | Mac: xcode-select --install, Linux: sudo apt install build-essential |

Q: How to uninstall or reinstall?

A:

# Uninstall OpenClaw
npm uninstall -g openclaw

# Clean config files (optional)
rm -rf ~/.openclaw

# Reinstall
npm install -g openclaw@latest

Q: How to update to the latest version?

A:

# Check current version
openclaw --version

# Update to latest
npm update -g openclaw

# Verify update
openclaw --version

Q: Which AI models are supported?

A: OpenClaw supports all major AI models:

  • Claude (Anthropic) - Recommended for complex tasks
  • ChatGPT (OpenAI) - Great ecosystem
  • DeepSeek - Affordable pricing
  • Google Gemini - Has free tier
  • Qwen (Tongyi Qianwen) - Alibaba Cloud model
  • Others - Any model with OpenAI-compatible API

Q: What if I encounter problems?

A:

  1. Run openclaw doctor --fix to auto-fix common issues
  2. Check GitHub Issues
  3. Ask for help in our community

Last updated: 2026-03-10