OpenClaw Setup Guide: Install to First AI Agent in 10 Minutes

OpenClaw is the best self-hosted AI agent framework in 2026, but the setup process confuses most people. They get stuck on authentication, channel configuration, or workspace setup. This guide gets you from zero to a working AI agent you can message from WhatsApp, Telegram, or Discord in under 10 minutes.

See also: How to 10x Your Productivity with AI Prompts

See also: AI Prompts for Teachers: Create Lesson Plans in Minutes

See also: OpenClaw vs AutoGPT vs CrewAI: Which AI Agent Framework in 2026

See also: AI Writing Tool Guide: From Blank Page to Published in 30 Minutes

No docker-compose files. No Kubernetes. No spending hours reading documentation. Just a straightforward install process with copy-paste commands that actually work.

What You Need Before Starting

OpenClaw has minimal requirements compared to other agent frameworks. Here's the complete checklist:

• Node.js 22 or newer (check with node --version)
• An Anthropic API key (or OpenAI, but Anthropic is recommended)
• A computer that stays on (laptop, desktop, or server)
• 5 minutes of focused time

That's it. No Docker required. No Redis. No PostgreSQL. OpenClaw runs as a single Node process with local file storage. You can add fancy infrastructure later if you want, but you don't need it to start.

Getting Your Anthropic API Key

If you don't have an Anthropic API key yet:

1. Go to console.anthropic.com
2. Sign up or log in
3. Navigate to API Keys section
4. Click "Create Key"
5. Copy the key (starts with sk-ant-)

New accounts get $5 free credit. That's enough for hundreds of messages to test OpenClaw. Production usage costs around $10-30/month depending on how much you use it.

Step 1: Install OpenClaw (2 Minutes)

OpenClaw provides an automatic installer that handles everything. Open your terminal and run:

macOS or Linux

Windows (PowerShell)

The installer does four things:

1. Downloads the latest OpenClaw package
2. Installs it globally via npm
3. Creates the config directory at ~/.openclaw/
4. Adds the openclaw command to your PATH

Verify the installation worked:

You should see something like openclaw v2026.2.5. If you get "command not found," restart your terminal and try again.

Alternative: Manual npm Install

If the automatic installer doesn't work, install via npm directly:

This works the same way but requires you to have npm already installed and configured.

Step 2: Run the Setup Wizard (3 Minutes)

OpenClaw includes an interactive setup wizard that configures everything in one go. Run:

The wizard will ask you a series of questions. Here's what to expect:

Authentication Setup

First question: "How do you want to authenticate?"

• Anthropic API key (recommended): Paste your sk-ant-... key
• OpenAI API key: Paste your sk-... key
• Anthropic OAuth: For Claude.ai subscription users

Pick the first option and paste your Anthropic key. The wizard saves it to ~/.openclaw/auth-profiles.json securely.

Gateway Configuration

Next: "What port should the Gateway run on?"

Default is 18789. Just press Enter unless you have a port conflict. The Gateway is OpenClaw's core service that routes messages and manages sessions.

Channel Selection

The wizard asks which channels you want to configure:

• WhatsApp (via WhatsApp Web, requires phone)
• Telegram (via bot token)
• Discord (via bot token)
• iMessage (macOS only)
• Skip for now (you can add channels later)

Start with one channel. We'll use Telegram because it's the fastest to set up. Select "Telegram" and the wizard will guide you through creating a bot.

Service Installation

Finally: "Install OpenClaw as a system service?"

Say yes. This makes OpenClaw start automatically when your computer boots. The wizard creates a systemd service (Linux) or launchd service (macOS).

On Windows, you'll need to set up the service manually or run the Gateway in a terminal window.

Step 3: Connect Your First Channel (Telegram) (3 Minutes)

Let's connect Telegram because it's the easiest channel to test. You need to create a Telegram bot first.

Create a Telegram Bot

1. Open Telegram and search for @BotFather
2. Start a chat and send /newbot
3. Follow the prompts:
   • Bot name: "My OpenClaw Agent" (or whatever you want)
   • Username: must end in "bot" (e.g., myopenclaw_bot)
4. BotFather gives you a token (looks like 1234567890:ABCdefGHIjklMNOpqrsTUVwxyz)
5. Copy this token

Configure Telegram in OpenClaw

If you skipped channel setup in the wizard, run:

Select "Telegram" and paste your bot token when prompted. OpenClaw saves it to your config file at ~/.openclaw/openclaw.json.

Alternative: WhatsApp Setup

If you prefer WhatsApp over Telegram:

