openclaw/docs/start/onboarding.md

summary, read_when, title, sidebarTitle

summary	read_when	title	sidebarTitle
First-run setup flow for OpenClaw (macOS app)	Designing the macOS onboarding assistant Implementing auth or identity setup	Onboarding (macOS app)	Onboarding: macOS App

The macOS app's first-run flow: pick where the Gateway runs, complete local setup through a Crestodian conversation, grant permissions, and hand off to the agent's own bootstrap ritual. For CLI onboarding and a comparison of both paths, see Onboarding Overview.

Security trust model:

• By default, OpenClaw is a personal agent: one trusted operator boundary.
• Shared/multi-user setups need lock-down: split trust boundaries, keep tool access minimal, and follow Security.
• Local onboarding defaults new configs to tools.profile: "coding" so fresh setups keep filesystem/runtime tools without the unrestricted full profile.
• If hooks/webhooks or other untrusted content feeds are enabled, use a strong modern model tier and keep strict tool policy/sandboxing.

Where does the Gateway run?

• This Mac (Local only): onboarding configures auth and writes credentials locally.
• Remote (over SSH/Tailnet): onboarding does not configure local auth; credentials must already exist on the gateway host. The remote gateway token field stores the token the macOS app uses to connect to that Gateway; existing gateway.remote.token SecretRef values are preserved until you replace them.
• Configure later: skip setup and leave the app unconfigured.

**Gateway auth tip:**

• Gateway auth mode defaults to token even for loopback binds, so local WS clients must authenticate.
• Setting gateway.auth.mode: "none" lets any local process connect; use that only on fully trusted machines.
• Use a token for multi-machine access or non-loopback binds.

Local setup installs the global `openclaw` CLI via npm, pnpm, or bun, preferring npm first. Node remains the recommended runtime for the Gateway itself. Existing compatible installations are reused. Local setup opens a dedicated conversation with Crestodian after the Gateway is ready. Crestodian detects an existing Claude Code or Codex login and supported API keys, proposes the workspace and configuration, then waits for approval before writing anything. Next remains locked until the conversation has authored setup state. Credential prompts use masked input; after an ambiguous transport failure, restart the setup conversation instead of replaying the previous turn.

Remote and Configure Later flows skip this local setup conversation.

Onboarding requests TCC permissions for: Automation (AppleScript), Notifications, Accessibility, Screen Recording, Microphone, Speech Recognition, Camera, and Location.

After setup, the app opens a separate agent onboarding chat so the agent can introduce itself and guide next steps without mixing that exchange into the normal conversation history. This follows the Crestodian setup conversation; it does not replace it. See [Bootstrapping](/start/bootstrapping) for what happens on the gateway host during the agent's first real turn.

Related

• Onboarding overview
• Getting started