How to use the OpenClaw Onboarding Wizard

I know the feeling of staring at a blank terminal, wondering which configuration file I need to edit first. Manual setup is often the most tedious part of starting a new project. I usually look for a way to automate these steps so I can focus on the actual code.

The openclaw onboard command is designed to handle this initial setup for you. Instead of hunting through files, you can use this wizard to get your environment ready.

What You’ll Need

The OpenClaw CLI installed in your environment.

Quick Start

You can start the configuration process in about a minute. Follow these steps:

Open your terminal or command prompt.
Run the onboarding wizard command:

openclaw onboard

This command triggers the interactive wizard to guide you through the necessary setup steps.

Troubleshooting

The current reference documentation does not list specific error codes or known issues for this command. If the wizard does not behave as expected, I recommend reviewing the high-level overview linked below.

If you need immediate help with a specific error, you can ask the AI Setup Assistant.

What’s Next

We have all been there: you download a new tool, excited to get started, only to spend the next two hours fighting with hidden config files and broken environment variables. It is frustrating when a setup process feels like a black box, leaving you wondering what exactly changed on your system or why an authentication token suddenly stopped working.

I prefer a setup that is transparent and gives me control. When you run the OpenClaw wizard in local mode, it follows a specific path to get your agent running without the guesswork. Here is exactly how that flow works and how you can get your environment ready in minutes.

What You’ll Need

Before starting, make sure you have these items ready based on the providers you plan to use:

Runtime: Node.js is recommended (required for WhatsApp and Telegram).
API Keys: Anthropic, OpenAI, xAI, Moonshot, or MiniMax keys.
Package Manager: npm or pnpm (Bun is not recommended).
System Tools: Homebrew (for some macOS dependencies) or loginctl for Linux lingering.

Quick Start

The setup wizard is designed to get you from zero to a running gateway in about five minutes. Here is the path it takes.

1. Config Detection

If you have used OpenClaw before, the wizard finds ~/.openclaw/openclaw.json. You can choose to Keep, Modify, or Reset your settings.

Running the wizard again does not wipe your data unless you choose Reset.
Use openclaw --reset to clear config, credentials, and sessions.
Use openclaw --reset-scope full to also remove your workspace.
If your config is broken, run openclaw doctor to fix it.

2. Model and Auth Setup

This is where you connect your AI providers. The wizard checks for existing environment variables like ANTHROPIC_API_KEY or OPENAI_API_KEY.

Anthropic: Supports API keys, OAuth (via Keychain on macOS or ~/.claude/.credentials.json on Linux), or setup tokens from claude setup-token.
OpenAI: Supports API keys or Codex subscriptions. If the model is unset, it defaults to openai-codex/gpt-5.2.
Proxies: You can configure OpenCode Zen, Vercel AI Gateway, or Cloudflare AI Gateway.
Storage: Keys are stored in plaintext by default. Use --secret-input-mode ref to use environment-backed references instead.

3. Workspace and Gateway

The wizard sets up ~/.openclaw/workspace and configures the Gateway.

Auth: I recommend keeping Token mode active even for local use.
Tokens: You can generate a plaintext token or use --gateway-token-ref-env <ENV_VAR> for non-interactive setups.
Binds: Non-loopback binds always require authentication for security.

4. Channels and Search

You can link OpenClaw to your communication apps and search engines.

Channels: Supports WhatsApp, Telegram, Discord, Google Chat, Mattermost, Signal, BlueBubbles (for iMessage), and a legacy iMessage CLI.
Web Search: Choose from providers like Perplexity, Brave, Gemini, Grok, or Kimi. Use --skip-search if you want to handle this later.

5. Daemon Installation

To keep the agent running in the background, the wizard installs a service.

macOS: Uses a LaunchAgent (requires a logged-in session).
Linux: Uses a systemd user unit and attempts to enable lingering via loginctl.
Validation: The install will block if your gateway.auth.token SecretRef is unresolved or if your auth mode is ambiguous.

6. Health Check and Skills

Finally, the wizard runs openclaw health to ensure everything is reachable. You can then choose your node manager (npm or pnpm) to install skills and dependencies.

Troubleshooting

If you hit a snag during the process, here are the solutions provided in the source documentation:

