HowtoSetUpOpenClawonmacOSandWindows:YourPersonalAIAssistant

OpenClaw is an open-source personal AI assistant with over 224,000 GitHub stars. It runs on your own machine, connects to any LLM provider (OpenAI, Anthropic, Google Gemini, Groq, Mistral, Ollama, and more), and plugs into WhatsApp, Telegram, Discord, Slack, iMessage, Signal, Teams, Matrix, and Google Chat from a single gateway.

No cloud subscription. No vendor lock-in. Your data stays on your hardware.

This guide walks you through installing OpenClaw, configuring it properly, connecting channels, hardening security, and avoiding the real-world issues that trip people up. Everything is sourced from the official docs, the GitHub README, and the 7,700+ open issues where users report what actually goes wrong.

Official repo: github.com/openclaw/openclaw (MIT License, ~224,900 stars) Official docs: docs.openclaw.ai

Table of Contents

1. What Is OpenClaw?
2. Prerequisites
3. Install OpenClaw
4. Run the Onboarding Wizard
5. Verify the Gateway
6. Open the Control UI
7. Configure Your AI Model
8. Run a Fully Local AI (Ollama)
9. Connect Messaging Channels
10. Chat Commands (The Hidden Power)
11. Customize Your Agent
12. Install Skills
13. Set Up Automation (Cron, Webhooks, Gmail)
14. Browser Control
15. Companion Apps (macOS, iOS, Android)
16. Remote Access with Tailscale
17. Docker Setup
18. Security Hardening
19. Commands Reference
20. File Locations
21. Real-World Gotchas (From 7,700+ GitHub Issues)
22. Troubleshooting
23. Uninstalling

What Is OpenClaw?

OpenClaw is a local-first AI gateway built on a WebSocket control plane. It is not just a chatbot -- it is an agent runtime that can:

• Chat from any platform -- WhatsApp, Telegram, Discord, Slack, iMessage, Signal, Teams, Matrix, Google Chat, and a browser-based web UI
• Use any LLM -- OpenAI, Anthropic, Google Gemini, Groq, Mistral, xAI Grok, or local models via Ollama
• Run tools -- browse the web, execute shell commands, read/write files, manage your calendar, generate images
• Control your browser -- a dedicated Chromium instance that the AI can navigate, screenshot, and interact with
• Talk across sessions -- agents can discover, read transcripts of, and message other active sessions
• Run on your phone -- companion apps for macOS, iOS, and Android with camera, screen recording, and voice
• Automate with cron -- schedule recurring tasks, webhooks, and Gmail triggers
• Self-host completely -- everything runs on your hardware with no data leaving your machine

Think of it as your own private AI infrastructure that you control end to end.

Prerequisites

You need Node.js 22 or newer. That is the only hard requirement.

Check your version:

node --version

If the output shows v22.x.x or higher, you are ready. If not:

macOS

brew install node@22

Or download from nodejs.org.

Windows

winget install OpenJS.NodeJS.LTS

Or download the LTS installer from nodejs.org. Make sure "Add to PATH" is checked during installation.

Other Requirements

Install OpenClaw

macOS and Linux

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

This downloads the CLI, installs it globally, and sets up the background service.

Windows (PowerShell as Administrator)

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

Strongly recommended: If you have WSL2, open your WSL terminal and use the macOS/Linux command instead. Windows native has known issues with plugin installation (spawn EINVAL errors) and general stability.

Alternative: npm / pnpm / bun

npm install -g openclaw@latest
# or
pnpm add -g openclaw@latest

Update Channels

OpenClaw has three release channels:

Switch channels:

openclaw update --channel stable
openclaw update --channel beta

Verify Installation

openclaw --version

If you see "command not found," close and reopen your terminal.

Run the Onboarding Wizard

openclaw onboard --install-daemon

The wizard walks you through:

1. Authentication setup for the Control UI
2. Gateway configuration (the background service that powers everything)
3. Model provider selection (which LLM to use)
4. Optional channel connections (WhatsApp, Telegram, etc.)

