Back to Tutorials
Complete Guide All Levels March 1, 2026 45 min read

The ULTIMATE OpenClaw Setup Guide! 🦞

The Complete Guide to OpenClaw: Setup, Configuration, and Advanced Workflows

OpenClaw (formerly known as Clawdbot) is a powerful, open-source, self-hosted AI agent framework. Unlike traditional cloud-based chatbots, OpenClaw operates locally on your machine, granting it the ability to execute terminal commands, manage files, and interact with third-party applications like WhatsApp, Telegram, and Discord.

This guide provides a comprehensive, step-by-step walkthrough for installing, configuring, and extending OpenClaw for professional use.

Prerequisites

Before initiating the installation process, ensure your system meets the following requirements:

1. Operating System

OpenClaw is cross-platform and supports:

  • macOS
  • Windows (via PowerShell or WSL)
  • Linux (Ubuntu/Debian recommended)

2. Node.js Environment

OpenClaw requires Node.js version 22.0.0 or higher. To verify your current installation, execute the following command in your terminal:

node --version

If Node.js is not installed or the version is below 22, download the LTS release from the official Node.js website or install it via a package manager (e.g., nvm or Homebrew ).

3. LLM API Provider

OpenClaw requires an API key from a supported Large Language Model (LLM) provider to function as its reasoning engine.

  • Anthropic (Recommended): Provides superior reasoning capabilities, particularly with the claude-3-5-sonnet or claude-3-opus models. Obtain an API key from the Anthropic Console.
  • OpenAI: A robust alternative using gpt-4o . Obtain an API key from the OpenAI Platform.

Part 1: Installation

The installation process is streamlined via an automated script. Open your terminal or command prompt and execute the appropriate command for your operating system.

For macOS and Linux:

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

For Windows (PowerShell):

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

This script will automatically download the OpenClaw binaries, install necessary dependencies, and configure the base environment.

To verify a successful installation, check the installed version:

openclaw --version

Part 2: Initial Configuration (Onboarding)

Once installed, you must initialize the OpenClaw environment and configure your LLM provider. We recommend installing the gateway daemon to allow OpenClaw to run persistently in the background.

Initiate the onboarding wizard:

openclaw onboard --install-daemon

The interactive CLI wizard will prompt you for the following configurations:

  • Agent Name: Define a custom identifier for your AI assistant.
  • LLM Provider: Select either Anthropic or OpenAI.
  • API Key: Securely input the API key obtained in the prerequisites step.
  • Model Selection: Choose your preferred model (e.g., claude-3-5-sonnet ).
  • Messaging Channels: Select the platforms you wish to integrate (e.g., Telegram, Discord). You can skip this and configure them later.

Understanding the Directory Structure

Upon completion, OpenClaw generates a hidden configuration directory in your home folder ( ~/.openclaw/ on Unix, C:\Users\Username\.openclaw\ on Windows).

Key directories include:

  • ~/.openclaw/openclaw.json : The primary configuration file.
  • ~/.openclaw/workspace/ : The isolated directory where the agent reads and writes files.
  • ~/.openclaw/logs/ : System and execution logs.

Part 3: Service Management and Web UI

OpenClaw operates via a local gateway service, typically running on port 18789 .

To check the status of the gateway daemon:

openclaw gateway status

If the service is not running, initiate it manually:

openclaw gateway start

Accessing the Dashboard

OpenClaw includes a comprehensive web-based Control UI for monitoring agent activity, managing configurations, and direct chat interaction.

To launch the dashboard in your default web browser:

openclaw dashboard

Alternatively, navigate directly to http://127.0.0.1:18789/ in your browser.

Part 4: Messaging Channel Integration

Integrating OpenClaw with external messaging platforms allows for remote, asynchronous interaction with your agent.

Telegram Integration (Recommended)

Telegram offers the most stable and straightforward integration process.

  • Open Telegram and initiate a chat with @BotFather .
  • Send the /newbot command and follow the prompts to generate a new bot.
  • Copy the provided HTTP API Token.
  • Inject the token into your OpenClaw configuration:

# Open the configuration file in your default CLI editor

openclaw config edit

Append the Telegram configuration block:

"channels" : {

"telegram" : {

"botToken" : "YOUR_TELEGRAM_BOT_TOKEN_HERE"

}

}

Restart the gateway to apply changes:

openclaw gateway restart

WhatsApp Integration

WhatsApp integration utilizes a QR code pairing mechanism.

Initiate the login sequence:

openclaw channels login whatsapp

Scan the generated QR code in your terminal using the "Linked Devices" feature in the WhatsApp mobile app.

Security Note: To prevent unauthorized access, explicitly approve your phone number for interaction:

openclaw pairing approve whatsapp +1234567890

Part 5: Extending Capabilities with Skills

"Skills" are modular plugins that expand OpenClaw's functionality, allowing it to interact with external APIs, manage calendars, or execute complex workflows.

Browse the official repository at ClawHub.ai.

To install a new skill (e.g., web searching capabilities):

openclaw skills install web-search

To verify installed skills:

openclaw skills list

Part 6: Advanced Configuration

Customizing Agent Behavior (SOUL.md)

You can strictly define your agent's persona, operational boundaries, and default behaviors by modifying the SOUL.md file located in the workspace directory.

# Navigate to the workspace directory

cd ~/.openclaw/workspace

# Edit the SOUL.md file

nano SOUL.md

Example SOUL.md configuration:

# Core Directives

You are a highly technical DevOps assistant.

Always provide terminal commands in standard Markdown code blocks.

Prioritize security and explicitly ask for confirmation before executing destructive commands (e.g., `rm -rf` ).

Cost Management and Token Limits

To prevent unexpected API charges, it is critical to enforce token consumption limits within the primary configuration file.

openclaw config edit

Append the limits configuration:

"limits" : {

"maxTokensPerDay" : 100000 ,

"alertWhenOver" : 50000

}

Part 7: Security Best Practices

Deploying an autonomous agent with local execution privileges requires strict adherence to security protocols:

  • API Key Protection: Never commit your openclaw.json file to public version control repositories.
  • Principle of Least Privilege: Do not run the OpenClaw daemon as the root or Administrator user.
  • Access Control: Always utilize the openclaw pairing approve command to restrict channel access to authorized user IDs or phone numbers.
  • Monitor Execution: Regularly review the execution logs to audit the agent's autonomous actions:

openclaw logs --tail 100

For further advanced configurations, refer to the Official OpenClaw Documentation.