How to Set Up OpenClaw: The Only Guide You Need

OpenClaw is a personal AI assistant that runs on your machine and talks to you through WhatsApp, Telegram, Slack, Discord, iMessage, or a dozen other channels. It does not just answer questions — it sends emails, manages files, runs terminal commands, and automates workflows on your behalf.

This guide gets you from zero to a working, secure OpenClaw installation in about 15 minutes.

What You Need Before Starting

• macOS, Linux, or Windows (WSL2 strongly recommended on Windows)
• Node.js 22 or newer — check with `node --version`
• An API key from Anthropic or OpenAI
• Basic terminal comfort — you will copy and paste a few commands

Which AI Provider?

OpenClaw works with Anthropic (Claude), OpenAI, or local models via Ollama. The project creator strongly recommends Anthropic Pro or Max with Opus 4.6 for the best results — better long-context handling and stronger prompt-injection resistance.

• Anthropic API key: console.anthropic.com
• OpenAI API key: platform.openai.com

Step 1 — Install OpenClaw

Pick whichever method you prefer. All three work.

Option A: npm (recommended)

``` npm install -g openclaw@latest ```

Or with pnpm:

``` pnpm add -g openclaw@latest ```

Option B: Install script

macOS / Linux / WSL2:

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

Windows PowerShell:

``` iwr -useb https://openclaw.ai/install.ps1 | iex ```

The script detects your Node version, installs OpenClaw, and launches the onboarding wizard automatically.

Option C: macOS App

Download and launch OpenClaw.app from the menu bar. The app bundles and manages the Gateway service for you. After launching, complete the onboarding checklist in the app.

Step 2 — Run the Onboarding Wizard

If you used npm or pnpm, run this next:

``` openclaw onboard --install-daemon ```

The wizard walks you through everything interactively:

1. Model and Auth — paste your Anthropic or OpenAI API key
2. Workspace — where agent files live (default: `~/.openclaw/workspace`)
3. Gateway — port, bind address, and auth mode
4. Channels — pick your messaging platforms (WhatsApp, Telegram, Slack, Discord, Signal, iMessage, Google Chat, Microsoft Teams, and more)
5. Daemon — installs a background service (launchd on macOS, systemd on Linux) so the gateway stays running
6. Skills — installs recommended skills and optional dependencies

That is it. One command handles the entire setup.

Step 3 — Verify It Works

Check the gateway

``` openclaw gateway status ```

You should see the gateway running on 127.0.0.1:18789 (localhost). If it shows 0.0.0.0, see the security section below.

Open the dashboard

``` openclaw dashboard ```

This opens the Control UI at http://127.0.0.1:18789/ in your browser. Send a test message — if you get a response, you are up and running.

Run a quick test from the CLI

``` openclaw agent --message "What time is it?" --thinking high ```

If you get a response, your API key and gateway are working correctly.

Run the doctor

``` openclaw doctor ```

This checks your configuration for common issues — misconfigured DM policies, missing dependencies, version problems. Fix anything it flags before connecting messaging channels.

Step 4 — Connect a Messaging Channel

OpenClaw supports WhatsApp, Telegram, Slack, Discord, Google Chat, Signal, BlueBubbles (iMessage), Microsoft Teams, Matrix, Zalo, and WebChat.

WhatsApp (most popular)

Run the channel login command:

``` openclaw channels login ```

Select WhatsApp. You will see a QR code — scan it with your phone's WhatsApp app to link the device. Then add allowed contacts in your config file (`~/.openclaw/openclaw.json`):

``` { channels: { whatsapp: { allowFrom: ["+15555550123"] } } } ```

Telegram

1. Create a bot with @BotFather on Telegram to get a bot token
2. Add the token to your config:

``` { channels: { telegram: { botToken: "YOUR_BOT_TOKEN" } } } ```

1. Message your bot on Telegram. You will receive a pairing code — approve it:

``` openclaw pairing approve telegram <code> ```

Discord

Similar to Telegram — add your bot token and app token to the config, invite the bot to your server, and approve pairing.

Full channel setup docs: docs.openclaw.ai/channels

Step 5 — Lock It Down

OpenClaw connects to real messaging surfaces and can execute commands on your machine. Security is not optional.

DM Pairing (enabled by default)

By default, unknown senders who message your bot receive a pairing code. The bot ignores their message until you approve them:

``` openclaw pairing approve <channel> <code> ```

This prevents strangers from controlling your agent. Do not disable this unless you know what you are doing.

Gateway Binding

The gateway should bind to 127.0.0.1 (localhost only), not 0.0.0.0 (all interfaces). Check with:

``` openclaw gateway status ```

If it shows 0.0.0.0, edit `~/.openclaw/openclaw.json`:

``` { gateway: { host: "127.0.0.1", port: 18789 } } ```

Then restart: `openclaw gateway stop && openclaw gateway start`

Docker Sandbox for Non-Main Sessions

For extra isolation, configure sandbox mode so non-main sessions run inside Docker containers:

``` { agents: { defaults: { sandbox: { mode: "non-main" } } } } ```

Remote Access — Use Tailscale or SSH

Never expose port 18789 to the internet. If you need to reach OpenClaw from your phone outside your network:

• Tailscale (recommended) — install on both devices, access through the mesh VPN
• SSH tunnel — `ssh -L 18789:localhost:18789 your-server`

Troubleshooting

Gateway will not start

``` openclaw logs --follow ```

Common causes: Node version below 22, port 18789 already in use, corrupted config. For port conflicts, use a different port: `openclaw gateway --port 18790`.

Permission errors on macOS

Do not use sudo. Fix npm permissions:

``` sudo chown -R $(whoami) ~/.npm ```

Or install Node via Homebrew, which sets permissions correctly.

API key not working

1. Verify the key is copied correctly — no extra spaces
2. Check you have credits or quota remaining
3. Make sure the key has access to the model you selected
4. Run `openclaw doctor` to check config

Something else broken

``` openclaw doctor --deep ```

This runs a deep diagnostic and flags exactly what needs fixing. For config resets, delete `~/.openclaw/openclaw.json` and re-run `openclaw onboard`.

What to Do Next

Your OpenClaw instance is installed, secured, and connected. Here is what to try:

1. Send it a task from your phone — "Check my calendar for tomorrow and list any conflicts"
2. Install a skill — browse curated skills at the ClawHub or install directly: `npx clawhub@latest install browser`
3. Explore automations — see [@portabletext/react] Unknown block type "span", specify a component for it in the `components.types` prop
4. Stay updated — run `openclaw update --channel stable` to get the latest patches
5. Join the community — discord.gg/clawd for support and skill sharing

OpenClaw has 190,000+ GitHub stars for a reason. It is the first AI assistant that actually does things — not just talks about them. Now it is running on your machine, secured and ready to work.

Sources:

• OpenClaw GitHub Repository (github.com/openclaw/openclaw)
• OpenClaw DeepWiki (deepwiki.com/openclaw/openclaw)
• OpenClaw Documentation (docs.openclaw.ai)
• SecurityScorecard STRIKE Report (Feb 9, 2026)