openclaw/docs/start/getting-started.md

summary	read_when
Beginner guide: from zero to first message (wizard, auth, channels, pairing)	First time setup from zero You want the fastest path from install → onboarding → first message

Getting Started

Goal: go from zero → first working chat (with sane defaults) as quickly as possible.

Diagram source (Mermaid)

flowchart TD
    A[Install Moltbot\nnpm install -g moltbot] --> B[Run Onboarding Wizard\nmoltbot onboard --install-daemon]
    B --> C[Model Auth\nOAuth or API Key]
    C --> D[Gateway Settings\nport, bind, token]
    D --> E[Channel Setup\nWhatsApp / Telegram / etc.]
    E --> F[Pairing Defaults\nSecure DM access]
    F --> G[Workspace Bootstrap\nAGENTS.md, SOUL.md, etc.]
    G --> H[Install Daemon\nlaunchd / systemd]
    H --> I[Gateway Running\nAlways-on service]
    I --> J[Send First Message\nmoltbot agent --message 'Hello']

Fastest chat: open the Control UI (no channel setup needed). Run moltbot dashboard and chat in the 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 (moltbot onboard). It sets up:

• model/auth (OAuth recommended)
• gateway settings
• channels (WhatsApp/Telegram/Discord/Mattermost (plugin)/...)
• pairing defaults (secure DMs)
• workspace bootstrap + skills
• optional background service

If you want the deeper reference pages, jump to: Wizard, Setup, Pairing, Security.

Sandboxing note: agents.defaults.sandbox.mode: "non-main" uses session.mainKey (default "main"), so group/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": "~/clawd",
        "sandbox": { "mode": "off" }
      }
    }
  }
}

0) Prereqs

• Node >=22
• pnpm (optional; recommended if you build from source)
• Recommended: Brave Search API key for web search. Easiest path: moltbot 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).

1) Install the CLI (recommended)

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

Installer options (install method, non-interactive, from GitHub): Install.

Windows (PowerShell):

iwr -useb https://molt.bot/install.ps1 | iex

Alternative (global install):

npm install -g moltbot@latest

pnpm add -g moltbot@latest

2) Run the onboarding wizard (and install the service)

moltbot onboard --install-daemon

What you’ll choose:

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

Wizard doc: Wizard

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): ~/.clawdbot/credentials/oauth.json

• Auth profiles (OAuth + API keys): ~/.clawdbot/agents/<agentId>/agent/auth-profiles.json

Headless/server tip: do OAuth on a normal machine first, then copy oauth.json to the gateway host.

3) Start the Gateway

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

moltbot gateway status

Manual run (foreground):

moltbot 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.

3.5) Quick verify (2 min)

moltbot status
moltbot health
moltbot security audit --deep

4) Pair + connect your first chat surface

WhatsApp (QR login)

moltbot channels login

Scan via WhatsApp → Settings → Linked Devices.

WhatsApp doc: WhatsApp

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.

5) 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:

moltbot pairing list whatsapp
moltbot pairing approve whatsapp <code>

Pairing doc: Pairing

From source (development)

If you’re hacking on Moltbot itself, run from source:

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

If you don’t have a global install yet, run the onboarding step via pnpm moltbot ... from the repo. pnpm build also bundles A2UI assets; if you need to run just that step, use pnpm canvas:a2ui:bundle.

Gateway (from this repo):

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

7) Verify end-to-end

In a new terminal, send a test message:

moltbot message send --target +15555550123 --message "Hello from Moltbot"

If moltbot 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: moltbot status --all is the best pasteable, read-only debug report. Health probes: moltbot health (or moltbot status --deep) asks the running gateway for a health snapshot.

Next steps (optional, but great)

• macOS menu bar app + voice wake: macOS app
• iOS/Android nodes (Canvas/camera/voice): Nodes
• Remote access (SSH tunnel / Tailscale Serve): Remote access and Tailscale
• Always-on / VPN setups: Remote access, exe.dev, Hetzner, macOS remote