From 9e0030b75f2ea20b1cc5e60df2a7c6418000a1e3 Mon Sep 17 00:00:00 2001 From: Seb Slight <19554889+sebslight@users.noreply.github.com> Date: Thu, 5 Feb 2026 13:46:11 -0500 Subject: [PATCH] docs(onboarding): streamline CLI onboarding docs (#9830) --- docs/cli/onboard.md | 18 +- docs/docs.json | 28 ++- docs/start/wizard-cli-automation.md | 141 +++++++++++ docs/start/wizard-cli-reference.md | 241 ++++++++++++++++++ docs/start/wizard.md | 372 +++------------------------- 5 files changed, 465 insertions(+), 335 deletions(-) create mode 100644 docs/start/wizard-cli-automation.md create mode 100644 docs/start/wizard-cli-reference.md diff --git a/docs/cli/onboard.md b/docs/cli/onboard.md index 322fdf12d..917986597 100644 --- a/docs/cli/onboard.md +++ b/docs/cli/onboard.md @@ -9,9 +9,12 @@ title: "onboard" Interactive onboarding wizard (local or remote Gateway setup). -Related: +## Related guides -- Wizard guide: [Onboarding](/start/onboarding) +- CLI onboarding hub: [Onboarding Wizard (CLI)](/start/wizard) +- CLI onboarding reference: [CLI Onboarding Reference](/start/wizard-cli-reference) +- CLI automation: [CLI Automation](/start/wizard-cli-automation) +- macOS onboarding: [Onboarding (macOS App)](/start/onboarding) ## Examples @@ -27,3 +30,14 @@ Flow notes: - `quickstart`: minimal prompts, auto-generates a gateway token. - `manual`: full prompts for port/bind/auth (alias of `advanced`). - Fastest first chat: `openclaw dashboard` (Control UI, no channel setup). + +## Common follow-up commands + +```bash +openclaw configure +openclaw agents add +``` + + +`--json` does not imply non-interactive mode. Use `--non-interactive` for scripts. + diff --git a/docs/docs.json b/docs/docs.json index ba963a71b..1880991e7 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -698,6 +698,18 @@ "source": "/wizard", "destination": "/start/wizard" }, + { + "source": "/start/wizard-cli-flow", + "destination": "/start/wizard-cli-reference" + }, + { + "source": "/start/wizard-cli-auth", + "destination": "/start/wizard-cli-reference" + }, + { + "source": "/start/wizard-cli-outputs", + "destination": "/start/wizard-cli-reference" + }, { "source": "/start/faq", "destination": "/help/faq" @@ -745,8 +757,22 @@ "start/getting-started", { "group": "Onboarding", - "pages": ["start/wizard", "start/onboarding", "start/bootstrapping"] + "pages": [ + { + "group": "CLI onboarding", + "pages": [ + "start/wizard", + "start/wizard-cli-reference", + "start/wizard-cli-automation" + ] + }, + { + "group": "macOS onboarding", + "pages": ["start/onboarding"] + } + ] }, + "start/bootstrapping", "start/pairing" ] }, diff --git a/docs/start/wizard-cli-automation.md b/docs/start/wizard-cli-automation.md new file mode 100644 index 000000000..081c0a195 --- /dev/null +++ b/docs/start/wizard-cli-automation.md @@ -0,0 +1,141 @@ +--- +summary: "Scripted onboarding and agent setup for the OpenClaw CLI" +read_when: + - You are automating onboarding in scripts or CI + - You need non-interactive examples for specific providers +title: "CLI Automation" +sidebarTitle: "CLI automation" +--- + +# CLI Automation + +Use `--non-interactive` to automate `openclaw onboard`. + + +`--json` does not imply non-interactive mode. Use `--non-interactive` (and `--workspace`) for scripts. + + +## Baseline non-interactive example + +```bash +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 +``` + +Add `--json` for a machine-readable summary. + +## Provider-specific examples + + + + ```bash + openclaw onboard --non-interactive \ + --mode local \ + --auth-choice gemini-api-key \ + --gemini-api-key "$GEMINI_API_KEY" \ + --gateway-port 18789 \ + --gateway-bind loopback + ``` + + + ```bash + openclaw onboard --non-interactive \ + --mode local \ + --auth-choice zai-api-key \ + --zai-api-key "$ZAI_API_KEY" \ + --gateway-port 18789 \ + --gateway-bind loopback + ``` + + + ```bash + 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 + ``` + + + ```bash + 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 + ``` + + + ```bash + openclaw onboard --non-interactive \ + --mode local \ + --auth-choice moonshot-api-key \ + --moonshot-api-key "$MOONSHOT_API_KEY" \ + --gateway-port 18789 \ + --gateway-bind loopback + ``` + + + ```bash + openclaw onboard --non-interactive \ + --mode local \ + --auth-choice synthetic-api-key \ + --synthetic-api-key "$SYNTHETIC_API_KEY" \ + --gateway-port 18789 \ + --gateway-bind loopback + ``` + + + ```bash + openclaw onboard --non-interactive \ + --mode local \ + --auth-choice opencode-zen \ + --opencode-zen-api-key "$OPENCODE_API_KEY" \ + --gateway-port 18789 \ + --gateway-bind loopback + ``` + + + +## Add another agent + +Use `openclaw agents add ` to create a separate agent with its own workspace, +sessions, and auth profiles. Running without `--workspace` launches the wizard. + +```bash +openclaw agents add work \ + --workspace ~/.openclaw/workspace-work \ + --model openai/gpt-5.2 \ + --bind whatsapp:biz \ + --non-interactive \ + --json +``` + +What it sets: + +- `agents.list[].name` +- `agents.list[].workspace` +- `agents.list[].agentDir` + +Notes: + +- Default workspaces follow `~/.openclaw/workspace-`. +- Add `bindings` to route inbound messages (the wizard can do this). +- Non-interactive flags: `--model`, `--agent-dir`, `--bind`, `--non-interactive`. + +## Related docs + +- Onboarding hub: [Onboarding Wizard (CLI)](/start/wizard) +- Full reference: [CLI Onboarding Reference](/start/wizard-cli-reference) +- Command reference: [`openclaw onboard`](/cli/onboard) diff --git a/docs/start/wizard-cli-reference.md b/docs/start/wizard-cli-reference.md new file mode 100644 index 000000000..52ff3a8be --- /dev/null +++ b/docs/start/wizard-cli-reference.md @@ -0,0 +1,241 @@ +--- +summary: "Complete reference for CLI onboarding flow, auth/model setup, outputs, and internals" +read_when: + - You need detailed behavior for openclaw onboard + - You are debugging onboarding results or integrating onboarding clients +title: "CLI Onboarding Reference" +sidebarTitle: "CLI reference" +--- + +# CLI Onboarding Reference + +This page is the full reference for `openclaw onboard`. +For the short guide, see [Onboarding Wizard (CLI)](/start/wizard). + +## What the wizard does + +Local mode (default) walks you through: + +- Model and auth setup (OpenAI Code subscription OAuth, Anthropic API key or setup token, plus MiniMax, GLM, Moonshot, and AI Gateway options) +- Workspace location and bootstrap files +- Gateway settings (port, bind, auth, tailscale) +- Channels and providers (Telegram, WhatsApp, Discord, Google Chat, Mattermost plugin, Signal) +- Daemon install (LaunchAgent or systemd user unit) +- Health check +- Skills setup + +Remote mode configures this machine to connect to a gateway elsewhere. +It does not install or modify anything on the remote host. + +## Local flow details + + + + - If `~/.openclaw/openclaw.json` exists, choose Keep, Modify, or Reset. + - Re-running the wizard does not wipe anything unless you explicitly choose Reset (or pass `--reset`). + - If config is invalid or contains legacy keys, the wizard stops and asks you to run `openclaw doctor` before continuing. + - Reset uses `trash` and offers scopes: + - Config only + - Config + credentials + sessions + - Full reset (also removes workspace) + + + - Full option matrix is in [Auth and model options](#auth-and-model-options). + + + - Default `~/.openclaw/workspace` (configurable). + - Seeds workspace files needed for first-run bootstrap ritual. + - Workspace layout: [Agent workspace](/concepts/agent-workspace). + + + - Prompts for port, bind, auth mode, and tailscale exposure. + - Recommended: keep token auth enabled 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. + + + - [WhatsApp](/channels/whatsapp): optional QR login + - [Telegram](/channels/telegram): bot token + - [Discord](/channels/discord): bot token + - [Google Chat](/channels/googlechat): service account JSON + webhook audience + - [Mattermost](/channels/mattermost) plugin: bot token + base URL + - [Signal](/channels/signal): optional `signal-cli` install + account config + - [BlueBubbles](/channels/bluebubbles): recommended for iMessage; server URL + password + webhook + - [iMessage](/channels/imessage): legacy `imsg` CLI path + DB access + - DM security: default is pairing. First DM sends a code; approve via + `openclaw pairing approve ` or use allowlists. + + + - macOS: LaunchAgent + - Requires logged-in user session; for headless, use a custom LaunchDaemon (not shipped). + - Linux and Windows via WSL2: systemd user unit + - Wizard attempts `loginctl enable-linger ` so 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 and Telegram). Bun is not recommended. + + + - Starts gateway (if needed) and runs `openclaw health`. + - `openclaw status --deep` adds gateway health probes to status output. + + + - Reads available skills and checks requirements. + - Lets you choose node manager: npm or pnpm (bun not recommended). + - Installs optional dependencies (some use Homebrew on macOS). + + + - Summary and next steps, including iOS, Android, and macOS app options. + + + + +If no GUI is detected, the wizard prints SSH port-forward instructions for the Control UI instead of opening a browser. +If Control UI assets are missing, the wizard attempts to build them; fallback is `pnpm ui:build` (auto-installs UI deps). + + +## Remote mode details + +Remote mode configures this machine to connect to a gateway elsewhere. + + +Remote mode does not install or modify anything on the remote host. + + +What you set: + +- Remote gateway URL (`ws://...`) +- Token if remote gateway auth is required (recommended) + + +- If gateway is loopback-only, use SSH tunneling or a tailnet. +- Discovery hints: + - macOS: Bonjour (`dns-sd`) + - Linux: Avahi (`avahi-browse`) + + +## Auth and model options + + + + Uses `ANTHROPIC_API_KEY` if present or prompts for a key, then saves it for daemon use. + + + - macOS: checks Keychain item "Claude Code-credentials" + - Linux and Windows: reuses `~/.claude/.credentials.json` if present + + On macOS, choose "Always Allow" so launchd starts do not block. + + + + Run `claude setup-token` on any machine, then paste the token. + You can name it; blank uses default. + + + If `~/.codex/auth.json` exists, the wizard can reuse it. + + + Browser flow; paste `code#state`. + + Sets `agents.defaults.model` to `openai-codex/gpt-5.2` when model is unset or `openai/*`. + + + + Uses `OPENAI_API_KEY` if present or prompts for a key, then saves it to + `~/.openclaw/.env` so launchd can read it. + + + Prompts for `OPENCODE_API_KEY` (or `OPENCODE_ZEN_API_KEY`). + Setup URL: [opencode.ai/auth](https://opencode.ai/auth). + + + Stores the key for you. + + + Prompts for `AI_GATEWAY_API_KEY`. + More detail: [Vercel AI Gateway](/providers/vercel-ai-gateway). + + + Prompts for account ID, gateway ID, and `CLOUDFLARE_AI_GATEWAY_API_KEY`. + More detail: [Cloudflare AI Gateway](/providers/cloudflare-ai-gateway). + + + Config is auto-written. + More detail: [MiniMax](/providers/minimax). + + + Prompts for `SYNTHETIC_API_KEY`. + More detail: [Synthetic](/providers/synthetic). + + + Moonshot (Kimi K2) and Kimi Coding configs are auto-written. + More detail: [Moonshot AI (Kimi + Kimi Coding)](/providers/moonshot). + + + Leaves auth unconfigured. + + + +Model behavior: + +- Pick default model from detected options, or enter provider and model manually. +- Wizard runs a model check and warns if the configured model is unknown or missing auth. + +Credential and profile paths: + +- OAuth credentials: `~/.openclaw/credentials/oauth.json` +- Auth profiles (API keys + OAuth): `~/.openclaw/agents//agent/auth-profiles.json` + + +Headless and 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. + + +## Outputs and internals + +Typical fields in `~/.openclaw/openclaw.json`: + +- `agents.defaults.workspace` +- `agents.defaults.model` / `models.providers` (if Minimax chosen) +- `gateway.*` (mode, bind, auth, tailscale) +- `channels.telegram.botToken`, `channels.discord.token`, `channels.signal.*`, `channels.imessage.*` +- Channel allowlists (Slack, Discord, Matrix, Microsoft Teams) when you opt in during prompts (names resolve to IDs when possible) +- `skills.install.nodeManager` +- `wizard.lastRunAt` +- `wizard.lastRunVersion` +- `wizard.lastRunCommit` +- `wizard.lastRunCommand` +- `wizard.lastRunMode` + +`openclaw agents add` writes `agents.list[]` and optional `bindings`. + +WhatsApp credentials go under `~/.openclaw/credentials/whatsapp//`. +Sessions are stored under `~/.openclaw/agents//sessions/`. + + +Some channels are delivered as plugins. When selected during onboarding, the wizard +prompts to install the plugin (npm or local path) before channel configuration. + + +Gateway wizard RPC: + +- `wizard.start` +- `wizard.next` +- `wizard.cancel` +- `wizard.status` + +Clients (macOS app and Control UI) can render steps without re-implementing onboarding logic. + +Signal setup behavior: + +- Downloads the appropriate release asset +- Stores it under `~/.openclaw/tools/signal-cli//` +- Writes `channels.signal.cliPath` in config +- JVM builds require Java 21 +- Native builds are used when available +- Windows uses WSL2 and follows Linux signal-cli flow inside WSL + +## Related docs + +- Onboarding hub: [Onboarding Wizard (CLI)](/start/wizard) +- Automation and scripts: [CLI Automation](/start/wizard-cli-automation) +- Command reference: [`openclaw onboard`](/cli/onboard) diff --git a/docs/start/wizard.md b/docs/start/wizard.md index d751e2d70..86b207f6b 100644 --- a/docs/start/wizard.md +++ b/docs/start/wizard.md @@ -9,12 +9,9 @@ sidebarTitle: "Wizard (CLI)" # Onboarding Wizard (CLI) -The onboarding wizard is the **recommended** way to set up OpenClaw 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. - -Primary entrypoint: +The CLI onboarding wizard is the recommended setup path for OpenClaw on macOS, +Linux, and Windows (via WSL2). It configures a local gateway or a remote +gateway connection, plus workspace defaults, channels, and skills. ```bash openclaw onboard @@ -25,343 +22,54 @@ Fastest first chat: open the Control UI (no channel setup needed). Run `openclaw dashboard` and chat in the browser. Docs: [Dashboard](/web/dashboard). -Follow‑up reconfiguration: +## QuickStart vs Advanced + +The wizard starts with **QuickStart** (defaults) vs **Advanced** (full control). + + + + - Local gateway on loopback + - Existing workspace or default workspace + - Gateway port `18789` + - Gateway auth token auto-generated (even on loopback) + - Tailscale exposure off + - Telegram and WhatsApp DMs default to allowlist (you may be prompted for your phone number) + + + - Exposes full prompt flow for mode, workspace, gateway, channels, daemon, and skills + + + +## CLI onboarding details + + + + Full local and remote flow, auth and model matrix, config outputs, wizard RPC, and signal-cli behavior. + + + Non-interactive onboarding recipes and automated `agents add` examples. + + + +## Common follow-up commands ```bash openclaw configure +openclaw agents add ``` + +`--json` does not imply non-interactive mode. For scripts, use `--non-interactive`. + + Recommended: set up a Brave Search API key so the agent can use `web_search` (`web_fetch` works without a key). Easiest path: `openclaw configure --section web` which stores `tools.web.search.apiKey`. Docs: [Web tools](/tools/web). -## QuickStart vs Advanced - -The wizard starts with **QuickStart** (defaults) vs **Advanced** (full control). - - - - - Local gateway (loopback) - - Workspace default (or existing workspace) - - Gateway port **18789** - - Gateway auth **Token** (auto‑generated, even on loopback) - - Tailscale exposure **Off** - - Telegram + WhatsApp DMs default to **allowlist** (you’ll be prompted for your phone number) - - - - Exposes every step (mode, workspace, gateway, channels, daemon, skills). - - - -## What the wizard does - -**Local mode (default)** walks you through: - -- Model/auth (OpenAI Code (Codex) subscription OAuth, Anthropic API key (recommended) or setup-token (paste), plus MiniMax/GLM/Moonshot/AI Gateway options) -- Workspace location + bootstrap files -- Gateway settings (port/bind/auth/tailscale) -- Providers (Telegram, WhatsApp, Discord, Google Chat, Mattermost (plugin), Signal) -- Daemon install (LaunchAgent / systemd user unit) -- Health check -- Skills (recommended) - -**Remote mode** only configures the local client to connect to a Gateway elsewhere. -It does **not** install or change anything on the remote host. - -To add more isolated agents (separate workspace + sessions + auth), use: - -```bash -openclaw agents add -``` - - -`--json` does **not** imply non-interactive mode. Use `--non-interactive` (and `--workspace`) for scripts. - - -## Flow details (local) - - - - - 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`). - - If the config is invalid or contains legacy keys, the wizard stops and asks - you to run `openclaw doctor` before continuing. - - Reset uses `trash` (never `rm`) and offers scopes: - - Config only - - Config + credentials + sessions - - Full reset (also removes workspace) - - - - **Anthropic API key (recommended)**: 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 saves it to `~/.openclaw/.env` so launchd can read it. - - **OpenCode Zen (multi-model proxy)**: prompts for `OPENCODE_API_KEY` (or `OPENCODE_ZEN_API_KEY`, get it at 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](/providers/vercel-ai-gateway) - - **Cloudflare AI Gateway**: prompts for Account ID, Gateway ID, and `CLOUDFLARE_AI_GATEWAY_API_KEY`. - - More detail: [Cloudflare AI Gateway](/providers/cloudflare-ai-gateway) - - **MiniMax M2.1**: config is auto-written. - - More detail: [MiniMax](/providers/minimax) - - **Synthetic (Anthropic-compatible)**: prompts for `SYNTHETIC_API_KEY`. - - More detail: [Synthetic](/providers/synthetic) - - **Moonshot (Kimi K2)**: config is auto-written. - - **Kimi Coding**: config is auto-written. - - More detail: [Moonshot AI (Kimi + Kimi Coding)](/providers/moonshot) - - **Skip**: no auth configured yet. - - Pick a default model from detected options (or enter provider/model manually). - - Wizard runs a model check and warns if the configured model is unknown or missing auth. - - OAuth credentials live in `~/.openclaw/credentials/oauth.json`; auth profiles live in `~/.openclaw/agents//agent/auth-profiles.json` (API keys + OAuth). - - More detail: [/concepts/oauth](/concepts/oauth) - - 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. - - - - - Default `~/.openclaw/workspace` (configurable). - - Seeds the workspace files needed for the agent bootstrap ritual. - - Full workspace layout + backup guide: [Agent workspace](/concepts/agent-workspace) - - - - 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. - - - - [WhatsApp](/channels/whatsapp): optional QR login. - - [Telegram](/channels/telegram): bot token. - - [Discord](/channels/discord): bot token. - - [Google Chat](/channels/googlechat): service account JSON + webhook audience. - - [Mattermost](/channels/mattermost) (plugin): bot token + base URL. - - [Signal](/channels/signal): optional `signal-cli` install + account config. - - [BlueBubbles](/channels/bluebubbles): **recommended for iMessage**; server URL + password + webhook. - - [iMessage](/channels/imessage): legacy `imsg` CLI path + DB access. - - DM security: default is pairing. First DM sends a code; approve via `openclaw pairing approve ` or use allowlists. - - - - 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 ` 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**. - - - - Starts the Gateway (if needed) and runs `openclaw health`. - - Tip: `openclaw status --deep` adds gateway health probes to status output (requires a reachable gateway). - - - - 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). - - - - Summary + next steps, including iOS/Android/macOS apps for extra features. - - - - -If no GUI is detected, the wizard prints SSH port-forward instructions for the Control UI instead of opening a browser. -If the Control UI assets are missing, the wizard attempts to build them; fallback is `pnpm ui:build` (auto-installs UI deps). - - -## Remote mode - -Remote mode configures a local client to connect to a Gateway elsewhere. - - -Remote mode does **not** install or change anything on the remote host. - - -What you’ll set: - -- Remote Gateway URL (`ws://...`) -- Token if the remote Gateway requires auth (recommended) - - -- If the Gateway is loopback‑only, use SSH tunneling or a tailnet. -- Discovery hints: - - macOS: Bonjour (`dns-sd`) - - Linux: Avahi (`avahi-browse`) - - -## Add another agent - -Use `openclaw agents add ` 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-`. -- Add `bindings` to route inbound messages (the wizard can do this). -- Non-interactive flags: `--model`, `--agent-dir`, `--bind`, `--non-interactive`. - -## Non‑interactive mode - -Use `--non-interactive` to automate or script onboarding: - -```bash -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 -``` - -Add `--json` for a machine‑readable summary. - - - - ```bash - openclaw onboard --non-interactive \ - --mode local \ - --auth-choice gemini-api-key \ - --gemini-api-key "$GEMINI_API_KEY" \ - --gateway-port 18789 \ - --gateway-bind loopback - ``` - - - ```bash - openclaw onboard --non-interactive \ - --mode local \ - --auth-choice zai-api-key \ - --zai-api-key "$ZAI_API_KEY" \ - --gateway-port 18789 \ - --gateway-bind loopback - ``` - - - ```bash - 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 - ``` - - - ```bash - 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 - ``` - - - ```bash - openclaw onboard --non-interactive \ - --mode local \ - --auth-choice moonshot-api-key \ - --moonshot-api-key "$MOONSHOT_API_KEY" \ - --gateway-port 18789 \ - --gateway-bind loopback - ``` - - - ```bash - openclaw onboard --non-interactive \ - --mode local \ - --auth-choice synthetic-api-key \ - --synthetic-api-key "$SYNTHETIC_API_KEY" \ - --gateway-port 18789 \ - --gateway-bind loopback - ``` - - - ```bash - openclaw 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) example: - -```bash -openclaw 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//`. -- 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) -- `gateway.*` (mode, bind, auth, tailscale) -- `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` - -`openclaw agents add` writes `agents.list[]` and optional `bindings`. - -WhatsApp credentials go under `~/.openclaw/credentials/whatsapp//`. -Sessions are stored under `~/.openclaw/agents//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 +- CLI command reference: [`openclaw onboard`](/cli/onboard) - macOS app onboarding: [Onboarding](/start/onboarding) -- Config reference: [Gateway configuration](/gateway/configuration) -- 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) -- Skills: [Skills](/tools/skills), [Skills config](/tools/skills-config) +- Agent first-run ritual: [Agent Bootstrapping](/start/bootstrapping)