Chapter 2: Environment Setup and Installation

🎯 Learning Objective: Complete the installation and configuration of OpenClaw, and successfully start your first Agent

🔍 Pre-Installation Checklist

Before you begin, ensure your environment meets the following requirements:

📋 Hardware Requirements

💻 Supported Operating Systems

✅ Ubuntu 22.04 LTS (Recommended) ✅ Debian 11+ ✅ CentOS 8+ ✅ macOS 12+ ✅ Windows 11 (WSL2)

🛠️ Required Software

• Node.js 18+ (Required)
• npm 8+ (Required)
• Git 2.0+ (Required)
• Docker 20+ (Optional, for containerized deployment)
• SSL Certificate (Optional, for HTTPS)

---

🚀 Installation Methods Compared

---

🎯 Method 1: One-Click Install Script ⭐ Recommended for Beginners

Download and Run the Script

# Download the install script
curl -sSL https://raw.githubusercontent.com/openclaw/openclaw/main/scripts/install.sh -o install-openclaw.sh

# Review the script contents (recommended)
cat install-openclaw.sh

# Run the install script
chmod +x install-openclaw.sh
./install-openclaw.sh

Script Features

✅ Auto-detects operating system ✅ Installs Node.js and dependencies ✅ Downloads OpenClaw CLI ✅ Creates workspace directory structure ✅ Generates initial configuration files ✅ Sets up environment variables

Installation Preview

🔍 Detecting OS: ubuntu
✅ Node.js version meets requirements: v20.10.0
📦 Installing OpenClaw CLI...
📁 Creating workspace: ~/.openclaw/workspace-main
⚙️  Generating config file: openclaw.json
🎉 Installation complete!

---

🛠️ Method 2: Manual Step-by-Step Installation

Step 1: Install Node.js

Ubuntu/Debian

# Add the NodeSource repository
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -

# Install Node.js
sudo apt-get install -y nodejs

# Verify installation
node --version  # Should show v20.x.x
npm --version   # Should show 9.x.x

CentOS/RHEL

# Add the NodeSource repository
curl -fsSL https://rpm.nodesource.com/setup_20.x | sudo bash -

# Install Node.js
sudo yum install -y nodejs

# Verify installation
node --version
npm --version

macOS

# Using Homebrew
brew install node

# Or download the official installer
# https://nodejs.org/en/download/

Step 2: Install OpenClaw CLI

# Install OpenClaw globally
sudo npm install -g openclaw

# Verify installation
openclaw --version
openclaw help

Step 3: Create the Workspace

# Create the OpenClaw home directory
mkdir -p ~/.openclaw/workspace-main
cd ~/.openclaw/workspace-main

# Initialize a git repository
git init
git config --local user.name "Your Name"
git config --local user.email "your.email@example.com"

# Create the directory structure
mkdir -p {memory,skills,projects,logs}

Step 4: Initialize Configuration

# Interactive configuration wizard
openclaw onboard

# Or manual setup
openclaw setup

# Or manually create openclaw.json
cat > openclaw.json << 'EOF'
{
  "gateway": {
    "port": 18789,
    "bind": "loopback"
  },
  "agents": [
    {
      "id": "main",
      "name": "Main Assistant",
      "model": "anthropic/claude-sonnet-4-20250514",
      "workspace": {
        "root": "."
      }
    }
  ],
  "auth": {
    "profiles": [
      {
        "id": "anthropic",
        "provider": "anthropic"
      }
    ]
  }
}
EOF

---

🐳 Method 3: Docker Deployment

Create a Dockerfile

# Based on the official Node.js image
FROM node:20-slim

# Set working directory
WORKDIR /app

