--- summary: "CLI reference for `openclaw setup` (system-agent chat with onboarding fallback)" read_when: - You want to chat with OpenClaw for setup or repair - You're doing first-run setup with the onboarding wizard - You want to set the default workspace path - You need the baseline-only setup flag for scripts title: "Setup CLI" --- # `openclaw setup` `openclaw setup` is the system-agent entry point. On a configured system, bare `openclaw setup` opens an interactive OpenClaw chat. On a fresh system, it falls through to guided onboarding. Use `-m`/`--message` for one request or `--baseline` to initialize config/workspace folders without the wizard. Routing order: 1. Any onboarding option (`--wizard`, `--baseline`, workspace, reset, non-interactive, flow, mode, Gateway, daemon, skip, import, remote, or auth options) runs onboarding exactly as `openclaw onboard` does. 2. `-m`/`--message` or `--yes` runs the system agent. 3. With no routing option, a configured interactive system opens OpenClaw. A fresh system runs onboarding. On a configured system, `--json` prints the system overview even without a TTY; an onboarding option keeps onboarding's JSON summary. In guided mode, `--workspace ` is the workspace proposed to OpenClaw; it is persisted only after you approve that proposal. Baseline, classic, and noninteractive setup persist the supplied workspace through their normal flow on a fresh install. When an existing agent roster would be remapped, the classic wizard requires explicit confirmation; noninteractive setup keeps the current fleet workspace and prints a warning. Guided inference detection runs on the Gateway host on macOS or Linux. The CLI and macOS app call the same Gateway-owned detector, which checks configured models, supported CLI logins, API-key environment variables, and already installed Ollama or LM Studio models. Local models are never downloaded by this discovery pass. Both CLI onboarding and the macOS app wait for you to choose a connection before testing it. A failed or cancelled attempt never selects another provider automatically. Setup saves the credential, then sends one tool-free confirmation turn using the candidate settings in memory. It saves the provider and model configuration only after that turn succeeds. A failed connection keeps the credential and leaves the configuration unchanged. Choose the saved sign-in to retry without signing in again. Custom endpoint settings stay available for retry while the Gateway runs; after a restart, enter the endpoint settings again. Initial Claude Code and Codex detection checks executable versions without running auth-status commands or starting an app server. Readable Codex credentials are reported as stored evidence; the active login remains unverified during detection. Stored credentials do not receive verified-subscription priority over environment API keys. Pi and OpenCode CLIs may also be reported for context when they cannot serve as the reusable inference route for guided setup. Gemini CLI and Antigravity are not offered as detected setup routes. `setup` accepts the same onboarding flags as `openclaw onboard`, including auth (`--auth-choice`, `--token`, provider key flags), Gateway (`--gateway-port`, `--gateway-bind`, `--gateway-auth`, `--install-daemon`), Tailscale (`--tailscale`), reset (`--reset`, `--reset-scope`), flow (`--flow quickstart|advanced|manual|import`), and skip flags (`--skip-channels`, `--skip-skills`, `--skip-bootstrap`, `--skip-search`, `--skip-health`, `--skip-ui`, `--skip-hooks`). Pass `--tui` to use the same terminal hatch as `openclaw onboard --tui`. See [Onboard](/cli/onboard) and [CLI automation](/start/wizard-cli-automation) for the full flag reference and non-interactive examples. `openclaw onboard --modern` remains a compatibility entry for the same inference-gated OpenClaw assistant. Local onboarding generates a Gateway secret in token mode by default, without asking you to choose token or password. Existing password-mode configs are preserved. Use `--gateway-auth password` or `--gateway-password ` to choose a password explicitly; Tailscale Funnel still requires password mode. `openclaw setup` is for mutable config installs. In Nix mode (`OPENCLAW_NIX_MODE=1`) OpenClaw refuses setup writes because the config file is managed by Nix. Use the first-party [nix-openclaw Quick Start](https://github.com/openclaw/nix-openclaw#quick-start) or the equivalent source config for another Nix package. ## Options | Flag | Description | | ------------------------------ | ---------------------------------------------------------------------------------------------------- | | `-m, --message ` | Run one OpenClaw request. | | `--yes` | Approve persistent config writes for one `--message` request. | | `--workspace ` | Workspace proposal; existing fleets require classic confirmation and are preserved noninteractively. | | `--baseline` | Create baseline config/workspace/session folders without onboarding. | | `--wizard` | Force interactive onboarding. | | `--classic` | Run the classic multi-step onboarding wizard; not valid with `--non-interactive`. | | `--agent-name ` | Name for the first agent (default: `main`). | | `--tui` | Use the terminal hatch instead of the browser handoff. | | `--non-interactive` | Run onboarding without prompts. | | `--accept-risk` | Acknowledge full-system agent access risk; required with `--non-interactive`. | | `--mode ` | Onboarding mode: `local` or `remote`. | | `--flow ` | Onboard flow: `quickstart`, `advanced`, `manual`, or `import`. | | `--reset` | Reset config + credentials + sessions before onboarding (workspace only with `--reset-scope full`). | | `--reset-scope ` | Reset scope: `config`, `config+creds+sessions`, or `full`. | | `--import-from ` | Migration provider to run during onboarding. | | `--import-source ` | Source agent home for `--import-from`. | | `--import-secrets` | Import supported secrets during onboarding migration. | | `--remote-url ` | Remote Gateway WebSocket URL. | | `--remote-token ` | Remote Gateway token (optional). | | `--remote-password ` | Remote Gateway password (optional). | | `--json` | Configured system: OpenClaw overview. Onboarding route: onboarding summary. | `--classic` and `--non-interactive` are mutually exclusive: classic opens the prompted wizard, while noninteractive setup uses the automation path. In interactive onboarding, `--remote-url`, `--remote-token`, and `--remote-password` prefill the remote Gateway step and take precedence over stored remote values for that run. Pass either a token or a password, not both. Changing the URL does not reuse stored credentials unless you also provide a new token or password. The interactive step asks for one **Gateway secret** and stores it as `gateway.remote.token`; either field is accepted by the Gateway. The credential remains masked and uses the wizard's selected plaintext or SecretRef storage mode. `--gateway-token`, `--gateway-token-ref-env`, and `--gateway-password` configure a local Gateway and are not valid in remote mode. For remote token SecretRefs, set `OPENCLAW_GATEWAY_TOKEN` and use `--remote-token` with `--secret-input-mode ref`. ### Baseline mode `openclaw setup --baseline` preserves the older baseline-only behavior: it creates the config, workspace, and session directories, then exits without running onboarding. It accepts `--workspace` and harmless output controls, but rejects explicit onboarding, Gateway, auth, reset, or daemon options instead of silently ignoring them. If an existing config is invalid, baseline setup preserves it and asks you to run `openclaw doctor` before retrying. ## Examples ```bash openclaw setup openclaw setup -m "status" openclaw setup -m "restart gateway" --yes openclaw setup --json openclaw setup --wizard openclaw setup --baseline openclaw setup --workspace ~/.openclaw/workspace openclaw setup --import-from hermes --import-source ~/.hermes openclaw setup --non-interactive --accept-risk --mode remote --remote-url wss://gateway-host:18789 --remote-token openclaw setup --non-interactive --accept-risk --mode remote --remote-url wss://gateway-host:18789 --remote-password ``` ## Notes - Inside the interactive OpenClaw chat, `configure skills`, `configure web search`, and `configure gateway` run hosted setup flows. `open search wizard` and `open gateway wizard` hand credential entry to masked terminal wizards. Gateway setup is local-only and config-only; restart afterward with `restart gateway` in chat or `openclaw gateway restart` in the terminal. See [`openclaw setup` operations](/cli/openclaw#operations-and-approval). - `import memory` copies detected local memory into the existing default agent workspace without importing config, credentials, or skills. Finish onboarding first; the chat reports partial and failed copies instead of assuming success. - After baseline setup, run `openclaw onboard` for the full guided journey, `openclaw configure` for targeted changes, or `openclaw channels add` to add channel accounts. - If Hermes state is detected, interactive onboarding can offer migration automatically. Import onboarding requires a fresh setup; use [Migrate](/cli/migrate) for dry-run plans, backups, and overwrite mode outside onboarding. ## Related - [CLI reference](/cli) - [Onboard](/cli/onboard) - [Onboarding (CLI)](/start/wizard) - [Getting started](/start/getting-started) - [Install overview](/install)