入门：macOS App

macOS 应用的首次运行流程：选择 Gateway 的运行位置，安装任何缺失的本地运行时，并连接经过验证的 AI 后端。然后，应用会在仪表板中打开引导式入门，以进行可选设置并完成向你的智能体的交接。有关 CLI 入门以及两条路径的对比，请参阅 入门概述。

1. 批准 macOS 警告

首次打开 OpenClaw.app 时，macOS 会要求你批准下载的应用。点击 打开 以继续。

2. 批准查找本地网络

随后，macOS 会询问 OpenClaw 是否可以查找本地网络上的设备。点击 允许。应用会使用此权限来连接另一台机器上的 Gateway。

3. 欢迎与安全声明

应用会在欢迎屏幕上显示安全声明。请阅读该声明，并在接受以下信任模型后继续。

阅读所显示的安全声明并据此决定

安全信任模型：

• 默认情况下，OpenClaw 是一个个人智能体：一个受信任的操作者边界。
• 共享/多用户设置需要锁定：拆分信任边界，保持工具访问权限最小化，并遵循 安全。
• 本地入门在未配置配置文件时选择 tools.profile: "full"，并保留显式配置文件和其他工具策略。完整的工具选择不会授予执行权限。请参阅 工具配置文件。
• 如果启用了 hooks/webhooks 或其他不受信任的内容源，请使用强大的现代模型层级，并保持严格的工具策略/沙箱。

4. 本地 vs 远程

Gateway 在哪里运行？

• 此 Mac（仅本地）： 入门会配置认证并在本地写入凭据。
• 远程（通过 SSH/Tailnet）： 入门不会配置本地认证；凭据必须已存在于网关主机上。远程网关令牌字段存储 macOS 应用用于连接该 Gateway 的令牌；现有的 gateway.remote.token SecretRef 值会保留，直到你替换它们。
• 稍后配置： 跳过设置并保持应用未配置。

5. CLI

本地设置会复用兼容的 CLI 安装，或使用捆绑的安装程序在私有托管运行时中安装 openclaw 和 Node。它不需要全局 npm、pnpm 或 bun 安装。

附加到独立管理的本地 Gateway 会跳过 CLI 安装，并直接进入 AI 检查，而不会接管其 CLI 或服务安装。请参阅 macOS 上的 Gateway。

6. 连接你的 AI

如果连接的 Gateway 已配置了智能体模型，它会显示为 当前模型。选择它以通过真实的补全请求验证该确切路由，并打开正常仪表板。打开入门不会测试现有路由或选择其他提供商。

Gateway 就绪后，入门会查找你已有的 AI 访问权限：Claude Code 或 Codex 登录、OPENAI_API_KEY / ANTHROPIC_API_KEY，或者已在可访问的 LM Studio 或 Ollama 服务器中加载的、具有至少 16K 实测有效上下文的具备工具能力的模型。检测在 Gateway 主机上运行，包括当 macOS 应用连接到 Linux Gateway 时。检测仅呈现选项：它不会测试、激活、安装或保存任何候选。

在 OpenClaw 保存任何返回的凭据并运行一轮不使用工具的确认之前，选择你想要的连接。它仅在成功后才激活该连接。特别是，现有的 Codex 订阅绝不会被自动选择。

如果设置失败，应用会保持详细原因可见，以便你可以重试或选择其他连接。本地发现绝不会拉取或下载模型。Ollama 会检查 /api/ps 以获取已加载的模型；仅在磁盘上安装的合格模型需要通过 选择连接 → 仅本地 进行显式设置。请参阅 Ollama。

提供商选择器由已安装的清单和 OpenClaw 的官方提供商插件目录构建，因此诸如 Meta 之类的可安装提供商会出现在其插件存在之前。当连接需要运行时插件时，应用和仪表板会显示暂存包的来源和功能，并在安装或启用之前提供可用的完整性信息，包括经过验证的第一方包。查看详细信息，然后明确确认接受以继续。拒绝或确认取消会停止该尝试，而不会选择其他推理路由。

如果确认轮次失败，应用会显示失败原因并保留已保存的凭据。在 模型设置 中选择已保存的登录信息以重试，无需再次登录。为该尝试安装的运行时插件会保留。

全新安装还会询问现有的原生提供商对话是否应出现在侧边栏中。这是就地发现，而不是转录复制，并且在选中之前处于关闭状态。关闭它会为可用的原生目录插件持久化 sessionCatalog.enabled=false；现有的升级安装会保持其当前行为。

对于本地 Gateway 上的自定义 OpenAI 或 Anthropic 兼容端点，请选择 自定义 OpenAI/Anthropic 兼容端点，并完成由 Gateway 提供的向导。当 Gateway 为远程时，Mac 不会收集该主机的密钥；请在 Gateway 主机上运行 openclaw onboard --auth-choice custom-api-key，然后返回应用并刷新检测。

If the result is uncertain or settings may already have been saved, the app keeps replacement setup blocked while it checks the Gateway. 再次检查 repeats that check without starting another activation; it does not discard the pending attempt or shorten its wait. If reconciliation still cannot confirm completion after the wait, the app returns to connection choices with the error visible instead of automatically retrying a detected credential. Retry that connection or choose another one to start a new activation.

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 取消, 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 取消.

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 使用 API 密钥或 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. If the starter is an alias, OpenClaw tests and saves the provider's canonical model name while preserving existing model settings that the starter does not replace. A replacement credential stays inactive until you accept 激活此已保存的 登录？ after verification. Declining keeps your current connection and the saved replacement. Setup preserves unrelated configuration edits made during verification. If the same connection settings change, review them and retry the saved sign-in instead of overwriting the newer settings. Continuing remains locked until one backend has passed, so the first agent chat cannot start without working inference.

7. 在仪表板中继续

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 设置 → 导入内存, 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 设置 → 权限. Available permissions include Automation (AppleScript), Notifications, Accessibility, Screen Recording, Microphone, Speech Recognition, Camera, and Location. See macOS 权限 for grant and recovery guidance.

See 引导 for what happens on the Gateway host during the agent's first real turn. OpenClaw remains available later under 设置 → OpenClaw.

相关¶

• 入门概览
• 快速开始