diff --git a/docs/assets/macos-onboarding/01-macos-warning.jpeg b/docs/assets/macos-onboarding/01-macos-warning.jpeg
new file mode 100644
index 000000000..255976fe5
Binary files /dev/null and b/docs/assets/macos-onboarding/01-macos-warning.jpeg differ
diff --git a/docs/assets/macos-onboarding/02-local-networks.jpeg b/docs/assets/macos-onboarding/02-local-networks.jpeg
new file mode 100644
index 000000000..0135e38f6
Binary files /dev/null and b/docs/assets/macos-onboarding/02-local-networks.jpeg differ
diff --git a/docs/assets/macos-onboarding/03-security-notice.png b/docs/assets/macos-onboarding/03-security-notice.png
new file mode 100644
index 000000000..ca0dac968
Binary files /dev/null and b/docs/assets/macos-onboarding/03-security-notice.png differ
diff --git a/docs/assets/macos-onboarding/04-choose-gateway.png b/docs/assets/macos-onboarding/04-choose-gateway.png
new file mode 100644
index 000000000..4e0233c22
Binary files /dev/null and b/docs/assets/macos-onboarding/04-choose-gateway.png differ
diff --git a/docs/assets/macos-onboarding/05-permissions.png b/docs/assets/macos-onboarding/05-permissions.png
new file mode 100644
index 000000000..910a5f8da
Binary files /dev/null and b/docs/assets/macos-onboarding/05-permissions.png differ
diff --git a/docs/docs.json b/docs/docs.json
index df6c2c100..ba963a71b 100644
--- a/docs/docs.json
+++ b/docs/docs.json
@@ -745,7 +745,7 @@
"start/getting-started",
{
"group": "Onboarding",
- "pages": ["start/wizard", "start/onboarding"]
+ "pages": ["start/wizard", "start/onboarding", "start/bootstrapping"]
},
"start/pairing"
]
diff --git a/docs/start/bootstrapping.md b/docs/start/bootstrapping.md
new file mode 100644
index 000000000..e3a284935
--- /dev/null
+++ b/docs/start/bootstrapping.md
@@ -0,0 +1,41 @@
+---
+summary: "Agent bootstrapping ritual that seeds the workspace and identity files"
+read_when:
+ - Understanding what happens on the first agent run
+ - Explaining where bootstrapping files live
+ - Debugging onboarding identity setup
+title: "Agent Bootstrapping"
+sidebarTitle: "Bootstrapping"
+---
+
+# Agent Bootstrapping
+
+Bootstrapping is the **first‑run** ritual that prepares an agent workspace and
+collects identity details. It happens after onboarding, when the agent starts
+for the first time.
+
+## What bootstrapping does
+
+On the first agent run, OpenClaw bootstraps the 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.
+
+## Where it runs
+
+Bootstrapping always runs on the **gateway host**. If the macOS app connects to
+a remote Gateway, the workspace and bootstrapping files live on that remote
+machine.
+
+
+When the Gateway runs on another machine, edit workspace files on the gateway
+host (for example, `user@gateway-host:~/.openclaw/workspace`).
+
+
+## Related docs
+
+- macOS app onboarding: [Onboarding](/start/onboarding)
+- Workspace layout: [Agent workspace](/concepts/agent-workspace)
diff --git a/docs/start/onboarding.md b/docs/start/onboarding.md
index 95b9ffee4..32a28d7c5 100644
--- a/docs/start/onboarding.md
+++ b/docs/start/onboarding.md
@@ -13,99 +13,67 @@ 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
+- **This Mac (Local only):** 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:
-
+
+**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:
+- Automation (AppleScript)
- 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//agent/auth-profiles.json`
-
-on the gateway host.
+- Microphone
+- Speech Recognition
+- Camera
+- Location
+
+
+ This step is optional
+ The app can install the global `openclaw` CLI via npm/pnpm so terminal
+ workflows and launchd tasks work out of the box.
+
+
+ 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. See [Bootstrapping](/start/bootstrapping) for
+ what happens on the gateway host during the first agent run.
+
+