OpenClaw Wizard

Quick Installation and Configuration

10-15 min

Beginner

openclaw onboard

Overview

The onboarding wizard is the recommended way to set up OpenClaw on macOS, Linux, or Windows (via WSL2; strongly recommended). It configures a local Gateway or a remote Gateway connection, plus channels, skills, and workspace defaults in one guided flow.

Primary entrypoint:

openclaw onboard

💡 Fastest first chat: open the Control UI (no channel setup needed). Run openclaw dashboard and chat in the browser.

QuickStart vs Advanced

QuickStart

Uses defaults, suitable for most users

Local gateway (loopback)
Workspace default
Gateway port 18789
Auto-generated auth token
Tailscale exposure off

Advanced

Full control over every option

Mode selection (local/remote)
Custom workspace path
Advanced gateway settings
Manual channel configuration
Daemon and skills control

Flow Details (Local Mode)

1. Existing Config Detection

If ~/.openclaw/openclaw.json exists, choose Keep / Modify / Reset. Re-running the wizard does not wipe anything unless you explicitly choose Reset (or pass --reset).

2. Model/Auth

Anthropic API Key (recommended): uses ANTHROPIC_API_KEY if present or prompts for a key

Anthropic OAuth (Claude Code CLI): on macOS the wizard checks Keychain item "Claude Code-credentials"; on Linux/Windows it reuses ~/.claude/.credentials.json if present

Anthropic Token (paste setup-token): run claude setup-token on any machine, then paste the token

OpenAI API Key: uses OPENAI_API_KEY if present or prompts for a key

MiniMax / Moonshot / Kimi / Synthetic / Vercel AI Gateway / OpenCode Zen: config is auto-written or prompts for API key

3. Workspace

Default ~/.openclaw/workspace (configurable). Seeds the workspace files needed for the agent bootstrap ritual.

4. Gateway

Port, bind, auth mode, tailscale exposure. Recommendation: keep Token even for loopback so local WS clients must authenticate.

5. Channels

WhatsApp: Optional QR login

Telegram: bot token

Discord: bot token

Google Chat: service account JSON + webhook audience

Signal: Optional signal-cli install

iMessage: Local imsg CLI path + DB access

DM Security: Default is pairing. First DM sends a code; approve via openclaw pairing approve <channel> <code> or use allowlists.

6. Daemon Install

macOS: LaunchAgent (requires a logged-in user session; for headless, use a custom LaunchDaemon)

Linux (and Windows via WSL2): systemd user unit

Wizard attempts to enable lingering via loginctl enable-linger <user> so the Gateway stays up after logout.

Runtime selection: Node (recommended; required for WhatsApp/Telegram). Bun is not recommended.

7. Health Check

Starts the Gateway (if needed) and runs openclaw health. Tip: openclaw status --deep adds gateway health probes to status output (requires a reachable gateway).

8. Skills (Recommended)

Reads the available skills and checks requirements. Lets you choose a node manager: npm / pnpm (bun not recommended). Installs optional dependencies (some use Homebrew on macOS).

Follow-up Reconfiguration

openclaw configure

Recommended: set up a Brave Search API key so the agent can use web_search (web_fetch works without a key). Easiest path: openclaw configure --section web which stores tools.web.search.apiKey.

Non-interactive Mode

Use --non-interactive to automate or script onboarding:

openclaw onboard --non-interactive \
  --mode local \
  --auth-choice apiKey \
  --anthropic-api-key "$ANTHROPIC_API_KEY" \
  --gateway-port 18789 \
  --gateway-bind loopback \
  --install-daemon \
  --daemon-runtime node \
  --skip-skills

Add --json for a machine-readable summary.

More examples:

# Gemini

openclaw onboard --non-interactive \
  --auth-choice gemini-api-key \
  --gemini-api-key "$GEMINI_API_KEY"

# Vercel AI Gateway

openclaw onboard --non-interactive \
  --auth-choice ai-gateway-api-key \
  --ai-gateway-api-key "$AI_GATEWAY_API_KEY"

# Moonshot

openclaw onboard --non-interactive \
  --auth-choice moonshot-api-key \
  --moonshot-api-key "$MOONSHOT_API_KEY"

Add Another Agent

Use openclaw agents add <name> to create a separate agent with its own workspace, sessions, and auth profiles. Running without --workspace launches the wizard.

openclaw agents add work \
  --workspace ~/.openclaw/workspace-work \
  --model openai/gpt-5.2 \
  --bind whatsapp:biz \
  --non-interactive \
  --json

What the Wizard Writes

~/.openclaw/openclaw.json

• agents.defaults.workspace
• agents.defaults.model / models.providers
• gateway.* (mode, bind, auth, tailscale)
• channels.telegram.botToken, channels.discord.token
• skills.install.nodeManager
• wizard.lastRunAt, wizard.lastRunVersion, etc.