{
  "title": "Onboarding (macOS app)",
  "content": "This doc describes the **current** first‑run onboarding flow. The goal is a\nsmooth “day 0” experience: pick where the Gateway runs, connect auth, run the\nwizard, and let the agent bootstrap itself.\n\n## Page order (current)\n\n1. Welcome + security notice\n2. **Gateway selection** (Local / Remote / Configure later)\n3. **Auth (Anthropic OAuth)** — local only\n4. **Setup Wizard** (Gateway‑driven)\n5. **Permissions** (TCC prompts)\n6. **CLI** (optional)\n7. **Onboarding chat** (dedicated session)\n8. Ready\n\n## 1) Welcome + security notice\n\nRead the security notice displayed and decide accordingly.\n\n## 2) Local vs Remote\n\nWhere does the **Gateway** run?\n\n* **Local (this Mac):** onboarding can run OAuth flows and write credentials\n  locally.\n* **Remote (over SSH/Tailnet):** onboarding does **not** run OAuth locally;\n  credentials must exist on the gateway host.\n* **Configure later:** skip setup and leave the app unconfigured.\n\n* The wizard now generates a **token** even for loopback, so local WS clients must authenticate.\n* If you disable auth, any local process can connect; use that only on fully trusted machines.\n* Use a **token** for multi‑machine access or non‑loopback binds.\n\n## 3) Local-only auth (Anthropic OAuth)\n\nThe macOS app supports Anthropic OAuth (Claude Pro/Max). The flow:\n\n* Opens the browser for OAuth (PKCE)\n* Asks the user to paste the `code#state` value\n* Writes credentials to `~/.openclaw/credentials/oauth.json`\n\nOther providers (OpenAI, custom APIs) are configured via environment variables\nor config files for now.\n\n## 4) Setup Wizard (Gateway‑driven)\n\nThe app can run the same setup wizard as the CLI. This keeps onboarding in sync\nwith Gateway‑side behavior and avoids duplicating logic in SwiftUI.\n\nOnboarding requests TCC permissions needed for:\n\n* Notifications\n* Accessibility\n* Screen Recording\n* Microphone / Speech Recognition\n* Automation (AppleScript)\n\nThe app can install the global `openclaw` CLI via npm/pnpm so terminal\nworkflows and launchd tasks work out of the box.\n\n## 7) Onboarding chat (dedicated session)\n\nAfter setup, the app opens a dedicated onboarding chat session so the agent can\nintroduce itself and guide next steps. This keeps first‑run guidance separate\nfrom your normal conversation.\n\n## Agent bootstrap ritual\n\nOn the first agent run, OpenClaw bootstraps a workspace (default `~/.openclaw/workspace`):\n\n* Seeds `AGENTS.md`, `BOOTSTRAP.md`, `IDENTITY.md`, `USER.md`\n* Runs a short Q\\&A ritual (one question at a time)\n* Writes identity + preferences to `IDENTITY.md`, `USER.md`, `SOUL.md`\n* Removes `BOOTSTRAP.md` when finished so it only runs once\n\n## Optional: Gmail hooks (manual)\n\nGmail Pub/Sub setup is currently a manual step. Use:\n\nSee [/automation/gmail-pubsub](/automation/gmail-pubsub) for details.\n\nWhen the Gateway runs on another machine, credentials and workspace files live\n**on that host**. If you need OAuth in remote mode, create:\n\n* `~/.openclaw/credentials/oauth.json`\n* `~/.openclaw/agents/<agentId>/agent/auth-profiles.json`",
  "code_samples": [],
  "headings": [
    {
      "level": "h2",
      "text": "Page order (current)",
      "id": "page-order-(current)"
    },
    {
      "level": "h2",
      "text": "1) Welcome + security notice",
      "id": "1)-welcome-+-security-notice"
    },
    {
      "level": "h2",
      "text": "2) Local vs Remote",
      "id": "2)-local-vs-remote"
    },
    {
      "level": "h2",
      "text": "3) Local-only auth (Anthropic OAuth)",
      "id": "3)-local-only-auth-(anthropic-oauth)"
    },
    {
      "level": "h2",
      "text": "4) Setup Wizard (Gateway‑driven)",
      "id": "4)-setup-wizard-(gateway‑driven)"
    },
    {
      "level": "h2",
      "text": "5) Permissions",
      "id": "5)-permissions"
    },
    {
      "level": "h2",
      "text": "6) CLI (optional)",
      "id": "6)-cli-(optional)"
    },
    {
      "level": "h2",
      "text": "7) Onboarding chat (dedicated session)",
      "id": "7)-onboarding-chat-(dedicated-session)"
    },
    {
      "level": "h2",
      "text": "Agent bootstrap ritual",
      "id": "agent-bootstrap-ritual"
    },
    {
      "level": "h2",
      "text": "Optional: Gmail hooks (manual)",
      "id": "optional:-gmail-hooks-(manual)"
    },
    {
      "level": "h2",
      "text": "Remote mode notes",
      "id": "remote-mode-notes"
    }
  ],
  "url": "llms-txt#onboarding-(macos-app)",
  "links": []
}