Getting Started

From zero to a running OpenClaw agent in 7 steps

This guide walks you through every step of a fresh OpenClaw installation — from Node.js prerequisites to your first skill install. Tested on Mac, Linux, and Windows.

Beginner friendly

~30 minutes to complete

Prerequisites

Before installing OpenClaw, make sure your system meets these minimum requirements. Most issues people hit during setup trace back to an outdated Node.js version or missing git.

Node.js 22 or higher — check with node --version
git installed — check with git --version
A terminal (Terminal.app, iTerm2, Windows Terminal, or any Linux shell)
At least 2 GB of free disk space
A code editor (VS Code recommended for the built-in terminal)

node --version   # must output v22.x.x or higher
git --version    # any recent version works

Tip: Use nvm to manage Node.js versions. Run: nvm install 22 && nvm use 22

Install OpenClaw

OpenClaw installs globally via npm. This gives you the openclaw CLI command that you will use for everything — starting the agent, installing skills, and managing config.

Install globally with npm to get the openclaw CLI
The install pulls all core dependencies automatically
Verify the install with openclaw --version
If you get permission errors, prefix with sudo or fix your npm prefix

npm install -g openclaw
openclaw --version   # should output the version number
openclaw init my-agent   # creates a new project folder

Tip: If npm install -g fails with EACCES, run: npm config set prefix ~/.npm-global and add ~/.npm-global/bin to your PATH.

Configure your .env file

The .env file holds your API keys, platform tokens, and runtime configuration. OpenClaw reads it on startup — changes require a full restart to take effect.

Copy .env.example to .env in your project root
Never commit your .env file to git — it is in .gitignore by default
Each variable must be on its own line, no quotes needed
OpenClaw does not hot-reload .env changes — restart required

cp .env.example .env

# Required — at least one AI provider key:
ANTHROPIC_API_KEY=sk-ant-...
# or
OPENAI_API_KEY=sk-...

# Optional — logging and port:
LOG_LEVEL=info
PORT=3000

Tip: Double-check for trailing whitespace in API keys — this is the #1 cause of 401 errors. Paste your key into a text editor first.

Choose an LLM provider

OpenClaw supports multiple AI providers. You need at least one API key to start. Claude Sonnet is the recommended default for the best balance of quality and cost.

Claude (Anthropic) — best overall quality, recommended default
GPT-4o (OpenAI) — fast, strong at code tasks
Gemini (Google) — generous free tier for testing
Ollama / LM Studio — free, fully local, no API key needed

Models & Cost guide

# In .env — pick one or more:
ANTHROPIC_API_KEY=sk-ant-your-key-here
OPENAI_API_KEY=sk-your-key-here
GOOGLE_AI_KEY=your-key-here

# For local models:
OLLAMA_HOST=http://localhost:11434

Tip: Start with Claude Sonnet for quality, switch to Ollama for privacy. See the Models & Cost guide for detailed pricing.

First agent run

With your .env configured and at least one API key set, you are ready for the first run. OpenClaw will load your SOUL.md, connect to the provider, and wait for messages.

Run openclaw start from your project directory
Watch the logs — it should print 'Agent ready' within 10 seconds
The default SOUL.md gives you a helpful assistant persona
Send a test message from the terminal or connected platform
If it fails, check LOG_LEVEL=debug for detailed error output

cd my-agent
openclaw start

# Expected output:
# [INFO] Loading SOUL.md...
# [INFO] Connecting to Claude Sonnet...
# [INFO] Agent ready — listening on port 3000

Tip: If the agent crashes on start, run openclaw doctor to diagnose common issues automatically.

Connect a messaging platform

OpenClaw supports 20+ messaging platforms out of the box. The most popular are WhatsApp, Telegram, and Discord. Each has a different auth flow — start with whichever you use most.

WhatsApp — scan a QR code from your terminal, no API key needed
Telegram — create a bot via BotFather and paste the token
Discord — create a bot app, enable Message Content Intent, add token
Slack — create a workspace app, add bot scopes, install to workspace
Signal — link as a secondary device via signal-cli

Channels guide

# In .env — add your platform tokens:
WHATSAPP_ENABLED=true
# or
TELEGRAM_BOT_TOKEN=123456:ABC-...
# or
DISCORD_BOT_TOKEN=your-token-here

# Then restart:
openclaw start

Tip: Start with one platform. Get it working before adding a second. Multi-platform is powerful but harder to debug.

Install your first skill

Skills extend what your agent can do — web search, image generation, calendar access, and hundreds more. OpenClaw ships with 53 bundled skills, but ClawHub has 400+ community skills.

Browse available skills with openclaw skills list
Install from ClawHub with openclaw skills install <name>
Skills auto-register — the agent picks them up on restart
Check installed skills with openclaw skills installed
Remove a skill with openclaw skills remove <name>

Skills guide

# List bundled skills:
openclaw skills list

# Install a popular skill from ClawHub:
openclaw skills install web-search
openclaw skills install image-gen

# Verify:
openclaw skills installed

# Restart to activate:
openclaw start

Tip: Audit ClawHub skills before installing — 26% have known vulnerabilities. Check the Security guide for how to vet skills.

Sources referenced on this page

These references are the primary docs that matter most when you want a stable baseline install instead of guesswork.

OpenClaw setup FAQ

These answers are written to be extractable in search and AI summaries without losing the core setup sequence.

You need a current Node.js runtime, git, a writable terminal environment, and at least one model provider or local model path ready before the first successful run.

Use the normal install flow, configure one provider, connect one channel, confirm the first successful run, and only then add more skills or platforms.

The common failures are wrong Node.js versions, bad environment variable names, stale API keys, and trying to wire multiple channels before the base agent run is stable.

Stuck during setup?

Check the troubleshooting guide for common installation errors, or hire Milan to handle the full setup for you.

Troubleshooting Hire Milan