OpenClaw Pre-Install Setup Guide — API keys, Telegram bot, platform guides (Mac, VPS, Pi, Docker)

00-OpenClaw-Setup-Guide.md

OpenClaw Pre-Install Checklist

Get everything ready before you install OpenClaw.

OpenClaw installs in one command — but it connects to external services that need accounts, API keys, and tokens. This checklist walks you through getting those ready so installation is seamless.

What You'll Need

Guide	What You're Getting	Required?
01 — Claude / Anthropic	AI brain (Claude Opus, Sonnet, Haiku)	✅ Yes
02 — Telegram Bot	Chat interface to talk to your agent	✅ Yes (if using Telegram)
03 — OpenAI API Key	Speech-to-text (Whisper) and text-to-speech	Optional
04 — Gemini API Key	AI image generation	Optional

Pick Your Platform

Guide	Platform
05 — macOS	Mac Mini, MacBook, iMac
06 — VPS	DigitalOcean, Hetzner, Oracle Cloud
07 — Raspberry Pi	Budget always-on setup
08 — Docker	Containerized (any platform)

The Checklist

Before you start installing, confirm you have:

• Claude Code account with access token (see guide 01)
• Telegram bot token from BotFather (see guide 02)
• (Optional) OpenAI API key (see guide 03)
• (Optional) Gemini API key (see guide 04)
• Your platform ready (see guides 05-08)

Once you've checked everything off, you're ready to install. The installation guide will tell you where to plug everything in.

01-anthropic-claude.md

01 — Claude / Anthropic (The AI Brain)

OpenClaw uses Anthropic's Claude as its AI model. The best way to get access is through a Claude Code subscription — flat monthly rate, way cheaper than pay-per-token API billing.

What You're Getting

A Claude Code account gives you access to:

• Claude Opus 4.6 — most capable model, best reasoning
• Claude Sonnet 4 — fast and capable, great for everyday tasks
• Claude Haiku 3.5 — lightweight, cheap, good for simple tasks

All under one subscription. No counting tokens.

Step 1: Sign Up for Claude

1. Open your web browser and go to claude.ai
2. Click Sign Up and create an account
3. Once logged in, subscribe to Claude Pro ($20/mo) or Claude Max ($100/mo for heavy usage)
4. Confirm your subscription is active before continuing

Step 2: Install Node.js

Node.js is a program that lets you run developer tools. You need it to install Claude Code.

If you're on a Mac:

1. Open Terminal (press Cmd + Space, type "Terminal", hit Enter)
2. Copy and paste this command to install Homebrew (a Mac package manager):

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

3. Follow the prompts on screen — it may ask for your Mac password
4. When it's done, copy and paste this command to install Node.js:

brew install node@22

5. Verify it worked — copy and paste this command:

node --version

You should see something like v22.x.x. If you do, you're good.

If you're on Windows:

1. Open your web browser and go to nodejs.org
2. Click the big green button to download the LTS version (v22.x)
3. Run the installer you just downloaded — click Next through everything, accept all defaults
4. Important: Close and reopen any Command Prompt or PowerShell windows you have open
5. Open PowerShell (press the Windows key, type "PowerShell", hit Enter)
6. Copy and paste this command to verify it worked:

node --version

You should see something like v22.x.x. If you do, you're good.

Step 3: Install Claude Code CLI

If you're on a Mac:

