AI & Privacy
How to Install and Set Up OpenClaw: A Complete Guide for First-Timers
Practical Web Tools Team
10 min read
OpenClaw is a self-hosted AI assistant gateway that connects large language models — Claude, GPT, Gemini, or local models via Ollama — to your local system and messaging platforms. Unlike a typical chatbot that disappears when you close a browser tab, OpenClaw runs as a persistent background daemon. It can execute shell commands, manage files, automate browser tasks, and reach you proactively through WhatsApp, Telegram, Discord, Slack, Signal, iMessage, and over a dozen other channels.
This guide walks you through installation, configuration, and your first conversation. Budget about 10–15 minutes if you already have Node.js and an API key ready, or 25–30 minutes starting from scratch.
Before you begin, make sure you have:
node --version. If you need to install it, use nvm on macOS/Linux or nvm-windows on Windows.Windows users: OpenClaw runs on both native Windows and WSL2, but WSL2 is the recommended path. It's more stable, and most of the community troubleshooting advice assumes a Linux-like environment. Install WSL2 first with wsl --install in PowerShell, then do everything else inside that Linux shell.
There are several installation methods. Pick whichever fits your workflow.
macOS / Linux:
curl -fsSL https://openclaw.ai/install.sh | bash
Windows (PowerShell, as Administrator):
iwr -useb https://openclaw.ai/install.ps1 | iex
If you prefer managing it through npm directly:
npm install -g openclaw@latest
If you get EACCES permission errors on macOS/Linux, either prefix with sudo or — better — use nvm so global installs don't require root.
Good for isolation, reproducibility, and server deployments:
docker pull openclaw/openclaw:latest
docker run -d \
--name openclaw \
-p 3000:3000 \
-v ~/.openclaw:/root/.openclaw \
--env-file ~/.openclaw/.env \
openclaw/openclaw:latest
Or use Docker Compose for a persistent setup:
version: '3.8'
services:
openclaw:
image: openclaw/openclaw:latest
ports:
- "3000:3000"
volumes:
- ~/.openclaw:/root/.openclaw
env_file: ~/.openclaw/.env
restart: unless-stopped
Docker mounts ~/.openclaw for configuration/credentials and uses a workspace directory as the agent's sandbox. Make sure the Node user (UID 1000) has permission to the mounted volumes. If you hit EACCES errors, fix ownership with chown -R 1000:1000 ~/.openclaw.
For VPS deployments with less than 2 GB of RAM, allocate a 4 GB swap file to avoid out-of-memory issues.
openclaw --version
You should see a version number like v2026.3.12. If the command isn't found, your PATH likely doesn't include the npm global bin directory — run npm bin -g to find it, then add it to your shell profile.
This is the interactive setup that walks you through everything:
openclaw onboard --install-daemon
The --install-daemon flag sets up a background service (launchd on macOS, systemd on Linux) so OpenClaw keeps running even after you close your terminal.
The wizard covers the following in order:
You'll be asked how to bind the gateway. For local-only use, select Loopback (127.0.0.1). This is the secure default — it means only your machine can reach the gateway. Don't bind to 0.0.0.0 unless you know what you're doing and have other access controls in place.
Choose your AI provider: Anthropic (Claude), OpenAI (GPT), Google (Gemini), or a local model through Ollama. You can switch providers anytime by editing the config file later.
A few notes on choosing:
Paste your key from the provider's dashboard. It gets stored locally in ~/.openclaw/openclaw.json (or .env depending on your install method). The key is only ever sent to the AI provider — treat this file like a password vault and never commit it to version control.
Tip: If you already have Claude Code installed, you can reuse existing credentials via claude setup-token without setting up a new key.
The wizard can connect messaging platforms right away, or you can skip this and add them later. More on this in Step 4.
Select Finished to save your configuration. The wizard will ask if you want to restart the service — say yes.
Run a few quick health checks:
# Check the gateway is up
openclaw gateway status
You should see the gateway listening on port 18789.
# Run diagnostics
openclaw doctor
This checks your Node.js version, dependencies, config files, and connectivity. Fix anything it flags before continuing.
# Confirm your models are accessible
openclaw models list
You should see your provider's models listed, something like anthropic/claude-sonnet-4-6. If the list is empty, that almost always means the API key is wrong or billing isn't set up on your provider account. Go back to your provider's console and verify.
This is where OpenClaw becomes more than a terminal chatbot. You can connect it to the messaging apps you already use daily.
Run the command the wizard provides (or openclaw channels login --channel whatsapp) to display a QR code. Open WhatsApp → Settings → Linked Devices → scan the code. A few things to know:
~/.openclaw/credentials/whatsapp/.Create a bot via @BotFather on Telegram, copy the bot token, and paste it during setup. One gotcha: your first DM to the bot will return a pairing code that you need to approve before the bot will respond. This is a security measure, not a bug.
Create an application at discord.com/developers, add a bot, copy the token, and paste it in. Make sure you enable the necessary intents (Message Content, etc.) in the developer portal.
This one takes a few more steps:
chat:write, im:read, channels:history, groups:history, and any others relevant to your use case.OpenClaw supports Signal, iMessage (via BlueBubbles), Google Chat, Microsoft Teams, Matrix, IRC, LINE, WeChat, and many more. Each has its own setup flow documented at docs.openclaw.ai/channels.
You have two main interfaces for direct interaction:
openclaw chat
Opens an interactive terminal session. Fast and clean — great if you already live in a terminal.
openclaw dashboard
This opens the Control UI at http://127.0.0.1:18789 in your browser. You'll need the access token that was displayed during setup (check your terminal output, or look in your config file). The web UI is better for longer conversations or when you want a more visual experience.
Either way, try sending a message like "What can you do?" to confirm everything is wired up.
OpenClaw isn't a sandboxed chatbot — it's a long-running, high-privilege gateway with shell access and file permissions. That creates a real attack surface. A few things to do immediately:
Enable consent mode. Set exec.ask: "on" in your config so the agent asks for your approval before running write or exec commands. This is especially important early on while you're learning what the agent can do.
Lock down DM policies. By default, unknown DMs receive a short pairing code and messages aren't processed until approved. Don't loosen this unless you have a good reason. Run openclaw doctor to surface risky DM policies.
Don't expose the Control UI to the public internet. If you need remote access, use SSH tunnels or Tailscale rather than opening port 18789 to the world.
Treat ~/.openclaw like a secrets directory. It contains API keys, session credentials, and messaging tokens. Default file permissions should restrict it to your user account — verify with ls -la ~/.openclaw.
Gateway not responding / "0 tokens used": The daemon stopped or API auth failed. Run openclaw gateway restart and double-check your API keys.
"RPC probe: failed": Port 18789 is in use by something else. Find the conflict with sudo lsof -i :18789 and terminate the other process.
"Access not configured" / "auth not configured": Your user ID isn't allowlisted, or you skipped the auth step during onboarding. Re-run the wizard or manually configure auth in your config file. Without it, the agent won't respond.
Empty model list: Invalid API key or billing not enabled on your provider account. Verify at your provider's dashboard.
Node.js version errors: OpenClaw requires Node 22.14+. Check with node --version and upgrade via nvm install --lts && nvm use --lts if needed.
Docker EACCES errors: The container's Node user (UID 1000) can't write to mounted volumes. Fix with chown -R 1000:1000 ~/.openclaw.
For anything else, openclaw doctor runs automated health checks and openclaw logs --follow gives you real-time debugging output. The OpenClaw Discord is also an active place for installation support.
| Command | What it does |
|---|---|
openclaw onboard |
Re-run the setup wizard |
openclaw gateway status |
Check if the gateway is running |
openclaw gateway restart |
Restart the gateway |
openclaw doctor |
Run automated health checks |
openclaw models list |
List available models from your provider |
openclaw chat |
Start a terminal chat session |
openclaw dashboard |
Open the web UI |
openclaw status --all |
Full debug report (good for copy-pasting into support channels) |
openclaw logs --follow |
Stream live logs |
openclaw update |
Update to the latest version |
openclaw update
Check the changelog for what's new in each release. Staying current is especially important for security patches, since you're running an agent with system-level access.
Once you have the basics running, the real power of OpenClaw opens up:
openclaw plugins list. Browser automation, web search, cron scheduling, and more are available out of the box.The full documentation lives at docs.openclaw.ai. Start with one real workflow — one chat platform, one model, a small workspace — and expand from there as you get comfortable with what the agent can do.
