Getting Started with OpenClaw

Getting Started with OpenClaw

Welcome to OpenClaw! This guide will help you get your multi-platform AI gateway running in minutes.

Prerequisites

Before you begin, make sure you have:

• Node.js 22+ - Required runtime
• npm or pnpm - Package manager
• One or more messaging platforms - WhatsApp, Telegram, Discord, or iMessage (macOS)

Installation Methods

Method 1: Global npm Install (Recommended)

The easiest way to install OpenClaw globally on your system:

# Install OpenClaw globally
npm install -g openclaw@latest

# Or using pnpm
pnpm add -g openclaw@latest

Method 2: Source Installation

For developers or custom builds:

# Clone the repository
git clone https://github.com/openclaw/openclaw.git
cd openclaw

# Install dependencies
pnpm install

# Build the project
pnpm build

# Build UI components
pnpm ui:build

Initial Setup

1. Run the Onboarding Wizard

The onboarding wizard configures OpenClaw for your environment:

# Run onboarding and install as a service
openclaw onboard --install-daemon

The wizard will:

• Create configuration files
• Set up the system service (launchd/systemd)
• Generate security tokens
• Configure default settings

2. Start the Gateway

The Gateway is the core component that manages all connections:

# Start the Gateway (if not running as a service)
openclaw gateway --port 18789

If installed as a service, the Gateway starts automatically.

3. Connect Your Messaging Platforms

WhatsApp

# Login to WhatsApp Web (shows QR code)
openclaw channels login whatsapp

# Scan the QR code with WhatsApp on your phone

Telegram

# Create a bot at https://t.me/BotFather
# Get your bot token and add it to config:
openclaw config set channels.telegram.botToken YOUR_BOT_TOKEN

Discord

# Create a Discord application at https://discord.com/developers/applications
# Get your bot token and add it to config:
openclaw config set channels.discord.botToken YOUR_BOT_TOKEN

iMessage (macOS only)

# iMessage works with the local imsg CLI
# No additional setup required

Verify Installation

Check Gateway Status

# Check if Gateway is running
openclaw gateway status

# View active connections
openclaw gateway connections

Open the Dashboard

Access the web dashboard at: http://127.0.0.1:18789/

From the dashboard you can:

• Monitor active channels
• Configure settings
• View message logs
• Manage agent connections

Send a Test Message

# Send a test message (replace with actual phone number)
openclaw message send --target +15555550123 --message "Hello from OpenClaw!"

Configuration

OpenClaw configuration is stored at ~/.openclaw/openclaw.json.

Basic Configuration

{
  channels: {
    whatsapp: {
      allowFrom: ["+15555550123"], // Allowed phone numbers
      groups: { "*": { requireMention: true } } // Group chat settings
    },
    telegram: {
      botToken: "YOUR_BOT_TOKEN"
    }
  },
  messages: {
    groupChat: {
      mentionPatterns: ["@openclaw"] // Trigger patterns
    }
  }
}

Agent Configuration

OpenClaw uses the Pi agent by default in RPC mode:

{
  agents: {
    default: {
      type: "pi",
      rpc: {
        host: "127.0.0.1",
        port: 8080
      }
    }
  }
}

Next Steps

• Configure your channels - Set up specific platform features
• Set up agents - Configure AI agents and routing
• Explore the dashboard - Learn the web interface
• Security best practices - Secure your installation

Troubleshooting

Common Issues

Gateway won’t start

# Check logs
openclaw gateway logs

# Verify configuration
openclaw config validate

WhatsApp connection fails

• Ensure WhatsApp Web is not active elsewhere
• Check network connectivity
• Try re-scanning QR code

Permission errors

• Make sure user has sufficient permissions
• Consider running in Docker for isolation

Get Help

• Troubleshooting guide
• GitHub Issues
• Community Discord

---

Congratulations! You now have OpenClaw running and ready to bridge your messaging platforms to AI agents. 🦞