Skip to content
BrainRoad BrainRoad
Documentation Menu

Setup Wizard

Walk through the setup wizard step by step to configure your OpenClaw agent.

On this page

Guided Agent Configuration

The setup wizard walks you through configuring your agent in a step-by-step flow. It runs openclaw onboard inside your agent’s container and handles everything from naming your agent to connecting messaging channels.

How to Launch

From your agent’s detail page, click Run Setup Wizard. Two things must be true before the wizard can start:

  1. Your agent must be running (not stopped). If it is stopped, start it first.
  2. You must have at least one API key added. The wizard needs access to an AI model to function. See Adding API Keys.

The wizard opens in a full-screen view separate from the normal dashboard layout.

Step by Step

1. Agent Name and Personality

Give your agent a name and define how it communicates. This sets the system instructions that shape your agent’s tone, behavior, and areas of focus. You can be as brief or detailed as you like — the agent will follow whatever guidance you provide.

2. Model Selection

Choose the default AI model your agent will use. The wizard lists all models available through your configured API keys.

Claude by Anthropic is recommended for the best balance of capability and reliability. OpenAI GPT and Google Gemini are also fully supported. You can always switch models later with the /model command.

3. Channel Connections

This step is optional. You can skip it entirely and connect channels later, or set up one or more of the following:

  • WhatsApp — a QR code appears in the terminal panel. Open WhatsApp on your phone, go to Settings > Linked Devices > Link a Device, and scan the code.
  • Signal — similar to WhatsApp. A QR code appears for you to scan with the Signal app on your phone.
  • iMessage — enter your Apple ID credentials and complete two-factor authentication.
  • Email — enter your IMAP and SMTP server details (server address, port, username, password).

For detailed setup instructions for each channel, see the Channels section.

The Terminal Panel

The bottom of the wizard page shows a terminal panel with real-time agent output. This panel has two tabs:

  • Agent Output — a read-only stream of your agent’s logs. Shows what the gateway is doing as the wizard runs.
  • Shell — an interactive terminal connected to your agent’s container. Available if you need to run commands manually.

During channel setup steps that involve QR codes (WhatsApp and Signal), the terminal panel automatically expands to fill most of the screen. This gives the QR code enough room to render clearly as Unicode block characters. Scan it with your phone’s camera or the relevant app’s QR scanner.

When the Wizard Finishes

Once all steps are complete, your agent is fully configured and running. You will be returned to the agent detail page where all tabs become active:

  • Chat — talk to your agent directly
  • Activity — see what your agent is doing
  • Console — terminal access to the container
  • Browser — watch your agent browse the web

Re-running the Wizard

You can re-run the setup wizard at any time from the agent detail page. It does not wipe your existing configuration — it layers new settings on top of what is already there. This is useful if you want to add a new channel or change your agent’s personality.

For smaller configuration changes after initial setup, you have two alternatives:

  • openclaw configure — run this in the Console tab for an interactive config editor.
  • Edit openclaw.json directly — open the file in the Console tab for full control over every setting.

Troubleshooting

”Wizard already running” error

A previous wizard session did not properly close. This happens if you:

  • Closed the browser tab or window while the wizard was running
  • Lost internet connection during setup
  • Your browser tab crashed

How to fix: Click the Restart Agent button visible on the wizard page. This will:

  1. Stop your agent
  2. Wait for it to shut down cleanly
  3. Start it again
  4. Automatically retry the wizard from the beginning

The restart takes about 30 seconds. You do not lose any configuration you already saved — the wizard will layer new settings on top of what was there before.

Connection errors and retries

If you see a “Connection failed” error, the wizard is trying to reach your agent but cannot establish the connection. This usually happens because:

  • Your agent container is still booting (waits up to 45 seconds before showing the restart prompt)
  • Network connectivity was lost
  • Your firewall or proxy is blocking WebSocket connections to your agent

The wizard automatically retries up to 3 times with increasing wait times (15, 30, then 45 seconds). If all retries fail, click Restart Agent to begin again.

Mid-wizard restart

After some configuration steps complete, your agent may restart automatically to apply changes. This is normal. You will see a Configuration Saved message and the wizard will pick up where it left off. You can also click Return to Dashboard if you want to skip the remaining steps — all configuration you completed has already been saved.

QR code not appearing

WhatsApp and Signal QR codes appear in the terminal panel when the wizard reaches the channel connection step. If you do not see a QR code:

  1. Make sure the terminal panel at the bottom of the page is open — click the gray bar to expand it
  2. Wait 5-10 seconds for the agent to generate the code
  3. If the panel shows “Generating QR code…” text, it is working — the code will appear shortly

If the QR code never appears after 15 seconds, the agent may have stalled. Click Restart Agent and try again.

QR code looks garbled or cut off

The terminal panel needs enough vertical space to display the full QR code properly. To fix:

  1. Drag the terminal resize handle upward to give it more vertical space
  2. Make your browser window taller if you are on a small screen
  3. Maximize or fullscreen your browser window

The QR code uses block characters to render, so it needs a minimum height of about 15-20 lines to display correctly.