Tech with Alex's Blog
0%

OpenClaw User Guide - Complete Tutorial

Posted on Edited on In , Views:
Symbols count in article: 17k Reading time ≈ 15 mins.

Understanding OpenClaw

What is OpenClaw?

OpenClaw is an open-source, self-hosted AI Agent system that transforms AI from a “chat tool” into a “digital employee capable of autonomously executing tasks.”

Dimension ChatGPT OpenClaw
Positioning Q&A Advisor Digital Employee
Deployment Cloud SaaS Local Self-hosted
Interaction Web Chat 20+ Chat Channels
Capability Answer Questions Execute Tasks
Data Cloud Storage Local Control

Core Capabilities

  • ✅ Multi-channel Connection: Telegram, WhatsApp, Feishu, DingTalk, Discord, etc.
  • ✅ Persistent Memory: Remembers your preferences, projects, contacts
  • ✅ Skill Extension: Infinitely expand capabilities through the Skills system
  • ✅ Proactive Work: Scheduled tasks, heartbeat checks, automatic reminders
  • ✅ Local Data: All data stored on your device
  • ✅ Multi-Agent Collaboration: Dedicated agents for different tasks

Architecture Overview

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
┌─────────────────────────────────────────────────────────┐
│                    User Chat Channels                   │
│   Telegram / WhatsApp / Feishu / DingTalk / Discord ... │
└────────────────────┬────────────────────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────────────────────┐
│                   Gateway Core Service                  │
│  - Message Routing  - Session Management  - Event Processing  - Task Scheduling │
└────────────────────┬────────────────────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────────────────────┐
│                    Agent System                         │
│  main / chat / coding / Custom Agents                   │
└────────────────────┬────────────────────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────────────────────┐
│                   Tools & Skills                        │
│  Skills / Plugins / Tools / Memory / Cron               │
└─────────────────────────────────────────────────────────┘

Quick Start

System Requirements

Requirement Description
Node.js v22.0.0 or higher
Operating System macOS / Linux / Windows (WSL2)
Memory Minimum 2GB, Recommended 4GB+
Storage Minimum 1GB available space

One-Click Installation

macOS / Linux:

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

Windows (PowerShell):

1
iwr -useb https://openclaw.ai/install.ps1 | iex

Verify Installation

1
2
3
4
5
6
7
8
# Check version
openclaw --version

# Run diagnostics
openclaw doctor

# Check status
openclaw status

5-Minute Quick Experience

1
2
3
4
5
6
7
8
9
10
11
12
13
# 1. Install
npm i -g openclaw

# 2. Run setup wizard
openclaw onboard

# 3. Start Gateway
openclaw gateway start

# 4. Open dashboard
openclaw dashboard

# 5. Start chatting in your browser!

Installation & Deployment

Installation Methods Comparison

Method Difficulty Use Case
One-Click Script ⭐ Recommended for beginners
npm Manual Install ⭐⭐ Familiar with Node.js
Docker ⭐⭐ Containerized deployment
Source Build ⭐⭐⭐⭐ Developers

Manual Installation (npm)

1
2
3
4
5
6
7
8
# Check Node.js version
node -v  # Requires >= 22.0.0

# Global installation
npm install -g openclaw@latest

# If encountering sharp module errors
SHARP_IGNORE_GLOBAL_LIBVIPS=1 npm install -g openclaw@latest

Configure PATH (if needed)

If you get openclaw: command not found:

1
2
3
4
5
6
7
8
# Find npm global path
npm prefix -g

# Add to ~/.bashrc or ~/.zshrc
export PATH="$(npm prefix -g)/bin:$PATH"

# Apply changes
source ~/.bashrc

Docker Deployment

1
2
3
4
5
docker run -d \
  --name openclaw \
  -v ~/openclaw-data:/root/.openclaw \
  -p 18789:18789 \
  openclaw/openclaw:latest

Version Updates

1
2
3
4
5
6
7
8
# Update to stable version (recommended)
openclaw update --channel stable

# Update to beta version
openclaw update --channel beta

# Update to dev version
openclaw update --channel dev

Channel Integration

Channel Difficulty Comparison

Tier Platform Time Description
First Tier Telegram, QQ 5-10 min Easiest, zero threshold
Second Tier Discord, Feishu 15-20 min Well-documented
Third Tier WhatsApp, Slack, DingTalk 25-40 min More configuration
Fourth Tier iMessage, WeChat 1+ hour Additional requirements

Step 1: Create Bot

  1. Search for @BotFather in Telegram
  2. Send /newbot command
  3. Set bot name (must end with bot)
  4. Save the returned Bot Token

Step 2: Configure OpenClaw

Edit ~/.openclaw/openclaw.json:

