Get Started with OpenClaw

Required Software & Accounts

• macOS, Linux, or Windows (WSL2 strongly recommended on Windows)
• Node.js 24 (recommended) or Node.js 22 LTS (22.16+) — powers the OpenClaw runtime
• An API key from a supported provider (Anthropic, OpenAI, etc.) — pay-as-you-go
• A messaging app — Telegram (easiest), WhatsApp, Discord, or another supported channel

Check Your Versions

node --version    # v24.x or v22.16+

System Requirements

• 2GB RAM minimum (4GB recommended for running multiple skills)
• 1GB free disk space
• macOS 12+, Linux (Ubuntu 20.04+, Debian 11+, etc.), or Windows 10+ (WSL2 strongly recommended)
• A stable internet connection for initial setup and LLM API calls

Install via Shell Script (Recommended)

The fastest way to get up and running. One command and you are ready.

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

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

Alternative: Install via npm

If you prefer using npm to manage global packages:

npm install -g openclaw@latest
openclaw onboard --install-daemon

Verify Installation

openclaw doctor
openclaw status

Launch the Wizard

openclaw onboard --install-daemon

QuickStart vs Advanced Mode

The wizard offers two modes to accommodate different preferences:

• QuickStart (Default) — Local gateway on loopback port 18789, auto-generated token auth, coding tool policy. Best for getting started quickly.
• Advanced — Full control over each step. Choose this if you want to customize gateway binding, auth mode, Tailscale exposure, and more.

Wizard Steps (in order)

The wizard guides you through these configuration steps:

• 1. Model/Auth — Select provider, pick default model. Supports API key, setup-token, or Custom auth.
• 2. Workspace — Set location (default: ~/.openclaw/workspace), seeds bootstrap files.
• 3. Gateway — Port, bind address, auth mode, Tailscale exposure.
• 4. Channels — Choose from WhatsApp, Telegram, Discord, Google Chat, Mattermost, Signal, BlueBubbles, iMessage.
• 5. Daemon — Installs LaunchAgent (macOS) or systemd user unit (Linux/WSL2).
• 6. Health Check — Starts Gateway, verifies operation.
• 7. Skills — Installs recommended skills with optional deps.

Configuration Output

The wizard creates your configuration at ~/.openclaw/openclaw.json and a workspace directory at ~/.openclaw/workspace/ containing your agent's files:

{
  "identity": { "name": "Clawd", "emoji": "🦞" },
  "agent": {
    "model": { "primary": "anthropic/claude-sonnet-4-6" }
  },
  "channels": {
    "telegram": { "enabled": true, "botToken": "TOKEN" }
  }
}

Verify Everything Works

# Check gateway and agent status
openclaw status

# Run health checks
openclaw health

# Diagnose issues
openclaw doctor

Telegram (Recommended for Beginners)

The easiest option to get started. Telegram is configured via config file or environment variable (not a login command).

• Open Telegram and message @BotFather
• Send /newbot and follow the prompts to create your bot
• Copy the bot token provided by BotFather
• Add the token to your config: set channels.telegram.botToken to your token in ~/.openclaw/openclaw.json
• Or set the environment variable: TELEGRAM_BOT_TOKEN=123:abc
• Start the gateway: openclaw gateway
• Approve pairing: openclaw pairing list telegram then openclaw pairing approve telegram <CODE>

WhatsApp

No bot account needed — OpenClaw connects directly to your personal WhatsApp account via QR code login.

• Install plugin if needed: openclaw plugins install @openclaw/whatsapp
• Login: openclaw channels login --channel whatsapp
• A QR code appears in your terminal
• Open WhatsApp on your phone > Settings > Linked Devices > Link a Device
• Scan the QR code — your agent is now available via WhatsApp
• Start the gateway: openclaw gateway
• Approve pairing if needed: openclaw pairing list then openclaw pairing approve <CODE>

Discord

Create a Discord application and bot to connect.

• Go to the Discord Developer Portal (discord.com/developers/applications)
• Create a new application, then add a Bot under the Bot tab
• Enable the Message Content Intent in bot settings
• Add the bot token to your OpenClaw config
• Start the gateway: openclaw gateway

DM Pairing

Both Telegram and WhatsApp use the pairing system to approve DM conversations. When someone messages your agent for the first time, they get a pairing code that you must approve.

# List pending pairing requests
openclaw pairing list

