mirror of
https://github.com/openclaw/openclaw.git
synced 2026-03-12 15:30:39 +00:00
3d7bc5958d
* add web search to onboarding flow * remove post onboarding step (now redundant) * post-onboarding nudge if no web search set up * address comments * fix test mocking * add enabled: false assertion to the no-key test * --skip-search cli flag * use provider that a user has a key for * add assertions, replace the duplicated switch blocks * test for quickstart fast-path with existing config key * address comments * cover quickstart falls through to key test * bring back key source * normalize secret inputs instead of direct string trimming * preserve enabled: false if it's already set * handle missing API keys in flow * doc updates * hasExistingKey to detect both plaintext strings and SecretRef objects * preserve enabled state only on the "keep current" paths * add test for preserving * better gate flows * guard against invalid provider values in config * Update src/commands/configure.wizard.ts Co-authored-by: greptile-apps[bot] <165735046+greptile-apps[bot]@users.noreply.github.com> * format fix * only mentions env var when it's actually available * search apiKey fields now typed as SecretInput * if no provider check if any search provider key is detectable * handle both kimi keys * remove .filter(Boolean) * do not disable web_search after user enables it * update resolveSearchProvider * fix(onboarding): skip search key prompt in ref mode * fix: add onboarding web search step (#34009) (thanks @kesku) --------- Co-authored-by: greptile-apps[bot] <165735046+greptile-apps[bot]@users.noreply.github.com> Co-authored-by: Shadow <hi@shadowing.dev>
5.6 KiB
5.6 KiB
summary, read_when, title, sidebarTitle
| summary | read_when | title | sidebarTitle | ||
|---|---|---|---|---|---|
| CLI onboarding wizard: guided setup for gateway, workspace, channels, and skills |
|
Onboarding Wizard (CLI) | Onboarding: 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.
openclaw onboard
To reconfigure later:
openclaw configure
openclaw agents add <name>
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) - Tool policy default for new local setups: `tools.profile: "messaging"` (existing explicit profile is preserved) - DM isolation default: local onboarding writes `session.dmScope: "per-channel-peer"` when unset. Details: [CLI Onboarding Reference](/start/wizard-cli-reference#outputs-and-internals) - 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 configures
Local mode (default) walks you through these steps:
- 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 refstores env-backed refs in auth profiles instead of plaintext API key values. In non-interactiverefmode, 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 (fileorexec), with a fast preflight validation before saving. - Workspace — Location for agent files (default
~/.openclaw/workspace). Seeds bootstrap files. - Gateway — Port, bind address, auth mode, Tailscale exposure.
In interactive token mode, choose default plaintext token storage or opt into SecretRef.
Non-interactive token SecretRef path:
--gateway-token-ref-env <ENV_VAR>. - Channels — WhatsApp, Telegram, Discord, Google Chat, Mattermost, Signal, BlueBubbles, or iMessage.
- Daemon — Installs a LaunchAgent (macOS) or systemd user unit (Linux/WSL2).
If token auth requires a token and
gateway.auth.tokenis SecretRef-managed, daemon install validates it but does not persist the resolved token into supervisor service environment metadata. If token auth requires a token and the configured token SecretRef is unresolved, daemon install is blocked with actionable guidance. If bothgateway.auth.tokenandgateway.auth.passwordare configured andgateway.auth.modeis unset, daemon install is blocked until mode is set explicitly. - Health check — Starts the Gateway and verifies it's running.
- Skills — Installs recommended skills and optional dependencies.
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 openclaw 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[].nameagents.list[].workspaceagents.list[].agentDir
Notes:
- Default workspaces follow
~/.openclaw/workspace-<agentId>. - Add
bindingsto 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.
Related docs
- CLI command reference:
openclaw onboard - Onboarding overview: Onboarding Overview
- macOS app onboarding: Onboarding
- Agent first-run ritual: Agent Bootstrapping