1
Approve macOS warning
2
Approve find local networks
3
Welcome and security notice
Read the security notice displayed and decide accordingly
- 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.
4
Local vs Remote
- 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.
5
CLI
Local setup reuses a compatible CLI installation or uses the bundled installer
to install
openclaw and Node in a private managed runtime. It does not require
a global npm, pnpm, or bun install.6
Connect your AI
If the connected Gateway already has a configured agent model, the app
verifies it with a real completion before opening the normal dashboard.
A configured model name alone does not skip verification. Fresh or incomplete
Gateways continue through provider setup.Once the Gateway is ready, onboarding looks 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
loaded in a reachable LM Studio or Ollama server. Detection runs on the
Gateway host, including when the macOS app connects to a Linux Gateway. The best
option is tested with a real completion and only saved
after it answers. If setup fails, the app shows the reason so you can retry or
choose another connection. If several options are found you can
switch between them before continuing. Automatic local discovery never pulls
or downloads a model. Ollama checks /api/ps for loaded models; an eligible
model that is only installed on disk requires explicit setup through
Choose connection → Local only. See Ollama.When a connection needs a runtime plugin, the app and dashboard show the
staged package’s source and capabilities, with integrity when available before installing or
enabling it. Review the details, then explicitly confirm acceptance to continue.
Declining, confirmed cancellation, or an interactive setup error stops that attempt without selecting another
inference route. You can retry or choose a different connection.The macOS setup sheet shows the selected provider and current activity with a
spinner while the Gateway works. Plugin installation does not estimate a
completion percentage. Review prompts and input controls appear when an answer
is needed; installation and the final live AI test stay in the same flow.After you choose Cancel, wait for confirmation. The Gateway may need to
finish an operation that has already reached its commit point. If cancellation
cannot be confirmed, the sheet says setup may still be running and lets you
retry Cancel.To use a Claude subscription when the Gateway host has no 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.Pi and OpenCode installs may be shown for context when they cannot be selected
as the reusable guided-setup inference route. They are whole-agent harnesses,
not setup inference routes; their session integrations require separate runtime
and plugin setup. Gemini CLI and Antigravity are not offered as detected setup
routes.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, xAI,
MiniMax Global and CN, and Chutes. Google is available through the supported AI
Studio API-key route. 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.
Continuing remains locked until one backend has passed, so the first agent
chat cannot start without working inference.7
Continue in the dashboard
After a new model passes its live check, native setup closes and opens guided
onboarding in the dashboard. OpenClaw helps configure the remaining workspace,
Gateway, channels, and other optional features, then hands you off to normal
agent chat. A verified pre-existing model opens the normal dashboard instead.Memory import is part of guided setup, not a separate native onboarding page.
For a local Gateway, supported sources include Claude Code auto-memory, Codex
consolidated memories, and Hermes memory files. Selected memories are copied
into the agent workspace under
memory/imports/ for indexed recall;
already-imported files are skipped. Import is optional and remains available
later under Settings → Import Memory, with per-file control.There is no separate native permissions walkthrough before this handoff. Grant
macOS access for the features you want to use from Settings → Permissions.
Available permissions include Automation (AppleScript), Notifications,
Accessibility, Screen Recording, Microphone, Speech Recognition, Camera, and
Location. See macOS permissions for grant and
recovery guidance.See Bootstrapping for what happens on the Gateway host
during the agent’s first real turn. OpenClaw remains available later under
Settings → OpenClaw.