Spaces:
Paused
Paused
File size: 3,414 Bytes
caea1dc | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 | ---
summary: "First-run onboarding flow for OpenClaw (macOS app)"
read_when:
- Designing the macOS onboarding assistant
- Implementing auth or identity setup
title: "Onboarding"
---
# Onboarding (macOS app)
This doc describes the **current** first‑run onboarding flow. The goal is a
smooth “day 0” experience: pick where the Gateway runs, connect auth, run the
wizard, and let the agent bootstrap itself.
## Page order (current)
1. Welcome + security notice
2. **Gateway selection** (Local / Remote / Configure later)
3. **Auth (Anthropic OAuth)** — local only
4. **Setup Wizard** (Gateway‑driven)
5. **Permissions** (TCC prompts)
6. **CLI** (optional)
7. **Onboarding chat** (dedicated session)
8. Ready
## 1) Welcome + security notice
Read the security notice displayed and decide accordingly.
## 2) Local vs Remote
Where does the **Gateway** run?
- **Local (this Mac):** onboarding can run OAuth flows and write credentials
locally.
- **Remote (over SSH/Tailnet):** onboarding does **not** run OAuth locally;
credentials must exist on the gateway host.
- **Configure later:** skip setup and leave the app unconfigured.
Gateway auth tip:
- The wizard now generates a **token** even for loopback, so local WS clients must authenticate.
- If you disable auth, any local process can connect; use that only on fully trusted machines.
- Use a **token** for multi‑machine access or non‑loopback binds.
## 3) Local-only auth (Anthropic OAuth)
The macOS app supports Anthropic OAuth (Claude Pro/Max). The flow:
- Opens the browser for OAuth (PKCE)
- Asks the user to paste the `code#state` value
- Writes credentials to `~/.openclaw/credentials/oauth.json`
Other providers (OpenAI, custom APIs) are configured via environment variables
or config files for now.
## 4) Setup Wizard (Gateway‑driven)
The app can run the same setup wizard as the CLI. This keeps onboarding in sync
with Gateway‑side behavior and avoids duplicating logic in SwiftUI.
## 5) Permissions
Onboarding requests TCC permissions needed for:
- Notifications
- Accessibility
- Screen Recording
- Microphone / Speech Recognition
- Automation (AppleScript)
## 6) CLI (optional)
The app can install the global `openclaw` CLI via npm/pnpm so terminal
workflows and launchd tasks work out of the box.
## 7) Onboarding chat (dedicated session)
After setup, the app opens a dedicated onboarding chat session so the agent can
introduce itself and guide next steps. This keeps first‑run guidance separate
from your normal conversation.
## Agent bootstrap ritual
On the first agent run, OpenClaw bootstraps a workspace (default `~/.openclaw/workspace`):
- Seeds `AGENTS.md`, `BOOTSTRAP.md`, `IDENTITY.md`, `USER.md`
- Runs a short Q&A ritual (one question at a time)
- Writes identity + preferences to `IDENTITY.md`, `USER.md`, `SOUL.md`
- Removes `BOOTSTRAP.md` when finished so it only runs once
## Optional: Gmail hooks (manual)
Gmail Pub/Sub setup is currently a manual step. Use:
```bash
openclaw webhooks gmail setup --account you@gmail.com
```
See [/automation/gmail-pubsub](/automation/gmail-pubsub) for details.
## Remote mode notes
When the Gateway runs on another machine, credentials and workspace files live
**on that host**. If you need OAuth in remote mode, create:
- `~/.openclaw/credentials/oauth.json`
- `~/.openclaw/agents/<agentId>/agent/auth-profiles.json`
on the gateway host.
|