OpenClaw — a complete beginner’s guide

🚀What Is OpenClaw?

OpenClaw is a personal AI assistant that runs on your own device. It can interact with you through the messaging channels you already use (WhatsApp, Telegram, Slack, Discord, Google Chat, Signal, iMessage, Microsoft Teams, WebChat, and more), and also supports advanced features such as voice conversations and Canvas visualization.

OpenClaw is a local-first AI assistant gateway. Its core design philosophy is:

• Personal: serves you as an individual, not an enterprise-grade multi-user system
• Runs locally: the Gateway runs on your device (macOS, Linux, Windows WSL2)
• Multi-channel access: supports nearly all mainstream messaging platforms
• Feature-rich: browser control, Canvas visualization, voice interaction, scheduled tasks, and more

Architecture Overview

WhatsApp / Telegram / Slack / Discord / Google Chat / Signal / iMessage / WebChat
               │
               ▼
┌───────────────────────────────┐
│            Gateway            │
│       (Control Plane - Core)        │
│     ws://127.0.0.1:18789      │
└──────────────┬────────────────┘
               │
               ├─ AI Agent (Agent)
               ├─ CLI command-line tool
               ├─ WebChat web interface
               ├─ macOS/iOS/Android clients
               └─ Browser control (Chrome CDP)

📦Installation Guide

System Requirements

• Node.js ≥ 22 (required)
• Operating system: macOS, Linux, Windows (WSL2)
• Package manager: npm, pnpm, or bun

Quick Install (Recommended)

macOS / Linux

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

Windows (PowerShell)

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

npm Install

# Using npm
npm install -g openclaw@latest

# Or using pnpm
pnpm add -g openclaw@latest

Run the Onboarding Wizard

# Full install wizard + install system service
openclaw onboard --install-daemon

# Run the configuration wizard only
openclaw onboard

Verify the Installation

# Check Gateway status
openclaw gateway status

# Open the dashboard
openclaw dashboard

⚡Quick Start

1. Start the Gateway

# Run in the foreground (good for debugging)
openclaw gateway --port 18789 --verbose

# Use the daemon (run in the background)
openclaw gateway start

2. Open the Dashboard

openclaw dashboard
# Or open directly in your browser:
# http://127.0.0.1:18789

3. Send a Test Message

openclaw message send --to +15555550123 --message "Hello from OpenClaw"

4. Chat with the Agent

# Chat directly from the command line
openclaw agent --message "Summarize today's meeting for me" --thinking high

📁Workspace

The Workspace is the OpenClaw agent's working directory, and the only place where it reads context, saves memory, and performs tool operations.

Workspace Structure

~/.openclaw/
├── openclaw.json # Main configuration file
├── workspace/ # Default workspace│
├── AGENTS.md # Operating instructions and memory│
├── SOUL.md # Personality, boundaries, tone│
├── TOOLS.md # Tool usage notes│
├── IDENTITY.md # Assistant name/avatar/emoji│
├── USER.md # User information│
├── MEMORY.md # Long-term memory (loaded only in the main session)│
└── skills/ # Workspace-level skills
├── agents/ # Multi-agent session storage
├── skills/ # Global skills
└── credentials/ # Credential storage

Core Files Explained

⚙️Configuring openclaw.json

~/.openclaw/openclaw.json is OpenClaw's core configuration file, written in JSON5 format (which supports comments and trailing commas).

Minimal Configuration Example

{
  "agents": {
    "defaults": {
      "workspace": "~/.openclaw/workspace"
    }
  },
  "channels": {
    "telegram": {
      "enabled": true,
      "botToken": "123456:ABC...",
      "dmPolicy": "pairing",
      "allowFrom": ["tg:123456789"]
    }
  }
}

Agents Configuration

{
  "agents": {
    "defaults": {
      "workspace": "~/.openclaw/workspace",
      "model": {
        "primary": "anthropic/claude-sonnet-4-5",
        "fallbacks": ["openai/gpt-5.2"]
      },
      "heartbeat": {
        "every": "30m",
        "target": "last"
      }
    }
  }
}

Session Management

