OpenClaw macOS App Onboarding Guide

The first run of the macOS app walks you through choosing where the Gateway runs, linking a verified AI backend, granting system permissions, and then passing control to the agent's own initial setup sequence.

For instructions using the command line and a comparison of the two methods, see Onboarding Overview.

Approve macOS warning

Approve find local networks

Welcome and security notice

Security trust model:

OpenClaw operates as a personal agent by default, defining a single trusted operator boundary.
Multi-user or shared configurations require stricter controls: separate trust boundaries, minimal tool permissions, and adherence to Security.
Local onboarding applies the tools.profile: "coding" profile to new configurations, giving fresh setups filesystem and runtime tools without enabling the unrestricted full profile.
When hooks, webhooks, or other untrusted content feeds are active, use a capable modern model tier and enforce strict tool policies and sandboxing.

Local vs Remote

Where does the Gateway run?

This Mac (Local only): The onboarding process sets up authentication and writes credentials locally.
Remote (over SSH/Tailnet): Local authentication is not configured during onboarding; the gateway host must already have credentials in place. The remote gateway token field holds the token the macOS app uses to reach that Gateway, and existing gateway.remote.token SecretRef values remain unchanged unless you replace them.
Configure later: Skip all setup and leave the app in an unconfigured state.

Tip

Gateway auth tip:

The default Gateway auth mode is token, even for loopback binds, so local WebSocket clients must authenticate.

Setting gateway.auth.mode: "none" permits any local process to connect; only use this on fully trusted machines.

For multi-machine access or non-loopback binds, use a token.

CLI

Local setup installs the global openclaw CLI through npm, pnpm, or bun, with npm as the preferred option. Node remains the recommended runtime for the Gateway itself. Any compatible existing installation is reused.

Connect your AI

If the connected Gateway already has an agent model configured, this page is skipped entirely and the normal agent UI opens. OpenClaw and provider setup only occur for a fresh or incomplete Gateway.

Once the Gateway is ready, onboarding checks for AI access you already have: a Claude Code or Codex login, OPENAI_API_KEY / ANTHROPIC_API_KEY, or a tool-capable model with at least 16K of measured effective context already installed on a reachable Ollama or LM Studio server. Detection runs on the Gateway host, even when the macOS app connects to a Linux Gateway. The best candidate is tested with a real completion and saved only after it responds; if a test fails, the app automatically tries the next option and explains why the previous one failed. When multiple options are found, you can switch between them before proceeding. Automatic local discovery never pulls or downloads a model.

To use a Claude subscription when the Gateway host lacks a Claude CLI login, run claude setup-token on any machine with Claude Code installed, then paste the printed token as Anthropic setup-token under Connect with an API key or token.

Installed Gemini CLI, Antigravity, Pi, and OpenCode CLIs are shown for context when they cannot be selected as the reusable guided-setup inference route. Gemini and Antigravity cannot enforce the tool-free inference probe. Pi and OpenCode are whole-agent harnesses rather than setup inference routes; their session integrations require separate runtime and plugin setup.

You can also sign in through the provider's own OAuth or device-pairing flow. The built-in choices include OpenAI/ChatGPT, OpenRouter, GitHub Copilot, Google Gemini CLI, xAI, MiniMax Global and CN, and Chutes. The list comes from the Gateway's active text-inference provider plugins rather than a fixed app list, so another provider can opt in without adding provider-specific macOS code.

The manual key/token picker uses the same provider registry. In every route, the provider supplies its starter model and configuration; 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, OpenClaw becomes available to help configure the remaining workspace, Gateway, channels, and other optional features. When OpenClaw offers a short list of choices, the app shows native option cards; choosing one sends the selection, and Skip for now always leaves the choice optional. OpenClaw is also available later under Settings → OpenClaw.

Import memories (shown when detected)

For a local Gateway, onboarding checks the Mac for memories from supported AI tools: Claude Code auto-memory, Codex consolidated memories, and Hermes memory files. When any are found, this page lists each source with its memory count and lets you import the selected sources into the agent workspace under memory/imports/ for indexed recall. Already-imported files are skipped, and the page never appears when there is nothing to import. Skipping is safe; the dashboard's Memory import page offers the same import later with per-file control.

Permissions

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

Finish

After inference passes, OpenClaw 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 OpenClaw. See Bootstrapping for what happens on the gateway host during the agent's first real turn.