OpenClaw Setup Wizard

OpenClaw Setup Wizard

The OpenClaw Setup Wizard provides an interactive, guided configuration experience for new users. It handles everything from initial setup to service installation.

Running the Wizard

Basic Wizard

# Start the interactive wizard
openclaw onboard

# Or with service installation
openclaw onboard --install-daemon

Advanced Wizard Options

# Wizard with custom configuration path
OPENCLAW_CONFIG_PATH=/custom/path/config.json openclaw onboard

# Wizard with specific profile
openclaw onboard --profile production

# Wizard with verbose output
openclaw onboard --verbose

Wizard Steps

The wizard guides you through several configuration steps:

1. Welcome and Overview

The wizard starts with an introduction to OpenClaw:

🦞 Welcome to OpenClaw!

OpenClaw is a multi-platform gateway that bridges messaging apps
to AI agents. This wizard will help you configure your installation.

Press Enter to continue...

2. Environment Check

The wizard verifies your system meets requirements:

✓ Node.js version: 22.1.0
✓ Package manager: npm found
✓ System: macOS (arm64)
✓ Memory: 16GB available
✓ Disk space: 250GB available

✓ Environment check passed!

If requirements aren’t met, the wizard provides installation guidance.

3. Installation Type

Choose your installation preference:

Select installation type:
1) Global npm install (Recommended)
2) Source installation (Development)
3) Docker container (Isolated)

Choice [1]:

4. Configuration Path

Set up your configuration location:

Configuration will be stored at: ~/.openclaw/
Press Enter to accept, or specify custom path:

5. Gateway Configuration

Configure the core Gateway settings:

Gateway Configuration:
- Port: 18789 (default)
- Bind address: 127.0.0.1 (loopback only)
- Enable authentication: Yes
- Generate token: Yes

Configure Gateway? [Y/n]:

6. Channel Selection

Choose which messaging platforms to enable:

Select messaging channels:
[ ] WhatsApp (requires phone)
[ ] Telegram (requires bot token)
[ ] Discord (requires bot token)
[ ] iMessage (macOS only)
[ ] Mattermost (plugin)

Select channels (space-separated numbers): 1 2

7. Agent Configuration

Set up the AI agent:

Agent Configuration:
- Agent type: Pi (default)
- Model: claude-3.5-sonnet
- Max tokens: 4096
- Temperature: 0.7

Configure agent? [Y/n]:

8. Security Settings

Configure security options:

Security Configuration:
- Enable sandboxing: Yes
- Require authentication: Yes
- Log level: info
- Backup config: Yes

Apply security defaults? [Y/n]:

9. Service Installation

Install system service for automatic startup:

Service Installation:
- Install as user service: Yes
- Auto-start on boot: Yes
- Restart on failure: Yes

Install service? [Y/n]:

10. Summary and Confirmation

Review your configuration before applying:

Configuration Summary:
- Installation: Global npm
- Gateway: Port 18789, Loopback only
- Channels: WhatsApp, Telegram
- Agent: Pi with Claude 3.5 Sonnet
- Security: Sandboxing enabled
- Service: User service installed

Apply configuration? [Y/n]:

Automated Configuration

Non-Interactive Mode

For automated deployments, use non-interactive mode:

openclaw onboard --auto \
  --install-type global \
  --gateway-port 18789 \
  --channels whatsapp,telegram \
  --agent-model claude-3.5-sonnet \
  --install-daemon

Configuration File

You can provide a configuration file:

# Create config file
cat > openclaw-config.json << EOF
{
  "gateway": {
    "port": 18789,
    "bind": "127.0.0.1"
  },
  "channels": {
    "whatsapp": true,
    "telegram": true
  },
  "agent": {
    "model": "claude-3.5-sonnet",
    "maxTokens": 4096
  },
  "security": {
    "sandboxing": true,
    "authentication": true
  }
}
EOF

# Apply configuration
openclaw onboard --config openclaw-config.json

Profiles

The wizard includes predefined profiles for different use cases:

Development Profile

openclaw onboard --profile development

Includes:

• Verbose logging
• Debug mode enabled
• Source installation
• No service installation

Production Profile

