> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wednesdayai.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Onboarding Wizard (CLI)

# Onboarding Wizard (CLI)

The onboarding wizard is the **recommended** way to set up WednesdayAI on macOS,
Linux, or Windows (via WSL2; strongly recommended).
It configures a local Gateway or a remote Gateway connection, plus channels, skills,
and workspace defaults in one guided flow.

```bash theme={"dark"}
wednesdayai onboard
```

> [!NOTE]
>
> Fastest first chat: no channel setup needed. Run `wednesdayai dashboard` to open Control UI v2, the
> operator console at the gateway root, and
> turn on the [web client](https://docs.wednesdayai.dev/next/admin/web/user-client.md) (`gateway.webClient.enabled: true`) to chat in the
> browser. Docs: [Dashboard](https://docs.wednesdayai.dev/next/admin/web/dashboard.md) and [Control UI v2](https://docs.wednesdayai.dev/next/admin/web/control-ui-v2.md).

To reconfigure later:

```bash theme={"dark"}
wednesdayai configure
wednesdayai agents add <name>
```

> [!NOTE]
>
> `--json` does not imply non-interactive mode. For scripts, use `--non-interactive`.

> [!TIP]
>
> Recommended: set up a Brave Search API key so the agent can use `web_search`
> (`web_fetch` works without a key). Easiest path: `wednesdayai configure --section web`
> which stores `tools.web.search.apiKey`. Docs: [Web tools](https://docs.wednesdayai.dev/next/users/tools/web.md).

## QuickStart vs Advanced

The wizard starts with **QuickStart** (defaults) vs **Advanced** (full control).

> [tab] QuickStart (defaults)
>
> * Local gateway (loopback)
> * Workspace default (or existing workspace)
> * Gateway port **18789**
> * Gateway auth **Token** (auto‑generated, even on loopback)
> * Tool policy default for new local setups: `tools.profile: "messaging"` (existing explicit profile is preserved). When `tools.profile` is unset, onboarding also writes `tools.alsoAllow: ["group:fs"]` and `tools.fs.workspaceOnly: true`, giving the agent workspace-contained `read`/`write`/`edit`/`delete` tools for the first-run ritual.
> * DM isolation default: local onboarding writes `session.dmScope: "per-channel-peer"` when unset. Details: [CLI Onboarding Reference](https://docs.wednesdayai.dev/next/users/start/wizard-cli-reference.md#outputs-and-internals)
> * Tailscale exposure **Off**
> * Telegram + WhatsApp DMs default to **allowlist** (you'll be prompted for your phone number)

> [tab] Advanced (full control)
>
> * Exposes every step (mode, workspace, gateway, channels, daemon, skills).

## What the wizard configures

**Local mode (default)** walks you through these steps:

1. **Model/Auth** — choose any supported provider/auth flow (API key, OAuth, or setup-token), including Custom Provider
   (OpenAI-compatible, Anthropic-compatible, or Unknown auto-detect). Pick a default model.
   Security note: if this agent will run tools or process webhook/hooks content, prefer the strongest latest-generation model available and keep tool policy strict. Weaker/older tiers are easier to prompt-inject.
   For non-interactive runs, `--secret-input-mode ref` stores env-backed refs in auth profiles instead of plaintext API key values.
   In non-interactive `ref` mode, the provider env var must be set; passing inline key flags without that env var fails fast.
   In interactive runs, choosing secret reference mode lets you point at either an environment variable or a configured provider ref (`file` or `exec`), with a fast preflight validation before saving.
2. **Workspace** — Location for agent files (default `~/.openclaw/workspace`). Seeds bootstrap files.
3. **Gateway** — Port, bind address, auth mode, Tailscale exposure.
4. **Channels** — WhatsApp, Telegram, Discord, Google Chat, Mattermost, Signal, BlueBubbles, or iMessage.
5. **Daemon** — Installs a LaunchAgent (macOS) or systemd user unit (Linux/WSL2).
6. **Health check** — Starts the Gateway and verifies it's running.
7. **Skills** — Installs recommended skills and optional dependencies.

> [!NOTE]
>
> Re-running the wizard does **not** wipe anything unless you explicitly choose **Reset** (or pass `--reset`).
> CLI `--reset` defaults to config, credentials, and sessions; use `--reset-scope full` to include workspace.
> If the config is invalid or contains legacy keys, the wizard asks you to run `wednesdayai doctor` first.

**Remote mode** only configures the local client to connect to a Gateway elsewhere.
It does **not** install or change anything on the remote host.

## Add another agent

Use `wednesdayai agents add <name>` to create a separate agent with its own workspace,
sessions, and auth profiles. Running without `--workspace` launches the wizard.

What it sets:

* `agents.list[].name`
* `agents.list[].workspace`
* `agents.list[].agentDir`

Notes:

* Default workspaces follow `~/.openclaw/workspace-<agentId>`.
* Add `bindings` to route inbound messages (the wizard can do this).
* Non-interactive flags: `--model`, `--agent-dir`, `--bind`, `--non-interactive`.

## Full reference

For detailed step-by-step breakdowns, non-interactive scripting, Signal setup,
RPC API, and a full list of config fields the wizard writes, see the
[Wizard Reference](https://docs.wednesdayai.dev/next/developers/reference/wizard.md).

## Related docs

* CLI command reference: [`wednesdayai onboard`](https://docs.wednesdayai.dev/next/users/cli/onboard)
* Onboarding overview: [Onboarding Overview](https://docs.wednesdayai.dev/next/users/start/onboarding-overview.md)
* macOS app onboarding: [Onboarding](https://docs.wednesdayai.dev/next/users/start/onboarding.md)
* Agent first-run ritual: [Agent Bootstrapping](https://docs.wednesdayai.dev/next/users/start/bootstrapping.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.