OpenClaw CLI Setup Command Reference

`openclaw setup`

The system agent is accessed through openclaw setup. When the system is already configured, running openclaw setup by itself launches an interactive OpenClaw chat. On a system that hasn't been set up yet, it automatically starts the guided onboarding process. For a single request, use -m or --message, or run --baseline to create the configuration and workspace directories without going through the wizard.

The routing follows this order:

Any onboarding option (--wizard, --baseline, workspace, reset, non-interactive, flow, mode, Gateway, daemon, skip, import, remote, or auth options) triggers onboarding in the same way openclaw onboard does.
The system agent runs when you use -m, --message, or --yes.
If no routing option is given, a configured interactive system opens OpenClaw, while a fresh system starts onboarding. On a system that is already configured, --json shows the system overview even without a TTY present. An onboarding option instead returns the JSON summary from onboarding.

During guided mode, --workspace <dir> is the workspace that gets proposed to OpenClaw. It is only saved after you confirm that proposal. On a fresh install, baseline, classic, and noninteractive setup persist the supplied workspace through their standard flow. If an existing agent roster would need to be remapped, the classic wizard asks for explicit confirmation. Noninteractive setup keeps the current fleet workspace and issues a warning.

On macOS or Linux, guided inference detection runs on the Gateway host. Both the CLI and the macOS app use the same detector owned by the Gateway. This detector checks configured models, supported CLI logins, API key environment variables, and any Ollama or LM Studio models already installed. Local models are never downloaded during this automatic check. After CLI and API key candidates are evaluated, detected local runtimes are automatically tested. When multiple local models are available, OpenClaw picks the strongest tool calling instruct family. Before the provider and model configuration are saved, the chosen candidate must successfully answer a real completion. Installed Gemini, Antigravity, Pi, and OpenCode CLIs are also reported when they cannot serve as the reusable inference route for guided setup.

The same onboarding flags that openclaw onboard accepts are also supported by setup. These include 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). To use the same terminal hatch as openclaw onboard --tui, pass --tui. For the complete flag reference and non-interactive examples, see Onboard and CLI automation. The openclaw onboard --modern entry remains a compatibility option for the same inference gated OpenClaw assistant.

Note

For mutable config installs, use openclaw setup. In Nix mode (OPENCLAW_NIX_MODE=1), OpenClaw refuses setup writes because Nix manages the config file. Instead, use the first party nix-openclaw Quick Start or the equivalent source config for another Nix package.

Options

Flag	Description
`-m, --message <text>`	Execute a single OpenClaw request.
`--yes`	Authorize persistent configuration writes for one `--message` request.
`--workspace <dir>`	Workspace suggestion; existing fleets need classic confirmation and stay unchanged noninteractively.
`--baseline`	Set up config, workspace, and session folders without going through onboarding.
`--wizard`	Compel interactive onboarding.
`--tui`	Employ the terminal hatch as an alternative to the browser handoff.
`--non-interactive`	Perform onboarding with no prompts.
`--accept-risk`	Acknowledge the risk of full-system agent access; mandatory when using `--non-interactive`.
`--mode <mode>`	Onboarding type: `local` or `remote`.
`--flow <flow>`	Onboarding path: `quickstart`, `advanced`, `manual`, or `import`.
`--reset`	Remove config, credentials, and sessions before onboarding (workspace only with `--reset-scope full`).
`--reset-scope <scope>`	Reset scope: `config`, `config+creds+sessions`, or `full`.
`--import-from <provider>`	Migration provider to execute during onboarding.
`--import-source <path>`	Source agent home directory for `--import-from`.
`--import-secrets`	Import supported secrets while migrating during onboarding.
`--remote-url <url>`	Remote Gateway WebSocket address.
`--remote-token <token>`	Remote Gateway token (not required).
`--json`	Configured system: OpenClaw summary. Onboarding path: onboarding summary.

--classic and --non-interactive cannot be used together: classic starts the prompt-driven wizard, while noninteractive setup follows the automation path. During interactive onboarding, --remote-url and --remote-token fill in the remote Gateway step and override any stored remote values for that session. Changing the URL without also providing a token means stored credentials are not reused. The token stays masked and uses the wizard's chosen plaintext or SecretRef storage mode.

Baseline mode

openclaw setup --baseline keeps the earlier baseline-only functionality: it generates the config, workspace, and session directories, then stops without launching onboarding. It supports --workspace and harmless output flags, but rejects explicit onboarding, Gateway, auth, reset, or daemon options rather than ignoring them silently. When an existing config is broken, baseline setup leaves it in place and asks you to run openclaw doctor before trying again.

Examples

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 <token>

Notes

After baseline setup, use openclaw onboard for the complete guided process, openclaw configure for specific modifications, or openclaw channels add to add channel accounts.
If Hermes state is detected, interactive onboarding may offer migration automatically. Import onboarding needs a fresh setup; refer to Migrate for dry-run plans, backups, and overwrite mode outside onboarding.