It generates a gateway token and writes your configuration to ~/.openclaw/openclaw.json.

Run diagnostics after onboarding to catch configuration issues early:

openclaw doctor

This checks your config, API keys, channel credentials, and gateway health. Fix anything it flags before proceeding.

Verify the Gateway

The gateway is the WebSocket control plane that coordinates everything -- channels, agents, tools, and the web UI.

openclaw gateway status

If it is not running, start it manually:

openclaw gateway --port 18789

For verbose output during troubleshooting:

openclaw gateway --port 18789 --verbose

Health check:

openclaw health

Open the Control UI

openclaw dashboard

This opens http://127.0.0.1:18789/ in your browser. The Control UI is the fastest way to start chatting -- no channel setup required. Type a message and your AI assistant responds.

Configure Your AI Model

OpenClaw supports every major provider out of the box. Models use the provider/model format.

Recommended: The README suggests Anthropic Pro/Max with Opus 4.6 for the best experience -- it has the strongest long-context handling and prompt-injection resistance.

Set Your API Key

# For Anthropic
export ANTHROPIC_API_KEY="sk-ant-your-key-here"

# For OpenAI
export OPENAI_API_KEY="sk-your-key-here"

Make it permanent:

macOS/Linux (zsh):

echo 'export ANTHROPIC_API_KEY="sk-ant-your-key-here"' >> ~/.zshrc
source ~/.zshrc

Windows (PowerShell profile):

Add-Content $PROFILE 'setx ANTHROPIC_API_KEY "sk-ant-your-key-here"'

Set a Default Model

Edit ~/.openclaw/openclaw.json:

{
  "agent": {
    "model": "anthropic/claude-opus-4-6"
  }
}

Model Failover

You can configure a primary model with fallbacks. If the primary fails (rate limit, outage), OpenClaw automatically tries the next one:

{
  "agent": {
    "model": "anthropic/claude-opus-4-6",
    "fallback": "openai/gpt-5.1-codex"
  }
}