openclaw onboard --profile production

Includes:

• Minimal logging
• Security hardening
• Service installation
• Monitoring enabled

Testing Profile

openclaw onboard --profile testing

Includes:

• Isolated configuration
• Mock services
• Test data
• No persistent storage

Custom Profiles

Create your own wizard profiles:

# Create custom profile
mkdir -p ~/.openclaw/profiles
cat > ~/.openclaw/profiles/custom.json << EOF
{
  "name": "Custom Setup",
  "description": "My custom OpenClaw configuration",
  "installation": {
    "type": "global",
    "service": true
  },
  "gateway": {
    "port": 19000,
    "bind": "0.0.0.0"
  },
  "channels": ["whatsapp", "discord"],
  "agent": {
    "model": "gpt-4",
    "temperature": 0.5
  },
  "security": {
    "sandboxing": false,
    "authentication": true
  }
}
EOF

# Use custom profile
openclaw onboard --profile custom

Troubleshooting the Wizard

Common Issues

Wizard hangs during setup

# Cancel with Ctrl+C and restart
openclaw onboard --force

# Check system logs
openclaw wizard logs

Permission errors

# Run with appropriate permissions
sudo openclaw onboard --install-daemon

# Or use user directory
openclaw onboard --user-dir

Network connectivity issues

# Use offline mode
openclaw onboard --offline

# Or specify mirror
openclaw onboard --npm-mirror https://registry.npmjs.org/

Debug Mode

Enable detailed wizard logging:

# Run wizard with debug output
openclaw onboard --debug

# Save wizard logs
openclaw onboard --log-file wizard.log

Reset Configuration

If wizard configuration fails, reset and retry:

# Reset wizard state
openclaw wizard reset

# Clear all configuration
openclaw wizard reset --full

# Start fresh
openclaw onboard

Wizard Configuration Files

Main Config

After completion, the wizard creates ~/.openclaw/openclaw.json:

{
  gateway: {
    port: 18789,
    bind: "127.0.0.1",
    token: "generated-token-here"
  },
  channels: {
    whatsapp: {
      enabled: true,
      allowFrom: []
    },
    telegram: {
      enabled: true,
      botToken: ""
    }
  },
  agents: {
    default: {
      type: "pi",
      model: "claude-3.5-sonnet"
    }
  },
  security: {
    sandboxing: true,
    authentication: true
  }
}

Service Files

The wizard installs system service files:

macOS (launchd): ~/Library/LaunchAgents/com.openclaw.gateway.plist
Linux (systemd): ~/.config/systemd/user/openclaw-gateway.service

Environment Files

Creates environment configuration:

~/.openclaw/env

OPENCLAW_CONFIG_PATH=~/.openclaw/openclaw.json
OPENCLAW_STATE_DIR=~/.openclaw/state
OPENCLAW_LOG_LEVEL=info

Post-Wizard Steps

After the wizard completes:

1. Verify Installation

# Check Gateway status
openclaw gateway status

# Test configuration
openclaw config validate

# View summary
openclaw wizard summary

2. Complete Channel Setup

# WhatsApp login
openclaw channels login whatsapp

# Add bot tokens
openclaw config set channels.telegram.botToken YOUR_TOKEN

3. Open Dashboard

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

4. Send Test Message

# Test your setup
openclaw message test

Advanced Wizard Features

Migration Mode

Migrate from existing installation:

# Migrate from old config
openclaw onboard --migrate /path/to/old/config

# Import from Clawdbot/Moltbot
openclaw onboard --import moltbot

Update Mode

Update existing configuration:

# Re-run wizard to update
openclaw onboard --update

# Add new channels only
openclaw onboard --add-channels discord,slack

Backup and Restore

# Backup wizard configuration
openclaw wizard backup

# Restore from backup
openclaw wizard restore openclaw-backup-2024-01-15.json

Next Steps

After completing the wizard:

• Configure specific channels - Complete platform setup
• Set up agents - Configure AI assistants
• Explore the dashboard - Learn the web interface
• Security hardening - Production security setup

---

The OpenClaw Setup Wizard makes getting started easy and ensures your configuration is secure and optimized from the start! 🧙‍♂️