Select "WhatsApp." OpenClaw will display a QR code in your terminal. Open WhatsApp on your phone, go to Settings → Linked Devices → Link a Device, and scan the QR code. The connection establishes in 5-10 seconds.

WhatsApp uses WhatsApp Web protocol (Baileys library), so it's stable and doesn't require business API access.

Step 4: Start the Gateway (30 Seconds)

Now we start the Gateway service. If you installed the daemon, it's probably already running:

If it says "running," you're good. If not, start it:

For debugging or testing, you can run the Gateway in the foreground (it stays attached to your terminal):

You'll see startup logs confirming channels initialized and the agent loaded. Look for:

• Gateway listening on http://127.0.0.1:18789
• Telegram channel ready
• Agent 'main' loaded

If you see errors, check the troubleshooting section at the end of this guide.

Step 5: Send Your First Message (30 Seconds)

Open Telegram and find your bot (search for the username you created). Start a chat and send:

Within 2-3 seconds, your OpenClaw agent should respond. This confirms:

• The Gateway is running
• Telegram integration works
• Authentication is configured correctly
• The agent model (default: Claude Sonnet 4.5) is responding

Congratulations! You have a working AI agent connected to Telegram. Everything from here is customization and adding features.

Step 6: Open the Control UI Dashboard (1 Minute)

OpenClaw includes a web dashboard for managing your agent. Open your browser and go to:

Or use the CLI shortcut:

The Control UI shows:

• Chat interface: Test your agent directly in the browser
• Sessions view: See all active conversations
• Logs: Real-time Gateway logs
• Configuration: Edit settings without touching JSON files
• Node pairing: Connect mobile devices (iOS, Android)

Try sending a message through the web chat. It uses the same agent as your Telegram bot, so the conversation history is shared.

Understanding Your OpenClaw Workspace

OpenClaw created a workspace directory where your agent lives. By default, it's at:

This directory contains the files that define your agent's behavior:

• SOUL.md: Your agent's personality and communication style
• AGENTS.md: Operational rules and workflows
• HEARTBEAT.md: Proactive check-in tasks (optional)
• USER.md: Information about you (optional)
• MEMORY.md: Long-term memory notes (optional)
• TOOLS.md: Local tool configuration like SSH hosts (optional)
• memory/: Daily conversation logs

Right now, most of these files don't exist yet. OpenClaw uses sensible defaults. But to customize your agent's personality, you'll want to create these files.

Create Your First SOUL.md

Let's give your agent a personality. Create a file called SOUL.md in your workspace:

Add this simple personality definition:

Save the file and restart the Gateway:

Now send another message to your bot. You'll notice the tone matches the personality you defined in SOUL.md. Check out our 50 OpenClaw prompts guide for more SOUL.md examples.

Optional: Set Up Proactive Heartbeats

One of OpenClaw's best features is heartbeat polling. Your agent can check email, calendar, or other services every 30-60 minutes and surface important updates without you asking.

To enable heartbeats, create HEARTBEAT.md in your workspace:

Configure the heartbeat interval in your config file (~/.openclaw/openclaw.json):

Restart the Gateway. Now every 30 minutes, your agent will run the heartbeat checklist. If everything is fine, it stays quiet (HEARTBEAT_OK). If something needs attention, it messages you.

Adding More Channels

You're not limited to one channel. OpenClaw supports multiple channels simultaneously. Here's how to add more:

Add WhatsApp

Select WhatsApp and scan the QR code with your phone.

Add Discord

1. Go to discord.com/developers/applications
2. Create a new application
3. Go to Bot section and create a bot
4. Copy the bot token
5. Run openclaw channels login, select Discord, paste token
6. Use the OAuth2 URL to invite the bot to your server

Add iMessage (macOS Only)

iMessage integration uses the local Messages.app database. Run:

Select iMessage. OpenClaw will request permission to access your Messages database. Grant it in System Preferences → Security & Privacy.