1
2
3
4
5
6
7
8
9
10
{
  "channels": {
    "telegram": {
      "enabled": true,
      "botToken": "YOUR_BOT_TOKEN",
      "dmPolicy": "pairing",
      "allowFrom": ["tg:YOUR_USER_ID"]
    }
  }
}

Step 3: Start and Pair

1
2
3
4
5
# Restart Gateway
openclaw gateway restart

# Send a message to the bot in Telegram
# You'll receive a pairing verification code

Feishu Integration

1
2
# Run configuration wizard
openclaw configure --section feishu

You need to create an enterprise self-built app in the Feishu Open Platform and obtain App ID and App Secret.

Multi-Channel Configuration

You can configure multiple channels simultaneously:

1
2
3
4
5
6
7
{
  "channels": {
    "telegram": { "enabled": true, "botToken": "..." },
    "feishu": { "enabled": true, "appId": "...", "appSecret": "..." },
    "discord": { "enabled": true, "botToken": "..." }
  }
}

Configuration Guide

Configuration File Locations

File Path Description
Main Config ~/.openclaw/openclaw.json Gateway, channels, models
Agent Config ~/.openclaw/agents/*/agent/ Individual agent configs
Workspace ~/.openclaw/workspace-*/ Agent workspaces

Model Configuration

