LLM/moltbot
1
0
Fork 0
mirror of https://github.com/moltbot/moltbot.git synced 2026-03-08 06:54:24 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
92c4a2a29e8780af6c5ea249656ebb736d380d27
moltbot/docs/start/wizard.md

4.9 KiB
Raw Blame History

summary, read_when, title, sidebarTitle
summary read_when title sidebarTitle
CLI onboarding wizard: guided setup for gateway, workspace, channels, and skills
Running or configuring the onboarding wizard
Setting up a new machine
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
Fastest first chat: open the Control UI (no channel setup needed). Run `openclaw dashboard` and chat in the browser. Docs: [Dashboard](/web/dashboard).

To reconfigure later:

openclaw configure
openclaw agents add <name>
`--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) - 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:

  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.
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 `openclaw 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 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[].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.

Related docs