Note: iMessage is read-only for now (outbound messages aren't supported in the current version).

Multi-Agent Setup (Advanced)

You can run multiple isolated agents in one Gateway. Each agent gets its own workspace, personality, and session history. This is useful for:

• Separating work and personal agents
• Running specialized agents (code reviewer, content writer, researcher)
• Multi-user setups (family members each get their own agent)

To add a second agent, run:

This creates a new agent called "work" with its own workspace at ~/.openclaw/workspace-work/. Configure routing in your config file:

Now messages from Telegram user 123456789 route to the "work" agent, while everyone else gets the "main" agent. Read more in the hidden features guide.

Configuring Security and Access Control

By default, OpenClaw accepts messages from anyone who has your bot username or phone number. For production use, you want to lock this down.

WhatsApp Allowlist

Restrict WhatsApp to specific phone numbers:

Telegram Allowlist

Restrict Telegram to specific user IDs:

To find your Telegram user ID, send a message to your bot and check the Gateway logs:

Group Chat Mention Gating

In group chats, require mentions before the agent responds:

Now the agent only responds when someone types "@bot" or "@assistant" in the message.

Common Setup Issues and Fixes

Gateway Won't Start

Check if another process is using port 18789:

If something else is running, either stop it or change OpenClaw's port in the config file.

Authentication Errors

If you get "Invalid API key" errors:

1. Verify your key is correct in ~/.openclaw/auth-profiles.json
2. Check your Anthropic account has available credits
3. Try regenerating the API key in the Anthropic console

No Response from Agent

Check the Gateway logs for errors:

Common issues:

• Rate limiting: You're sending messages too fast
• Model errors: The API is temporarily down
• Session conflicts: Multiple Gateway instances running

WhatsApp QR Code Won't Scan

Make sure:

• Your phone has internet connection
• WhatsApp is updated to the latest version
• You're scanning from WhatsApp app (not camera app)
• The terminal window is large enough to display the full QR code

Telegram Bot Not Responding

Verify:

• You started a chat with the bot (click "Start" in Telegram)
• The bot token is correct in your config
• The Gateway is actually running (openclaw gateway status)

Next Steps After Setup

You now have a working OpenClaw agent. Here are the most impactful things to do next:

Customize Your Agent Personality

Create SOUL.md and AGENTS.md files to define how your agent behaves. Our prompts guide has 50 ready-to-use examples.

Enable Heartbeats

Set up proactive monitoring so your agent checks email, calendar, or other services automatically.

Add More Channels

Connect WhatsApp, Discord, and Telegram simultaneously. Your agent maintains separate conversation histories per channel.

Set Up Cron Jobs

Schedule recurring tasks like daily summaries or weekly reports:

Explore Hidden Features

OpenClaw has capabilities most users never discover. Read our hidden features guide to unlock the full potential.

Upgrading OpenClaw

OpenClaw releases updates frequently. To upgrade to the latest version:

Then restart the Gateway:

Your configuration and workspace files are preserved during upgrades. Major version upgrades (e.g., v2025 to v2026) may require config migration, but the upgrade command handles this automatically.

Running OpenClaw on a Server

If you want your agent available 24/7, run OpenClaw on a server instead of your laptop.

Quick VPS Setup

Any Linux VPS works. Recommended specs:

• 1 CPU core
• 1GB RAM
• 10GB disk
• Ubuntu 22.04 or newer

Providers like DigitalOcean, Linode, or Hetzner work great. Cost: around $5-10/month.

Install Node.js on the server:

Then follow the same setup steps from this guide. Install as a systemd service so OpenClaw starts automatically after server reboots.

Accessing the Control UI Remotely

By default, the Control UI only listens on 127.0.0.1 (localhost). To access it from your laptop while the Gateway runs on a server, use SSH port forwarding:

Now open http://127.0.0.1:18789 on your laptop, and it tunnels to the server.

Alternatively, configure OpenClaw to listen on all interfaces (less secure):

Then access it at http://your-server-ip:18789. Add firewall rules to restrict access to your IP only.

Monitoring and Logs

Keep an eye on your agent's health with these commands:

Check Gateway Status

View Real-Time Logs

View Session History

Check Disk Space

OpenClaw stores session history and memory files locally. Over time, this can grow. Check disk usage:

Archive old sessions periodically to keep disk usage low.

Backup and Disaster Recovery

Your OpenClaw workspace contains everything: configuration, memory files, session history. Back it up regularly:

Store backups in a safe place (external drive, cloud storage). To restore:

Consider using git to version control your workspace files:

Now you can track changes and roll back if you break something.

Conclusion: Your OpenClaw Agent is Ready

In under 10 minutes, you installed OpenClaw, connected a channel, and sent your first message to an AI agent. From here, everything is customization. Define your agent's personality in SOUL.md. Set up proactive heartbeats. Connect more channels. Add cron jobs for scheduled tasks.

The difference between a basic OpenClaw setup and a truly useful one is how well you configure the personality and workflows. Check out our other guides:

• 50 Best OpenClaw Prompts for SOUL.md, AGENTS.md, and HEARTBEAT.md
• 7 Hidden Features most users never discover
• OpenClaw vs AutoGPT vs CrewAI comparison
• 10 Ways to Make Money with OpenClaw automation