> ## 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 Reference

# Onboarding Wizard Reference

This is the full reference for the `wednesdayai onboard` CLI wizard.
For a high-level overview, see [Onboarding Wizard](https://docs.wednesdayai.dev/next/users/start/wizard.md).

## Flow details (local mode)

**1. Existing config detection**

* If `~/.openclaw/openclaw.json` exists, choose **Keep / Modify / Reset**.
* Re-running the wizard does **not** wipe anything unless you explicitly choose **Reset**
  (or pass `--reset`).
* CLI `--reset` defaults to `config+creds+sessions`; use `--reset-scope full`
  to also remove workspace.
* If the config is invalid or contains legacy keys, the wizard stops and asks
  you to run `wednesdayai doctor` before continuing.
* Reset uses `trash` (never `rm`) and offers scopes:
  * Config only
  * Config + credentials + sessions
  * Full reset (also removes workspace)

**2. Model/Auth**

* **Anthropic API key**: uses `ANTHROPIC_API_KEY` if present or prompts for a key, then saves it for daemon use.
* **Anthropic OAuth (Claude Code CLI)**: on macOS the wizard checks Keychain item "Claude Code-credentials" (choose "Always Allow" so launchd starts don't block); on Linux/Windows it reuses `~/.claude/.credentials.json` if present.
* **Anthropic token (paste setup-token)**: run `claude setup-token` on any machine, then paste the token (you can name it; blank = default).
* **OpenAI Code (Codex) subscription (Codex CLI)**: if `~/.codex/auth.json` exists, the wizard can reuse it.
* **OpenAI Code (Codex) subscription (OAuth)**: browser flow; paste the `code#state`.
  * Sets `agents.defaults.model` to `openai-codex/gpt-5.2` when model is unset or `openai/*`.
* **OpenAI API key**: uses `OPENAI_API_KEY` if present or prompts for a key, then stores it in auth profiles.
* **xAI (Grok) API key**: prompts for `XAI_API_KEY` and configures xAI as a model provider.
* **OpenCode Zen (multi-model proxy)**: prompts for `OPENCODE_API_KEY` (or `OPENCODE_ZEN_API_KEY`, get it at [https://opencode.ai/auth](https://opencode.ai/auth)).
* **API key**: stores the key for you.
* **Vercel AI Gateway (multi-model proxy)**: prompts for `AI_GATEWAY_API_KEY`.
* More detail: [Vercel AI Gateway](https://docs.wednesdayai.dev/next/admin/providers/vercel-ai-gateway.md)
* **Cloudflare AI Gateway**: prompts for Account ID, Gateway ID, and `CLOUDFLARE_AI_GATEWAY_API_KEY`.
* More detail: [Cloudflare AI Gateway](https://docs.wednesdayai.dev/next/admin/providers/cloudflare-ai-gateway.md)
* **MiniMax M2.5**: config is auto-written.
* More detail: [MiniMax](https://docs.wednesdayai.dev/next/admin/providers/minimax.md)
* **Synthetic (Anthropic-compatible)**: prompts for `SYNTHETIC_API_KEY`.
* More detail: [Synthetic](https://docs.wednesdayai.dev/next/admin/providers/synthetic.md)
* **Moonshot (Kimi K2)**: config is auto-written.
* **Kimi Coding**: config is auto-written.
* More detail: [Moonshot AI (Kimi + Kimi Coding)](https://docs.wednesdayai.dev/next/admin/providers/moonshot.md)
* **Skip**: no auth configured yet.
* Pick a default model from detected options (or enter provider/model manually). For best quality and lower prompt-injection risk, choose the strongest latest-generation model available in your provider stack.
* Wizard runs a model check and warns if the configured model is unknown or missing auth.
* API key storage mode defaults to plaintext auth-profile values. Use `--secret-input-mode ref` to store env-backed refs instead (for example `keyRef: { source: "env", provider: "default", id: "OPENAI_API_KEY" }`).
* OAuth credentials live in `~/.openclaw/credentials/oauth.json`; auth profiles live in `~/.openclaw/agents/<agentId>/agent/auth-profiles.json` (API keys + OAuth).
* More detail: [/concepts/oauth](https://docs.wednesdayai.dev/next/developers/concepts/oauth.md)

> [!NOTE]
>
> Headless/server tip: complete OAuth on a machine with a browser, then copy
> `~/.openclaw/credentials/oauth.json` (or `$OPENCLAW_STATE_DIR/credentials/oauth.json`) to the
> gateway host.

**3. Workspace**

* Default `~/.openclaw/workspace` (configurable).
* Seeds the workspace files needed for the agent bootstrap ritual.
* Full workspace layout + backup guide: [Agent workspace](https://docs.wednesdayai.dev/next/developers/concepts/agent-workspace.md)

**4. Gateway**

* Port, bind, auth mode, tailscale exposure.
* Auth recommendation: keep **Token** even for loopback so local WS clients must authenticate.
* Disable auth only if you fully trust every local process.
* Non‑loopback binds still require auth.

**5. Channels**

* [WhatsApp](https://docs.wednesdayai.dev/next/admin/channels/whatsapp.md): optional QR login.
* [Telegram](https://docs.wednesdayai.dev/next/admin/channels/telegram.md): bot token.
* [Discord](https://docs.wednesdayai.dev/next/admin/channels/discord.md): bot token.
* [Google Chat](https://docs.wednesdayai.dev/next/admin/channels/googlechat.md): service account JSON + webhook audience.
* [Mattermost](https://docs.wednesdayai.dev/next/admin/channels/mattermost.md) (plugin): bot token + base URL.
* [Signal](https://docs.wednesdayai.dev/next/admin/channels/signal.md): optional `signal-cli` install + account config.
* [BlueBubbles](https://docs.wednesdayai.dev/next/admin/channels/bluebubbles.md): **recommended for iMessage**; server URL + password + webhook.
* [iMessage](https://docs.wednesdayai.dev/next/admin/channels/imessage.md): legacy `imsg` CLI path + DB access.
* DM security: default is pairing. First DM sends a code; approve via `wednesdayai pairing approve <channel> <code>` or use allowlists.

**6. Daemon install**

* macOS: LaunchAgent
  * Requires a logged-in user session; for headless, use a custom LaunchDaemon (not shipped).
* Linux (and Windows via WSL2): systemd user unit
  * Wizard attempts to enable lingering via `loginctl enable-linger <user>` so the Gateway stays up after logout.
  * May prompt for sudo (writes `/var/lib/systemd/linger`); it tries without sudo first.
* **Runtime selection:** Node (recommended; required for WhatsApp/Telegram). Bun is **not recommended**.

**7. Health check**

* Starts the Gateway (if needed) and runs `wednesdayai health`.
* Tip: `wednesdayai status --deep` adds gateway health probes to status output (requires a reachable gateway).

**8. Skills (recommended)**

* Reads the available skills and checks requirements.
* Lets you choose a node manager: **npm / pnpm** (bun not recommended).
* Installs optional dependencies (some use Homebrew on macOS).

**9. Finish**

* Summary + next steps, including iOS/Android/macOS apps for extra features.

> [!NOTE]
>
> If no GUI is detected, the wizard prints SSH port-forward instructions for the Control UI instead of opening a browser.
> The wizard does not build the Control UI. From a source checkout, run `pnpm control:build:packaged` before opening it; until then the console URL answers `503` naming that command.

## Non-interactive mode

Use `--non-interactive` to automate or script onboarding:

```bash theme={"dark"}
wednesdayai 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
```

Add `--json` for a machine‑readable summary.

> [!NOTE]
>
> `--json` does **not** imply non-interactive mode. Use `--non-interactive` (and `--workspace`) for scripts.

> [accordion] Gemini example
>
> ```bash theme={"dark"}
> wednesdayai onboard --non-interactive \
>   --mode local \
>   --auth-choice gemini-api-key \
>   --gemini-api-key "$GEMINI_API_KEY" \
>   --gateway-port 18789 \
>   --gateway-bind loopback
> ```

> [accordion] Z.AI example
>
> ```bash theme={"dark"}
> wednesdayai onboard --non-interactive \
>   --mode local \
>   --auth-choice zai-api-key \
>   --zai-api-key "$ZAI_API_KEY" \
>   --gateway-port 18789 \
>   --gateway-bind loopback
> ```

> [accordion] Vercel AI Gateway example
>
> ```bash theme={"dark"}
> wednesdayai 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
> ```

> [accordion] Cloudflare AI Gateway example
>
> ```bash theme={"dark"}
> wednesdayai 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
> ```

> [accordion] Moonshot example
>
> ```bash theme={"dark"}
> wednesdayai onboard --non-interactive \
>   --mode local \
>   --auth-choice moonshot-api-key \
>   --moonshot-api-key "$MOONSHOT_API_KEY" \
>   --gateway-port 18789 \
>   --gateway-bind loopback
> ```

> [accordion] Synthetic example
>
> ```bash theme={"dark"}
> wednesdayai onboard --non-interactive \
>   --mode local \
>   --auth-choice synthetic-api-key \
>   --synthetic-api-key "$SYNTHETIC_API_KEY" \
>   --gateway-port 18789 \
>   --gateway-bind loopback
> ```

> [accordion] OpenCode Zen example
>
> ```bash theme={"dark"}
> wednesdayai onboard --non-interactive \
>   --mode local \
>   --auth-choice opencode-zen \
>   --opencode-zen-api-key "$OPENCODE_API_KEY" \
>   --gateway-port 18789 \
>   --gateway-bind loopback
> ```

### Add agent (non-interactive)

```bash theme={"dark"}
wednesdayai agents add work \
  --workspace ~/.openclaw/workspace-work \
  --model openai/gpt-5.2 \
  --bind whatsapp:biz \
  --non-interactive \
  --json
```

## Gateway wizard RPC

The Gateway exposes the wizard flow over RPC (`wizard.start`, `wizard.next`, `wizard.cancel`, `wizard.status`).
Clients (macOS app, Control UI) can render steps without re‑implementing onboarding logic.

## Signal setup (signal-cli)

The wizard can install `signal-cli` from GitHub releases:

* Downloads the appropriate release asset.
* Stores it under `~/.openclaw/tools/signal-cli/<version>/`.
* Writes `channels.signal.cliPath` to your config.

Notes:

* JVM builds require **Java 21**.
* Native builds are used when available.
* Windows uses WSL2; signal-cli install follows the Linux flow inside WSL.

## What the wizard writes

Typical fields in `~/.openclaw/openclaw.json`:

* `agents.defaults.workspace`
* `agents.defaults.model` / `models.providers` (if Minimax chosen)
* `tools.profile` (local onboarding defaults to `"messaging"` when unset; existing explicit values are preserved)
* `tools.alsoAllow` and `tools.fs.workspaceOnly` (when `tools.profile` is unset, local onboarding writes `tools.alsoAllow: ["group:fs"]` — skipped if `tools.allow` is already set — and `tools.fs.workspaceOnly: true`, unless `tools.fs.workspaceOnly` is explicitly `false`)
* `gateway.*` (mode, bind, auth, tailscale)
* `session.dmScope` (behavior details: [CLI Onboarding Reference](https://docs.wednesdayai.dev/next/users/start/wizard-cli-reference.md#outputs-and-internals))
* `channels.telegram.botToken`, `channels.discord.token`, `channels.signal.*`, `channels.imessage.*`
* Channel allowlists (Slack/Discord/Matrix/Microsoft Teams) when you opt in during the prompts (names resolve to IDs when possible).
* `skills.install.nodeManager`
* `wizard.lastRunAt`
* `wizard.lastRunVersion`
* `wizard.lastRunCommit`
* `wizard.lastRunCommand`
* `wizard.lastRunMode`

`wednesdayai agents add` writes `agents.list[]` and optional `bindings`.

WhatsApp credentials go under `~/.openclaw/credentials/whatsapp/<accountId>/`.
Sessions are stored under `~/.openclaw/agents/<agentId>/sessions/`.

Some channels are delivered as plugins. When you pick one during onboarding, the wizard
will prompt to install it (npm or a local path) before it can be configured.

## Related docs

* Wizard overview: [Onboarding Wizard](https://docs.wednesdayai.dev/next/users/start/wizard.md)
* macOS app onboarding: [Onboarding](https://docs.wednesdayai.dev/next/users/start/onboarding.md)
* Config reference: [Gateway configuration](https://docs.wednesdayai.dev/next/admin/gateway/configuration.md)
* Providers: [WhatsApp](https://docs.wednesdayai.dev/next/admin/channels/whatsapp.md), [Telegram](https://docs.wednesdayai.dev/next/admin/channels/telegram.md), [Discord](https://docs.wednesdayai.dev/next/admin/channels/discord.md), [Google Chat](https://docs.wednesdayai.dev/next/admin/channels/googlechat.md), [Signal](https://docs.wednesdayai.dev/next/admin/channels/signal.md), [BlueBubbles](https://docs.wednesdayai.dev/next/admin/channels/bluebubbles.md) (iMessage), [iMessage](https://docs.wednesdayai.dev/next/admin/channels/imessage.md) (legacy)
* Skills: [Skills](https://docs.wednesdayai.dev/next/users/tools/skills.md), [Skills config](https://docs.wednesdayai.dev/next/users/tools/skills-config.md)


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