OpenClaw Setup Guide
Get OpenClaw running on your machine in under 30 minutes. This guide covers every platform — Windows, Mac, and Linux — with the exact commands we used to set up the SSBAA agent stack.
What is OpenClaw?
OpenClaw is an open-source AI agent platform that runs on your own machine. Unlike ChatGPT or Claude's web interface, it doesn't live in a browser tab — it runs as a persistent background service (called the Gateway) that connects AI models to your messaging apps and gives them access to real tools: your file system, the web, APIs, shell commands, and anything else you plug in.
The architecture is straightforward. A Gateway process sits at the centre, connecting your chat channels (Telegram, WhatsApp, Discord, Slack) to an AI model (Claude, GPT-4, local models) that has access to skills — pre-built or custom modules that give the agent capabilities. You message your agent from your phone. It thinks, executes, and replies.
At SSBAA, we run three agents on OpenClaw — YOSHI (operations), FOX (build), and ZELDA (content). They run overnight on a 14-job cron schedule and send us a Telegram brief every morning at 6am. This guide gets you to the point where your first agent is online and responding.
Why OpenClaw over alternatives? Self-hosted means your data stays on your machine. No subscription, no usage caps, no model restrictions. You choose the AI model, you own the memory, you control the skills. The SSBAA stack costs about $20–50/month in API calls depending on volume. Nothing else.
Requirements
Before you start, make sure your system has the following:
| Requirement | Minimum | Recommended |
|---|---|---|
| Node.js | v18 (may work) | v22+ (required for stable operation) |
| Git | Any recent version | Latest |
| RAM | 4GB | 8GB+ for multi-agent |
| Disk space | 500MB free | 2GB+ for logs and memory |
| OS | macOS 12, Ubuntu 20.04, Windows WSL2 | Latest of each |
| API key | Anthropic or OpenAI account | Anthropic Claude (best results) |
| Port 18789 | Must be free — this is the Gateway's WebSocket port | |
Check your Node version before anything else:
If you need to upgrade Node, use nodejs.org or run nvm install 22 && nvm use 22 if you have nvm.
Installation
OpenClaw installs as a global npm package. There are two methods — the one-liner (fastest) and the manual install (more control). We recommend the one-liner for first-time setups.
Windows (WSL2) — what we use at SSBAA
OpenClaw runs inside WSL2 on Windows. If you don't have WSL2 set up yet, open PowerShell as Administrator and run:
Once inside your WSL2 Ubuntu terminal, install Node.js v22 and then OpenClaw:
⚠️ Windows path note: Your Windows files are accessible inside WSL2 at /mnt/c/Users/YourName/. Your OpenClaw workspace will be at ~/.openclaw inside WSL2, which is separate from your Windows file system. Keep this in mind when copying files between the two environments.
macOS
If you hit an EACCES permission error on macOS, fix it with:
Linux (Ubuntu/Debian)
First-time setup (all platforms)
Once OpenClaw is installed, run the onboarding wizard. This sets up your workspace, connects your first AI model, and configures the Gateway:
💡 OpenRouter tip: If you want to run multiple agents on different models (like we do at SSBAA), choose OpenRouter as your provider. One API key routes to Claude, GPT-4, Gemini, DeepSeek, or any other model without separate accounts. Get your key at openrouter.ai.
Starting the Gateway
The Gateway is the core process — it's what actually runs your agent in the background. Start it with:
The Dashboard
With the Gateway running, open http://localhost:18789 in your browser. This is Mission Control — where you can see live agent sessions, memory usage, logs, active skills, and cron jobs.
What you'll see: A session panel showing your active agent, a memory panel showing the current MEMORY.md content and character count, a skills panel listing installed capabilities, and a log stream showing everything your agent is doing in real time.
Connecting an AI model
Your agent needs an AI model to think with. The two most common options:
Option A — Anthropic Claude (recommended)
- Go to console.anthropic.com and create an account
- Navigate to API Keys → Create Key
- Copy the key (starts with
sk-ant-) - Add it to OpenClaw:
openclaw config set anthropic_api_key sk-ant-YOUR-KEY
Option B — OpenRouter (for multiple models)
- Go to openrouter.ai and create an account
- Create an API key under Keys
- Add it:
openclaw config set openrouter_api_key sk-or-YOUR-KEY - Set your default model:
openclaw config set model openrouter/anthropic/claude-sonnet-4-6
⚠️ Never hardcode API keys in files you'll commit to Git or share publicly. OpenClaw stores keys in ~/.openclaw/openclaw.json which is local to your machine. Keep it that way.
Telegram integration
Telegram is the most reliable channel for interacting with your agent from your phone. Here's how to connect it:
Create a bot via BotFather
Open Telegram and search for @BotFather. Send /newbot, choose a name and username, and copy the token it gives you (looks like 1234567890:ABCdefGHI...).
Disable privacy mode
In BotFather, send /mybots → select your bot → Bot Settings → Group Privacy → Turn Off. This lets your bot read messages in group chats, not just direct messages.
Add the token to OpenClaw
Get your chat ID
Message your bot in Telegram, then run:
Save this. You'll need it for cron jobs that send you Telegram notifications.
Verifying it works
Send a message to your bot in Telegram. You should get a response within a few seconds. If it works, you're done. Your agent is live.
Troubleshooting
lsof -i :18789 then kill -9 [PID]. Or change the Gateway port in ~/.openclaw/openclaw.json.npm config get prefix to find it, then add /bin to your PATH in ~/.bashrc or ~/.zshrc.openclaw config set anthropic_api_key YOUR-KEY.openclaw gateway restart after any config change.~/.openclaw/memory/MEMORY.md — if it's over 8,000 characters, your agent may be hallucinating and crashing. Trim it manually or run openclaw memory compact.