# Approve a pairing for a specific channel
openclaw pairing approve telegram <CODE>
openclaw pairing approve <CODE>

Adding More Channels Later

You can add or modify channels at any time:

# WhatsApp uses QR-based login
openclaw channels login --channel whatsapp

# Edit your configuration directly
openclaw config edit

Install & Update Skills

Use the clawhub CLI to install skills to your workspace:

# Install a skill by slug
clawhub install <skill-slug>

# Update all installed skills
clawhub update --all

# Query installed skills
openclaw skills list
openclaw skills info weather
openclaw skills check

Install via Chat

You can also ask your assistant to install skills directly from your messaging app. Just say something like:

• "Install the GitHub skill"
• "Find me a skill for weather updates"
• "What skills are available for productivity?"

Browse ClawHub

For a visual interface, browse the full skill registry online:

• clawhub.com — the main skill marketplace with reviews and ratings
• claw.tools — browse community tools and integrations

Skill Loading Order

Skills load from three locations, with higher priority overriding lower:

• Bundled (lowest priority) — Built-in skills that ship with OpenClaw (always available)
• Managed (~/.openclaw/skills) — Skills installed from ClawHub (community-maintained, audited)
• Workspace (workspace/skills/) (highest priority) — Custom skills you create in your workspace

IDENTITY.md — The Agent's Name, Vibe, and Emoji

Auto-created during bootstrap. Define who your agent is:

# Identity

## Name
Clawd

## Role
Personal AI assistant

## Goals
- Help with daily tasks and planning
- Provide quick answers to questions
- Manage reminders and schedules

SOUL.md — Persona, Tone, and Boundaries

Define your agent's persona, tone, and boundaries:

# Soul

## Personality
- Friendly and warm, but professional
- Concise — no unnecessary filler
- Uses humor sparingly and naturally

## Communication Style
- Always confirm before taking actions with real-world consequences
- Proactively suggest related tasks when relevant
- Keep responses brief in chat; offer to elaborate if needed
- Use bullet points for lists of 3+ items

USER.md — Who the User Is and How to Address Them

Help your agent understand who you are and how to address you:

# User Profile

## About Me
- Software engineer working on web applications
- Based in UTC-5 timezone
- Prefers TypeScript over JavaScript

## Preferences
- Use metric units for weather
- British English spelling
- Morning standup reminder at 9am

Other Workspace Files

Your workspace at ~/.openclaw/workspace includes several more files you can customize:

• AGENTS.md — Operating instructions for the agent and how it should use memory
• TOOLS.md — Notes about your local tools and conventions (does NOT control tool availability)
• MEMORY.md — Curated long-term memory (only loaded in main private session)
• memory/YYYY-MM-DD.md — Daily memory logs
• HEARTBEAT.md — Optional tiny checklist for heartbeat runs (keep it short to avoid token burn)
• BOOT.md — Optional startup checklist executed on gateway restart
• BOOTSTRAP.md — One-time first-run ritual (deleted after complete)
• skills/ — Workspace-specific skills

HEARTBEAT.md — Optional Tiny Checklist for Heartbeat Runs

Keep this file short to avoid token burn. Configure scheduled proactive check-ins:

# Heartbeat Configuration

## Morning Briefing
- Schedule: Every weekday at 8:30am
- Include: Weather, calendar events, top 3 TODO items

## Evening Wind-down
- Schedule: Every day at 6pm
- Include: Summary of completed tasks, pending reminders

Cron System for Scheduled Tasks

Use the cron system for recurring automated tasks:

# Add a scheduled task
openclaw cron add

DM Pairing System

OpenClaw uses a pairing system to ensure only authorized users can interact with your agent in DMs. Pairing codes expire after 1 hour.

• dmPolicy options: "pairing" (default), "allowlist", "open", "disabled"
• groupPolicy options: "allowlist" (default), "open", "disabled"

# List pending and approved pairings
openclaw pairing list

# Approve a new pairing request
openclaw pairing approve <CODE>

Sandbox Mode for Group Chats

In group chats, OpenClaw runs tool calls inside Docker containers for isolation. This prevents untrusted users from exploiting your agent's capabilities in shared channels.

Security Auditing

Regularly audit your agent's security posture:

# Run the built-in diagnostic tool with auto-fix
openclaw doctor --deep --yes

