{
  "title": "Onboarding Wizard (CLI)",
  "content": "The onboarding wizard is the **recommended** way to set up OpenClaw on macOS,\nLinux, or Windows (via WSL2; strongly recommended).\nIt configures a local Gateway or a remote Gateway connection, plus channels, skills,\nand workspace defaults in one guided flow.\n\nFastest first chat: open the Control UI (no channel setup needed). Run\n`openclaw dashboard` and chat in the browser. Docs: [Dashboard](/web/dashboard).\n\nFollow‑up reconfiguration:\n\nRecommended: set up a Brave Search API key so the agent can use `web_search`\n(`web_fetch` works without a key). Easiest path: `openclaw configure --section web`\nwhich stores `tools.web.search.apiKey`. Docs: [Web tools](/tools/web).\n\n## QuickStart vs Advanced\n\nThe wizard starts with **QuickStart** (defaults) vs **Advanced** (full control).\n\n**QuickStart** keeps the defaults:\n\n* Local gateway (loopback)\n* Workspace default (or existing workspace)\n* Gateway port **18789**\n* Gateway auth **Token** (auto‑generated, even on loopback)\n* Tailscale exposure **Off**\n* Telegram + WhatsApp DMs default to **allowlist** (you’ll be prompted for your phone number)\n\n**Advanced** exposes every step (mode, workspace, gateway, channels, daemon, skills).\n\n## What the wizard does\n\n**Local mode (default)** walks you through:\n\n* Model/auth (OpenAI Code (Codex) subscription OAuth, Anthropic API key (recommended) or setup-token (paste), plus MiniMax/GLM/Moonshot/AI Gateway options)\n* Workspace location + bootstrap files\n* Gateway settings (port/bind/auth/tailscale)\n* Providers (Telegram, WhatsApp, Discord, Google Chat, Mattermost (plugin), Signal)\n* Daemon install (LaunchAgent / systemd user unit)\n* Health check\n* Skills (recommended)\n\n**Remote mode** only configures the local client to connect to a Gateway elsewhere.\nIt does **not** install or change anything on the remote host.\n\nTo add more isolated agents (separate workspace + sessions + auth), use:\n\nTip: `--json` does **not** imply non-interactive mode. Use `--non-interactive` (and `--workspace`) for scripts.\n\n## Flow details (local)\n\n1. **Existing config detection**\n   * If `~/.openclaw/openclaw.json` exists, choose **Keep / Modify / Reset**.\n   * Re-running the wizard does **not** wipe anything unless you explicitly choose **Reset**\n     (or pass `--reset`).\n   * If the config is invalid or contains legacy keys, the wizard stops and asks\n     you to run `openclaw doctor` before continuing.\n   * Reset uses `trash` (never `rm`) and offers scopes:\n     * Config only\n     * Config + credentials + sessions\n     * Full reset (also removes workspace)\n\n2. **Model/Auth**\n   * **Anthropic API key (recommended)**: uses `ANTHROPIC_API_KEY` if present or prompts for a key, then saves it for daemon use.\n   * **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.\n   * **Anthropic token (paste setup-token)**: run `claude setup-token` on any machine, then paste the token (you can name it; blank = default).\n   * **OpenAI Code (Codex) subscription (Codex CLI)**: if `~/.codex/auth.json` exists, the wizard can reuse it.\n   * **OpenAI Code (Codex) subscription (OAuth)**: browser flow; paste the `code#state`.\n     * Sets `agents.defaults.model` to `openai-codex/gpt-5.2` when model is unset or `openai/*`.\n   * **OpenAI API key**: uses `OPENAI_API_KEY` if present or prompts for a key, then saves it to `~/.openclaw/.env` so launchd can read it.\n   * **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)).\n   * **API key**: stores the key for you.\n   * **Vercel AI Gateway (multi-model proxy)**: prompts for `AI_GATEWAY_API_KEY`.\n   * More detail: [Vercel AI Gateway](/providers/vercel-ai-gateway)\n   * **Cloudflare AI Gateway**: prompts for Account ID, Gateway ID, and `CLOUDFLARE_AI_GATEWAY_API_KEY`.\n   * More detail: [Cloudflare AI Gateway](/providers/cloudflare-ai-gateway)\n   * **MiniMax M2.1**: config is auto-written.\n   * More detail: [MiniMax](/providers/minimax)\n   * **Synthetic (Anthropic-compatible)**: prompts for `SYNTHETIC_API_KEY`.\n   * More detail: [Synthetic](/providers/synthetic)\n   * **Moonshot (Kimi K2)**: config is auto-written.\n   * **Kimi Coding**: config is auto-written.\n   * More detail: [Moonshot AI (Kimi + Kimi Coding)](/providers/moonshot)\n   * **Skip**: no auth configured yet.\n   * Pick a default model from detected options (or enter provider/model manually).\n   * Wizard runs a model check and warns if the configured model is unknown or missing auth.\n\n* OAuth credentials live in `~/.openclaw/credentials/oauth.json`; auth profiles live in `~/.openclaw/agents/<agentId>/agent/auth-profiles.json` (API keys + OAuth).\n* More detail: [/concepts/oauth](/concepts/oauth)\n\n3. **Workspace**\n   * Default `~/.openclaw/workspace` (configurable).\n   * Seeds the workspace files needed for the agent bootstrap ritual.\n   * Full workspace layout + backup guide: [Agent workspace](/concepts/agent-workspace)\n\n4. **Gateway**\n   * Port, bind, auth mode, tailscale exposure.\n   * Auth recommendation: keep **Token** even for loopback so local WS clients must authenticate.\n   * Disable auth only if you fully trust every local process.\n   * Non‑loopback binds still require auth.\n\n5. **Channels**\n   * [WhatsApp](/channels/whatsapp): optional QR login.\n   * [Telegram](/channels/telegram): bot token.\n   * [Discord](/channels/discord): bot token.\n   * [Google Chat](/channels/googlechat): service account JSON + webhook audience.\n   * [Mattermost](/channels/mattermost) (plugin): bot token + base URL.\n   * [Signal](/channels/signal): optional `signal-cli` install + account config.\n   * [BlueBubbles](/channels/bluebubbles): **recommended for iMessage**; server URL + password + webhook.\n   * [iMessage](/channels/imessage): legacy `imsg` CLI path + DB access.\n   * DM security: default is pairing. First DM sends a code; approve via `openclaw pairing approve <channel> <code>` or use allowlists.\n\n6. **Daemon install**\n   * macOS: LaunchAgent\n     * Requires a logged-in user session; for headless, use a custom LaunchDaemon (not shipped).\n   * Linux (and Windows via WSL2): systemd user unit\n     * Wizard attempts to enable lingering via `loginctl enable-linger <user>` so the Gateway stays up after logout.\n     * May prompt for sudo (writes `/var/lib/systemd/linger`); it tries without sudo first.\n   * **Runtime selection:** Node (recommended; required for WhatsApp/Telegram). Bun is **not recommended**.\n\n7. **Health check**\n   * Starts the Gateway (if needed) and runs `openclaw health`.\n   * Tip: `openclaw status --deep` adds gateway health probes to status output (requires a reachable gateway).\n\n8. **Skills (recommended)**\n   * Reads the available skills and checks requirements.\n   * Lets you choose a node manager: **npm / pnpm** (bun not recommended).\n   * Installs optional dependencies (some use Homebrew on macOS).\n\n9. **Finish**\n   * Summary + next steps, including iOS/Android/macOS apps for extra features.\n\n* If no GUI is detected, the wizard prints SSH port-forward instructions for the Control UI instead of opening a browser.\n* If the Control UI assets are missing, the wizard attempts to build them; fallback is `pnpm ui:build` (auto-installs UI deps).\n\nRemote mode configures a local client to connect to a Gateway elsewhere.\n\n* Remote Gateway URL (`ws://...`)\n* Token if the remote Gateway requires auth (recommended)\n\n* No remote installs or daemon changes are performed.\n* If the Gateway is loopback‑only, use SSH tunneling or a tailnet.\n* Discovery hints:\n  * macOS: Bonjour (`dns-sd`)\n  * Linux: Avahi (`avahi-browse`)\n\nUse `openclaw agents add <name>` to create a separate agent with its own workspace,\nsessions, and auth profiles. Running without `--workspace` launches the wizard.\n\n* `agents.list[].name`\n* `agents.list[].workspace`\n* `agents.list[].agentDir`\n\n* Default workspaces follow `~/.openclaw/workspace-<agentId>`.\n* Add `bindings` to route inbound messages (the wizard can do this).\n* Non-interactive flags: `--model`, `--agent-dir`, `--bind`, `--non-interactive`.\n\n## Non‑interactive mode\n\nUse `--non-interactive` to automate or script onboarding:\n\nAdd `--json` for a machine‑readable summary.\n\nVercel AI Gateway example:\n\nCloudflare AI Gateway example:\n\nOpenCode Zen example:\n\nAdd agent (non‑interactive) example:\n\n## Gateway wizard RPC\n\nThe Gateway exposes the wizard flow over RPC (`wizard.start`, `wizard.next`, `wizard.cancel`, `wizard.status`).\nClients (macOS app, Control UI) can render steps without re‑implementing onboarding logic.\n\n## Signal setup (signal-cli)\n\nThe wizard can install `signal-cli` from GitHub releases:\n\n* Downloads the appropriate release asset.\n* Stores it under `~/.openclaw/tools/signal-cli/<version>/`.\n* Writes `channels.signal.cliPath` to your config.\n\n* JVM builds require **Java 21**.\n* Native builds are used when available.\n* Windows uses WSL2; signal-cli install follows the Linux flow inside WSL.\n\n## What the wizard writes\n\nTypical fields in `~/.openclaw/openclaw.json`:\n\n* `agents.defaults.workspace`\n* `agents.defaults.model` / `models.providers` (if Minimax chosen)\n* `gateway.*` (mode, bind, auth, tailscale)\n* `channels.telegram.botToken`, `channels.discord.token`, `channels.signal.*`, `channels.imessage.*`\n* Channel allowlists (Slack/Discord/Matrix/Microsoft Teams) when you opt in during the prompts (names resolve to IDs when possible).\n* `skills.install.nodeManager`\n* `wizard.lastRunAt`\n* `wizard.lastRunVersion`\n* `wizard.lastRunCommit`\n* `wizard.lastRunCommand`\n* `wizard.lastRunMode`\n\n`openclaw agents add` writes `agents.list[]` and optional `bindings`.\n\nWhatsApp credentials go under `~/.openclaw/credentials/whatsapp/<accountId>/`.\nSessions are stored under `~/.openclaw/agents/<agentId>/sessions/`.\n\nSome channels are delivered as plugins. When you pick one during onboarding, the wizard\nwill prompt to install it (npm or a local path) before it can be configured.\n\n* macOS app onboarding: [Onboarding](/start/onboarding)\n* Config reference: [Gateway configuration](/gateway/configuration)\n* Providers: [WhatsApp](/channels/whatsapp), [Telegram](/channels/telegram), [Discord](/channels/discord), [Google Chat](/channels/googlechat), [Signal](/channels/signal), [BlueBubbles](/channels/bluebubbles) (iMessage), [iMessage](/channels/imessage) (legacy)\n* Skills: [Skills](/tools/skills), [Skills config](/tools/skills-config)",
  "code_samples": [
    {
      "code": "Fastest first chat: open the Control UI (no channel setup needed). Run\n`openclaw dashboard` and chat in the browser. Docs: [Dashboard](/web/dashboard).\n\nFollow‑up reconfiguration:",
      "language": "unknown"
    },
    {
      "code": "Recommended: set up a Brave Search API key so the agent can use `web_search`\n(`web_fetch` works without a key). Easiest path: `openclaw configure --section web`\nwhich stores `tools.web.search.apiKey`. Docs: [Web tools](/tools/web).\n\n## QuickStart vs Advanced\n\nThe wizard starts with **QuickStart** (defaults) vs **Advanced** (full control).\n\n**QuickStart** keeps the defaults:\n\n* Local gateway (loopback)\n* Workspace default (or existing workspace)\n* Gateway port **18789**\n* Gateway auth **Token** (auto‑generated, even on loopback)\n* Tailscale exposure **Off**\n* Telegram + WhatsApp DMs default to **allowlist** (you’ll be prompted for your phone number)\n\n**Advanced** exposes every step (mode, workspace, gateway, channels, daemon, skills).\n\n## What the wizard does\n\n**Local mode (default)** walks you through:\n\n* Model/auth (OpenAI Code (Codex) subscription OAuth, Anthropic API key (recommended) or setup-token (paste), plus MiniMax/GLM/Moonshot/AI Gateway options)\n* Workspace location + bootstrap files\n* Gateway settings (port/bind/auth/tailscale)\n* Providers (Telegram, WhatsApp, Discord, Google Chat, Mattermost (plugin), Signal)\n* Daemon install (LaunchAgent / systemd user unit)\n* Health check\n* Skills (recommended)\n\n**Remote mode** only configures the local client to connect to a Gateway elsewhere.\nIt does **not** install or change anything on the remote host.\n\nTo add more isolated agents (separate workspace + sessions + auth), use:",
      "language": "unknown"
    },
    {
      "code": "Tip: `--json` does **not** imply non-interactive mode. Use `--non-interactive` (and `--workspace`) for scripts.\n\n## Flow details (local)\n\n1. **Existing config detection**\n   * If `~/.openclaw/openclaw.json` exists, choose **Keep / Modify / Reset**.\n   * Re-running the wizard does **not** wipe anything unless you explicitly choose **Reset**\n     (or pass `--reset`).\n   * If the config is invalid or contains legacy keys, the wizard stops and asks\n     you to run `openclaw doctor` before continuing.\n   * Reset uses `trash` (never `rm`) and offers scopes:\n     * Config only\n     * Config + credentials + sessions\n     * Full reset (also removes workspace)\n\n2. **Model/Auth**\n   * **Anthropic API key (recommended)**: uses `ANTHROPIC_API_KEY` if present or prompts for a key, then saves it for daemon use.\n   * **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.\n   * **Anthropic token (paste setup-token)**: run `claude setup-token` on any machine, then paste the token (you can name it; blank = default).\n   * **OpenAI Code (Codex) subscription (Codex CLI)**: if `~/.codex/auth.json` exists, the wizard can reuse it.\n   * **OpenAI Code (Codex) subscription (OAuth)**: browser flow; paste the `code#state`.\n     * Sets `agents.defaults.model` to `openai-codex/gpt-5.2` when model is unset or `openai/*`.\n   * **OpenAI API key**: uses `OPENAI_API_KEY` if present or prompts for a key, then saves it to `~/.openclaw/.env` so launchd can read it.\n   * **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)).\n   * **API key**: stores the key for you.\n   * **Vercel AI Gateway (multi-model proxy)**: prompts for `AI_GATEWAY_API_KEY`.\n   * More detail: [Vercel AI Gateway](/providers/vercel-ai-gateway)\n   * **Cloudflare AI Gateway**: prompts for Account ID, Gateway ID, and `CLOUDFLARE_AI_GATEWAY_API_KEY`.\n   * More detail: [Cloudflare AI Gateway](/providers/cloudflare-ai-gateway)\n   * **MiniMax M2.1**: config is auto-written.\n   * More detail: [MiniMax](/providers/minimax)\n   * **Synthetic (Anthropic-compatible)**: prompts for `SYNTHETIC_API_KEY`.\n   * More detail: [Synthetic](/providers/synthetic)\n   * **Moonshot (Kimi K2)**: config is auto-written.\n   * **Kimi Coding**: config is auto-written.\n   * More detail: [Moonshot AI (Kimi + Kimi Coding)](/providers/moonshot)\n   * **Skip**: no auth configured yet.\n   * Pick a default model from detected options (or enter provider/model manually).\n   * Wizard runs a model check and warns if the configured model is unknown or missing auth.\n\n* OAuth credentials live in `~/.openclaw/credentials/oauth.json`; auth profiles live in `~/.openclaw/agents/<agentId>/agent/auth-profiles.json` (API keys + OAuth).\n* More detail: [/concepts/oauth](/concepts/oauth)\n\n3. **Workspace**\n   * Default `~/.openclaw/workspace` (configurable).\n   * Seeds the workspace files needed for the agent bootstrap ritual.\n   * Full workspace layout + backup guide: [Agent workspace](/concepts/agent-workspace)\n\n4. **Gateway**\n   * Port, bind, auth mode, tailscale exposure.\n   * Auth recommendation: keep **Token** even for loopback so local WS clients must authenticate.\n   * Disable auth only if you fully trust every local process.\n   * Non‑loopback binds still require auth.\n\n5. **Channels**\n   * [WhatsApp](/channels/whatsapp): optional QR login.\n   * [Telegram](/channels/telegram): bot token.\n   * [Discord](/channels/discord): bot token.\n   * [Google Chat](/channels/googlechat): service account JSON + webhook audience.\n   * [Mattermost](/channels/mattermost) (plugin): bot token + base URL.\n   * [Signal](/channels/signal): optional `signal-cli` install + account config.\n   * [BlueBubbles](/channels/bluebubbles): **recommended for iMessage**; server URL + password + webhook.\n   * [iMessage](/channels/imessage): legacy `imsg` CLI path + DB access.\n   * DM security: default is pairing. First DM sends a code; approve via `openclaw pairing approve <channel> <code>` or use allowlists.\n\n6. **Daemon install**\n   * macOS: LaunchAgent\n     * Requires a logged-in user session; for headless, use a custom LaunchDaemon (not shipped).\n   * Linux (and Windows via WSL2): systemd user unit\n     * Wizard attempts to enable lingering via `loginctl enable-linger <user>` so the Gateway stays up after logout.\n     * May prompt for sudo (writes `/var/lib/systemd/linger`); it tries without sudo first.\n   * **Runtime selection:** Node (recommended; required for WhatsApp/Telegram). Bun is **not recommended**.\n\n7. **Health check**\n   * Starts the Gateway (if needed) and runs `openclaw health`.\n   * Tip: `openclaw status --deep` adds gateway health probes to status output (requires a reachable gateway).\n\n8. **Skills (recommended)**\n   * Reads the available skills and checks requirements.\n   * Lets you choose a node manager: **npm / pnpm** (bun not recommended).\n   * Installs optional dependencies (some use Homebrew on macOS).\n\n9. **Finish**\n   * Summary + next steps, including iOS/Android/macOS apps for extra features.\n\n* If no GUI is detected, the wizard prints SSH port-forward instructions for the Control UI instead of opening a browser.\n* If the Control UI assets are missing, the wizard attempts to build them; fallback is `pnpm ui:build` (auto-installs UI deps).\n\n## Remote mode\n\nRemote mode configures a local client to connect to a Gateway elsewhere.\n\nWhat you’ll set:\n\n* Remote Gateway URL (`ws://...`)\n* Token if the remote Gateway requires auth (recommended)\n\nNotes:\n\n* No remote installs or daemon changes are performed.\n* If the Gateway is loopback‑only, use SSH tunneling or a tailnet.\n* Discovery hints:\n  * macOS: Bonjour (`dns-sd`)\n  * Linux: Avahi (`avahi-browse`)\n\n## Add another agent\n\nUse `openclaw agents add <name>` to create a separate agent with its own workspace,\nsessions, and auth profiles. Running without `--workspace` launches the wizard.\n\nWhat it sets:\n\n* `agents.list[].name`\n* `agents.list[].workspace`\n* `agents.list[].agentDir`\n\nNotes:\n\n* Default workspaces follow `~/.openclaw/workspace-<agentId>`.\n* Add `bindings` to route inbound messages (the wizard can do this).\n* Non-interactive flags: `--model`, `--agent-dir`, `--bind`, `--non-interactive`.\n\n## Non‑interactive mode\n\nUse `--non-interactive` to automate or script onboarding:",
      "language": "unknown"
    },
    {
      "code": "Add `--json` for a machine‑readable summary.\n\nGemini example:",
      "language": "unknown"
    },
    {
      "code": "Z.AI example:",
      "language": "unknown"
    },
    {
      "code": "Vercel AI Gateway example:",
      "language": "unknown"
    },
    {
      "code": "Cloudflare AI Gateway example:",
      "language": "unknown"
    },
    {
      "code": "Moonshot example:",
      "language": "unknown"
    },
    {
      "code": "Synthetic example:",
      "language": "unknown"
    },
    {
      "code": "OpenCode Zen example:",
      "language": "unknown"
    },
    {
      "code": "Add agent (non‑interactive) example:",
      "language": "unknown"
    }
  ],
  "headings": [
    {
      "level": "h2",
      "text": "QuickStart vs Advanced",
      "id": "quickstart-vs-advanced"
    },
    {
      "level": "h2",
      "text": "What the wizard does",
      "id": "what-the-wizard-does"
    },
    {
      "level": "h2",
      "text": "Flow details (local)",
      "id": "flow-details-(local)"
    },
    {
      "level": "h2",
      "text": "Remote mode",
      "id": "remote-mode"
    },
    {
      "level": "h2",
      "text": "Add another agent",
      "id": "add-another-agent"
    },
    {
      "level": "h2",
      "text": "Non‑interactive mode",
      "id": "non‑interactive-mode"
    },
    {
      "level": "h2",
      "text": "Gateway wizard RPC",
      "id": "gateway-wizard-rpc"
    },
    {
      "level": "h2",
      "text": "Signal setup (signal-cli)",
      "id": "signal-setup-(signal-cli)"
    },
    {
      "level": "h2",
      "text": "What the wizard writes",
      "id": "what-the-wizard-writes"
    },
    {
      "level": "h2",
      "text": "Related docs",
      "id": "related-docs"
    }
  ],
  "url": "llms-txt#onboarding-wizard-(cli)",
  "links": []
}