Getting Started

Goal: Go from Zero → First Successful Chat in record time using sensible defaults.

Fastest Way to Chat: Open the control interface (no channel setup required). Run openclaw dashboard

Then chat in your browser or open http://127.0.0.1:18789/ (on the Gateway host).

Docs: Dashboard and Control UI.

Recommended Path: Use the CLI Onboarding Wizard (openclaw onboard). It sets up:

• Models/Auth (OAuth recommended)
• Gateway Settings
• Channels (WhatsApp/Telegram/Discord/etc.)
• Pairing Defaults (Secure DMs)
• Workspace Onboarding + Skills
• Optional Background Services

If you need more detailed reference pages, jump to: Wizard, Setup, Pairing, Security.

Sandbox Notes: agents.defaults.sandbox.mode: "non-main" uses session.mainKey (default "main"), so groups/channel sessions are sandboxed. If you want the main agent to always run on host, set an explicit per-agent override:

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

• Node >=22
• pnpm (optional; recommended if building from source)
• Recommended: Brave Search API key for web search.

Simplest way: openclaw configure --section web (stores tools.web.search.apiKey).

See Web Tool.

macOS: If you plan to build the app, install Xcode / CLT. For CLI + Gateway only, Node is enough.

Windows: Use WSL2 (Ubuntu recommended). Native Windows is untested and tool compatibility is lower. See Windows (WSL2).

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

Installation options (shell flavor, non-interactive, from GitHub): Installation.

Windows (PowerShell):

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

Alternative (global install):

npm install -g openclaw@latest

pnpm add -g openclaw@latest

openclaw onboard --install-daemon

What you'll need to choose:

• Local vs Remote Gateway
• Auth: OpenAI Code (Codex) subscription (OAuth) or API Key. For Anthropic, we recommend API keys; claude setup-token is also supported.
• Providers: WhatsApp QR login, TG/Discord Bot tokens, etc.
• Daemon: Background install (launchd/systemd)
• Runtime: Node (Recommended; required for WhatsApp/TG). Bun not recommended.
• Gateway Token: The wizard generates one by default and stores it in gateway.auth.token.

Wizard Docs: Wizard

• Recommended Anthropic path: Set API key (wizard can store it for the service). claude setup-token is supported if you want to reuse Claude Code credentials.
• OAuth credentials (legacy import): ~/.openclaw/credentials/oauth.json
• Auth Profile (OAuth + API Keys): ~/.openclaw/agents/<agentId>/agent/auth-profiles.json

Headless/Server Tip: Do OAuth on a desktop machine first, then copy oauth.json to the Gateway host.

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

openclaw gateway status

Manual run (foreground):

openclaw gateway --port 18789 --verbose

Dashboard (localhost): http://127.0.0.1:18789/

If a token is configured, paste it into the Control UI settings (stored as connect.params.auth.token).

openclaw channels login

Scan via WhatsApp → Settings → Linked Devices.

WhatsApp Docs: WhatsApp

The wizard can write tokens/config for you. If you prefer manual config, start here:

• Telegram: Telegram
• Discord: Discord
• Mattermost (Plugin): Mattermost (Plugin)

TG DM Tip: Your first DM will return a pairing code. Approve it (see next step) or the bot won't reply.

Default policy: Unknown DMs get a shortcode and messages aren't processed until approved.

If your first DM gets no response, approve the pairing:

openclaw pairing list whatsapp
openclaw pairing approve whatsapp <code>

Pairing Docs: Pairing

If you're developing OpenClaw itself, run from source:

git clone https://github.com/openclaw/openclaw.git
cd openclaw
pnpm install
pnpm ui:build # auto-installs UI deps on first run
pnpm build
openclaw onboard --install-daemon

If you haven't installed globally, run onboarding step via pnpm openclaw ... (from within the repo).

pnpm build also bundles A2UI assets; use pnpm canvas:a2ui:bundle if you just need that.

Gateway (from this repo):

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

In a new terminal, send a test message:

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

If openclaw health says "Auth not configured", go back to the wizard to set up OAuth/Key auth—agents cannot reply without it.

Tip: openclaw status --all is the best pasteable read-only debug report.

Health probe: openclaw health (or openclaw status --deep) asks the running Gateway for a health snapshot.

• macOS Menu Bar App + Voice Wake: macOS Menu Bar App + Voice Wake
• iOS/Android Nodes (Canvas/Camera/Voice): iOS/Android Nodes (Canvas/Camera/Voice)
• Remote Access (SSH Tunnel / Tailscale Serve): Remote Access (SSH Tunnel / Tailscale Serve)
• Tailscale: Tailscale
• Running permanently / VPN settings: Remote Access (SSH Tunnel / Tailscale Serve), exe.dev, Hetzner