mirror of
https://github.com/openclaw/openclaw.git
synced 2026-03-13 11:00:50 +00:00
c0befdee0b
* feat(onboard): add custom/local API configuration flow * ci: retry macos check * fix: expand custom API onboarding (#11106) (thanks @MackDing) * fix: refine custom endpoint detection (#11106) (thanks @MackDing) * fix: streamline custom endpoint onboarding (#11106) (thanks @MackDing) * fix: skip model picker for custom endpoint (#11106) (thanks @MackDing) * fix: avoid allowlist picker for custom endpoint (#11106) (thanks @MackDing) * Onboard: reuse shared fetch timeout helper (#11106) (thanks @MackDing) * Onboard: clarify default base URL name (#11106) (thanks @MackDing) --------- Co-authored-by: OpenClaw Contributor <contributor@openclaw.ai> Co-authored-by: Gustavo Madeira Santana <gumadeiras@gmail.com>
82 lines
2.6 KiB
Markdown
82 lines
2.6 KiB
Markdown
---
|
||
summary: "First-run onboarding flow for OpenClaw (macOS app)"
|
||
read_when:
|
||
- Designing the macOS onboarding assistant
|
||
- Implementing auth or identity setup
|
||
title: "Onboarding (macOS App)"
|
||
sidebarTitle: "Onboarding: macOS App"
|
||
---
|
||
|
||
# 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.
|
||
For a general overview of onboarding paths, see [Onboarding Overview](/start/onboarding-overview).
|
||
|
||
<Steps>
|
||
<Step title="Approve macOS warning">
|
||
<Frame>
|
||
<img src="/assets/macos-onboarding/01-macos-warning.jpeg" alt="" />
|
||
</Frame>
|
||
</Step>
|
||
<Step title="Approve find local networks">
|
||
<Frame>
|
||
<img src="/assets/macos-onboarding/02-local-networks.jpeg" alt="" />
|
||
</Frame>
|
||
</Step>
|
||
<Step title="Welcome and security notice">
|
||
<Frame caption="Read the security notice displayed and decide accordingly">
|
||
<img src="/assets/macos-onboarding/03-security-notice.png" alt="" />
|
||
</Frame>
|
||
</Step>
|
||
<Step title="Local vs Remote">
|
||
<Frame>
|
||
<img src="/assets/macos-onboarding/04-choose-gateway.png" alt="" />
|
||
</Frame>
|
||
|
||
Where does the **Gateway** run?
|
||
|
||
- **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.
|
||
|
||
<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.
|
||
</Tip>
|
||
</Step>
|
||
<Step title="Permissions">
|
||
<Frame caption="Choose what permissions do you want to give OpenClaw">
|
||
<img src="/assets/macos-onboarding/05-permissions.png" alt="" />
|
||
</Frame>
|
||
|
||
Onboarding requests TCC permissions needed for:
|
||
|
||
- Automation (AppleScript)
|
||
- Notifications
|
||
- Accessibility
|
||
- Screen Recording
|
||
- Microphone
|
||
- Speech Recognition
|
||
- Camera
|
||
- Location
|
||
|
||
</Step>
|
||
<Step title="CLI">
|
||
<Info>This step is optional</Info>
|
||
The app can install the global `openclaw` CLI via npm/pnpm so terminal
|
||
workflows and launchd tasks work out of the box.
|
||
</Step>
|
||
<Step title="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. See [Bootstrapping](/start/bootstrapping) for
|
||
what happens on the gateway host during the first agent run.
|
||
</Step>
|
||
</Steps>
|