Workflow:Openclaw Openclaw Initial Setup And Onboarding
| Knowledge Sources | |
|---|---|
| Domains | DevOps, CLI, Gateway_Ops |
| Last Updated | 2026-02-06 12:00 GMT |
Overview
End-to-end process for installing OpenClaw, running the interactive onboarding wizard, and starting the gateway daemon to enable AI-assisted messaging across channels.
Description
This workflow covers the complete first-run experience for a new OpenClaw user. It begins with installing the CLI binary via the shell installer or npm, then walks through the interactive onboarding wizard that configures authentication providers, workspace directories, channel connections, and daemon installation. The result is a fully operational gateway running as a background service with at least one messaging channel connected.
Key outputs:
- A running OpenClaw gateway daemon (launchd on macOS, systemd on Linux)
- Configuration file at ~/.openclaw/openclaw.json
- Authenticated model provider credentials
- Optional channel connections (WhatsApp, Telegram, Discord, etc.)
Usage
Execute this workflow when setting up OpenClaw for the first time on a new machine. The user has no prior OpenClaw configuration and wants to go from zero to a working personal AI assistant reachable via messaging channels or the built-in web UI.
Execution Steps
Step 1: Install the CLI
Download and install the OpenClaw command-line binary using the platform-appropriate installer. On macOS and Linux, the shell installer fetches the latest stable release from npm and places the binary on the system PATH. On Windows, WSL2 with Ubuntu is the recommended approach.
Key considerations:
- Node.js 22+ must be available on the system
- The installer supports both npm global install and direct binary download
- macOS users can alternatively install via the OpenClaw.app which bundles the CLI
Step 2: Run the Onboarding Wizard
Launch the interactive setup wizard that walks through all required configuration. The wizard detects existing configuration and offers to keep, modify, or reset it. It covers model provider authentication, workspace initialization, gateway port and bind settings, and optional channel setup.
What happens:
- Model provider selection (Anthropic, OpenAI, Gemini, Ollama, OpenRouter, etc.)
- OAuth flow or API key entry for the selected provider
- Workspace directory creation with bootstrap files (AGENTS.md, SOUL.md, TOOLS.md, USER.md)
- Gateway configuration (port, bind mode, auth token)
Step 3: Configure Messaging Channels
Optionally connect one or more messaging platforms during the wizard or afterward via the CLI. Each channel has its own authentication flow: WhatsApp uses QR code scanning, Telegram and Discord require bot tokens, and Slack needs app and bot tokens.
Key considerations:
- WhatsApp requires QR scan via Linked Devices on a mobile phone
- Telegram requires creating a bot via @BotFather
- Discord requires creating an Application in the Developer Portal
- DM policies default to "pairing" for security (explicit owner approval)
Step 4: Install the Gateway Daemon
Register the gateway as a system service so it starts automatically on boot. On macOS this creates a launchd LaunchAgent, on Linux a systemd user service. The daemon runs on the configured port (default 18789) and binds to loopback by default.
What happens:
- Service registration with the platform init system
- Gateway process started in the background
- Lock file created to prevent duplicate instances
- Health endpoint available for monitoring
Step 5: Verify and Send First Message
Confirm the gateway is running and all configured channels are connected. Open the Control UI in a browser or send a test message via the CLI to verify end-to-end functionality.
What happens:
- Gateway health check confirms WebSocket server is listening
- Channel status probe verifies each connected platform
- First message triggers agent bootstrap (creates initial session)
- Control UI accessible at http://127.0.0.1:18789/