Onboarding (macOS app)

Open OpenClaw.app to set up a Gateway on this Mac and connect an AI model. The app includes its own runtime; you do not need to install Node or a package manager. If you already use OpenClaw, setup keeps your existing connection.

Automatic first run

On a fresh install, open the app and follow Setting up OpenClaw on this Mac:

1. The app prepares its runtime and starts a local Gateway.
2. The dashboard opens and connects available AI access.
3. A live AI test verifies the connection before guided setup continues.

An already configured model is kept. You can then set up optional features and start chatting. To choose the connection yourself, select Set up manually.

Existing configurations and saved connections keep their settings; setup does not automatically switch to a discovered Gateway. Older apps may open manual setup first; developer builds and Gateways without automatic setup support use it instead. Nix mode and background-only launches do not run automatic first setup.

If setup fails, the app opens the relevant manual step with the error visible. If you close setup early, reopen it from the app menu.

macOS prompts

These operating-system prompts can appear during setup; their timing can vary.

Approve macOS warning

The first time you open OpenClaw.app, macOS asks you to approve a downloaded app. Click Open to continue.

Approve find local networks

macOS may ask whether OpenClaw or bun may find devices on your local network. Bun is the runtime included with OpenClaw.app's bundled Gateway. Choose Allow when you want LAN discovery and access to a Gateway on another machine. Don't Allow can prevent discovery and local-network connections.

A separate firewall prompt may ask whether bun can accept incoming network connections. Allow permits incoming connections subject to your Gateway's bind and authentication settings; Don't Allow can block other devices from reaching this Mac's Gateway. These prompts do not change Gateway authentication or enable a LAN listener. You can revisit local-network and firewall permissions in macOS System Settings.

Manual setup

Choose Set up manually to use these steps. The app also opens them when automatic setup cannot finish. The screenshots show an earlier manual flow; your build may use different labels or layouts.

Read the security notice

OpenClaw is a personal agent designed for one trusted operator. For shared use, separate trust boundaries and limit tool access; see [Security](/gateway/security). Use a strong modern model and strict tool policy or sandboxing when enabling hooks, webhooks, or other untrusted content feeds.

Local setup defaults to tools.profile: "full" only if no profile is set. Existing profiles and tool policies stay unchanged. A full tool profile does not grant execution permissions. See Tool profiles. These rules apply to automatic setup too.

Choose where the Gateway runs

• This Mac (Local only): set up authentication and save credentials on this Mac.
• Remote (over SSH/Tailnet): connect to a Gateway that already has credentials on its host. The app does not configure local authentication. Its remote token field saves the connection token and preserves an existing gateway.remote.token SecretRef until you replace it.
• Configure later: leave the app unconfigured.

Prepare the local runtime

Wait for **Getting things ready** to finish. This step appears only when local runtime setup is needed. Connecting to an independently managed Gateway skips installation without taking over its CLI or service. See [Gateway on macOS](/platforms/mac/bundled-gateway#automatic-setup) for runtime details.

macOS may offer to install Command Line Tools when OpenClaw initializes Git in a new workspace. Git is optional; setup continues without it. Install the tools if you want to use Git.

Connect your AI

Choose a detected connection, sign in to a provider, or enter an API key or token. The manual picker waits for your choice before testing, installing, or saving anything. Setup must pass a live AI test before you can continue.

See AI connection options below for login reuse, local models, and custom endpoints.

Continue in the dashboard

A newly verified model opens guided setup for your workspace, Gateway, channels, and optional features, then agent chat. An already configured model opens the normal dashboard.

• Import memory (optional): choose files during guided setup or later in Settings → Import Memory. Local Gateways can import Claude Code, Codex, and Hermes memories into memory/imports/; previously imported files are skipped.
• Grant macOS access as needed: open Settings → This Mac → Permissions for features such as screen recording, microphone access, and automation. See macOS permissions for the full list and recovery steps.

See Bootstrapping for the agent's first turn. You can return to Settings → OpenClaw later.

AI connection options

The dashboard shows the selected connection and alternatives. Change models in its provider and model settings, or choose Connection… → Gateways to switch Gateways. AI setup always runs on the Gateway host, even when your Mac connects to a Linux Gateway.

Automatic selection

If no model is configured, automatic setup checks these sources in order:

1. Saved OpenClaw auth profiles.
2. Codex credentials in CODEX_HOME or ~/.codex on the Gateway host.
3. A Claude CLI login.
4. OPENAI_API_KEY, then ANTHROPIC_API_KEY.
5. Eligible loaded models in Ollama, LM Studio, or llama.cpp.

It tries at most four detected connections and saves the first model that passes a live completion test. Apple Foundation Models is a utility option, not a primary model.

If none works, setup installs or enables the official Codex plugin, then reuses a Codex login or offers ChatGPT sign-in. This is the only plugin capability approval automatic setup grants. If it fails, the dashboard shows the reason and lets you choose another connection.

Codex login and isolation

Choose whether to share your existing Codex state:

When automatic setup selects an existing Codex ChatGPT or API-key login, it uses Reuse. Without an existing login, the offered ChatGPT sign-in uses a separate home. To switch, choose Sign in separately on the setup card, or sign in with ChatGPT or an OpenAI API key in Models. Completing that sign-in selects the isolated home.

Choosing a Claude or Codex model does not automatically show native conversations in the sidebar. Enable conversation discovery separately if you want to browse them. For shared-home settings and authentication details, see Native Codex state.

Other connections

openclaw onboard --auth-choice custom-api-key

If AI setup stalls

• An earlier attempt may still be running: choose Check again to check its status without starting another activation. Wait for it to finish before replacing the connection.
• The wait ends without a confirmed result: setup returns to connection choices with the error visible. Retry that connection or choose another; it does not automatically retry detected credentials.
• You want to cancel: choose Cancel and wait for confirmation. If the sheet says setup may still be running, retry Cancel.

Related

• Onboarding overview
• Getting started