mirror of
https://github.com/openclaw/openclaw.git
synced 2026-07-12 20:56:03 +00:00
2bc50d0656
* feat(crestodian): add live-tested structured inference setup (detect/activate gateway RPCs) * feat(macos): redesign onboarding around a verified Connect-your-AI step * docs: describe the verified AI onboarding step and gemini setup ladder entry * chore(macos): drop replaced OnboardingView+CrestodianSetup source * fix(macos): keep the AI-detect error card from pairing with an unproven empty-state claim * chore(protocol): regenerate Swift gateway models for crestodian.setup methods * test(crestodian): give setup-inference mocks explicit params for test-types lane * chore(i18n): sync native app string inventory for onboarding redesign * chore(i18n): sync native app string inventory for onboarding redesign
107 lines
4.4 KiB
Markdown
107 lines
4.4 KiB
Markdown
---
|
|
summary: "First-run setup 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"
|
|
---
|
|
|
|
The macOS app's first-run flow: pick where the Gateway runs, connect a
|
|
verified AI backend, grant permissions, and hand off to the agent's own
|
|
bootstrap ritual.
|
|
For CLI onboarding and a comparison of both 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>
|
|
|
|
Security trust model:
|
|
|
|
- By default, OpenClaw is a personal agent: one trusted operator boundary.
|
|
- Shared/multi-user setups need lock-down: split trust boundaries, keep tool access minimal, and follow [Security](/gateway/security).
|
|
- Local onboarding defaults new configs to `tools.profile: "coding"` so fresh setups keep filesystem/runtime tools without the unrestricted `full` profile.
|
|
- If hooks/webhooks or other untrusted content feeds are enabled, use a strong modern model tier and keep strict tool policy/sandboxing.
|
|
|
|
</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 configures auth and writes credentials locally.
|
|
- **Remote (over SSH/Tailnet):** onboarding does **not** configure local auth;
|
|
credentials must already exist on the gateway host. The remote gateway token
|
|
field stores the token the macOS app uses to connect to that Gateway;
|
|
existing `gateway.remote.token` SecretRef values are preserved until you
|
|
replace them.
|
|
- **Configure later:** skip setup and leave the app unconfigured.
|
|
|
|
<Tip>
|
|
**Gateway auth tip:**
|
|
|
|
- Gateway auth mode defaults to `token` even for loopback binds, so local WS clients must authenticate.
|
|
- Setting `gateway.auth.mode: "none"` lets any local process connect; use that only on fully trusted machines.
|
|
- Use a token for multi-machine access or non-loopback binds.
|
|
|
|
</Tip>
|
|
</Step>
|
|
<Step title="CLI">
|
|
Local setup installs the global `openclaw` CLI via npm, pnpm, or bun,
|
|
preferring npm first. Node remains the recommended runtime for the Gateway
|
|
itself. Existing compatible installations are reused.
|
|
</Step>
|
|
<Step title="Connect your AI">
|
|
Once the Gateway is ready, onboarding looks for AI access you already have:
|
|
a Claude Code, Codex, or Gemini CLI login, or `OPENAI_API_KEY` /
|
|
`ANTHROPIC_API_KEY`. The best option is tested with a real completion and
|
|
only saved after it answers; when a test fails the app automatically tries
|
|
the next option and shows why the previous one failed. If several options
|
|
are found you can switch between them before continuing.
|
|
|
|
If nothing is found (or nothing works), a manual step accepts an API key for
|
|
Anthropic, OpenAI, or Google, verifies it the same way, and stores it as an
|
|
auth profile. Next remains locked until one backend has passed its live test,
|
|
so the first agent chat can never start without working inference. The
|
|
Crestodian chat stays available from this page (and later under
|
|
Settings → Crestodian) for help in plain language.
|
|
|
|
Configure Later skips this step.
|
|
</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 for: Automation (AppleScript), Notifications, Accessibility, Screen Recording, Microphone, Speech Recognition, Camera, and Location.
|
|
|
|
</Step>
|
|
<Step title="Onboarding Chat (dedicated session)">
|
|
After setup, the app opens a separate agent onboarding chat so the agent can
|
|
introduce itself and guide next steps without mixing that exchange into the
|
|
normal conversation history. This follows the Crestodian setup conversation;
|
|
it does not replace it. See [Bootstrapping](/start/bootstrapping) for what
|
|
happens on the gateway host during the agent's first real turn.
|
|
</Step>
|
|
</Steps>
|
|
|
|
## Related
|
|
|
|
- [Onboarding overview](/start/onboarding-overview)
|
|
- [Getting started](/start/getting-started)
|