OpenClaw 15-Minute Quick Start

Get started with OpenClaw in just 15 minutes - your personal AI assistant that runs on your own devices!

📋 Prerequisites

• ✅ Basic command line knowledge (know how to open terminal)
• ✅ Node.js 22+ installed - Download here ⚠️ Important: Node.js 22 or higher is required
• ✅ An AI provider API key (OpenAI, Anthropic, or other supported providers)

---

🚀 Step 1: Installation (2 minutes)

Install OpenClaw globally on your system:

npm install -g openclaw@latest
# or: pnpm add -g openclaw@latest

Verify installation:

openclaw --version

You should see the version number displayed.

Troubleshooting:

• If you see “command not found”, restart your terminal
• For permission errors, try sudo npm install -g openclaw@latest (Mac/Linux)
• Windows users: run terminal as Administrator

---

📁 Step 2: Run the Onboarding Wizard (3 minutes)

OpenClaw includes an interactive wizard that guides you through the complete setup:

openclaw onboard --install-daemon

What the wizard sets up:

• Gateway - The core service that manages your AI assistant
• Workspace - Your skills and configuration directory (~/.openclaw/workspace)
• Channels - Connect your favorite messaging apps (optional)
• API Keys - Configure your AI provider credentials

Wizard prompts you for:

1. AI Provider Selection - Choose OpenAI, Anthropic, or others
2. API Key - Enter your provider’s API key
3. Model Selection - Pick your preferred AI model
4. Channel Setup (optional) - Connect WhatsApp, Telegram, Slack, etc.

What gets created:

~/.openclaw/
├── openclaw.json          # Main configuration
├── workspace/              # Your skills and agents
│   ├── skills/            # Custom skills
│   ├── AGENTS.md          # Agent behavior
│   ├── SOUL.md            # AI personality
│   └── TOOLS.md           # Available tools
└── credentials/           # Stored API keys (encrypted)

---

🔑 Step 3: Start the Gateway (2 minutes)

Once setup is complete, start the OpenClaw Gateway:

openclaw gateway --port 18789 --verbose

What this does:

• Starts the WebSocket gateway (control plane)
• Enables communication with your AI assistant
• Displays detailed logging output
• Runs on port 18789 by default

Keep the gateway running - This is your AI assistant’s control center.

Alternative: Run as a daemon/service If you used --install-daemon during onboarding, the gateway may already be running as a background service.

Check gateway status:

# Test if gateway is running
curl http://localhost:18789/health

# Or use OpenClaw CLI
openclaw status

---

⚡ Step 4: Send Your First Message (4 minutes)

Now you can interact with your AI assistant through multiple methods:

Method 1: Command Line (Direct)

openclaw agent --message "Hello! What can you help me with?"

Method 2: Send to Connected Channel

If you set up a channel during onboarding:

# Send to WhatsApp number
openclaw message send --to +1234567890 --message "Hello from OpenClaw!"

# Send to Telegram
openclaw message send --to @username --message "Test message"

Method 3: Use WebChat UI

Open your browser and navigate to:

http://localhost:18789

This opens the WebChat interface where you can:

• Chat directly with your AI assistant
• View conversation history
• Manage sessions
• Monitor gateway status

Example conversations to try:

# Get help
openclaw agent --message "What are your capabilities?"

# Create a to-do list
openclaw agent --message "Create a shopping list for dinner"

# Get information
openclaw agent --message "What's the weather like today?"

---

🛠️ Step 5: Explore Skills & Automation (4 minutes)

OpenClaw uses a skills-based system for automation. Skills are reusable capabilities that your AI assistant can use.

Check Available Skills:

# List installed skills
openclaw skills list

# Get skill details
openclaw skills info web-scraper

Create Your First Skill:

Skills in OpenClaw are Markdown files in your workspace:

# Navigate to workspace
cd ~/.openclaw/workspace/skills

# Create a new skill directory
mkdir my-first-skill
cd my-first-skill

# Create the skill definition file
cat > SKILL.md << 'EOF'
# My First Skill

