AI
Builder Hub
Blog
What Is OpenClaw? Accurate Install Guide & Usage for Windows, macOS and Ubuntu
buildAI2026-03-1710 min

What Is OpenClaw? Accurate Install Guide & Usage for Windows, macOS and Ubuntu

The accurate OpenClaw 🦞 guide — local-first AI assistant with 250k+ GitHub stars: install via npm in one command, configure via openclaw.json, connect Telegram/Discord/WhatsApp, understand Gateway, Sessions, Skills and the security model.

OpenClaw 🦞 is an open-source AI personal assistant with over 250,000 GitHub stars — one of the fastest-growing open-source AI projects of 2025-2026. Originally launched as Clawdbot (November 2025), rebranded to Moltbot, then OpenClaw (early 2026), developed by Austrian programmer Peter Steinberger.

The core differentiator: OpenClaw is local-first — the Gateway runs on your machine, connecting to 20+ messaging platforms (Telegram, Discord, WhatsApp, Slack, Signal, iMessage...) so you can command the AI from anywhere.

OpenClaw AI assistant — install and use on Windows, macOS, Ubuntu

OpenClaw 🦞 — Local-first AI agent connecting 20+ messaging platforms

Core Concepts

ConceptExplanation
GatewayThe central control plane — runs locally at ws://127.0.0.1:18789, managing all channels, tools, and events
SessionA conversation session — stores context, history, and agent state
ChannelThe communication interface (Telegram, Discord, CLI terminal, WebChat...)
SkillExtension plugin at ~/.openclaw/workspace/skills/<skill>/SKILL.md
NodeHardware extension component (iOS, Android, camera, voice wake...)

Architecture overview:

Telegram / Discord / WhatsApp / Signal / iMessage...
                        │
                        ▼
            ┌─────────────────────┐
            │      Gateway        │  ← runs locally
            │  ws://127.0.0.1:18789│
            └──────────┬──────────┘
                       │
          ├─ AI Agent (RPC)
          ├─ CLI (openclaw ...)
          ├─ WebChat UI
          └─ macOS app / iOS / Android nodes

Installation

Requirements

  • Node.js ≥ 22 (required)
  • npm or pnpm

One-Command Install (Recommended)

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

# Then run onboarding (auto-installs launchd/systemd daemon):
openclaw onboard --install-daemon

The onboard --install-daemon command installs the Gateway as a background service — auto-starts with your OS (launchd on macOS, systemd on Linux).

Start the Gateway

openclaw gateway --port 18789 --verbose

Check Status

openclaw doctor

The doctor command checks your configuration, connections, and surfaces security risks.

Install From Source (For Developers)

git clone https://github.com/openclaw/openclaw.git
cd openclaw
pnpm install
pnpm ui:build        # build UI (auto-installs deps on first run)
pnpm build           # produces dist/

# Run onboarding:
pnpm openclaw onboard --install-daemon

# Dev loop (auto-reload on source/config changes):
pnpm gateway:watch

Basic Configuration

Main config file: ~/.openclaw/openclaw.json

Minimal config (just the AI model):

{
  "agent": {
    "model": "anthropic/claude-opus-4-6"
  }
}

With Telegram:

{
  "agent": {
    "model": "openai/gpt-4o"
  },
  "channels": {
    "telegram": {
      "token": "YOUR_BOT_TOKEN",
      "allowFrom": ["YOUR_TELEGRAM_USER_ID"]
    }
  }
}

With Ollama (fully offline local model):

{
  "agent": {
    "model": "ollama/qwen3.5:latest"
  }
}

Full configuration reference for all keys: docs.openclaw.ai/gateway/configuration

Supported Channels

OpenClaw supports 20+ platforms:

CategoryPlatforms
MessagingWhatsApp, Telegram, Signal, iMessage, BlueBubbles
WorkSlack, Discord, Microsoft Teams, Google Chat
SocialTwitch, Nostr, LINE, Zalo, Feishu
Self-hostedMatrix, Mattermost, Nextcloud Talk, Synology Chat
WebWebChat (built-in browser UI)

Basic Usage

After installation, interact via Telegram or the CLI:

# Send a message to the agent via CLI:
openclaw message send --to +1234567890 --message "Hello"

# Run the agent with a specific task:
openclaw agent --message "Ship checklist" --thinking high

# Approve a pairing request from a new user:
openclaw pairing approve telegram <code>

Common Chat Commands

# Find files
Find all PDFs in the Downloads folder created this week

# Summarize a document
Summarize /Documents/report.pdf

# Web search
Find the latest news about GPT-5 and summarize it

# Execute code
Run backup.sh and report the result

Real-World Use Cases

1. Personal File Management

"Find all Excel files named 'budget' on the Desktop,
 copy them to /Archive/2025/"

2. Browser Automation

"Open Chrome, go to gmail.com, read my 5 latest unread emails and summarize"

3. Research Agent

"Research the Astro.js framework, compare with Next.js,
 write a 300-word summary and save to ~/research/astro.md"

4. Voice Wake (macOS/iOS)

Set up the wake word "Hey Claw" → speak commands directly without opening any app.

5. Scheduled Task (Cron)

"Every morning at 8am: get weather + summarize tech news,
 send to my Telegram"

Skills System

Skills are extension plugins at ~/.openclaw/workspace/skills/<skill>/SKILL.md:

  • ClawHub — community skills marketplace
  • Skills inject context into the agent via AGENTS.md, SOUL.md, TOOLS.md
  • Custom skill: create a folder + SKILL.md with name and description frontmatter

Security Model — Read Before You Deploy

⚠️ OpenClaw connects to real messaging surfaces. Treat all inbound DMs as untrusted input.

DM Pairing (default behavior):

{
  "channels": {
    "telegram": {
      "dmPolicy": "pairing"  // unknown senders receive a pairing code and must verify
    }
  }
}

Approve a new user:

openclaw pairing approve telegram <code>

Sandbox for groups/channels (recommended):

{
  "agents": {
    "defaults": {
      "sandbox": {
        "mode": "non-main"  // non-main sessions run inside per-session Docker containers
      }
    }
  }
}

Safe update channels:

openclaw update --channel stable    # tagged stable releases
# or:
openclaw update --channel beta      # prerelease builds

Summary

OpenClaw is the right choice if you want:

  • ✅ Local-first AI agent — data never leaves your machine
  • ✅ Connect 20+ platforms (Telegram, Discord, WhatsApp...)
  • ✅ Simple install via one npm command
  • ✅ Deep customization via Skills and openclaw.json
  • ✅ Gateway daemon auto-runs in the background with your OS

Official resources: