Getting Started10 min readBeginner

Getting Started with OpenClaw

Learn how to install, configure, and start using OpenClaw AI gateway. From CLI installation to your first AI conversation in minutes.

What You'll Learn

  • Install OpenClaw CLI using curl, npm, or pnpm
  • Run the onboarding wizard to configure your environment
  • Start the OpenClaw Gateway service
  • Pair and connect WhatsApp, Telegram, or other channels
  • Send your first AI message through OpenClaw

Table of Contents

0Prereqs

Before starting, make sure you have:

  • Node >=22
  • pnpm (optional; recommended if you build from source)
  • Recommended: Brave Search API key for web search. Easiest path: openclaw configure --section web (stores tools.web.search.apiKey). See Web tools.
  • macOS: if you plan to build the apps, install Xcode / CLT. For the CLI + gateway only, Node is enough.
  • Windows: use WSL2 (Ubuntu recommended). WSL2 is strongly recommended; native Windows is untested, more problematic, and has poorer tool compatibility. Install WSL2 first, then run the Linux steps inside WSL. See Windows (WSL2).

1Install the CLI (Recommended)

Choose your preferred installation method:

Using curl (Linux/macOS)

Quick one-line installation:

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

Using PowerShell (Windows)

Quick installation for Windows:

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

Using npm

Install via npm package manager:

npm install -g openclaw@latest

Using pnpm

Install via pnpm (faster alternative):

pnpm add -g openclaw@latest

2Run the Onboarding Wizard (and Install the Service)

The onboarding wizard will guide you through initial configuration and daemon installation:

openclaw onboard --install-daemon

What the wizard does:

  • 1Local vs Remote gateway
  • 2Auth: OpenAI Code (Codex) subscription (OAuth) or API keys. For Anthropic we recommend an API key; claude setup-token is also supported.
  • 3Providers: WhatsApp QR login, Telegram/Discord bot tokens, Mattermost plugin tokens, etc.
  • 4Daemon: background install (launchd/systemd; WSL2 uses systemd)
  • 5Runtime: Node (recommended; required for WhatsApp/Telegram). Bun is not recommended.
  • 6Gateway token: the wizard generates one by default (even on loopback) and stores it in gateway.auth.token.

Auth: Where It Lives (Important)

Recommended Anthropic path: set an API key (wizard can store it for service use). claude setup-token is also supported if you want to reuse Claude Code credentials. OAuth credentials (legacy import): ~/.openclaw/credentials/oauth.json. Auth profiles (OAuth + API keys): ~/.openclaw/agents/[agentId]/agent/auth-profiles.json. Headless/server tip: do OAuth on a normal machine first, then copy oauth.json to the gateway host.

3Start the Gateway

If you installed the service during onboarding, the Gateway should already be running:

Check Gateway Status

openclaw gateway status

Manual Run (Foreground)

openclaw gateway --port 18789 --verbose
Dashboard (local loopback): http://127.0.0.1:18789/ If a token is configured, paste it into the Control UI settings (stored as connect.params.auth.token). ⚠️ Bun warning (WhatsApp + Telegram): Bun has known issues with these channels. If you use WhatsApp or Telegram, run the Gateway with Node.

Quick Verify (2 min)

Verify your OpenClaw installation is working correctly:

Check Status

openclaw status

Shows overall system status and configuration

Run Health Check

openclaw health

Verifies all components are functioning

Security Audit

openclaw security audit --deep

Checks for security vulnerabilities

4Pair + Connect Your First Chat Surface

Connect your preferred messaging platform to start chatting with AI:

📱WhatsApp (QR Login)

Scan via WhatsApp → Settings → Linked Devices.

openclaw channels login

💬Telegram / Discord / Others

The wizard can write tokens/config for you. If you prefer manual config, start with: Telegram: Telegram; Discord: Discord; Mattermost (plugin): Mattermost. Telegram DM tip: your first DM returns a pairing code. Approve it (see next step) or the bot won't respond.

DM Safety (Pairing Approvals)

Default posture: unknown DMs get a short code and messages are not processed until approved. If your first DM gets no reply, approve the pairing:

List Pending Pairings

openclaw pairing list whatsapp

Approve a Pairing

openclaw pairing approve whatsapp \<code\>

From Source (Development)

If you're hacking on OpenClaw itself, run from source:

Clone Repository

git clone https://github.com/openclaw/openclaw.git cd openclaw

Install Dependencies

pnpm install

Build UI

pnpm ui:build # auto-installs UI deps on first run

Build Project

pnpm build

Run Onboarding

openclaw onboard --install-daemon

Start Gateway

node openclaw.mjs gateway --port 18789 --verbose

Verify End-to-End

In a new terminal, send a test message:

openclaw message send --target +15555550123 --message "Hello from OpenClaw"

💡 If openclaw health shows 'no auth configured', go back to the wizard and set OAuth/key auth — the agent won't be able to respond without it. Tip: openclaw status --all is the best pasteable, read-only debug report. Health probes: openclaw health (or openclaw status --deep) asks the running gateway for a health snapshot.

Next Steps (Optional, but Great)

  • macOS menu bar app + voice wake: <a href="https://docs.openclaw.ai/platforms/macos" target="_blank" rel="noopener noreferrer" class="text-primary hover:underline">macOS app</a>
  • iOS/Android nodes (Canvas/camera/voice): <a href="https://docs.openclaw.ai/nodes" target="_blank" rel="noopener noreferrer" class="text-primary hover:underline">Nodes</a>
  • Remote access (SSH tunnel / Tailscale Serve): <a href="https://docs.openclaw.ai/remote" target="_blank" rel="noopener noreferrer" class="text-primary hover:underline">Remote access and Tailscale</a>
  • Always-on / VPN setups: <a href="https://docs.openclaw.ai/remote" target="_blank" rel="noopener noreferrer" class="text-primary hover:underline">Remote access</a>, <a href="https://exe.dev" target="_blank" rel="noopener noreferrer" class="text-primary hover:underline">exe.dev</a>, <a href="https://docs.openclaw.ai/platforms/hetzner" target="_blank" rel="noopener noreferrer" class="text-primary hover:underline">Hetzner</a>, <a href="https://docs.openclaw.ai/platforms/macos-remote" target="_blank" rel="noopener noreferrer" class="text-primary hover:underline">macOS remote</a>

Troubleshooting

Installation script fails
Make sure you have Node.js 18+ installed. Try installing with npm or pnpm instead of the curl script.
Gateway won't start
Check if the port is already in use. Run 'openclaw gateway status' to see detailed error logs.
Can't connect to WhatsApp
Ensure you've completed the QR code login process. Check that the Gateway is running with 'openclaw status'.
Messages not being delivered
Verify your API keys are configured correctly. Run 'openclaw health' to check all system components.

Continue Learning

Now that OpenClaw is running, explore more features:

View All TutorialsVisit Official Docs