OpenClaw Installation and Setup Guide

By ModelWise team - Professional AI Agent Solutions

This skill provides comprehensive guidance for installing, configuring, and running OpenClaw - an open-source personal AI assistant gateway.

Overview

OpenClaw is a multi-channel AI assistant gateway that enables users to use AI assistants on their existing messaging platforms (WhatsApp, Telegram, Slack, Discord, etc.).

Key Features:

Local-first architecture
20+ messaging channel integrations
Multi-model support (Anthropic, OpenAI, Google, local models)
Voice interaction (Voice Wake + Talk Mode)
Canvas visualization workspace (A2UI protocol)
Skills extension system

Prerequisites

System Requirements

Platform	Requirements
Windows	Windows 10/11, Node.js >= 22.12.0
macOS	macOS 12+, Node.js >= 22.12.0
Linux	Ubuntu 20.04+/Debian 11+, Node.js >= 22.12.0

Node.js Installation

Check Node.js version first:

node --version

Windows

# Option 1: Using winget
winget install OpenJS.NodeJS.LTS

# Option 2: Using Chocolatey
choco install nodejs-lts

# Option 3: Download installer
# https://nodejs.org/

macOS / Linux

# Install nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash

# Reload shell
source ~/.zshrc  # or ~/.bashrc

# Install Node.js 22
nvm install 22
nvm use 22
nvm alias default 22

Installation

Step 1: Install OpenClaw CLI

# All platforms
npm install -g openclaw@latest

# Verify installation
openclaw --version

Step 2: Run Configuration Wizard

# Start interactive configuration
openclaw onboard

# Or with daemon installation (recommended)
openclaw onboard --install-daemon

The wizard will guide through:

Model provider selection (Anthropic, OpenAI, Volcengine, etc.)
API key configuration
Channel setup (Telegram, Slack, etc.)
Gateway configuration

Step 3: Configure API Keys

API keys are stored in ~/.openclaw/credentials/ (or %USERPROFILE%\.openclaw\credentials\ on Windows).

# Set Anthropic API key
openclaw credentials set anthropic YOUR_API_KEY

# Set Volcengine API key (for Kimi)
openclaw credentials set volcengine YOUR_API_KEY

# Set OpenAI API key
openclaw credentials set openai YOUR_API_KEY

Step 4: Start Gateway

# Start gateway on default port (18789)
openclaw gateway

# Or specify port
openclaw gateway --port 18789

# Run in background (macOS/Linux)
openclaw gateway --daemon

# Windows: run in new window or use pm2
start /B openclaw gateway

Configuration

Config File Location

Platform	Path
macOS/Linux	`~/.openclaw/openclaw.json`
Windows	`%USERPROFILE%\.openclaw\openclaw.json`

Essential Configuration

{
  // Gateway settings
  gateway: {
    enabled: true,
    port: 18789,
    mode: "local",
    bind: "0.0.0.0"
  },

  // Agent settings
  agents: {
    defaults: {
      model: "volcengine/kimi-k2.5",
      thinking: {
        enabled: true,
        level: "medium"
      }
    }
  },

  // Telegram channel (example)
  telegram: {
    enabled: true,
    botToken: "YOUR_BOT_TOKEN",
    dmPolicy: "open",
    streaming: "partial"
  }
}

Model Provider Configuration

Provider	Model Format	Credentials Key
Anthropic	`anthropic/claude-opus-4-6`	`anthropic`
OpenAI	`openai/gpt-5.2`	`openai`
Volcengine	`volcengine/kimi-k2.5`	`volcengine`
Google	`google/gemini-2.5-pro`	`google`
Local	`local/llama-3.2`	N/A

Channel Setup

Telegram Bot Setup

Create Bot:
- Open @BotFather on Telegram
- Send /newbot
- Follow instructions to get bot token
Configure OpenClaw:

