First-Run Flow
Onboarding
This page describes the first-run experience for the macOS app: decide where the Gateway runs, finish auth and permissions, install the CLI if needed and enter a dedicated onboarding chat. The goal is to turn first use into one continuous flow instead of a pile of settings.
First-Run Order
1. Welcome and safety notice
Make it clear up front that this is a system capable of touching real files, commands and chat channels, not just a toy chatbot.
2. Choose the Gateway location
Local mode can finish OAuth and credential writes on the current Mac. Remote mode only connects and does not create auth state on your behalf.
3. Model authentication
The current docs focus on local Anthropic auth, but other providers commonly use environment variables or config files.
4. Run the setup wizard
The app can reuse the same onboarding flow as the CLI so UI and Gateway logic do not split into two separate implementations.
5. Permissions and CLI
Handle notifications, accessibility, screen recording, microphone / speech recognition and automation in order, then optionally install the global CLI.
6. Onboarding chat
Finish inside a dedicated onboarding conversation so the agent can explain next steps without polluting your normal day-to-day context.
Important Notes
Remote mode does not create credentials locally
If the Gateway runs on another machine, the credentials and workspace also live there. Prepare OAuth or auth-profile files on the remote host itself.
The first agent run bootstraps the workspace
OpenClaw initializes files like AGENTS.md, BOOTSTRAP.md, IDENTITY.md and USER.md, then configures identity through a guided conversation.