Onboarding

This document describes the **current** first-run onboarding flow. The goal is a smooth "Day 0" experience: choosing where the Gateway runs, authenticating, running the wizard, and letting the Agent automatically bootstrap itself.

1. Welcome + Safety Note

2. **Gateway Selection** (Local / Remote / Configure Later)

3. **Authentication (Anthropic OAuth)** — Local mode only

4. **Setup Wizard** (Driven by Gateway)

5. **Permissions** (TCC Authorization alerts)

6. **CLI** (Optional)

7. **Onboarding Chat** (Dedicated session)

8. Finished

Read the safety notes displayed and decide whether to proceed accordingly.

Where is the **Gateway** running?

- **Local (This Mac):** Onboarding can run the OAuth flow and write credentials locally.

- **Remote (via SSH/Tailnet):** Onboarding **will not** run OAuth locally; credentials must already exist on the gateway host.

- **Configure Later:** Skip setup and leave the app unconfigured.

Gateway Auth Tips:

- Now even loopback requires a **token** generated by the wizard, so local WS clients must also authenticate.

- If you disable auth, any local process can connect; only use this on fully trusted machines.

- Use a **token** for multi-machine access or non-loopback bindings.

The macOS app supports Anthropic OAuth (Claude Pro/Max). The flow is as follows:

- Open browser for OAuth (PKCE)

- Ask user to paste the `code#state` value

- Write credentials to `~/.openclaw/credentials/oauth.json`

Other providers (OpenAI, Custom API) are currently configured via environment variables or config files.

The app can run the same setup wizard as the CLI. This keeps onboarding consistent with Gateway-side behavior and avoids duplicating logic in SwiftUI.

Onboarding will request TCC permissions required by OpenClaw, including:

- Notifications

- Accessibility

- Screen Recording

- Microphone / Speech Recognition

- Automation (AppleScript)

The app can install the global `openclaw` CLI via npm/pnpm, making terminal workflows and launchd tasks work out of the box.

After completing the setup, the app opens a dedicated onboarding chat session where the Agent introduces itself and guides the next steps. This separates the first-run guidance from daily conversations.

When running the Agent for the first time, OpenClaw bootstraps a workspace (defaults to `~/.openclaw/workspace`):

- Generates `AGENTS.md`, `BOOTSTRAP.md`, `IDENTITY.md`, `USER.md`

- Performs a short Q&A ceremony (one question at a time)

- Writes identity and preferences to `IDENTITY.md`, `USER.md`, `SOUL.md`

- Deletes `BOOTSTRAP.md` upon completion to ensure it only runs once

Gmail Pub/Sub still requires manual setup for now. Use:

openclaw webhooks gmail setup --account [email protected]

See /automation/gmail-pubsub for details.

When the Gateway runs on another machine, credentials and workspace files are located on **that host**. If you need to use OAuth in remote mode, please create the following on the gateway host:

- `~/.openclaw/credentials/oauth.json`

- `<code2>~/.openclaw/agents/<agentId>/agent/auth-profiles.json</code2>`