{
  "session": {
    "dmScope": "per-channel-peer",
    "reset": {
      "mode": "daily",
      "atHour": 4,
      "idleMinutes": 120
    }
  }
}

💬Configuring Conversation Endpoints (Channels)

DM Security Policies

Telegram Configuration

{
  "channels": {
    "telegram": {
      "enabled": true,
      "botToken": "your-bot-token",
      "dmPolicy": "pairing",
      "allowFrom": ["tg:123456789"],
      "streaming": "partial"
    }
  }
}

🤖Configuring Multi-Agent Setups

{
  "agents": {
    "defaults": {
      "workspace": "~/.openclaw/workspace"
    },
    "list": [
      {
        "id": "main",
        "description": "General-purpose assistant"
      },
      {
        "id": "coder",
        "workspace": "~/.openclaw/workspace-coder",
        "description": "Coding expert"
      }
    ]
  }
}

🧩Installing Skills

OpenClaw uses a skill system to extend its functionality. Skills are reusable functional modules that can be installed from clawhub.com via the ClawHub CLI.

💡 Skills let you add new capabilities with a single command, such as image generation, weather lookups, GitHub operations, video processing, and more, without manually configuring each tool.

Install the ClawHub CLI

First, make sure the ClawHub command-line tool is installed:

npm install -g clawhub

Search for Skills

Search ClawHub for the skills you need:

# Search by keyword
clawhub search "postgres backups"
clawhub search "image generation"
clawhub search "weather"

Install a Skill

Once you find the skill you want, install it with the following command:

# Install the latest version
clawhub install baoyu-image-gen

# Install a specific version
clawhub install baoyu-image-gen --version 1.2.3

Manage Skills

Recommended Popular Skills

How Skills Work

A skill is a folder that contains the following:

my-skill/
├── SKILL.md # Skill definition and usage instructions
└── Other files # Scripts, configuration, etc.

✅ After installation, OpenClaw automatically recognizes the skill's capabilities and invokes it when a relevant task is triggered. No extra configuration is needed.

Publish Your Own Skill

If you've developed your own skill, you can publish it to ClawHub to share:

# Log in to ClawHub
clawhub login

# Publish the skill
clawhub publish ./my-skill \
  --slug my-skill \
  --name "My Skill" \
  --version 1.0.0 \
  --changelog "Initial release"

⚠️ Note: The default skill registry is https://clawhub.com, which can be overridden via the CLAWHUB_REGISTRY environment variable or the --registry parameter.

⌨️Common CLI Commands

Gateway Management

# Check status
openclaw gateway status

# Start/stop/restart
openclaw gateway start
openclaw gateway stop
openclaw gateway restart

Configuration Management

# Run the configuration wizard
openclaw onboard

# Get/set configuration values
openclaw config get agents.defaults.workspace
openclaw config set agents.defaults.model.primary "openai/gpt-5.2"

Diagnostic Tools

# Health check
openclaw doctor

# Auto-fix
openclaw doctor --fix

# View logs
openclaw logs --follow

🔒Security Best Practices

⚠️ Never expose DMs publicly without protection:
use dmPolicy: "pairing" or allowlist instead of open

Multi-User Environments

{
  "session": {
    "dmScope": "per-channel-peer"
  }
}

Sandboxed Execution

{
  "agents": {
    "defaults": {
      "sandbox": {
        "mode": "non-main",
        "scope": "agent"
      }
    }
  }
}

🔧Troubleshooting

🔗Resources

• Official site: openclaw.ai
• Documentation: docs.openclaw.ai
• GitHub: github.com/openclaw/openclaw
• Discord: discord.gg/clawd
• Skill marketplace: clawhub.com

📝Summary

OpenClaw is a powerful and flexible personal AI assistant platform. Key takeaways:

1. The Gateway is the core - everything revolves around the Gateway
2. The Workspace is your working space - keep files tidy and control token usage
3. Configuration as code - openclaw.json defines all behavior
4. Security first - use pairing mode by default and open DMs with caution
5. Multi-agent support - create specialized assistants for different tasks

Enjoy using it!🦞