?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

Workspace core files and their purposes
File Purpose When loaded
AGENTS.md Operating instructions, continuity rules, important memory First message of each session
SOUL.md Personality definition, tone, boundaries First message of each session
TOOLS.md Environment-specific tool descriptions First message of each session
USER.md User information, preferences, project background First message of each session
IDENTITY.md Assistant identity (name, emoji, avatar) First message of each session
MEMORY.md Long-term memory (security-sensitive content) Main session only

⚙️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

Comparison of messaging channel DM security policies
Policy Description Use case
pairing Unknown senders receive a pairing code and require the owner's approval Default, most secure
allowlist Allows only senders on the list Known contacts
open Allows all inbound DMs Public bots
disabled Ignores all DMs Group-only use

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

Common ClawHub CLI commands
Command Description Example
clawhub list List installed skills View all skills in the current workspace
clawhub update <skill> Update a specific skill to the latest version clawhub update baoyu-image-gen
clawhub update --all Update all skills Batch-update all installed skills
clawhub update --force Force update (ignore version check) Use when resolving version conflicts

Recommended Popular Skills

Recommended popular OpenClaw skills
Skill name Functionality Install command
baoyu-image-gen AI image generation (OpenAI, Google, Replicate, etc.) clawhub install baoyu-image-gen
weather Weather lookups and forecasts clawhub install weather
github GitHub operations (Issues, PRs, code review) clawhub install github
video-frames Video frame extraction and editing clawhub install video-frames
xurl X (Twitter) API operations clawhub install xurl
find-skills Helps discover and install skills clawhub install find-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

Common errors and their solutions
Error Cause Solution
Config validation failed Malformed configuration Run openclaw doctor
Unauthorized Invalid API Key Check the auth configuration
Session not found The session has expired Send /new to reset

?Resources

?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!?