mirror of
https://github.com/openclaw/openclaw.git
synced 2026-07-18 05:31:38 +00:00
96f0983a85
* fix(crestodian): keep onboarding RPCs restart-safe * fix(profiles): isolate approval state migrations * fix(crestodian): bypass configured gateway setup * test(crestodian): type onboarding mocks * fix(onboarding): require inference before Crestodian * fix(onboarding): enforce verified inference handoff * fix(macos): reset setup on gateway endpoint edits * chore(i18n): refresh native source inventory * fix(gateway): keep socket on request cancellation * test(packaging): require workspace templates * fix(onboarding): bind setup to verified inference * fix(onboarding): align inference gate contracts * fix(crestodian): classify concurrent policy rejection * test(crestodian): expect registry restoration * fix(onboarding): bind setup to configured gateways * fix(codex): preserve startup phase deadlines * test(crestodian): match fail-closed policy ordering * test(onboarding): assert bound gateway handoff * fix(codex): bind runtime resolution to spawn cwd * test(crestodian): assert policy rejection order * fix(cli): preserve gateway routing across restarts * fix(macos): fail closed during gateway edits * test(macos): cover gateway route generation races * chore: keep release notes out of onboarding PR * fix(ci): refresh onboarding generated checks * style(swift): align gateway channel formatting * fix(ci): refresh plugin SDK surface budgets * fix(ci): resync native string inventory * refactor(swift): split gateway channel support * test(doctor): isolate plugin compatibility registry * test(macos): isolate gateway onboarding fixtures * test(macos): assert gateway lease health ordering * fix(codex): reconcile computer-use startup changes
115 lines
4.9 KiB
Markdown
115 lines
4.9 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">
|
|
A connected Gateway that already has a configured agent model skips this
|
|
page entirely and opens the normal agent UI. Crestodian and provider setup
|
|
only run for a fresh or incomplete Gateway.
|
|
|
|
Once the Gateway is ready, onboarding looks for AI access you already have:
|
|
a Claude Code or Codex 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.
|
|
|
|
Gemini CLI remains available for normal agents after setup, but it is not
|
|
offered here because it cannot enforce the tool-free inference probe.
|
|
|
|
If nothing is found (or nothing works), the manual key/token picker loads the
|
|
Gateway's active text-inference provider plugins instead of using a fixed app
|
|
list. The selected provider supplies its starter model and config; OpenClaw
|
|
verifies the credential with the same live test before storing its auth profile. Next
|
|
remains locked until one backend has passed, so the first agent chat cannot
|
|
start without working inference. After that live check passes, Crestodian becomes
|
|
available to help configure the remaining workspace, Gateway, channels, and
|
|
other optional features; it is also available later under Settings → Crestodian.
|
|
</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="Finish">
|
|
After inference passes, Crestodian owns the remaining optional setup and can
|
|
hand you off to the normal agent chat. Finishing the permission walkthrough
|
|
opens that same chat; the app does not create a workspace or launch a separate
|
|
agent setup conversation before Crestodian. 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)
|