Skip to main content
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.
1

Approve macOS warning

2

Approve find local networks

3

Welcome and security notice

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 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.
4

Local vs Remote

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.
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.
5

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.
6

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), 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. The Crestodian chat stays available from this page (and later under Settings → Crestodian) for help in plain language.Configure Later skips this step.
7

Permissions

Onboarding requests TCC permissions for: Automation (AppleScript), Notifications, Accessibility, Screen Recording, Microphone, Speech Recognition, Camera, and Location.
8

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 for what happens on the gateway host during the agent’s first real turn.