# Install system dependencies
RUN apt-get update && apt-get install -y \
    git \
    curl \
    && rm -rf /var/lib/apt/lists/*

# Install OpenClaw
RUN npm install -g openclaw

# Create workspace
RUN mkdir -p /app/workspace
WORKDIR /app/workspace

# Copy configuration files
COPY openclaw.json .
COPY auth-profiles.json .

# Expose port
EXPOSE 18789

# Startup command
CMD ["openclaw", "gateway", "start", "--port", "18789"]

Docker Compose Deployment

version: '3.8'

services:
  openclaw-gateway:
    build: .
    ports:
      - "18789:18789"
    volumes:
      - ./workspace:/app/workspace
      - ./logs:/app/logs
    environment:
      - NODE_ENV=production
    restart: unless-stopped

  openclaw-agent-1:
    build: .
    ports:
      - "18790:18789"
    volumes:
      - ./agents/agent-1:/app/workspace
    environment:
      - AGENT_ID=agent-1
      - NODE_ENV=production
    restart: unless-stopped

---

🔧 API Key Configuration

After installation, configure the API keys for your AI models:

Configure Anthropic Claude

# Interactive configuration
openclaw auth add anthropic

# Or set environment variables directly
export ANTHROPIC_API_KEY="sk-ant-api03-..."

# Verify configuration
openclaw auth list

Configure OpenAI GPT

# Add OpenAI authentication
openclaw auth add openai

# Set the API key
export OPENAI_API_KEY="sk-..."

# Test the connection
openclaw test openai

Other Model Configurations

# Google Gemini
export GOOGLE_API_KEY="..."
openclaw auth add google

# Azure OpenAI
export AZURE_OPENAI_API_KEY="..."
export AZURE_OPENAI_ENDPOINT="https://..."
openclaw auth add azure-openai

---

🎮 First Launch and Testing

Start the Gateway

# Navigate to the workspace
cd ~/.openclaw/workspace-main

# Start the Gateway (foreground)
openclaw gateway start

# Or run in the background
openclaw gateway start --daemon

# Check status
openclaw status

Test Basic Functionality

# In another terminal, test the API
curl -X POST http://localhost:18789/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "main",
    "messages": [
      {"role": "user", "content": "Hello, OpenClaw!"}
    ]
  }'

Expected Response

{
  "id": "chatcmpl-...",
  "object": "chat.completion",
  "model": "main",
  "choices": [
    {
      "message": {
        "role": "assistant",
        "content": "Hello! I'm the OpenClaw AI assistant. Happy to help!"
      }
    }
  ]
}

---

❗ Common Issues and Solutions

Issue 1: Node.js Version Too Old

# Error message
Error: OpenClaw requires Node.js 18 or higher

# Solution
# Remove the old version
sudo apt remove nodejs npm

# Reinstall the latest version
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

Issue 2: Permission Error

# Error message
EACCES: permission denied, mkdir '/usr/local/lib/node_modules/@openclaw'

# Solution: Configure npm global directory
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
npm install -g @openclaw/openclaw

Issue 3: Port Already in Use

# Error message
Error: listen EADDRINUSE :::18789

# Solution: Find the process using the port
sudo netstat -tlnp | grep 18789
sudo kill -9 <PID>

# Or use a different port
openclaw gateway start --port 18790

Issue 4: Invalid API Key

# Error message
AuthenticationError: Invalid API key

# Solution: Reconfigure the key
openclaw auth remove anthropic
openclaw auth add anthropic
# Enter the correct API key

# Verify configuration
openclaw auth test anthropic

Issue 5: Network Connectivity Issues

# Error message
fetch failed

# Solution: Check network and firewall
# Test connectivity
curl -I https://api.anthropic.com
curl -I https://api.openai.com

# Configure proxy (if needed)
export HTTPS_PROXY=http://proxy.company.com:8080
export HTTP_PROXY=http://proxy.company.com:8080

---

✅ Post-Installation Verification Checklist

After installation, verify each item:

• [ ] Node.js version: node --version >= v18.0.0
• [ ] OpenClaw CLI: openclaw --version shows version info
• [ ] Workspace: ~/.openclaw/workspace-main exists
• [ ] Configuration: openclaw.json is valid
• [ ] API keys: openclaw auth list shows configured providers
• [ ] Gateway starts: openclaw gateway start runs without errors
• [ ] API test: HTTP request returns a normal response
• [ ] Logging: logs/gateway.log contains normal log entries

---

📊 Performance Optimization Tips

System-Level Optimization

# Increase file descriptor limits
echo "* soft nofile 65536" | sudo tee -a /etc/security/limits.conf
echo "* hard nofile 65536" | sudo tee -a /etc/security/limits.conf

# Optimize Node.js memory
export NODE_OPTIONS="--max-old-space-size=4096"

# Enable high-performance mode
echo performance | sudo tee /sys/devices/system/cpu/cpu*/cpufreq/scaling_governor

OpenClaw Configuration Optimization

{
  "gateway": {
    "maxConcurrency": 10,
    "timeout": 30000,
    "keepAlive": true
  },
  "agents": [
    {
      "id": "main",
      "maxConcurrency": 3,
      "contextPruning": {
        "enabled": true,
        "maxTokens": 100000
      }
    }
  ]
}

---

🚀 Next Steps

Congratulations! OpenClaw has been successfully installed. Now you can:

Next Chapter: Your First Agent →

---

📝 Chapter Summary

After this chapter, you should have:

• [x] Completed OpenClaw installation and basic configuration
• [x] Mastered both one-click and manual installation methods
• [x] Configured AI model API keys
• [x] Successfully started the OpenClaw Gateway
• [x] Learned solutions for common issues
• [x] Understood performance optimization techniques

Ready to create your first Agent? 🎯

---

📌 This article is written by the AI team at TechsFree

🔗 Read more → Check out TechsFree Tech Blog for more articles on AI, multi-agent systems, and automation!

🌐 Website | 📖 Tech Blog | 💼 Our Services