How to Set Up OpenClaw: Complete Installation Guide for Mac, Windows, and Linux [2026]

OpenClaw is the most popular open-source AI agent framework in the world — over 321,000 GitHub stars and growing. But getting it running for the first time can feel confusing if you've never set up a self-hosted agent before.

This guide walks you through the entire setup process from zero to a working OpenClaw agent. No prior experience required. By the end, you'll have an AI agent running on your machine, connected to your preferred AI model, and ready to connect to messaging platforms like WhatsApp, Telegram, Slack, and Discord.

What Do You Need Before Setting Up OpenClaw?

OpenClaw has just two requirements: Node.js version 22.16 or higher (version 24 recommended) and an API key from at least one AI model provider like Anthropic, OpenAI, or Google.

Checking Your Node.js Version

node --version

If you see v22.16.0 or higher, you're good. If you get an error or a lower version number, install Node.js from nodejs.org before continuing.

Getting an API Key

Important: Keep your API key private. Never share it in public channels, paste it into untrusted tools, or commit it to Git. If you've already exposed a key, rotate it immediately through your provider's dashboard.

How Do You Install OpenClaw?

OpenClaw installs with a single terminal command on Mac or Linux, or a PowerShell command on Windows — the official installer handles dependencies, sets up the binary, and adds OpenClaw to your system PATH.

Mac or Linux

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

Windows

Open PowerShell as Administrator and run:

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

Windows users: OpenClaw supports both native Windows and WSL2 (Windows Subsystem for Linux). WSL2 is recommended for the most stable experience.

How Do You Run the OpenClaw Onboarding Wizard?

The onboarding wizard walks you through model provider selection, API key configuration, and Gateway setup in about 2 minutes — the --install-daemon flag ensures the Gateway starts automatically on boot.

openclaw onboard --install-daemon

This launches an interactive setup wizard that walks you through three things:

1. Model provider selection — Choose which AI provider you want to use.
2. API key configuration — Enter your API key securely. It's stored locally on your machine — it's never sent to OpenClaw's servers.
3. Gateway setup — Configures the always-on Gateway process that handles all incoming and outgoing messages.

How Do You Verify the OpenClaw Gateway Is Running?

The Gateway is OpenClaw's control plane — verify it's listening on port 18789 with the gateway status command, and start it manually if needed.

openclaw gateway status

If the Gateway isn't running, start it manually:

openclaw gateway start

How Do You Open the OpenClaw Dashboard?

Launch the OpenClaw Control UI with the dashboard command — from here you can chat with your agent, configure channels, manage skills, edit memory files, and monitor all activity.

openclaw dashboard

In the Control UI chat box, type any message and press enter. If everything is configured correctly, you'll receive an AI-generated response within a few seconds.

How Do You Connect Messaging Channels to OpenClaw?

OpenClaw supports 6 messaging channels out of the box — start with Telegram (fastest to connect), then add WhatsApp, Discord, Slack, iMessage, or use the built-in browser chat.

4 AI personas and 7 free skills — browse the marketplace.

How Do You Configure Your OpenClaw Agent's Personality?

OpenClaw's personality and knowledge are defined by two markdown files: soul.md (who the agent is) for persistent personality and boundaries, and memory.md (what it knows) for accumulated facts and preferences.

soul.md — Who Your Agent Is

This file defines the agent's personality, role, tone, and boundaries. Think of it as a system prompt that persists across all conversations and channels.

You are a helpful business assistant. You are professional but friendly.
You help with scheduling, email drafts, research, and brainstorming.
You never share confidential information outside approved channels.
You always confirm before taking actions that affect external systems.

memory.md — What Your Agent Knows

This file stores accumulated knowledge — facts, preferences, context, and anything the agent has learned over time.

Both files live in your OpenClaw home directory and can be edited with any text editor. Changes take effect immediately — no restart required.

How Do OpenClaw Skills Work?

Skills are plain-English markdown files that teach OpenClaw how to perform specific tasks — the framework ships with 52+ built-in skills and supports three levels of precedence from bundled to workspace-specific.

1. Bundled skills — Ship with OpenClaw (lowest priority)
2. Local skills — Added to your local OpenClaw directory
3. Workspace skills — Project-specific skills (highest priority)

What Are the Most Common OpenClaw Setup Issues?

The most frequent setup issues are PATH not updating after install, port 18789 already in use, invalid API keys, vague agent responses from missing soul.md, and WhatsApp connection drops from session expiry.

"command not found: openclaw"

Your PATH wasn't updated after installation. Restart your terminal session or run source ~/.zshrc (Mac) / source ~/.bashrc (Linux).

Gateway won't start

Check if port 18789 is already in use: lsof -i :18789 (Mac/Linux). Ensure Node.js 22.16+ is installed.

API key errors

Verify your key is valid by testing it directly with your provider's API. Re-run onboarding to reconfigure: openclaw onboard.

Agent responds but seems confused

Check soul.md — a vague or missing soul file leads to generic responses. Check which model is configured — smaller or budget models may produce lower quality output.

What Should You Do After OpenClaw Setup?

After initial setup, refine your soul.md, connect Telegram as your first channel, add 2-3 custom skills for repetitive tasks, configure the scheduler for proactive behaviors, and cautiously explore the Claw Hub marketplace.

1. Refine your soul.md — Spend 15 minutes writing a clear, specific personality and role definition.
2. Connect Telegram — It's the fastest channel to set up and test with.
3. Add 2-3 custom skills — Start small. Write skills for tasks you do repeatedly.
4. Set up the scheduler — Configure heartbeat intervals so the agent proactively checks your inbox or runs recurring tasks.
5. Explore the Claw Hub — Browse community-created skills. Be cautious — always review skill files before installing them.

Frequently Asked Questions

How long does OpenClaw setup take?

About 5-10 minutes from start to a working agent. The installer takes under a minute, onboarding takes about 2 minutes, and initial configuration takes another few minutes.

Is OpenClaw free?

Yes. OpenClaw is free, open-source software (MIT license). The only cost is the API fees from your chosen AI model provider.

Do I need a powerful computer to run OpenClaw?

No. OpenClaw itself is lightweight — it runs on a Mac Mini, Raspberry Pi, or any basic VPS. The AI processing happens on your model provider's servers, not locally.

Can I run OpenClaw on a Raspberry Pi?

Yes. OpenClaw supports ARM processors and runs well on Raspberry Pi 4 and newer models. Just ensure Node.js 22.16+ is installed.

What's the difference between the installer and Docker?

The installer sets up OpenClaw directly on your system with access to your files and tools. Docker runs OpenClaw in an isolated container — more secure but slightly more complex to configure file access and channel integrations.

Can I change my AI model provider after setup?

Yes. Run openclaw onboard again to reconfigure your provider and API key. Your existing channels, skills, and memory are preserved.

Do I need to keep my computer on for OpenClaw to work?

Yes — unless you deploy to a cloud server or VPS. OpenClaw's Gateway needs to be running to receive and process messages. For 24/7 availability, deploy on a VPS or use the managed hosting option via getclaw.

What is getclaw?

getclaw is the managed hosting option for OpenClaw. It handles infrastructure, Gateway uptime, and maintenance for you. Setup takes under 5 minutes with no terminal commands required.

Is my API key safe?

Your API key is stored locally on your machine in your OpenClaw configuration file. It is never transmitted to OpenClaw's servers. However, treat your config file as sensitive — don't commit it to Git or share it publicly.

Can I run multiple OpenClaw agents on one machine?

Yes. Use the OPENCLAW_HOME environment variable to point each instance to a separate directory. Each instance needs its own Gateway port.

Last updated: March 2026