OpenClaw Setup Wizard: Complete Walkthrough for First-Time Users

When Does the Setup Wizard Appear?

The setup wizard appears automatically the first time you access OpenClaw's web UI when no prior configuration exists. Specifically, it triggers when:

• No config.json or config.yaml file is found in the data directory
• No API keys are set via environment variables
• The SETUP_COMPLETE flag is not set to true

After starting OpenClaw for the first time, navigate to http://your-server:18789 (or whatever your gateway bind address is). Instead of the normal dashboard, you will see the setup wizard — a clean, step-by-step interface that walks you through the essential configuration.

If you have already configured everything via environment variables in your .env file or docker-compose.yml, the wizard detects this and skips itself. This is useful for automated deployments where you want to pre-configure everything without manual interaction.

You can also force the wizard to appear by setting SETUP_COMPLETE=false in your environment, which is useful if you want to reconfigure from scratch.

What Does the Gateway Mode Step Ask?

The first step asks you to choose a gateway mode. This determines how OpenClaw's HTTP server operates:

Standard (recommended): The gateway runs on the configured bind address and handles all traffic — web UI, API, and webhook callbacks. This is the right choice for 95% of deployments.

API Only: The gateway serves only the REST API and webhook endpoints. The web UI is disabled. Choose this if you manage OpenClaw entirely through the API or messaging platforms and do not need a web dashboard.

Reverse Proxy: Similar to Standard, but the gateway trusts proxy headers (X-Forwarded-For, X-Forwarded-Proto) for correct client IP detection and HTTPS handling. Choose this if OpenClaw sits behind Nginx, Caddy, Traefik, or a similar reverse proxy.

For most first-time users, Standard is the correct choice. You can change this later by modifying the GATEWAY_MODE environment variable.

The wizard also shows your current gateway bind address and lets you change it. The default 0.0.0.0:18789 is correct for Docker deployments. Only change it if you have a specific reason to use a different port or interface.

How Do You Choose an API Provider?

The second step asks you to select an AI model provider and enter your API key. This is the most important step — without a model provider, OpenClaw cannot function.

The wizard presents these options:

Anthropic (Claude): The recommended choice for most operators. Claude models excel at agent tasks — following complex instructions, maintaining context, and producing reliable structured output. You need an Anthropic API key from console.anthropic.com.

OpenAI (GPT): A solid alternative with broad model availability. Works well for general-purpose agent tasks. API key from platform.openai.com.

Google (Gemini): Good for operators already in the Google ecosystem. API key from Google AI Studio.

Ollama (Local): For operators who want to run models locally without external API calls. Requires Ollama installed and running on the same machine or network. No API key needed, but you need to specify the model name.

Custom/OpenAI-Compatible: For any provider that offers an OpenAI-compatible API endpoint (Together, Groq, Fireworks, etc.). Requires a base URL and API key.

After selecting a provider, the wizard asks for your API key. It validates the key by making a small test request. If validation fails, it shows the error and lets you try again.

You can add multiple providers later from the web UI or .env file. The wizard only requires one to get started.

How Do You Connect a Messaging Platform?

The third step lets you connect a messaging platform. This is optional — you can use OpenClaw through the web UI alone — but most operators want at least one messaging integration.

The wizard supports:

Telegram: The most popular choice. Enter your bot token from BotFather. The wizard tests the connection by calling the Telegram API's getMe endpoint to verify the token is valid.

Discord: Enter your bot token from the Discord Developer Portal. The wizard verifies the token and shows the bot's username for confirmation.

WhatsApp: Requires a WhatsApp Business API setup. The wizard walks you through connecting to the Meta Business API or a third-party provider like Twilio.

Slack: Enter a Slack Bot Token (starts with xoxb-). The wizard verifies permissions and shows which workspace the bot will connect to.

Skip for now: You can skip this step entirely and add messaging platforms later. Some operators prefer to verify the agent is working correctly via the web UI before exposing it to a messaging platform.

Each platform has a "Test Connection" button that verifies your credentials before proceeding. If the test fails, the wizard shows the specific error and suggests fixes.

What Is the Persona Configuration Step?

The fourth step lets you configure the agent's persona — its name, system prompt, and behavioral guidelines. This determines how the agent introduces itself, what tone it uses, and what boundaries it respects.

The wizard provides three options:

Default persona: A general-purpose assistant with a professional tone. Good for getting started, but generic.

Atlas persona: A pre-built AI Chief of Staff persona designed for executive productivity — outreach, lead management, content creation, and inbox management. This is the persona included with the Atlas product.

Custom persona: Write your own system prompt. The wizard provides a text editor and guidelines for writing effective persona prompts (length, structure, do/don't lists).

The persona is stored as a SKILL.md file in the data directory. You can modify it at any time by editing the file or through the web UI's persona editor. The wizard's persona step is just a starting point.

For first-time users, the default persona is fine. You can always customize it later once you understand how the agent responds and what behaviors you want to change.

What Does the Security Step Cover?

The fifth and final step covers basic security configuration:

Gateway token: A secret token used to authenticate API requests. The wizard generates a random token and shows it to you. Save it somewhere secure — you will need it for any API access or integrations that connect to the gateway.

Allowed users: A list of user IDs (Telegram user IDs, Discord user IDs) that are allowed to interact with the agent. If empty, anyone who messages the bot can interact with it. The wizard recommends adding at least your own user ID.

Web UI authentication: Whether to enable login protection for the web UI. The wizard offers to set up Google or GitHub OAuth, or to disable authentication (for private networks only).

Rate limiting: Basic rate limiting to prevent abuse. The wizard sets sensible defaults (30 messages per minute per user) that you can adjust later.

Security configuration is important but often overlooked by first-time users who are eager to see the agent working. The wizard's defaults are reasonable for a private deployment, but you should tighten security before exposing the agent to the public internet.

What Happens After the Wizard Finishes?

When you click "Complete Setup" on the final step, OpenClaw:

1. Saves configuration to the config.json file in the data directory.
2. Sets SETUP_COMPLETE=true so the wizard does not appear again.
3. Restarts services to apply the new configuration.
4. Redirects you to the dashboard where you can see the agent's status, active sessions, and recent activity.

If you connected a messaging platform, the agent starts responding to messages immediately. Send a test message to your bot to verify everything is working.

The dashboard shows real-time information including active conversations, model usage, error rates, and system resource consumption. If something is wrong, the dashboard's alerts panel will highlight the issue.

From the dashboard, you can access additional settings not covered by the wizard — memory configuration, skill management, multi-model routing, webhook integrations, and more. The wizard covers the essentials; the dashboard gives you full control.

What Are the Most Common Setup Choices?

Based on the community, here is what most operators choose during setup:

This gets you a working agent in under 10 minutes. From there, the typical progression is: customize the persona, add a second messaging platform, install skills from ClawHub, configure multi-model routing for cost optimization, and tighten security before exposing to the public.

If you want to skip the wizard entirely and deploy with a pre-configured setup, check the Docker Compose guide for a complete docker-compose.yml with all configuration pre-set.