Edit ~/.openclaw/openclaw.json:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
{
  "models": {
    "mode": "merge",
    "providers": {
      "bailian": {
        "baseUrl": "https://dashscope.aliyuncs.com/compatible-mode/v1",
        "apiKey": "sk-YOUR_API_KEY",
        "api": "openai-completions",
        "models": [
          {
            "id": "qwen3.5-plus",
            "name": "qwen3.5-plus",
            "contextWindow": 1000000,
            "maxTokens": 65536
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "bailian/qwen3.5-plus"
      }
    }
  }
}

Provider Model Use Case
Alibaba Cloud qwen3.5-plus General tasks, cost-effective
Anthropic Claude Opus 4.6 Programming, code generation
Zhipu glm-5 Optimized for Chinese tasks
Moonshot AI kimi-k2.5 Long text processing

5.4 Gateway Configuration

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{
  "gateway": {
    "port": 18789,
    "mode": "local",
    "bind": "lan",
    "auth": {
      "mode": "token",
      "token": "your-secure-token"
    },
    "controlUi": {
      "allowedOrigins": ["http://192.168.1.100:18789"],
      "allowInsecureAuth": true
    }
  }
}

Authentication Modes

Token Authentication (Recommended for API Integration):

1
2
3
4
5
6
7
8
{
  "gateway": {
    "auth": {
      "mode": "token",
      "token": "your-token"
    }
  }
}

Password Authentication (Recommended for Web UI):

1
2
3
4
5
6
7
{
  "gateway": {
    "auth": {
      "mode": "password"
    }
  }
}

Multi-Agent Configuration

What is Multi-Agent?

OpenClaw supports running multiple independent Agent instances, where each Agent can:

  • Use different model configurations
  • Have independent workspaces and memory
  • Focus on specific types of tasks
  • Configure Skills and tools independently

Built-in Agent Types

Agent Purpose Recommended Model
main Main conversation Agent, handles daily tasks qwen3.5-plus
chat Pure chat Agent, casual conversation qwen3.5-plus
coding Programming Agent, code generation/review Claude Opus 4.6
analysis Data analysis Agent qwen3.5-plus

Creating Custom Agents

1
2
3
4
5
6
7
8
9
10
11
# Create new Agent
openclaw agents create my-agent

# Set dedicated model
openclaw agents config my-agent --model glm-5

# Configure workspace
openclaw agents workspace my-agent --path ~/projects/my-agent

# Start Agent
openclaw agents start my-agent

Assign Agents to Different Tasks

Task Type Recommended Agent Invocation
Daily conversation, Q&A main Default
Writing code, Debugging coding /agent coding
Data analysis, Reports analysis /agent analysis
Creative writing chat /agent chat
Domain-specific tasks Custom Agent /agent <name>

Agent Routing Configuration

Method 1: Command Prefix

1
2
/agent coding Help me write a Python script
/agent analysis Analyze this data

Method 2: Automatic Routing (Keyword-based)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
  "routing": {
    "rules": [
      {
        "keywords": ["code", "programming", "python", "javascript"],
        "agent": "coding"
      },
      {
        "keywords": ["analyze", "data", "chart"],
        "agent": "analysis"
      }
    ]
  }
}

Method 3: Channel Binding

1
2
3
4
5
6
7
8
9
10
{
  "channels": {
    "telegram": {
      "defaultAgent": "main"
    },
    "discord": {
      "defaultAgent": "chat"
    }
  }
}

Multi-Agent Best Practices

✅ Recommended:

  • Create dedicated Agents for high-frequency tasks
  • Use separate Agents for programming (avoid context pollution)
  • Create independent Agent instances for different projects
  • Regularly clean up inactive Agents

❌ Avoid:

  • Creating too many Agents (recommended ≤5)
  • All Agents using the same model (wastes resources)
  • Ignoring memory isolation between Agents

View and Manage Agents

1
2
3
4
5
6
7
8
9
10
11
12
13
14
# List all Agents
openclaw agents list

# Check Agent status
openclaw agents status my-agent

# View Agent configuration
openclaw agents config my-agent --show

# Stop Agent
openclaw agents stop my-agent

# Delete Agent
openclaw agents delete my-agent

Multi-Agent Architecture Example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
┌─────────────────────────────────────────────────────────┐
│                    User Message                         │
└────────────────────┬────────────────────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────────────────────┐
│              Routing Layer (distributes by rules)       │
│   Keyword Matching / Command Prefix / Channel Binding   │
└──────────┬──────────────┬──────────────┬────────────────┘
           │              │              │
           ▼              ▼              ▼
    ┌──────────┐   ┌──────────┐   ┌──────────┐
    │   main   │   │  coding  │   │ analysis │
    │  Agent   │   │  Agent   │   │  Agent   │
    └────┬─────┘   └────┬─────┘   └────┬─────┘
         │              │              │
         ▼              ▼              ▼
    ┌──────────┐   ┌──────────┐   ┌──────────┐
    │ General  │   │  Code    │   │   Data   │
    │  Memory  │   │  Skills  │   │  Tools   │
    │ Qwen3.5  │   │  Claude  │   │  Pandas  │
    └──────────┘   └──────────┘   └──────────┘

Here’re the Telegram Bot I’ve configured with diffent agent roles:

pic

Skills System

What are Skills?

Skills are OpenClaw’s plugin system, enabling AI to:

  • Access external APIs (weather, news, stocks)
  • Operate local resources (files, cameras)
  • Execute specific tasks (GitHub, calendar, email)

Installing Skills

1
2
3
4
5
6
7
8
9
10
11
# Install from ClawHub
openclaw skill install <skill-slug>

# Search Skills
openclaw skill search <keyword>

# List installed
openclaw skill list

# Update Skills
openclaw skill update

Skill Function Install Command
weather Weather forecast openclaw skills install weather
github GitHub operations openclaw skills install github
news-aggregator News aggregation npx skills add https://github.com/BODYsuperman/world-news-aggregator-skill
pinchtab-browser Browser automation openclaw skills install pinchtab-browser

Creating Custom Skills

1
2
3
4
5
6
7
8
9
10
11
12
13
# Create Skill directory
mkdir -p ~/.openclaw/workspace-main/skills/my-skill

# Create SKILL.md
cat > ~/.openclaw/workspace-main/skills/my-skill/SKILL.md << 'EOF'
# my-skill

## Description
My custom skill

## Usage
/MyCommand [arguments]
EOF

Memory System

Memory Types

Type File Description
Long-term Memory MEMORY.md Curated important information
Daily Memory memory/YYYY-MM-DD.md Raw logs
Identity IDENTITY.md AI personality settings
User USER.md User information
Soul SOUL.md Behavioral guidelines

Memory File Locations

1
2
3
4
5
6
7
8
9
10
11
~/.openclaw/workspace-main/
├── MEMORY.md              # Long-term memory
├── IDENTITY.md            # Identity settings
├── USER.md                # User information
├── SOUL.md                # Behavioral guidelines
├── AGENTS.md              # Workspace description
├── TOOLS.md               # Tool notes
├── HEARTBEAT.md           # Heartbeat tasks
└── memory/
    ├── 2026-03-16.md      # Daily memory
    └── 2026-03-15.md

Search Memory

1
2
3
4
5
# Semantic search
openclaw memory search "project mentioned last time"

# Search by date
openclaw memory search --date 2026-03-15 "meeting"

Memory Maintenance

Recommended to review MEMORY.md regularly (weekly):

  • Remove outdated information
  • Add new decisions and context
  • Organize highlights from daily memory files

Scheduled Tasks

Cron Basics

1
2
3
4
5
6
7
8
9
10
11
# Add scheduled task
openclaw cron add --schedule "0 9 * * *" --message "Good morning! Today's tasks:"

# List tasks
openclaw cron list

# Run task
openclaw cron run <job-id>

# Remove task
openclaw cron remove <job-id>

Cron Expressions

Expression Description
0 9 * * * Daily at 9:00
0 9 * * 1 Every Monday at 9:00
*/30 * * * * Every 30 minutes
0 0 1 * * 1st of each month at 0:00

Heartbeat Tasks

Edit HEARTBEAT.md:

1
2
3
4
5
6
# HEARTBEAT.md

- [ ] Check unread emails
- [ ] View calendar (within 24 hours)
- [ ] Check weather (if going out)
- [ ] Review memory files (weekly)

Practical Cron Examples

Daily News Briefing:

1
2
3
4
openclaw cron add \
  --name "daily-news" \
  --schedule "0 8 * * *" \
  --message "Execute news-aggregator skill, send daily news"

Weekly Backup:

1
2
3
4
openclaw cron add \
  --name "weekly-backup" \
  --schedule "0 2 * * 0" \
  --message "Backup workspace and memory directories"

Common Commands

Gateway Management

1
2
3
4
5
6
openclaw gateway start      # Start
openclaw gateway stop       # Stop
openclaw gateway restart    # Restart
openclaw gateway status     # Status
openclaw gateway install    # Install as system service
openclaw gateway uninstall  # Uninstall service

Configuration Management

1
2
3
4
5
6
openclaw onboard            # Initial setup wizard
openclaw configure          # Configure channels
openclaw doctor             # Health check
openclaw status             # Check status
openclaw dashboard          # Open web dashboard
openclaw tui                # Terminal interface

Model Management

1
2
3
openclaw models status      # Model status
openclaw models list        # List models
openclaw models add         # Add model

Channel Management

1
2
3
openclaw channels list      # List channels
openclaw channels add       # Add channel
openclaw channels remove    # Remove channel

Agent Management

1
2
3
4
5
6
openclaw agents list            # List Agents
openclaw agents create <name>   # Create Agent
openclaw agents config <name>   # Configure Agent
openclaw agents start <name>    # Start Agent
openclaw agents stop <name>     # Stop Agent
openclaw agents delete <name>   # Delete Agent

Memory Operations

1
2
3
openclaw memory search <query>   # Search memory
openclaw memory list             # List memory files
openclaw memory edit             # Edit memory

Session Management

1
2
3
openclaw sessions list           # List sessions
openclaw sessions history <key>  # View history
openclaw sessions send           # Send message to session

Troubleshooting

Common Issues

Issue 1: openclaw: command not found

1
2
3
4
5
6
7
8
9
# Find npm global path
npm prefix -g

# Add to PATH
export PATH="$(npm prefix -g)/bin:$PATH"

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

Issue 2: Gateway fails to start

1
2
3
4
5
6
7
8
# Check port usage
lsof -i :18789

# View logs
journalctl --user -u openclaw-gateway.service -n 50

# Restart service
systemctl --user restart openclaw-gateway.service

Issue 3: Not receiving Telegram messages

1
2
3
4
5
6
7
8
# Check if Bot Token is correct
cat ~/.openclaw/openclaw.json | grep botToken

# Check if offset is updated
cat ~/.openclaw/telegram/update-offset-*.json

# View Gateway logs
journalctl -t gateway-start.sh -n 30 | grep telegram

Issue 4: Model API call failures

1
2
3
4
5
6
7
8
9
# Check API Key
openclaw models status

# Test connection
curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.example.com/v1/models

# Check network
ping api.example.com

Viewing Logs

1
2
3
4
5
6
7
8
9
# Gateway logs
journalctl --user -u openclaw-gateway.service -f

# Last 50 entries
journalctl --user -u openclaw-gateway.service -n 50

# Specific time range
journalctl --user -u openclaw-gateway.service \
  --since "2026-03-16 10:00:00" --until "2026-03-16 12:00:00"

Diagnostic Commands

1
2
3
4
5
6
7
8
# Full diagnostics
openclaw doctor

# Check system
openclaw status

# Check configuration
openclaw config list

11.4 Reset & Recovery

1
2
3
4
5
6
7
8
9
10
# Reset configuration (use with caution)
openclaw onboard --reset

# Reinstall Gateway
openclaw gateway uninstall
openclaw gateway install

# Clear cache
rm -rf ~/.openclaw/browser
rm -rf ~/.openclaw/cron

Appendix

Resource Link
OpenClaw-Cookbook https://github.com/BODYsuperman/OpenClaw-Cookbook

B. Version Information

  • Document Version: v1.1
  • Applicable OpenClaw Version: v2026.3.11+
  • Last Updated: 2026-03-17

C. Contributors

This document integrates content from:

  • OpenClaw Orange Book (Hua Shu)
  • Datawhale OpenClaw Tutorial
  • APIFox OpenClaw User Guide
  • OpenClaw Official Documentation

For questions or suggestions, please provide feedback to the OpenClaw community.