The Onboarding Wizard

+15 Mana ✨
OpenClaw Onboarding Guide(DOCUMENTATION)OpenClaw Environment Configuration(DOCUMENTATION)

Introduction

Once OpenClaw is installed, the onboarding wizard is your next stop. It automates the tedious setup tasks like authentication, gateway configuration, and channel registration so you can start chatting with AI models in minutes. This lesson walks through every step of the wizard and explains what happens behind the scenes.

Key Concepts

  • Onboard command (openclaw onboard --install-daemon) is the single entry point for post-installation setup
  • Daemon is a background process that manages connections between your client and AI model gateways
  • Gateway is the routing layer that directs your prompts to the correct AI provider
  • Channels are named configurations that pair a gateway with specific model parameters
  • Authentication links your local installation to your OpenClaw account for billing and access control

Real World Context

Imagine joining a new company where IT has pre-configured your laptop with all the tools you need. The onboarding wizard plays a similar role for OpenClaw: it handles the plumbing so you can focus on actually using AI models. Without it, you would need to manually edit configuration files, generate API tokens, start background services, and register channels one by one.

Deep Dive

The onboarding wizard is invoked with a single command:

bash
openclaw onboard --install-daemon

The --install-daemon flag tells the wizard to also install and start the background daemon process. Without this flag, only configuration is performed and you would need to start the daemon manually later.

Step-by-Step Walkthrough

Step 1: Authentication

The wizard opens a browser window for you to log in to your OpenClaw account. Once authenticated, it stores a refresh token locally so subsequent commands do not require re-authentication.

bash
# The wizard outputs something like:
# Opening browser for authentication...
# Authenticated as user@example.com

This browser-based flow uses OAuth under the hood, ensuring your credentials are never stored in plain text on disk.

Step 2: Gateway Configuration

Next, the wizard detects available gateways and configures routing rules. Gateways determine which AI provider handles your requests.

bash
# Example output:
# Detecting gateways...
# Configured gateway: default (OpenAI GPT-4)
# Configured gateway: anthropic (Claude)

The wizard writes this configuration to a file at the path specified by the OPENCLAW_CONFIG_PATH environment variable, or the default location under OPENCLAW_HOME.

Step 3: Channel Registration

Channels are created to give you named endpoints for different use cases. The wizard sets up a default channel automatically.

bash
# Example output:
# Registering channels...
# Channel 'general' created (gateway: default)

You can create additional channels later for specialized tasks like code review, documentation, or debugging.

Step 4: Daemon Installation and Startup

Finally, the wizard installs the daemon as a system service and starts it:

bash
# Example output:
# Installing daemon...
# Daemon started (PID: 42351)
# OpenClaw is ready!

The daemon runs in the background, managing WebSocket connections and keeping your session alive. You can check its status anytime with openclaw gateway status.

Environment Variables

Three environment variables control where OpenClaw stores its data:

bash
export OPENCLAW_HOME=~/.openclaw           # Base directory for all OpenClaw files
export OPENCLAW_STATE_DIR=~/.openclaw        # Runtime state and daemon PID files
export OPENCLAW_CONFIG_PATH=~/.openclaw/openclaw.json  # Main configuration file

These lines show the default values. You only need to set them explicitly if you want to customize the locations, for example when running multiple OpenClaw instances.

Common Pitfalls

  • Running openclaw onboard without --install-daemon: This skips daemon installation, meaning you must manually start it later with a separate command. Always include the flag for a complete setup.
  • Firewall blocking the OAuth callback: The authentication step requires your browser to redirect back to a local port. Corporate firewalls or VPNs may block this, causing authentication to hang indefinitely.

Best Practices

  • Run openclaw doctor immediately after onboarding to verify everything was configured correctly.
  • Set environment variables in your shell profile (.bashrc, .zshrc) so they persist across terminal sessions.
  • Re-run openclaw onboard --install-daemon after major version upgrades to pick up new configuration options.

Summary

  • The openclaw onboard --install-daemon command automates authentication, gateway config, channels, and daemon setup
  • Authentication uses a browser-based OAuth flow that stores tokens locally
  • Gateways route prompts to AI providers; channels are named configurations for different use cases
  • The daemon runs as a background service managing persistent connections
  • Environment variables OPENCLAW_HOME, OPENCLAW_STATE_DIR, and OPENCLAW_CONFIG_PATH control storage locations (defaults: ~/.openclaw, ~/.openclaw, and ~/.openclaw/openclaw.json)
✓ Completed