1. Open Terminal (if it's not already open)
2. Copy and paste this command:

brew install --cask claude-code

3. Wait for it to finish installing

If you're on Windows:

1. Open PowerShell (if it's not already open)
2. Copy and paste this command:

npm install -g @anthropic-ai/claude-code

3. Wait for it to finish installing

Verify it worked (Mac and Windows):

Copy and paste this command:

claude --version

You should see a version number. If you do, you're good.

Step 4: Generate Your Access Token

This is the key that lets OpenClaw use your Claude subscription.

1. In your Terminal (Mac) or PowerShell (Windows), copy and paste this command:

claude setup-token

2. A browser window will open — sign in with your Claude account
3. After you sign in, the terminal will display a long token string
4. Copy that entire token and save it somewhere safe (a text file, a note, whatever works) — you'll need it during OpenClaw installation

What You Should Have When Done

• A Claude Pro or Max subscription (active and paid)
• Node.js installed (node --version shows a version number)
• Claude Code CLI installed (claude --version shows a version number)
• An access token saved from claude setup-token

Alternative: API Key (Pay-Per-Token)

If you prefer usage-based billing instead of a subscription:

1. Open your browser and go to console.anthropic.com
2. Create an account
3. Go to API Keys → Create Key
4. Copy the key (it starts with sk-ant-...) and save it somewhere safe
5. Add billing info (credit card)

This works too, but costs add up fast with heavy use. The subscription is usually the better deal.

---

Next: Guide 02 — Telegram Bot

02-telegram-bot.md

02 — Telegram Bot (Your Chat Interface)

Telegram is the easiest way to talk to your OpenClaw agent. You'll create a bot and save its token.

Step 1: Install Telegram

If you don't already have Telegram:

1. Go to telegram.org on your phone or computer
2. Download and install the app
3. Create an account (requires a phone number)

Step 2: Create Your Bot

1. Open Telegram
2. In the search bar at the top, type @BotFather and tap on the result with the blue checkmark — this is Telegram's official bot-making tool
3. Tap Start (or type /start)
4. Type /newbot and send it
5. BotFather will ask you for a display name — type whatever you want (e.g., "My AI Assistant") and send it
6. BotFather will ask you for a username — this must end in bot (e.g., myassistant_bot) and send it
7. BotFather will reply with a message containing your bot token — it looks like this: 7123456789:AAHx...
8. Copy that token and save it somewhere safe — you'll need it during OpenClaw installation

Step 3: Configure Bot Settings (Recommended)

Still in the BotFather chat, send these commands one at a time:

1. Type /setprivacy and send it

   • Select your bot
   • Choose Disable — this lets the bot see all group messages, not just @mentions

2. Type /setjoingroups and send it

   • Select your bot
   • Choose Enable — this allows adding the bot to group chats

3. (Optional) Type /setdescription — set whatever description you want

4. (Optional) Type /setuserpic — upload a photo to give your bot an avatar

Step 4: Find Your Telegram User ID

You'll need your numeric user ID during OpenClaw setup.

1. In Telegram, search for @userinfobot and tap on it
2. Tap Start (or type /start)
3. It will reply with your user ID — a number like 8182125465
4. Save this number — you'll need it during OpenClaw installation

Step 5: Pair Telegram with OpenClaw

After OpenClaw is installed and running, you need to approve the Telegram connection.

1. Send any message to your bot in Telegram
2. OpenClaw will show a pairing code in the terminal
3. Run this command to approve it:

openclaw pairing approve telegram <code>

Replace <code> with the code shown in your terminal.

What You Should Have When Done

• Telegram installed and account created
• A bot created via @BotFather
• Bot token saved (the 7123456789:AAHx... string)
• Privacy mode disabled
• Your Telegram user ID (a number)
• Pairing approved after first message to bot

---

Next: Guide 03 — OpenAI API Key

03-openai-api.md

03 — OpenAI API Key (Whisper & TTS)

Optional but recommended. An OpenAI API key unlocks voice features — your agent can understand voice messages and reply with audio.

What It Enables

Feature	What It Does	Cost
Whisper (speech-to-text)	Transcribes voice messages you send	$0.006/min (~3¢ per 5-min message)
TTS (text-to-speech)	Converts text replies to voice notes	$0.015/1K characters
GPT models	Alternative/fallback AI models	Varies by model

Note: OpenClaw also has a free TTS option (Edge TTS) that requires no API key. But Whisper transcription requires this key.

Step 1: Create an OpenAI Platform Account

This is NOT the same as a ChatGPT account. You need the developer platform.

1. Open your browser and go to platform.openai.com
2. Click Sign Up and create an account (or sign in if you already have one)

Step 2: Add Billing Info

1. Once logged in, click on your profile icon in the top-right
2. Go to Settings → Billing
3. Add a credit card — this is pay-as-you-go (you only pay for what you use, no subscription)

Step 3: Create an API Key

1. In the left sidebar, click API Keys
2. Click Create new secret key
3. Give it a name (e.g., "OpenClaw")
4. Click Create secret key
5. Copy the key immediately — it starts with sk-... and you won't be able to see it again
6. Save it somewhere safe — you'll need it during OpenClaw installation

What You Should Have When Done

• An OpenAI platform account (at platform.openai.com)
• Billing info added
• API key saved (starts with sk-...)

---

Next: Guide 04 — Gemini API Key

04-gemini-api.md

04 — Gemini API Key (Image Generation)

Optional. A Gemini API key enables AI image generation — ask your agent to create or edit images and it sends them back in chat.

What It Enables

• Text-to-image — "Generate an image of a sunset over Dallas"
• Image editing — Send a photo with instructions to modify it
• Multi-image composition — Combine multiple images into one scene

Pricing: Gemini API has a generous free tier. For personal use, you likely won't pay anything.

Step 1: Get the API Key

1. Open your browser and go to aistudio.google.com
2. Sign in with your Google account (any Gmail account works)
3. Click Get API Key in the left sidebar
4. Click Create API key
5. If it asks you to select a project, click Create project (or select an existing one)
6. Copy the key and save it somewhere safe — you'll need it during OpenClaw installation

Step 2: Install uv (Required Dependency)

The image generation feature needs a tool called uv. Install it now so it's ready.

If you're on a Mac:

1. Open Terminal (press Cmd + Space, type "Terminal", hit Enter)
2. Copy and paste this command:

brew install uv

Note: This requires Homebrew. If you followed Guide 01, you already have it. If not, see Guide 01 Step 2 for Homebrew installation.

3. Verify it worked — copy and paste this command:

uv --version

You should see a version number. If you do, you're good.

If you're on Windows:

1. Open PowerShell (press the Windows key, type "PowerShell", hit Enter)
2. Copy and paste this command:

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

3. Close and reopen PowerShell
4. Verify it worked — copy and paste this command:

uv --version

You should see a version number. If you do, you're good.

What You Should Have When Done

• Gemini API key saved
• uv installed (uv --version shows a version number)

---

Now pick your platform: Guide 05 (macOS), 06 (VPS), 07 (Raspberry Pi), or 08 (Docker)

05-platform-mac.md

05 — Platform: macOS

The best OpenClaw experience. macOS gets the full companion app with menu bar controls, Canvas, camera access, screen recording, and voice wake.

Requirements

• macOS (Apple Silicon or Intel)
• Homebrew installed
• ~500MB disk space

Pre-Install Checklist

• macOS machine available (Mac Mini, MacBook, iMac, etc.)
• Admin access (you can install software)
• Terminal app accessible (Applications → Utilities → Terminal)

1. Install Homebrew

If you don't already have it:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

2. Install Node.js 22

brew install node@22

Verify:

node --version  # Should show v22.x.x

3. Recommended Optional Tools

These aren't required for OpenClaw itself, but unlock additional features:

brew install uv       # Required for image generation (see guide 04)
brew install ffmpeg    # Video/audio processing
brew install jq        # JSON processing in skills

When You're Ready to Install

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

This installs OpenClaw and launches the onboarding wizard. Have your keys and tokens from guides 01-04 ready.

What You Should Have When Done

• Homebrew installed (brew --version works)
• Node.js 22+ installed (node --version)
• Optional tools installed as needed

---

Other platforms: Guide 06 (VPS), Guide 07 (Raspberry Pi), Guide 08 (Docker)

06-platform-vps.md

06 — Platform: VPS (Cloud Server)

A VPS gives you a persistent, always-on gateway without tying up your personal machine. Runs 24/7 for a few bucks a month.

VPS Provider Comparison

We've put together a spreadsheet comparing VPS providers, pricing, and specs:

VPS Comparison Spreadsheet: https://docs.google.com/spreadsheets/d/181qrOmFwQvj35qztnT9jFbHl4qG0_zps26FAOIy8PqM/edit?usp=sharing

Recommended Setup: Laravel Forge

We'll be using Laravel Forge to provision and manage the VPS. Forge handles all the server setup for you.

• Laravel Forge: https://forge.laravel.com
• Laravel Forge VPS Setup Guide (video): https://youtu.be/_u7jYzIM8Zc?si=5ZySpiFkXarCEr7Z

DigitalOcean

If you're going with DigitalOcean, they have an official guide for running OpenClaw:

• DigitalOcean: https://www.digitalocean.com
• DigitalOcean OpenClaw Guide: https://www.digitalocean.com/community/tutorials/how-to-run-openclaw

Pre-Install Checklist

• VPS provider account created (see spreadsheet above for options)
• Server provisioned and running
• You can SSH into your server

When You're Ready

1. Open your terminal and SSH into your server
2. Most VPS providers already have OpenClaw installed when the server is provisioned. If yours doesn't, copy and paste this command:

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

3. Have your keys and tokens from guides 01-04 ready

---

Other platforms: Guide 05 (macOS), Guide 07 (Raspberry Pi), Guide 08 (Docker)

07-platform-raspberry-pi.md

07 — Platform: Raspberry Pi

The cheapest always-on setup. One-time hardware cost, $0/month after. A dedicated AI assistant that lives on your desk.

For a detailed walkthrough from someone running OpenClaw on a Pi day-to-day, check out this excellent guide: https://ajfisher.me/2026/02/03/openclaw-raspberrypi-howto/

Hardware

Pi Model	RAM	Verdict
Pi 5 (4GB/8GB)	4-8GB	✅ Best — recommended
Pi 4 (4GB)	4GB	✅ Good — sweet spot
Pi 4 (2GB)	2GB	✅ OK — works with swap
Pi 3B+	1GB	⚠️ Slow but functional
Pi Zero 2 W	512MB	❌ Not recommended

Break-even vs cloud: ~6-12 months compared to a $6/mo VPS.

Shopping List

• Raspberry Pi 4 or 5 (4GB+ recommended) — $35-80
• MicroSD card 64GB+ (or NVMe SSD for much better performance) — $10-30
• Official Pi power supply — $8-15
• Network connection (Ethernet or WiFi)
• A Telegram, Discord, or Slack account for chatting with your agent from your phone

Optional upgrades:

• NVMe M.2 SSD — huge performance improvement over SD cards
• Raspberry Pi camera module — lets your agent "see"

Step 1: Flash the OS

1. Download Raspberry Pi Imager from raspberrypi.com/software
2. Choose Raspberry Pi OS Lite (64-bit) — no desktop needed, runs faster
3. Click the ⚙️ gear icon to pre-configure:
   • Set a hostname (e.g., openclaw-pi)
   • Enable SSH
   • Set your username and password
   • Configure WiFi (if not using Ethernet)
4. Flash to your SD card or SSD
5. Insert it into the Pi and power it on

Important: Use the 64-bit version. You can verify later by running uname -m — it should show aarch64.

Step 2: Connect to Your Pi

1. Open Terminal (Mac) or PowerShell (Windows) on your computer
2. Copy and paste this command (replace with your Pi's hostname or IP):

ssh user@openclaw-pi

3. Enter the password you set during the flash step

Step 3: Update and Install the Basics

Copy and paste these commands one at a time:

Update the system:

sudo apt-get update && sudo apt-get upgrade -y

Install essential tools:

sudo apt install -y git jq ripgrep curl wget build-essential vim gh ffmpeg chromium zsh

Set your timezone (change to your timezone):

sudo timedatectl set-timezone America/Chicago

Step 4: Install Node.js 22

Copy and paste these commands one at a time:

curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install nodejs -y

Set up a global npm directory (so you don't need sudo for npm installs):

mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo "export PATH=$HOME/.npm-global/bin:$PATH" >> ~/.bashrc

Log out and log back in for the path change to take effect, then verify:

node --version

You should see something like v22.x.x. If you do, you're good.

Step 5: Add Swap (Important!)

Copy and paste these commands one at a time:

sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile
echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab
echo 'vm.swappiness=10' | sudo tee -a /etc/sysctl.conf
sudo sysctl -p

Step 6: Install OpenClaw

Copy and paste this command:

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

This will install OpenClaw and launch the onboarding wizard. Have your keys and tokens from guides 01-04 ready.

During onboarding:

• Choose API keys for auth (OAuth can be finicky on headless Pi)
• If you previously set up Claude Code or another coding agent on the Pi, OpenClaw will detect and reuse those credentials
• Say yes to the daemon setup (systemd) so it starts automatically on boot

Step 7: Set Up a Chat Channel

This is a huge unlock — being able to message your agent from your phone. Set up Telegram (guide 02), Discord, or Slack so you can chat with your Pi-based assistant from anywhere.

Once your channel is connected, you and your assistant communicate through that service. You get mobility, and the Pi stays safely inside your personal network.

Step 8: Verify Everything Works

openclaw status

You should see the gateway running. Try sending a message through your chat channel — if it replies, you're all set.

Performance Tips

Use an SSD instead of an SD card — this is the single biggest upgrade. SD cards are slow and wear out.

Reduce memory usage on headless Pi:

echo 'gpu_mem=16' | sudo tee -a /boot/config.txt
sudo systemctl disable bluetooth

Monitor your Pi:

free -h                    # check memory
vcgencmd measure_temp      # check CPU temperature

Remember: The Pi is just the gateway — the AI models (Claude, GPT, Gemini) run in the cloud. Don't try to run local LLMs for your main tasks. Small local models via Ollama can handle lightweight orchestration if you want, but keep expectations realistic.

What You Should Have When Done

• Pi booted, updated, and accessible via SSH
• Node.js 22+ installed
• Swap enabled
• OpenClaw installed and running
• Chat channel connected (Telegram, Discord, etc.)

---

Other platforms: Guide 05 (macOS), Guide 06 (VPS), Guide 08 (Docker)

08-platform-docker.md

08 — Platform: Docker

Docker lets you run OpenClaw in an isolated container without installing anything directly on your machine. Good if you want to keep things sandboxed.

Note: Docker is optional. If you're on macOS or a personal machine, the standard install (guide 05) is simpler. Simon Willison wrote a great walkthrough of his Docker setup experience here: https://til.simonwillison.net/llms/openclaw-docker

Requirements

• Docker Desktop installed (see below)
• Enough disk space (~2GB)

Step 1: Install Docker Desktop

If you're on a Mac:

1. Open your browser and go to docker.com/products/docker-desktop
2. Download Docker Desktop for Mac
3. Open the downloaded file and drag Docker to your Applications folder
4. Open Docker Desktop from your Applications folder
5. Wait for it to start up (you'll see a whale icon in your menu bar)

If you're on Windows:

1. Open your browser and go to docker.com/products/docker-desktop
2. Download Docker Desktop for Windows
3. Run the installer — accept all defaults
4. Restart your computer when prompted
5. Open Docker Desktop from your Start menu

Verify it's working:

Open Terminal (Mac) or PowerShell (Windows) and copy and paste this command:

docker --version

You should see a version number. If you do, you're good.

Step 2: Clone the OpenClaw Repository

1. Open Terminal (Mac) or PowerShell (Windows)
2. Copy and paste this command:

git clone https://github.com/openclaw/openclaw

3. Then move into that folder:

cd openclaw

Step 3: Run the Setup Script

Copy and paste this command:

./docker-setup.sh

This will:

• Build the Docker image
• Walk you through the onboarding wizard (have your keys and tokens from guides 01-04 ready)
• Start the gateway

During the onboarding wizard, some tips:

• When asked about onboarding mode, choose manual
• When asked what to set up, choose Local gateway (this machine)
• For model provider, choose the option that matches what you set up in Guide 01

Step 4: Verify It's Running

Copy and paste this command:

docker compose run --rm openclaw-cli status

Important: You must run this from the same folder where you cloned OpenClaw.

Accessing the Web Dashboard

OpenClaw runs a web UI on port 18789. To get the access URL, copy and paste this command:

docker compose run --rm openclaw-cli dashboard --no-open

Copy the URL it gives you (it includes an authentication token) and open it in your browser.

Where Your Files Live

Docker mounts two folders from your computer into the container:

• ~/.openclaw/ — configuration, API keys, memory
• ~/openclaw/workspace/ — files the agent can see and create

These survive container restarts. Everything the agent does is saved here.

What You Should Have When Done

• Docker Desktop installed and running
• OpenClaw container running (docker ps shows it)
• Web dashboard accessible in your browser

---

Other platforms: Guide 05 (macOS), Guide 06 (VPS), Guide 07 (Raspberry Pi)