Gotcha: A 429 rate-limit error on one Gemini model can trigger a global auth profile cooldown that kills all your fallback models too (#13623). If you use Gemini, be aware of this.

Run a Fully Local AI with Ollama

If you want zero API costs and complete privacy -- nothing leaves your machine -- use Ollama.

Install Ollama

Download from ollama.ai and install. Then pull a model:

ollama pull llama3

Configure OpenClaw

{
  "agent": {
    "model": "ollama/llama3"
  }
}

No API key. No cloud. Completely private. The tradeoff is that local models are less capable than cloud models like Claude Opus or GPT-5, but for personal tasks, summarization, and simple coding help, they work well.

Gotcha: Some users report that changing the model to Ollama does not take effect (#4544). If this happens, restart the gateway after changing your config: stop the gateway, update openclaw.json, then start it again.

Connect Messaging Channels

This is where OpenClaw gets powerful. All channels run simultaneously from the same gateway.

WhatsApp

WhatsApp uses QR code pairing through WhatsApp Web:

openclaw channels login

A QR code appears in your terminal. Open WhatsApp on your phone > Settings > Linked Devices > Link a Device > scan the code. Send yourself a message and OpenClaw responds.

Configure who can DM your bot:

{
  "channels": {
    "whatsapp": {
      "allowFrom": ["+15551234567"],
      "groups": ["group-id-here"]
    }
  }
}

Telegram

1. Open Telegram and search for @BotFather
2. Send /newbot and follow the prompts
3. Copy the bot token

openclaw channels add --channel telegram --token "YOUR_BOT_TOKEN"

Or configure directly:

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

Optional: Set up webhook mode for better reliability:

{
  "channels": {
    "telegram": {
      "botToken": "YOUR_TOKEN",
      "webhookUrl": "https://your-domain.com/telegram",
      "webhookSecret": "your-secret"
    }
  }
}

For groups: Add requireMention: true so the bot only responds when @mentioned.

Discord

1. Go to discord.com/developers/applications > New Application
2. Go to Bot section > Add Bot
3. Enable Message Content Intent under Privileged Gateway Intents
4. Copy the bot token
5. Use OAuth2 > URL Generator with bot scope and "Send Messages" + "Read Message History" permissions
6. Open the generated URL to invite the bot to your server

openclaw channels add --channel discord --token "YOUR_DISCORD_BOT_TOKEN"

Gotcha: Reasoning/thinking content from some models leaks into Discord messages regardless of settings (#6470). Check your output formatting if you see raw thinking blocks in Discord.

Slack

1. Go to api.slack.com/apps > Create new app
2. Enable Socket Mode and create an App-Level Token (xapp-)
3. Under OAuth & Permissions, add bot scopes: chat:write, channels:read, im:read, im:write
4. Install the app to your workspace

Configure:

{
  "channels": {
    "slack": {
      "botToken": "xoxb-...",
      "appToken": "xapp-...",
      "dmPolicy": "pairing",
      "allowFrom": ["U1234567890"]
    }
  }
}

Signal

Requires the signal-cli binary installed separately. Configure the channels.signal section in your config.

iMessage (via BlueBubbles)

Requires a macOS machine running BlueBubbles server:

{
  "channels": {
    "bluebubbles": {
      "serverUrl": "http://your-mac-ip:1234",
      "password": "your-bluebubbles-password",
      "webhookPath": "/bluebubbles"
    }
  }
}

The BlueBubbles server must run on macOS, but the OpenClaw gateway can run elsewhere.

Microsoft Teams

Requires a Teams app registration + Bot Framework. Configure msteams.allowFrom and groupAllowFrom allowlists. Set groupPolicy: "open" for group access.

Matrix

Configure channels.matrix with your homeserver, access token, and session scope settings.

All Channels at Once

Every channel connects to the same gateway simultaneously. You can chat with the same AI from WhatsApp on your phone, Discord on your desktop, and the web UI in your browser -- all sharing context if desired.

Chat Commands

Once you are chatting with your OpenClaw assistant (from any channel or the web UI), these commands work inline. Most people do not know these exist.

Thinking Levels

This is one of OpenClaw's best features. You can control how deeply the AI reasons about your request:

• off -- No extended thinking, fastest responses
• minimal / low -- Light reasoning
• medium -- Balanced (default)
• high / xhigh -- Deep reasoning for complex problems

Change it mid-conversation: /think high

Customize Your Agent

OpenClaw uses special markdown files in your workspace to define your agent's behavior and identity.

Workspace Structure

Everything lives in ~/.openclaw/workspace/:

AGENTS.md

This is like CLAUDE.md but for OpenClaw. Define what your agent knows, how it should behave, and what rules it follows:

# Agent Instructions

## Identity
You are my personal assistant. Be concise and direct.

## Rules
- Never share my personal information
- Always cite sources when making claims
- For code, prefer Python unless I specify otherwise
- Use metric units

## Knowledge
- My timezone is US/Eastern
- I work at Acme Corp in the DevOps team
- Our tech stack is AWS, Terraform, Kubernetes

SOUL.md

Define your agent's personality:

# Personality

You are professional but approachable. Use humor sparingly.
You prefer practical solutions over theoretical ones.
When uncertain, say so rather than guessing.

Version Control Your Workspace

Pro tip: Make ~/.openclaw/workspace a private Git repo:

cd ~/.openclaw/workspace
git init
git add -A
git commit -m "Initial workspace"

This version-controls your skills, prompts, agent config, and memories.

Install Skills

Skills extend what your assistant can do. OpenClaw has over 3,500 skills on ClawHub.

# Browse available skills
openclaw skills list

# Install from ClawHub
clawhub install <skill-name>

Manual Installation

cd ~/.openclaw/workspace
git clone https://github.com/some-user/some-skill ./skills/some-skill

Skills need a SKILL.md file with YAML frontmatter. After installing, restart the gateway for the skill to activate.

Popular skills include web browsing, file management, shell command execution, image generation, calendar integration, and code execution.

Gotcha: npm-based extension/plugin installation is broken on Windows with spawn EINVAL errors (#7631). Use WSL or install skills manually via git clone.

Set Up Automation

OpenClaw has built-in automation that most guides skip entirely.

Cron Jobs

Schedule recurring tasks that your AI executes on a schedule:

{
  "cron": {
    "daily-summary": {
      "schedule": "0 9 * * *",
      "message": "Summarize my unread emails and Slack messages",
      "announce": "telegram"
    }
  }
}

This runs every day at 9 AM and sends the result to your Telegram.

Webhooks

Trigger your AI from external services:

{
  "webhooks": {
    "deploy-alert": {
      "path": "/webhook/deploy",
      "message": "A deployment just happened. Check the status and summarize."
    }
  }
}

Gmail Pub/Sub Triggers

Connect Gmail to trigger your AI when emails arrive matching certain criteria.

Cross-Session Communication

Agents can talk to each other across sessions:

• sessions_list -- Discover active sessions
• sessions_history -- Read another session's transcript
• sessions_send -- Send a message to another session

This enables multi-agent workflows where specialized agents collaborate.

Browser Control

OpenClaw can launch and control a dedicated Chromium instance.

Enable it in your config:

{
  "browser": {
    "enabled": true,
    "color": "#FF4500"
  }
}

Once enabled, your agent can:

• Open URLs and navigate pages
• Take screenshots and snapshots
• Fill forms and click buttons
• Upload files
• Manage browser profiles

Gotcha: Browser control is intermittently broken -- browser.act times out while snapshot and open work fine (#14503). If you hit this, restart the gateway.

Companion Apps

OpenClaw is not just a terminal tool.

macOS

A menu bar app with:

• Quick access to your AI
• Voice Wake ("Hey OpenClaw")
• Talk Mode overlay
• WebChat integration

iOS

• Canvas support
• Voice Wake and Talk Mode
• Camera and screen recording access
• Bonjour pairing with your gateway

Android

• Canvas and Talk Mode
• Camera and screen recording
• Optional SMS channel

Gotcha: The macOS companion app has a known issue where it fails to pass the gateway auth token over SSH tunnels (#13552). There is no UI field to enter it manually and it does not auto-read from remote config. If you use SSH tunnels, configure the token manually in the app's settings file.

Linux and Windows companion apps are an open feature request (#75).

Remote Access with Tailscale

If you want to access your OpenClaw instance from outside your local network, Tailscale integration is built in.

Modes

Configuration

{
  "gateway": {
    "bind": "loopback",
    "tailscale": {
      "mode": "serve"
    }
  }
}

Important rules:

• gateway.bind must stay loopback when Tailscale is enabled
• Funnel mode requires gateway.auth.mode: "password" (it is publicly accessible)
• Optional: gateway.tailscale.resetOnExit: true for cleanup

Architecture for Remote Setups

A common pattern: run the gateway on a Linux VPS or home server, then connect from anywhere via Tailscale. Tool execution (shell commands, file access) runs where the gateway lives. Device actions (camera, notifications) run on your local device nodes.

Docker Setup

Docker is ideal for always-on setups or full isolation.

Requirements

• Docker Desktop (macOS/Windows) or Docker Engine (Linux)
• Docker Compose v2

Quick Start

git clone https://github.com/openclaw/openclaw.git
cd openclaw
./docker-setup.sh

This builds the image, generates a token, starts the gateway, and runs onboarding.

After it finishes, open http://127.0.0.1:18789/ and paste your token in Settings.

Manual Docker Commands

docker build -t openclaw:local -f Dockerfile .
docker compose run --rm openclaw-cli onboard
docker compose up -d openclaw-gateway

Connect Channels via Docker

# WhatsApp
docker compose run --rm openclaw-cli channels login

# Telegram
docker compose run --rm openclaw-cli channels add --channel telegram --token "TOKEN"

# Discord
docker compose run --rm openclaw-cli channels add --channel discord --token "TOKEN"

Config persists at ~/.openclaw/ on the host.

Gotcha: Docker manual setup frequently fails because the CLI cannot reach the gateway due to network configuration issues (#5559). Make sure the CLI container can resolve the gateway's hostname. Using docker compose (not standalone containers) avoids most of these issues.

Security Hardening

This is critical. In January 2026, security researchers found that 93.4% of publicly exposed OpenClaw instances were vulnerable to exploitation. Take these steps seriously.

1. Never Expose the Gateway to the Public Internet

The gateway defaults to 127.0.0.1 (localhost only). Keep it that way. Use Tailscale if you need remote access.

2. Use a Strong Gateway Token

The onboarding wizard generates one automatically. Rotate it periodically:

openclaw gateway token rotate

3. Understand the DM Security Model

By default, OpenClaw uses pairing mode:

• An unknown sender messages your bot
• They receive a short pairing code
• You approve it: openclaw pairing approve <channel> <code>
• The sender is added to your allowlist

Open mode (dmPolicy: "open") lets anyone message your bot. This is risky. The openclaw doctor command will warn you if open mode is enabled.

4. Enable Agent Sandboxing for Groups/Channels

For untrusted inputs (group chats, public channels), enable Docker-based sandboxing:

{
  "agents": {
    "defaults": {
      "sandbox": {
        "mode": "non-main",
        "scope": "agent",
        "docker": {
          "network": "none",
          "user": "1000:1000",
          "capDrop": ["ALL"],
          "memory": "1g",
          "pidsLimit": 256
        }
      }
    }
  }
}

This runs tool execution for non-main sessions inside isolated containers with no network, dropped capabilities, and resource limits.

Default sandbox allowlist: bash, process, read, write, edit, sessions_list, sessions_history, sessions_send, sessions_spawn

Default sandbox denylist: browser, canvas, nodes, cron, discord, gateway

5. Protect API Keys from Agent Access

There is an open security discussion about preventing agents from reading API keys from environment variables or config files (#11829). For now, avoid storing sensitive credentials in places the agent can cat or env.

6. Keep OpenClaw Updated

openclaw update --channel stable

Or reinstall:

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

The installer detects existing installations and upgrades in place.

Commands Reference

CLI Commands

In-Chat Commands

File Locations

Real-World Gotchas

These come from tracking the 7,700+ open issues on GitHub. You will not find most of these in the documentation.

npm Installation Fails

The most basic issue -- npm install -g openclaw@latest fails outright for some users (#23861). If this happens, use the curl installer instead.

macOS Gateway Never Becomes Ready

The setup wizard gets stuck on "Retry" because the gateway never reaches a ready state (#6156). Workaround: Start the gateway manually with openclaw gateway --port 18789 --verbose and check the output for errors.

Windows Plugin Installation Broken

openclaw plugins install fails on Windows with spawn EINVAL (#7631). Use WSL or install skills manually via git clone.

Cannot Change Model

Some users report that changing the model in config has no effect (#4544, #19196). Workaround: Stop the gateway completely, edit ~/.openclaw/openclaw.json, then restart.

Gemini Outputs Fake Tool Calls

Google Gemini models sometimes output text that looks like a tool call instead of actually executing tools (#3344). This is a model-level issue. Switching to Anthropic or OpenAI models avoids it.

NVIDIA NIM Hangs the Gateway

The NVIDIA NIM provider can cause the gateway to freeze during requests (#5980). If you use NVIDIA NIM, monitor for hangs and restart the gateway when needed.

Browser Control Intermittent Timeouts

browser.act times out while snapshot and open work fine (#14503). Restarting the gateway usually fixes it temporarily.

Legacy Config File Conflicts

If you upgraded from an older version, stale legacy config files can interfere even when openclaw.json exists (#11602). Clean up old config files in ~/.openclaw/ if you see unexpected behavior after upgrading.

Docker CLI Cannot Reach Gateway

Docker manual setup frequently fails because containers cannot resolve the gateway's network address (#5559). Use docker compose instead of standalone docker run commands.

Reasoning Content Leaking to Channels

Extended thinking content from some models appears in Discord and other channels as raw text (#6470). Toggle /verbose off or check your model's streaming configuration.

400 Error: "Only one of reasoning and reasoning_effort"

Appears in version 2026.2.22+ when both parameters are set (#24213). Update to the latest version or remove conflicting thinking configuration.

Troubleshooting

"command not found: openclaw"

Close and reopen your terminal, or:

source ~/.zshrc   # macOS/Linux

On Windows, open a new PowerShell window.

Gateway Won't Start

Check if the port is already in use:

lsof -i :18789          # macOS/Linux
netstat -ano | findstr 18789   # Windows

Kill the conflicting process or use a different port:

openclaw gateway --port 18790

"unauthorized" or "disconnected (1008)" in Control UI

Fetch a fresh dashboard link and approve your device:

openclaw dashboard --no-open
openclaw devices list
openclaw devices approve <device-id>

WhatsApp QR Code Not Scanning

Make sure your phone and computer are on the same network. If the QR expires, run openclaw channels login again.

Model Not Responding

Verify your API key is set:

echo $OPENAI_API_KEY        # macOS/Linux
echo $env:OPENAI_API_KEY    # Windows PowerShell

If empty, set it and restart the gateway.

Web UI Shows "Unsupported schema node"

Known bug in the Nodes/Accounts section of the web UI (#1749). Does not affect functionality.

Nuclear Reset

# Remove everything
rm -rf ~/.openclaw
npm uninstall -g openclaw

# Reinstall
curl -fsSL https://openclaw.ai/install.sh | bash
openclaw onboard --install-daemon

Uninstalling OpenClaw

npm Installation

npm uninstall -g openclaw

curl Installation

rm -f ~/.local/bin/openclaw

Remove All Data

rm -rf ~/.openclaw

This deletes config, workspace, credentials, agent state, and logs.

What You Can Do With OpenClaw

Once running, here is what people are actually using it for:

• Personal AI on WhatsApp that knows your schedule, answers questions, and manages tasks without switching apps
• Team Slack bot that answers engineering questions, searches internal docs, and summarizes threads
• Discord server assistant with custom personality and knowledge
• Fully private AI running Ollama locally with zero data leaving your machine
• Multi-channel inbox where the same AI responds from WhatsApp, Telegram, Discord, and web simultaneously
• Automated daily briefings via cron -- morning summary of emails, calendar, and Slack delivered to Telegram
• Browser automation -- have your AI navigate websites, fill forms, and take screenshots
• Cross-device assistant with companion apps on macOS, iOS, and Android using camera, voice, and screen recording

The power is in combining channels + skills + automation + your choice of model. You own the entire stack.

Wrapping Up

OpenClaw is the most capable self-hosted AI assistant in the open-source space. Over 224,000 developers on GitHub agree. The channel integrations are seamless, the automation features (cron, webhooks, cross-session communication) go far beyond a simple chatbot, and the fact that you own the entire stack changes how you think about AI tools.

The key things most people miss:

1. Run openclaw doctor after setup -- it catches problems early
2. Use chat commands -- /think high for hard problems, /compact when context fills up
3. Customize AGENTS.md and SOUL.md -- they dramatically improve response quality
4. Enable sandboxing for group chats -- the default gives full host access
5. Use Tailscale, not port forwarding -- for remote access
6. Version control your workspace -- ~/.openclaw/workspace as a git repo
7. WSL on Windows -- native Windows has too many open bugs

OpenClaw GitHub | Official Docs | ClawHub Skills

If you found this guide useful, share it with your team. For more AI and DevOps deep dives, check out my guide on setting up Claude Code or my 71 free browser-based AI and DevOps tools.