Wizard stops with a “legacy keys” error: This means your config is invalid. Run openclaw doctor before continuing.
Daemon install is blocked: Check if your gateway.auth.token SecretRef is correctly configured in your environment. If you have both a token and password set but no mode defined, you must set the mode explicitly.
No GUI detected: If you are on a remote server, the wizard will print SSH port-forward instructions for the Control UI.
Missing Control UI assets: The wizard will try to build them automatically. If that fails, run pnpm ui:build.
Gateway health issues: Use openclaw status --deep to see detailed health probes.

For more interactive help, you can use the AI Setup Assistant.

What’s Next

I hate doing the same manual setup over and over. If I am building a script or setting up a new environment, I don’t want to sit there answering prompts or clicking through menus. I want a command I can run once that handles everything.

That is where non-interactive mode comes in. It lets you automate the entire onboarding process, which is perfect for CI/CD or just making your own life easier when you need to spin up a new instance quickly.

What You’ll Need

The openclaw CLI installed on your machine.
Your API keys (like Anthropic, Gemini, or Moonshot) saved as environment variables.
A terminal or script environment ready for execution.

Quick Start

To skip the manual questions, use the --non-interactive flag. This tells the CLI to look for arguments instead of asking you for them. Here is a basic example using Anthropic:

openclaw onboard --non-interactive \
  --mode local \
  --auth-choice apiKey \
  --anthropic-api-key "$ANTHROPIC_API_KEY" \
  --gateway-port 18789 \
  --gateway-bind loopback \
  --install-daemon \
  --daemon-runtime node \
  --skip-skills

If you need a machine-readable summary after the command finishes, you can add the --json flag to the end.

Using Different Providers

I often switch between different LLM providers depending on the task. Here is how you handle other auth choices in non-interactive mode:

Gemini example

openclaw onboard --non-interactive \
  --mode local \
  --auth-choice gemini-api-key \
  --gemini-api-key "$GEMINI_API_KEY" \
  --gateway-port 18789 \
  --gateway-bind loopback

Z.AI example

openclaw onboard --non-interactive \
  --mode local \
  --auth-choice zai-api-key \
  --zai-api-key "$ZAI_API_KEY" \
  --gateway-port 18789 \
  --gateway-bind loopback

Vercel AI Gateway example

openclaw onboard --non-interactive \
  --mode local \
  --auth-choice ai-gateway-api-key \
  --ai-gateway-api-key "$AI_GATEWAY_API_KEY" \
  --gateway-port 18789 \
  --gateway-bind loopback

Cloudflare AI Gateway example

openclaw onboard --non-interactive \
  --mode local \
  --auth-choice cloudflare-ai-gateway-api-key \
  --cloudflare-ai-gateway-account-id "your-account-id" \
  --cloudflare-ai-gateway-gateway-id "your-gateway-id" \
  --cloudflare-ai-gateway-api-key "$CLOUDFLARE_AI_GATEWAY_API_KEY" \
  --gateway-port 18789 \
  --gateway-bind loopback

Moonshot example

openclaw onboard --non-interactive \
  --mode local \
  --auth-choice moonshot-api-key \
  --moonshot-api-key "$MOONSHOT_API_KEY" \
  --gateway-port 18789 \
  --gateway-bind loopback

Synthetic example

openclaw onboard --non-interactive \
  --mode local \
  --auth-choice synthetic-api-key \
  --synthetic-api-key "$SYNTHETIC_API_KEY" \
  --gateway-port 18789 \
  --gateway-bind loopback

OpenCode Zen example

openclaw onboard --non-interactive \
  --mode local \
  --auth-choice opencode-zen \
  --opencode-zen-api-key "$OPENCODE_API_KEY" \
  --gateway-port 18789 \
  --gateway-bind loopback

Handling Gateway Tokens

If you are using a token for gateway authentication, I recommend using a SecretRef to keep things secure. You can export your token to an environment variable and then reference that variable name in the command:

export OPENCLAW_GATEWAY_TOKEN="your-token"
openclaw onboard --non-interactive \
  --mode local \
  --auth-choice skip \
  --gateway-auth token \
  --gateway-token-ref-env OPENCLAW_GATEWAY_TOKEN

Adding Agents via Script

You aren’t limited to just onboarding. I use the non-interactive flag to add agents to specific workspaces without any manual input:

openclaw agents add work \
  --workspace ~/.openclaw/workspace-work \
  --model openai/gpt-5.2 \
  --bind whatsapp:biz \
  --non-interactive \
  --json

Troubleshooting

If things aren’t working as expected, check these two common issues:

