# macOS Onboarding

## Overview

This documentation describes the first-run onboarding experience for the OpenClaw macOS application. The process guides users through initial setup in eight sequential steps, culminating in a dedicated onboarding chat session.

## Key Setup Stages

The onboarding flow progresses through:
1. Welcome/security notice
2. Gateway location selection
3. Authentication
4. Setup wizard execution
5. System permissions requests
6. Optional CLI installation
7. Introductory agent chat session

## Gateway Configuration Options

Users can choose where the Gateway runs:

- **Local (this Mac)**: Allows OAuth flows and local credential storage
- **Remote (over SSH/Tailnet)**: Requires pre-existing credentials on the gateway host
- **Defer**: Lets users skip configuration entirely

## Authentication Details

For local setups with Anthropic, the process involves browser-based OAuth using PKCE flow. Users authenticate and credentials are stored at `~/.openclaw/credentials/oauth.json`. Other providers require environment variables or config files.

## System Permissions

The app requests macOS permissions for:
- Notifications
- Accessibility
- Screen recording
- Microphone/speech recognition
- AppleScript automation

## Agent Bootstrapping

Upon first run, the system initializes a workspace at `~/.openclaw/workspace` and seeds configuration files. An interactive Q&A ritual gathers user preferences before the bootstrap process completes.

## Additional Setup

Gmail webhook integration requires manual CLI commands, while remote Gateway setups need credentials pre-configured on the host machine.