Complete OpenClaw Setup Guide | From Zero to Hero
What is OpenClaw?
OpenClaw is an open-source AI agent developed by an Austrian engineer. It runs on your own PC and lets you interact with AI through chat apps like Discord, Telegram, and WhatsApp.
- ⚡ Send instructions to AI via Discord/Telegram/WhatsApp and other chat apps
- ⚡ Automates real-world tasks: web search, file management, calendar, etc.
- ⚡ Runs on your PC — you control your data and API keys (privacy-first, unlike SaaS)
- ⚡ Customize AI behavior and personality via SOUL.md file
- ⚡ Extend functionality with installable skills (plugins)
Prerequisites
You need the following to run OpenClaw.
PC: Mac, Windows, or Linux. 4GB+ RAM recommended.
Node.js 22+: Download LTS from nodejs.org. Verify: node --version
Port 18789: Used for OpenClaw's control UI. Keep it free.
LLM Provider API Key: Instructions in the next section.
Getting API Keys
OpenClaw uses LLM APIs to work. Get a key from one of these services. Anthropic is recommended.
Google Gemini
1. Go to Google AI Studio and log in with your Google account.
2. Click 'Get API key' on the left menu.
3. Click the blue 'Create API key' button in the center.
4. Copy the long string of text that appears (this is your API key) and paste it into a notepad to save it safely.
💡 Pro Tip: You can choose the standard Gemini 3.2 Pro or the ultra-fast Gemini 3 Flash. This is highly recommended for those who want to experiment with AI for free!
Anthropic (Claude) — Recommended
1. Go to console.anthropic.com, sign up/log in.
2. Click 'API Keys' in the left menu.
3. Click 'Create Key'.
4. Copy the random string and save it in a notepad. You'll paste it into the terminal later.
Pricing: Pay-as-you-go.
OpenAI (GPT)
1. Go to platform.openai.com/api-keys, log in.
2. Click 'Create new secret key'.
3. Copy and save the key.
Pricing: Pay-as-you-go.
EvoLink.AI (Cheaper Claude)
1. Sign up at evolink.ai.
2. Generate API key in dashboard.
3. During onboarding, select 'Skip' for provider.
4. Edit
openclaw.json later: add baseUrl: "https://code.evolink.ai" with your key in models section.Groq
1. Go to Groq Console and click 'Login' to create an account.
2. Click 'API Keys' on the left menu.
3. Click the 'Create API Key' button at the top right.
4. Give it a name (like
openclaw), click Submit, and copy the key to your notepad.💡 Pro Tip: If you want your chatbot to reply instantly, Groq is the best choice. Great tool to try out for free.
OpenRouter
1. Go to OpenRouter and click 'Sign In' to create an account.
2. Click your profile icon at the top right, then select 'Keys'.
3. Click the 'Create Key' button, give it a name, and save the key to your notepad.
💡 Pro Tip: By adding just a few dollars in credits using your credit card, you can freely switch between models like Claude 3.5 Sonnet, GPT-4o, and Llama 3 using this single key.
Local LLM (Ollama / LM Studio)
This method runs AI completely inside your own computer, so your data never leaves your machine.
【The Easiest Way: Ollama】
1. Download and install the software from ollama.com.
2. Open your computer's Terminal (the black screen).
3. Simply type
ollama launch openclaw and press Enter. It will magically configure OpenClaw completely automatically!⚠️ Note: To run local models smoothly, you need a decent computer (specifically, a graphics card with 12GB+ of memory).
Installation
Mac / Linux
Open Terminal:
- Mac: Command + Space, type 'Terminal', press Enter.
- Linux: Ctrl + Alt + T.
Copy and paste the command below, press Enter. Node.js auto-installs if missing:
curl -fsSL https://openclaw.ai/install.sh | bash Verify: type openclaw --version and press Enter. You should see a version number. If 'command not found', close and reopen terminal.
Windows (Quickstart via PowerShell)
【Step 1】 Open PowerShell (Admin)
1. Press the 'Windows key' on your keyboard.
2. Type powershell.
3. Right-click 'Windows PowerShell' in the search results.
4. Select 'Run as Administrator'.
5. Click 'Yes' if asked for permission.
【Step 2】 Adjust Security Settings
Windows blocks external scripts by default. We need to tell it this is safe.
Copy the text below, right-click inside the black PowerShell screen to paste it, and press Enter:Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
If it asks you to confirm, type Y on your keyboard and press Enter.
【Step 3】 Install OpenClaw!
Now, copy and paste the quickstart command below and press Enter:
iwr -useb https://openclaw.ai/install.ps1 | iex 💡 Pro Tip: If it asks 'Node.js is not installed, do you want to install it?', just follow the on-screen instructions (e.g., type 'Y') to let it automatically install the required software.
Alternative (npm): npm install -g openclaw@latest — for users with existing Node.js setup.
Onboarding Wizard (All Questions)
openclaw onboard --install-daemon Paste and press Enter. Questions appear one by one. Use Up/Down arrow keys to select, Enter to confirm. The --install-daemon flag enables auto-start on boot.
| Onboarding Item | The Answer to Give |
|---|---|
| Q1: Security warning | Select 'Yes' > Enter. Confirms external access permission. |
| Q2: Onboarding mode | Select 'QuickStart' > Enter. Sets Port: 18789, Bind: 127.0.0.1 (safe defaults). Change later with <code>openclaw configure</code>. |
| Q3: Model provider | Select the provider matching your API key (Anthropic/OpenAI etc.) > Enter. For EvoLink: 'Skip'. |
| Q4: Auth method | Usually keep default > Enter. |
| Q5: API Key | Select 'Paste API key now', paste your key (right-click > paste) > Enter. Characters won't show but are entered. |
| Q6: Default model | Select model (e.g. claude-sonnet-4.5) > Enter. |
| Q7: Messaging channels | Press Space to select apps, Enter to confirm. Multiple selections OK. |
| Q8: Configure skills? | Start with 'No' or minimal. Add later via <code>openclaw configure</code>. |
| Q9: Install daemon? | 'Yes' > Enter. Auto-starts on boot. |
| Q10: Hatch method | 'Hatch in TUI' starts interactive AI chat in terminal. |
Success looks like this:
After gateway starts, you should see:
- Discord: ok
- Control UI: http://127.0.0.1:18789
- Gateway token: xxxx
Chat App Integration
Discord Bot Setup (All 10 Steps)
- 1 Create a test Discord server if needed (click '+' in Discord sidebar).
- 2 Open Discord Developer Portal in your browser.
- 3 Click 'New Application', enter a name (e.g. OpenClaw Bot), click 'Create'.
- 4 Click 'Bot' in the left menu.
- 5 Click 'Reset Token' and copy the token immediately — it only shows once. Save it in a notepad.
- 6 [CRITICAL — Bot won't work without this]
Scroll down to 'Privileged Gateway Intents' and turn ON all 3 switches (blue):
-Presence Intent
-Server Members Intent
-Message Content Intent
Click 'Save Changes'. - 7 Go to 'OAuth2' > 'URL Generator'. Check 'bot' in SCOPES.
- 8 In BOT PERMISSIONS, check 'Send Messages', 'Read Messages/View Channels', 'Read Message History'.
- 9 Copy the 'Generated URL' at the bottom, open it in browser, select your server, click 'Authorize'.
- 10 Paste the token into the terminal when asked during onboarding. Select 'Allowlist' for channel access and enter channel name (e.g. servername/#general).
Run openclaw gateway restart. Test by sending @BotName hello in your Discord server. If bot is offline, recheck Intents (step 6).
DMs: First DM returns 'access not configured'. Use the pairing code: openclaw pairing approve discord PAIRING_CODE
Telegram Bot Setup (All 8 Steps)
- 1 Open Telegram on your phone or PC.
- 2 Search for
@BotFather(official account with blue checkmark). - 3 Send
/start. - 4 Send
/newbot. - 5 Enter a display name (e.g. My OpenClaw Bot).
- 6 Enter a username ending in 'bot' (e.g.
myopenclaw_bot). - 7 BotFather replies with a token like
123456789:ABCdefGHI.... Copy it. - 8 Paste the token into the terminal when asked during onboarding.
Search your bot in Telegram, send /start to get a pairing code. In a new terminal: openclaw pairing approve telegram CODE. Then send a message to test.
WhatsApp Setup (All 7 Steps)
- 1 In terminal:
openclaw channels login whatsapp - 2 A QR code appears in the terminal.
- 3 Open WhatsApp on your phone.
- 4 Tap 3 dots (menu) > 'Linked Devices' > 'Link a Device'.
- 5 Point your phone camera at the QR code on screen. Wait a few seconds.
- 6 Approve access:
openclaw pairing approve whatsapp +1XXXXXXXXXX(your phone number). - 7 Send yourself a message on WhatsApp to test.
Warning: WhatsApp integration may use unofficial libraries (not Meta Cloud API). There is a non-zero risk of account bans. Use a dedicated account.
Customization & Advanced Settings
Control OpenClaw's behavior deeply through configuration files. Always run openclaw gateway restart after any modifications.
SOUL.md — Define AI Personality & Rules
The SOUL.md file in your workspace directory acts as the ultimate system prompt for your AI. It shapes how your assistant thinks and acts.
Find file location:cat ~/.openclaw/openclaw.json | grep workspace
SOUL.md consists of three main sections:
- ✔ Personality: Defines the communication style.
E.g. 'You are an expert programmer. Be professional but highly friendly.', 'Never use pleasantries. Get straight to the point.' - ✔ Core Values: Absolute rules that cannot be broken.
E.g. 'Never transmit personal information or passwords externally.', 'Do not guess; if you are unsure, use web search immediately.' - ✔ Long-Term Instructions: Persistent formatting or logic rules.
E.g. 'Always summarize reports in under 5 bullet points.', 'Respond strictly in English.'
openclaw.json — Core Configuration
This is the primary file for managing limits, model changes, and security permissions.
Location: run openclaw config to edit.
Practical Examples:
Daily token limits (Cost control):"limits": { "maxTokensPerDay": 100000 }
Only reply when mentioned on Discord:"channels": { "discord": { "requireMention": true } }
Restrict bot usage solely to yourself:"allowFrom": ["user:YOUR_DISCORD_USER_ID"]
*To get your ID: Discord Settings > Advanced > Enable Developer Mode. Then right-click your profile icon > Copy ID.
Troubleshooting
Common issues and solutions during setup.
⚠️ openclaw: command not found
Close and reopen terminal. Verify Node.js with node --version (need v22+).
⚠️ Windows: script execution disabled
Run Set-ExecutionPolicy RemoteSigned -Scope CurrentUser, type 'Y', press Enter.
⚠️ HTTP 429 / Insufficient balance
API limit reached. Open http://127.0.0.1:18789, change model in Dashboard, or run openclaw configure.
⚠️ Discord Bot stays offline
Check all 3 Privileged Gateway Intents are ON in Developer Portal. Run openclaw gateway restart. Check logs: openclaw logs | tail -20 — look for code 4014.
⚠️ Port 18789 in use
Mac/Linux: sudo lsof -i :18789. Windows: netstat -ano | findstr 18789. Kill the conflicting process.
⚠️ Docker containers crash
Docker Desktop > Settings > Resources > Memory to 8GB+, CPU to 4+ cores.
⚠️ Pairing stuck
Run openclaw doctor, then openclaw gateway restart and retry pairing.
⚠️ Skill install fails (Broken pipe)
Run openclaw doctor to check skill status, then reinstall.
Useful diagnostic commands:
- ▶
openclaw gateway status— Check gateway status - ▶
openclaw logs --follow— Real-time logs - ▶
openclaw doctor— Auto-diagnosis - ▶
openclaw configure— Change settings - ▶
openclaw dashboard— Open control UI in browser