JSON isn’t enough: Just adding --json does not mean the command is non-interactive. You must explicitly include the --non-interactive flag (and usually --workspace) for scripts to run without hanging.
Token conflicts: You cannot use --gateway-token and --gateway-token-ref-env at the same time. These two flags are mutually exclusive, so pick one.

If you run into other issues, you can always check with the AI Setup Assistant.

What’s Next

I have spent too much time in the past rebuilding the same onboarding logic for different platforms. It is frustrating when you have to write the same validation and step-sequencing code for a desktop app and a web dashboard. You usually end up with inconsistent behavior or bugs that only exist on one client.

The Gateway solves this by exposing the onboarding flow directly over RPC. This keeps the logic in one place while your clients just handle the rendering.

What You’ll Need

Java 21: This is required for JVM builds of the tools.
WSL2: If you are running on Windows, the setup follows the Linux flow inside a WSL2 environment.

Quick Start

The Gateway exposes the wizard flow through four specific RPC methods. You can call these from your macOS app or Control UI to guide users through the setup process.

wizard.start: Begins the onboarding sequence.
wizard.next: Moves the user to the following step.
wizard.cancel: Aborts the current wizard process.
wizard.status: Checks the current state of the setup.

One of the main tasks this wizard handles is the signal-cli setup. I find this helpful because it automates the manual work:

It downloads the correct release asset directly from GitHub.
It stores the files in ~/.openclaw/tools/signal-cli/<version>/.
It automatically updates your configuration by writing to channels.signal.cliPath.
It selects native builds whenever they are available for your system.

Troubleshooting

If you run into issues during the automated setup, check these common points from the documentation:

JVM Build Failures: Ensure your environment is using Java 21. Older versions will not work with the JVM builds.
Windows Installation: If you are on Windows, the signal-cli installation will fail outside of WSL2. Make sure your environment is correctly configured to follow the Linux flow inside WSL.

If you have questions about specific RPC parameters or need help with a custom implementation, talk to the AI Setup Assistant.

What’s Next

I often find it frustrating when a CLI tool sets things up behind the scenes without explaining where the data goes. It makes me feel like I am losing control of my own environment. I want to know exactly which files are being modified so I can fix things if they break or just understand how the system works.

When you run the OpenClaw onboarding wizard, it handles the heavy lifting of configuration for you. I will show you exactly what it writes to your disk and where those settings live.

What You’ll Need

Quick Start

The wizard primarily interacts with your home directory, specifically inside ~/.openclaw/openclaw.json. This file acts as the central hub for your setup.

Here are the typical fields you will find in ~/.openclaw/openclaw.json:

agents.defaults.workspace
agents.defaults.model
models.providers (this appears if you choose Minimax)
tools.profile (this defaults to "coding" for local onboarding when unset, but the wizard preserves any existing explicit values)

It also configures how the system communicates through the gateway:

gateway.mode
gateway.bind
gateway.auth
gateway.tailscale

If you set up communication channels, the wizard stores tokens and behavior settings:

session.dmScope (you can find more details in the CLI Onboarding Reference)
channels.telegram.botToken
channels.discord.token
channels.signal.*
channels.imessage.*

When you opt into specific channels like Slack, Discord, Matrix, or Microsoft Teams, the wizard writes to the channel allowlists. It tries to resolve names to IDs whenever possible.

The wizard also tracks its own state with these metadata fields:

wizard.lastRunAt
wizard.lastRunVersion
wizard.lastRunCommit
wizard.lastRunCommand
wizard.lastRunMode
skills.install.nodeManager

Beyond the main JSON file, other commands and services use specific paths. When you run openclaw agents add, the tool writes to agents.list[] and sets up optional bindings.

Credentials and session data are stored in these directories:

WhatsApp credentials: ~/.openclaw/credentials/whatsapp/<accountId>/
Agent sessions: ~/.openclaw/agents/<agentId>/sessions/

Troubleshooting

If you are trying to configure a specific channel and it seems to be missing, remember that some channels are delivered as plugins.

Plugin Requirement: When you pick a plugin-based channel during onboarding, the wizard will prompt you to install it via npm or a local path. You must complete this installation before the wizard can finish the configuration.

Need more help with your specific setup? Reach out to the AI Setup Assistant.

What’s Next

OpenClaw Expert

Still stuck?

If this page didn't answer your case, ask OpenClaw Expert for step-by-step guidance.