> ## Documentation Index
> Fetch the complete documentation index at: https://cryptoclawdocs.termix.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Onboarding (macOS App)

# Onboarding (macOS App)

This doc describes the **current** first‑run onboarding flow. The goal is a
smooth “day 0” experience: pick where the Gateway runs, connect auth, run the
wizard, and let the agent bootstrap itself.
For a general overview of onboarding paths, see [Onboarding Overview](/start/onboarding-overview).

<Steps>
  <Step title="Approve macOS warning">
    <Frame>
      <img src="https://mintcdn.com/termix/oGtzOLzqpC6VRWQv/assets/macos-onboarding/01-macos-warning.jpeg?fit=max&auto=format&n=oGtzOLzqpC6VRWQv&q=85&s=481bb41d0c5b0c06250d85e5a687d289" alt="" width="1132" height="818" data-path="assets/macos-onboarding/01-macos-warning.jpeg" />
    </Frame>
  </Step>

  <Step title="Approve find local networks">
    <Frame>
      <img src="https://mintcdn.com/termix/oGtzOLzqpC6VRWQv/assets/macos-onboarding/02-local-networks.jpeg?fit=max&auto=format&n=oGtzOLzqpC6VRWQv&q=85&s=cdc0a23ea84bdf5a0bd02be2eb570897" alt="" width="1132" height="818" data-path="assets/macos-onboarding/02-local-networks.jpeg" />
    </Frame>
  </Step>

  <Step title="Welcome and security notice">
    <Frame caption="Read the security notice displayed and decide accordingly">
      <img src="https://mintcdn.com/termix/oGtzOLzqpC6VRWQv/assets/macos-onboarding/03-security-notice.png?fit=max&auto=format&n=oGtzOLzqpC6VRWQv&q=85&s=81424c95c8c0813428032f770bc610aa" alt="" width="1262" height="1570" data-path="assets/macos-onboarding/03-security-notice.png" />
    </Frame>

    Security trust model:

    * By default, OpenClaw is a personal agent: one trusted operator boundary.
    * Shared/multi-user setups require lock-down (split trust boundaries, keep tool access minimal, and follow [Security](/gateway/security)).
    * Local onboarding now defaults new configs to `tools.profile: "messaging"` so broad runtime/filesystem tools are opt-in.
    * 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="https://mintcdn.com/termix/oGtzOLzqpC6VRWQv/assets/macos-onboarding/04-choose-gateway.png?fit=max&auto=format&n=oGtzOLzqpC6VRWQv&q=85&s=499400f670b32e370db5ea1cef3885d1" alt="" width="1262" height="1570" data-path="assets/macos-onboarding/04-choose-gateway.png" />
    </Frame>

    Where does the **Gateway** run?

    * **This Mac (Local only):** onboarding can configure auth and write credentials
      locally.
    * **Remote (over SSH/Tailnet):** onboarding does **not** configure local auth;
      credentials must exist on the gateway host.
    * **Configure later:** skip setup and leave the app unconfigured.

    <Tip>
      **Gateway auth tip:**

      * The wizard now generates a **token** even for loopback, so local WS clients must authenticate.
      * If you disable auth, any local process can connect; use that only on fully trusted machines.
      * Use a **token** for multi‑machine access or non‑loopback binds.
    </Tip>
  </Step>

  <Step title="Permissions">
    <Frame caption="Choose what permissions do you want to give OpenClaw">
      <img src="https://mintcdn.com/termix/oGtzOLzqpC6VRWQv/assets/macos-onboarding/05-permissions.png?fit=max&auto=format&n=oGtzOLzqpC6VRWQv&q=85&s=d5af125971b0e42ad5247631a959bdd8" alt="" width="1262" height="1570" data-path="assets/macos-onboarding/05-permissions.png" />
    </Frame>

    Onboarding requests TCC permissions needed for:

    * Automation (AppleScript)
    * Notifications
    * Accessibility
    * Screen Recording
    * Microphone
    * Speech Recognition
    * Camera
    * Location
  </Step>

  <Step title="CLI">
    <Info>This step is optional</Info>
    The app can install the global `openclaw` CLI via npm/pnpm so terminal
    workflows and launchd tasks work out of the box.
  </Step>

  <Step title="Onboarding Chat (dedicated session)">
    After setup, the app opens a dedicated onboarding chat session so the agent can
    introduce itself and guide next steps. This keeps first‑run guidance separate
    from your normal conversation. See [Bootstrapping](/start/bootstrapping) for
    what happens on the gateway host during the first agent run.
  </Step>
</Steps>