# Getting Started

## Goal
Go from **zero** → **first working chat** (with sane defaults) as quickly as possible.

**Fastest chat:** Open the Control UI. Run `openclaw dashboard` and chat in the browser, or open `http://127.0.0.1:18789/` on the gateway host.

**Recommended path:** Use the CLI onboarding wizard (`openclaw onboard`). It sets up:
* model/auth (OAuth recommended)
* gateway settings
* channels (WhatsApp/Telegram/Discord/Mattermost)
* pairing defaults (secure DMs)
* workspace bootstrap + skills
* optional background service

## Sandboxing Configuration
Non-main sandbox mode uses `session.mainKey` (default `"main"`), so group/channel sessions are sandboxed. For main agent to always run on host:

```json
{
  "routing": {
    "agents": {
      "main": {
        "workspace": "~/.openclaw/workspace",
        "sandbox": { "mode": "off" }
      }
    }
  }
}
```

## 0) Prerequisites
* Node `>=22`
* `pnpm` (optional; recommended for source builds)
* **Recommended:** Brave Search API key for web search

**macOS:** Install Xcode/CLT if building apps. Node sufficient for CLI + gateway.
**Windows:** Use **WSL2** (Ubuntu recommended).

## 1) Install the CLI

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

**Windows (PowerShell):**
```powershell
iwr -useb https://openclaw.ai/install.ps1 | iex
```

**Alternative (global install):**
```bash
npm install -g openclaw@latest
```

## 2) Run the Onboarding Wizard

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

**Configuration choices:**
* Local vs Remote gateway
* Auth: OpenAI Code subscription (OAuth) or API keys
* Providers: WhatsApp QR login, Telegram/Discord bot tokens, etc.
* Daemon: background install (launchd/systemd; WSL2 uses systemd)
* Gateway token: auto-generated

### Auth Storage
* **Anthropic (recommended):** API key or `claude setup-token`
* OAuth credentials: `~/.openclaw/credentials/oauth.json`
* Auth profiles: `~/.openclaw/agents/<agentId>/agent/auth-profiles.json`

## 3) Start the Gateway

```bash
openclaw gateway status
```

**Manual run:**
```bash
openclaw gateway --port 18789 --verbose
```

Dashboard: `http://127.0.0.1:18789/`

⚠️ **Bun warning:** Known issues with WhatsApp + Telegram. Use **Node** for the Gateway.

## 3.5) Quick Verification

```bash
openclaw status
openclaw health
openclaw security audit --deep
```

## 4) Pair + Connect Chat Surface

### WhatsApp (QR login)
```bash
openclaw channels login
```
Scan via WhatsApp → Settings → Linked Devices.

### Telegram / Discord / Others
```bash
openclaw channels login
```

## 5) DM Safety (Pairing Approvals)

Default behavior: unknown DMs receive a short code. Messages aren't processed until approved.

```bash
openclaw pairing list whatsapp
openclaw pairing approve whatsapp <code>
```

## From Source (Development)

```bash
git clone https://github.com/openclaw/openclaw.git
cd openclaw
pnpm install
pnpm ui:build
pnpm build
openclaw onboard --install-daemon
```

**Gateway from repo:**
```bash
node openclaw.mjs gateway --port 18789 --verbose
```

## 7) Verify End-to-End

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

## Next Steps (Optional)
* macOS menu bar app + voice wake
* iOS/Android nodes (Canvas/camera/voice)
* Remote access (SSH tunnel / Tailscale Serve)
* Always-on / VPN setups