OpenClaw Setup Command Guide

`openclaw setup`

The openclaw setup command serves as the entry point for the system agent. When run on a system that is already configured, a bare openclaw setup invocation launches an interactive OpenClaw chat session. On a machine that has not been set up yet, it automatically transitions into a guided onboarding flow. For single requests, -m or --message can be used, while --baseline initializes configuration and workspace directories without launching the wizard.

The routing logic follows this sequence:

Any onboarding-related option (--wizard, --baseline, workspace, reset, non-interactive, flow, mode, Gateway, daemon, skip, import, remote, or auth) triggers onboarding in the same manner as openclaw onboard.
The system agent is executed when -m, --message, or --yes is specified.
When no routing option is given, a configured interactive system starts OpenClaw. A fresh system runs through onboarding instead. On a configured system, --json outputs the system overview even when no TTY is present; choosing an onboarding option preserves the JSON summary from onboarding.

During guided mode, --workspace <dir> designates the workspace offered to OpenClaw, and this choice is saved only once you confirm the proposal. On a fresh install, baseline, classic, and noninteractive setup persist the provided workspace through their standard flow. If an existing agent roster would be reassigned, the classic wizard asks for explicit confirmation, whereas noninteractive setup leaves the current fleet workspace intact and emits a warning.

On macOS or Linux, guided inference detection executes on the Gateway host. Both the CLI and the macOS app rely on the same Gateway-owned detector, which examines configured models, supported CLI logins, API-key environment variables, and any Ollama or LM Studio models already present. This automatic pass never downloads local models. After CLI and API-key candidates are tested, detected local runtimes undergo auto-testing; when multiple local models exist, OpenClaw selects the strongest tool-calling instruct family. The chosen candidate must complete a real request before its provider and model configuration get saved. Pi and OpenCode CLIs may also appear in the report for context when they cannot act as the reusable inference route for guided setup. Gemini CLI and Antigravity are excluded from the detected setup routes.

The setup command accepts the same onboarding flags as openclaw onboard, covering 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 reuse the same terminal hatch as openclaw onboard --tui, pass --tui. The full flag reference and non-interactive examples are available in Onboard and CLI automation. For the same inference-gated OpenClaw assistant, openclaw onboard --modern remains a compatibility entry point.

Note

Mutable config installs are the intended use case for openclaw setup. In Nix mode (OPENCLAW_NIX_MODE=1), OpenClaw blocks setup writes because Nix manages the config file. Refer to the first-party nix-openclaw Quick Start or the corresponding source config for another Nix package.

Options

Flag	Description
`-m, --message <text>`	Execute a single OpenClaw request.
`--yes`	Grant approval for persistent config changes during one `--message` request.
`--workspace <dir>`	Suggests a workspace; established fleets need classic confirmation and stay untouched when run noninteractively.
`--baseline`	Set up default config, workspace, and session directories without going through onboarding.
`--wizard`	Compel the interactive onboarding process.
`--tui`	Switch to the terminal hatch rather than the browser handoff.
`--non-interactive`	Carry out onboarding with no prompts.
`--accept-risk`	Confirm you accept the risk of full-system agent access; mandatory when `--non-interactive` is used.
`--mode <mode>`	Onboarding type: `local` or `remote`.
`--flow <flow>`	Onboarding sequence: `quickstart`, `advanced`, `manual`, or `import`.
`--reset`	Clear config, credentials, and sessions prior to onboarding (workspace only when `--reset-scope full` is specified).
`--reset-scope <scope>`	Reset target: `config`, `config+creds+sessions`, or `full`.
`--import-from <provider>`	Migration backend to execute during onboarding.
`--import-source <path>`	Agent home directory used as the source for `--import-from`.
`--import-secrets`	Bring in supported secrets while migrating during onboarding.
`--remote-url <url>`	WebSocket endpoint for the Remote Gateway.
`--remote-token <token>`	Remote Gateway token, if needed.
`--remote-password <password>`	Remote Gateway password, if needed.
`--json`	System as configured: OpenClaw summary. Onboarding path: summary of onboarding.

--classic and --non-interactive cannot be used together: classic launches the interactive wizard, whereas noninteractive setup follows the automation route. During interactive onboarding, --remote-url, --remote-token, and --remote-password fill in the remote Gateway step ahead of time and override any saved remote settings for that session. Supply either a token or a password, never both. Pointing to a new URL won't reuse stored credentials unless you also pass a fresh token or password. The credential stays hidden and adopts the wizard's chosen plaintext or SecretRef storage approach. --gateway-token, --gateway-token-ref-env, and --gateway-password set up a local Gateway and don't work in remote mode. For remote token SecretRefs, configure OPENCLAW_GATEWAY_TOKEN and pair --remote-token with --secret-input-mode ref.

Baseline mode

openclaw setup --baseline keeps the older baseline-only behavior: it builds the config, workspace, and session folders, then stops without triggering onboarding. It allows --workspace and harmless output flags, but rejects explicit onboarding, Gateway, auth, reset, or daemon options rather than ignoring them quietly. When an existing config is broken, baseline setup leaves it as is and tells 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>
openclaw setup --non-interactive --accept-risk --mode remote --remote-url wss://gateway-host:18789 --remote-password <password>

Notes

Within the interactive OpenClaw chat, configure skills, configure web search, and configure gateway trigger hosted setup procedures. Credential input is delegated to masked terminal assistants by open search wizard and open gateway wizard. Gateway configuration applies solely to the local environment; after making changes, restart using restart gateway in the chat interface or openclaw gateway restart from the command line. For details, refer to openclaw setup operations.
Detected local memory is transferred by import memory into the existing default agent workspace, leaving config, credentials, and skills untouched. Complete the initial onboarding process first; the chat reports both partial and failed copies rather than assuming everything succeeded.
Once the baseline setup is finished, execute openclaw onboard for the complete guided experience, openclaw configure for specific adjustments, or openclaw channels add to add channel accounts.
When Hermes state is present, the interactive onboarding flow may suggest migration automatically. A fresh setup is mandatory for import-based onboarding; use Migrate for dry-run plans, backups, and overwrite mode outside the onboarding context.