OpenClaw in 10 Minutes: Complete Setup Guide

OpenClaw in 10 Minutes ⚡

OpenClaw is a self-hosted AI assistant platform that connects to your messaging apps. One server, 20+ channels, full control over your data. By the end of this guide, you’ll have a working AI assistant you can message from your phone.

Prerequisites

Requirement	Details
OS	macOS, Linux, or Windows (WSL2 strongly recommended)
Node.js	v22 or newer (node --version to check)
AI Provider Key	Anthropic, OpenAI, Google, or any OpenAI-compatible provider
10 minutes	That’s it

Tip

Don’t have Node.js? The installer handles it automatically on macOS and Linux. On Windows, it tries winget → Chocolatey → Scoop.

Step 1: Install OpenClaw

import { Tabs, TabItem } from ‘@astrojs/starlight/components’;

```bash curl -fsSL https://openclaw.ai/install.sh | bash ``` This installs Node.js if needed (via Homebrew on macOS, NodeSource on Linux), installs Git if missing, and does a global npm install of OpenClaw. ```powershell iwr -useb https://openclaw.ai/install.ps1 | iex ``` Requires PowerShell 5+. Installs Node via winget/Chocolatey/Scoop if missing. ```bash curl -fsSL https://openclaw.ai/install-cli.sh | bash ``` Installs everything under `~/.openclaw` with its own Node runtime. No sudo needed. ```bash npm install -g openclaw@latest ``` If you already have Node 22+ and want to manage things yourself.

Verify the install

openclaw --version

openclaw: command not found?

This usually means npm’s global bin directory isn’t in your PATH. Run npm config get prefix — the binary lives in <prefix>/bin/. Add it to your shell’s PATH:

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

On Linux, if you get EACCES errors, the installer can switch npm’s prefix to ~/.npm-global. Re-run the installer or do it manually:

npm config set prefix ~/.npm-global
export PATH="$HOME/.npm-global/bin:$PATH"

Step 2: Run the Onboarding Wizard

openclaw onboard --install-daemon

The wizard walks you through everything:

1. Auth — Choose your AI provider and paste your API key (or use OAuth for Anthropic). Supports OpenAI, Anthropic, Google, and any OpenAI-compatible endpoint.
2. Workspace — Sets up ~/.openclaw/workspace/ with starter files (SOUL.md, AGENTS.md, USER.md).
3. Gateway — Configures the local server (default port 18789).
4. Channels — Connect WhatsApp, Telegram, Discord, Signal, Slack, and more.
5. Daemon — Installs a LaunchAgent (macOS) or systemd user unit (Linux) so OpenClaw starts automatically.
6. Skills — Installs recommended skills and optional dependencies.

QuickStart vs Advanced

The wizard defaults to QuickStart mode with sensible defaults (local gateway, token auth, standard ports). Choose Advanced if you want full control over every setting.

Model selection matters

Use the strongest model available for the best experience. Claude Opus or GPT-4o are recommended. Weaker models are more susceptible to prompt injection when processing external content (emails, webhooks).

Step 3: Verify the Gateway

If you used --install-daemon, the Gateway should already be running:

openclaw gateway status

You should see the Gateway running on port 18789. You can also test it immediately without any channel setup:

openclaw dashboard

This opens the Control UI in your browser at http://127.0.0.1:18789/ — you can chat with your agent right there.

Running without a daemon

For quick tests or troubleshooting, run the Gateway in the foreground:

openclaw gateway --port 18789

Step 4: Connect a Channel

Telegram (easiest to set up)

1. Open @BotFather on Telegram
2. Send /newbot and follow the prompts
3. Copy the bot token (looks like 123456:ABC-DEF...)
4. Paste it when the wizard asks — or add it later:

   openclaw configure --section channels

5. Message your bot on Telegram

WhatsApp

1. The wizard (or openclaw channels login --channel whatsapp) shows a QR code
2. Open WhatsApp on your phone → Settings → Linked Devices → Link a Device
3. Scan the QR code
4. Done — your assistant is live on WhatsApp

Discord

1. Go to discord.com/developers → New Application
2. Go to Bot → Reset Token → copy it
3. Enable Message Content Intent under Privileged Gateway Intents (required!)
4. Go to OAuth2 → URL Generator → select bot scope → select permissions → invite to your server
5. Paste the token in the wizard

Other channels

OpenClaw supports 20+ channels: Signal, Slack, Google Chat, iMessage, Matrix, Mattermost, IRC, Line, Nostr, and more. Run openclaw configure --section channels to add any of them.

Step 5: Send Your First Message

Open your messaging app and send anything to your bot:

“Hey, what can you do?”

Your AI assistant will respond. Out of the box, it can:

• 🔍 Search the web (set up a Brave Search API key via openclaw configure --section web for best results)
• 📁 Read and write files on your machine
• 🖥️ Run shell commands
• ⏰ Set reminders and cron jobs
• 🌐 Control a web browser
• 📷 Access cameras (with paired mobile nodes)
• 🎤 Voice conversations (macOS/iOS/Android)
• 📊 Manage sessions and spawn sub-agents

Step 6: Make It Yours

The real power is in the workspace files at ~/.openclaw/workspace/. These aren’t just config — they’re your agent’s brain.

SOUL.md — Personality & Boundaries

This defines who your agent is. Tone, values, what it will and won’t do.

# Who You Are

Be genuinely helpful, not performatively helpful.
Skip the "Great question!" — just help.

Have opinions. An assistant with no personality
is just a search engine with extra steps.

Be resourceful before asking. Try to figure it out.
Read the file. Search for it. Then ask if you're stuck.

👉 Full guide: Crafting the Perfect SOUL.md

AGENTS.md — Operating Instructions

How your agent handles tasks, memory, tools, and communication. This is the playbook.

USER.md — Who You Are

Tell your agent about yourself so it can be contextually helpful:

# About You
- **Name:** Alex
- **Timezone:** America/New_York
- **Notes:** Runs a startup. Time is scarce.
  Short messages = full expectations.

IDENTITY.md — Name & Avatar

Your agent’s name, emoji, and vibe. Created during the bootstrap ritual.

Troubleshooting

openclaw doctor

Run the built-in diagnostic tool:

openclaw doctor

This checks your install, config, credentials, and common issues.

Common issues

Problem	Fix
openclaw: command not found	Add npm’s bin directory to PATH (see Step 1)
Gateway won’t start	Check if port 18789 is in use: lsof -i :18789
WhatsApp QR code expired	Re-run openclaw channels login --channel whatsapp
spawn git ENOENT on Windows	Install Git for Windows, reopen PowerShell
sharp/libvips build errors	Set SHARP_IGNORE_GLOBAL_LIBVIPS=1 (the installer does this by default)
Extra workspace directories	Keep one active workspace. openclaw doctor warns about extras. Remove old ones with trash ~/openclaw
EACCES on npm install (Linux)	Installer can fix this. Or manually: npm config set prefix ~/.npm-global

Environment variables

If you need custom paths:

• OPENCLAW_HOME — home directory for internal path resolution
• OPENCLAW_STATE_DIR — override state directory
• OPENCLAW_CONFIG_PATH — override config file path

What’s Next?

• Crafting the Perfect SOUL.md — Give your agent real personality
• 5 Automations That Save Hours — Cron jobs, heartbeats, email monitoring
• Multi-Agent Routing — One bot per channel
• Starter Kits — Pre-built configurations for specific workflows

---

Having issues? Run openclaw doctor to diagnose common problems, or check the OpenClaw docs.