# Deep security audit
openclaw security audit --deep

Cost Management

Control API costs by switching models based on your needs. OpenClaw supports multiple model providers with different cost profiles. You can switch models mid-conversation with a chat command:

• Haiku — ~$0.001 per message (fast, great for simple tasks, cheapest option)
• Sonnet — ~$0.01 per message (balanced, good for most tasks)
• Opus — ~$0.10 per message (most capable, for complex reasoning)

/model list                          # See all available models
/model anthropic/claude-haiku-4-5    # Switch to cheapest option

Authentication

OpenClaw connects to LLM providers via API keys (pay-as-you-go):

• Anthropic API key — from console.anthropic.com (recommended for Claude models)
• OpenAI API key — from platform.openai.com
• Mistral, Google Gemini — API keys from their respective consoles
• Ollama — free local models, no API key needed

Remote Access

Access your agent from anywhere using secure tunneling:

• Tailscale — Zero-config VPN for accessing your gateway remotely
• SSH tunnel — Forward the gateway port (18789) over SSH for secure remote access

Useful CLI Commands

# Status and health
openclaw status
openclaw health
openclaw doctor

# Gateway management
openclaw gateway start
openclaw gateway stop
openclaw gateway restart

# Open the web dashboard
openclaw dashboard

# Send a message directly from CLI
openclaw message send "Hello from the terminal"

/status     # Check agent status
/new        # Start a new conversation
/compact    # Compress conversation history
/think high # Enable extended thinking
/verbose on # Enable verbose output
/restart    # Restart the agent

Gateway Won't Start

If your gateway fails to start or crashes on launch, run the built-in diagnostic tool to automatically detect and fix common issues:

# Auto-diagnose and fix common problems
openclaw doctor --deep --yes

# Check the gateway logs for errors
openclaw logs --follow

# Restart the gateway manually
openclaw gateway stop
openclaw gateway start

Bot Not Responding to Messages

If your agent is running but not replying to messages, check these common causes:

• Pairing not approved — new contacts must be paired first. Run: openclaw pairing list
• Channel disconnected — check channel status: openclaw channels status
• Gateway not running — verify with: openclaw status
• Wrong chat — make sure you are messaging the correct bot account (not yourself)

# Check if your channels are connected
openclaw channels status

# List pending pairing requests
openclaw pairing list

# Approve a pairing request
openclaw pairing approve <code>

"openclaw" Command Not Found

If your terminal says "command not found" after installation, it is almost always a PATH issue:

• Restart your terminal (close and reopen the window)
• Run: source ~/.bashrc (or source ~/.zshrc for Zsh users)
• Check where npm installed it: npm prefix -g
• Make sure the npm global bin directory is in your PATH

# Find where npm installs global packages
npm prefix -g

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

# Verify openclaw is now accessible
which openclaw
openclaw --version

High API Costs

If your API bill is higher than expected, consider switching to a cheaper model or using free local models:

• Switch to Haiku for simple tasks: /model anthropic/claude-haiku-4-5 (~$0.001 per message)
• Use Ollama for free local inference with no API costs at all
• Avoid Opus for routine tasks — reserve it for complex reasoning
• Monitor usage in the gateway dashboard at http://127.0.0.1:18789/

# List all available models and their costs
/model list

# Switch to the cheapest cloud model
/model anthropic/claude-haiku-4-5

# Or use free local models via Ollama
# Install Ollama from https://ollama.com, then:
openclaw config set agent.model.primary ollama/llama3

Getting Help

If you are still stuck, here is where to find the community and support resources:

• Discord — Join the OpenClaw community server for real-time help from other users and maintainers
• GitHub Issues — Report bugs or request features at the OpenClaw GitHub repository
• Documentation — Full reference docs are available at openclaw.ai/docs
• Ask your agent — Try asking your OpenClaw agent itself for help (it knows its own docs!)

Useful Diagnostic Commands

Keep these commands handy for debugging any issues:

# Full system status with all details
openclaw status --all --deep

# Verbose health check
openclaw health --verbose

# Auto-diagnose and fix issues
openclaw doctor --deep --yes

# View live gateway logs
openclaw logs --follow

# Gateway status and restart
openclaw gateway status
openclaw gateway restart

# Check channel connectivity
openclaw channels status

# List pairing requests
openclaw pairing list

# Verify skill integrity
openclaw skills check