openclaw credentials set telegram 7123456789:AAHxxxxxxxx
openclaw config set telegram.enabled true
openclaw config set telegram.dmPolicy "open"

Restart Gateway:

openclaw gateway restart

Security Policies

DM Policy Options:

open: Accept messages from anyone (for public bots)
pairing: Require pairing code approval (default, more secure)

Common Commands

Diagnostics

# Check system status
openclaw doctor

# View running processes (macOS/Linux)
ps aux | grep openclaw | grep -v grep

# View running processes (Windows PowerShell)
Get-Process | Where-Object {$_.ProcessName -eq "node"}

# Check gateway status
openclaw gateway status

Updates

# Update to latest stable
openclaw update --channel stable

# Update to beta version
openclaw update --channel beta

Maintenance

# Stop gateway (macOS/Linux)
killall openclaw openclaw-gateway

# Stop gateway (Windows PowerShell)
Stop-Process -Name "node" -Force

# View logs
tail -f ~/.openclaw/logs/gateway.log  # macOS/Linux
Get-Content $env:USERPROFILE\.openclaw\logs\gateway.log -Tail 100  # Windows

# Clear sessions
openclaw sessions prune

Directory Structure

Platform	Base Path
macOS/Linux	`~/.openclaw/`
Windows	`%USERPROFILE%\.openclaw\`

.openclaw/
├── openclaw.json       # Main configuration
├── credentials/        # API keys (encrypted)
├── sessions/           # Session data
├── logs/               # Log files
├── workspace/          # Working directory
│   └── skills/         # Custom skills
├── agents/             # Agent configurations
├── canvas/             # Canvas data
├── browser/            # Browser profiles
└── memory/             # Memory storage

Troubleshooting

Common Issues

1. Node.js version mismatch:

# Check version
node --version  # Should be >= 22.12.0

# Fix (macOS/Linux)
nvm use 22

# Fix (Windows)
# Download and install from https://nodejs.org/

2. Port already in use:

# macOS/Linux
lsof -i :18789
kill -9 <PID>

# Windows PowerShell
netstat -ano | findstr :18789
taskkill /PID <PID> /F

3. Permission denied:

# macOS/Linux
sudo chown -R $(whoami) ~/.npm

# Windows (run PowerShell as Administrator)
npm cache clean --force

4. Gateway not starting:

# Check logs (macOS/Linux)
cat ~/.openclaw/logs/gateway.log

# Check logs (Windows)
type %USERPROFILE%\.openclaw\logs\gateway.log

# Run diagnostics
openclaw doctor

Reset Configuration

# Backup and reset (macOS/Linux)
cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak
rm -rf ~/.openclaw
openclaw onboard

# Backup and reset (Windows PowerShell)
Copy-Item $env:USERPROFILE\.openclaw\openclaw.json $env:USERPROFILE\.openclaw\openclaw.json.bak
Remove-Item -Recurse -Force $env:USERPROFILE\.openclaw
openclaw onboard

Quick Reference

# Installation
npm install -g openclaw@latest

# Configuration
openclaw onboard --install-daemon

# Start/Stop
openclaw gateway              # Start
killall openclaw              # Stop (macOS/Linux)

# Status
openclaw doctor               # Diagnostics
openclaw --version            # Version

# Update
openclaw update --channel stable

Additional Resources

Scripts

Cross-platform installation checkers:

scripts/check-installation.sh - Bash script (macOS/Linux/Windows Git Bash)
scripts/check-installation.ps1 - PowerShell script (Windows)

Reference Files

references/configuration-reference.md - Complete configuration options

Example Files

examples/openclaw.json - Full configuration example
examples/telegram-setup.md - Telegram channel setup guide

Official Resources

Website: https://openclaw.ai
Documentation: https://docs.openclaw.ai
GitHub: https://github.com/openclaw/openclaw
Discord: https://discord.gg/clawd
ClawHub (Skills): https://clawhub.com

OpenClaw Setup (ModelWise)