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
4.9 KiB
summary, read_when, title, sidebarTitle
| summary | read_when | title | sidebarTitle | ||
|---|---|---|---|---|---|
| First-run setup flow for OpenClaw (macOS app) |
|
Onboarding (macOS app) | 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.
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.
- Local onboarding defaults new configs to
tools.profile: "coding"so fresh setups keep filesystem/runtime tools without the unrestrictedfullprofile. - If hooks/webhooks or other untrusted content feeds are enabled, use a strong modern model tier and keep strict tool policy/sandboxing.
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.tokenSecretRef values are preserved until you replace them. - Configure later: skip setup and leave the app unconfigured.
- Gateway auth mode defaults to
tokeneven 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.
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.
Onboarding requests TCC permissions for: Automation (AppleScript), Notifications, Accessibility, Screen Recording, Microphone, Speech Recognition, Camera, and Location.
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.