## Description
This skill demonstrates how to create custom OpenClaw skills.

## Capabilities
- Greet users
- Provide helpful information
- Demonstrate skill structure

## Usage
Simply ask the assistant to use this skill!

EOF

Use Your New Skill:

# Ask your assistant to use the skill
openclaw agent --message "Use the my-first-skill to greet me"

---

🔧 Common Issues & Solutions

Issue: “command not found: openclaw”

Solution: Make sure npm global bin directory is in your PATH

# Check npm prefix
npm config get prefix

# Add to PATH (example)
export PATH="$PATH:$(npm config get prefix)/bin"

# Or restart your terminal after installation

Issue: “Gateway won’t start” or “Port already in use”

Solution:

# Check if something is using port 18789
lsof -i :18789  # Mac/Linux
netstat -ano | findstr :18789  # Windows

# Use a different port
openclaw gateway --port 18790

Issue: “Invalid API key”

Solution:

• Verify your API key with your provider (OpenAI, Anthropic, etc.)
• Make sure you copied the entire key
• Re-run the onboarding wizard: openclaw onboard

Issue: “Node.js version too old”

Solution:

# Check your Node.js version
node --version

# Upgrade to Node.js 22+
# Visit https://nodejs.org or use nvm:
nvm install 22
nvm use 22

Issue: “Permission denied” when installing

Solution:

# Clear npm cache
npm cache clean --force

# Reinstall with proper permissions
sudo npm install -g openclaw@latest  # Mac/Linux
# Run terminal as Administrator  # Windows

---

💡 Pro Tips

Tip 1: Run Gateway as a Background Service

Instead of keeping a terminal window open:

# Install as a daemon (systemd/launchd service)
openclaw onboard --install-daemon

# Start the service
openclaw gateway start

# Check status
openclaw status

# View logs
openclaw logs

Tip 2: Configure Your AI Model

Edit ~/.openclaw/openclaw.json:

{
  "agent": {
    "model": "openai/gpt-4o"
  }
}

Tip 3: Enable Remote Access

Use Tailscale to access your gateway from anywhere:

# Configure in openclaw.json
{
  "gateway": {
    "tailscale": {
      "mode": "serve"  // tailnet-only or "funnel" for public
    }
  }
}

# Or use SSH tunnel
ssh -L 18789:localhost:18789 your-server

Tip 4: Connect Multiple Channels

OpenClaw supports 20+ messaging platforms:

# Run onboarding again to add channels
openclaw onboard

# Popular options:
# - WhatsApp (requires phone pairing)
# - Telegram (requires bot token)
# - Slack (requires app setup)
# - Discord (requires bot token)
# - iMessage (Mac only, BlueBubbles)

---

🎯 What’s Next?

You’ve successfully set up your personal AI assistant! Continue your journey:

• 📱 Connect Your Favorite Channels - Set up WhatsApp, Telegram, Slack, Discord, and more
• 🛠️ Create Custom Skills - Build your own automation skills
• 🔧 Advanced Configuration - Fine-tune your assistant’s behavior
• 📚 Explore the Skills Library - Discover community-built skills
• 🌐 Remote Access Setup - Access your assistant from anywhere

---

🆘 Need Help?

• 💬 Discord Community - Chat with other users
• 📖 Official Documentation - Comprehensive guides
• 🐛 GitHub Issues - Report bugs
• 📚 FAQ - Frequently asked questions

---

⏱️ Total Time: 15 minutes 📊 Difficulty: Beginner 🎯 Result: Your personal AI assistant is running and ready to help!

---

🌟 Key Concepts

• Gateway: The core service that manages your AI assistant (runs on port 18789)
• Workspace: Directory at ~/.openclaw/workspace containing your skills and configuration
• Channels: Messaging platforms where you can interact with your assistant
• Skills: Reusable automation capabilities that your assistant can use
• Sessions: Conversation contexts that the AI maintains

Next Steps: Start chatting with your assistant through the WebChat UI at http://localhost:18789 or through any connected channel!