跳转至

入门:macOS App

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

Tip

还没有该应用?下载适用于 macOS 的 OpenClaw,然后返回此处进行首次运行设置。

1. 批准 macOS 警告

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

macOS 对话框,询问是否打开下载的 OpenClaw 应用

2. 批准查找本地网络

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

macOS 对话框,询问 OpenClaw 是否可以查找本地网络上的设备

3. 欢迎与安全声明

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

OpenClaw 欢迎屏幕及其安全声明

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

安全信任模型:

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

4. 本地 vs 远程

Gateway 在哪里运行?

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

Tip

Gateway 认证提示:

  • 即使对于环回绑定,Gateway 认证模式也默认为 token,因此本地 WS 客户端必须进行认证。
  • 设置 gateway.auth.mode: "none" 可让任何本地进程连接;仅在完全受信任的机器上使用。
  • 对于多机器访问或非环回绑定,请使用令牌。

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,然后返回应用并刷新检测。

如果结果不确定,或者设置可能已经保存,应用会在检查 Gateway 期间保持替换设置流程处于阻止状态。再次检查会重复该检查,而不会启动另一次激活;它不会丢弃待处理尝试,也不会缩短其等待时间。如果等待后协调仍无法确认完成,应用会返回连接选择界面,并显示错误,而不是自动重试已检测到的凭据。重试该连接或选择其他连接以启动新的激活。

macOS 设置面板会在 Gateway 工作时显示所选提供商和当前活动,并带有加载指示器。插件安装不会估算完成百分比。当需要回答时,会显示审核提示和输入控件;安装和最终的实时 AI 测试保持在同一流程中。

选择取消后,请等待确认。Gateway 可能需要完成一个已达到提交点的操作。如果无法确认取消,面板会提示设置可能仍在运行,并允许你重试取消。

当 Gateway 主机没有 Claude CLI 登录时,若要使用 Claude 订阅,请在任何已安装 Claude Code 的机器上运行 claude setup-token,然后将打印的 token 粘贴到通过 API 密钥或 token 连接下的Anthropic setup-token。

当 Pi 和 OpenCode 安装无法作为可重用的引导设置推理路线选择时,可能会显示它们以提供上下文。它们是完整的智能体框架,而不是设置推理路线;其会话集成需要单独的运行时和插件设置。Gemini CLI 和 Antigravity 不作为检测到的设置路线提供。

你还可以通过提供商自己的 OAuth 或设备配对流程登录。内置选项包括 OpenAI/ChatGPT、OpenRouter、GitHub Copilot、xAI、MiniMax Global 和 CN 以及 Chutes。Google 可通过受支持的 AI Studio API 密钥路线使用。该列表来自 Gateway 的活动文本推理提供商插件,而不是固定的应用列表,因此其他提供商可以加入,而无需添加特定于提供商的 macOS 代码。

手动密钥/token 选择器使用相同的提供商注册表。在每条路线中,提供商都会提供其初始模型和配置。如果初始项是别名,OpenClaw 会测试并保存提供商的规范模型名称,同时保留初始项未替换的现有模型设置。 验证后,替换凭据会保持非活动状态,直到你接受激活此已保存的登录?。拒绝会保留当前连接和已保存的替换项。设置会保留验证期间进行的无关配置编辑。如果相同的连接设置发生变化,请审查它们并重试已保存的登录,而不是覆盖较新的设置。 在某个后端通过之前,继续操作保持锁定,因此没有可用的推理就无法启动第一个智能体聊天。

7. 在仪表板中继续

当新模型通过实时检查后,原生设置会关闭,并在仪表板中打开引导式入门。OpenClaw 会帮助配置剩余的工作区、Gateway、频道和其他可选功能,然后交接到普通智能体聊天。已验证的现有模型则会打开普通仪表板。

记忆导入是引导设置的一部分,而不是单独的原生入门页面。对于本地 Gateway,支持的来源包括 Claude Code 自动记忆、Codex 合并记忆和 Hermes 记忆文件。所选记忆会被复制到智能体工作区下的 memory/imports/ 中,用于索引召回;已导入的文件会被跳过。导入是可选的,之后仍可在设置 → 导入记忆下使用,并支持逐文件控制。

在此交接之前,没有单独的原生权限引导流程。请从设置 → 权限中授予你想要使用的功能的 macOS 访问权限。可用权限包括自动化(AppleScript)、通知、辅助功能、屏幕录制、麦克风、语音识别、摄像头和位置。有关授予和恢复指导,请参阅 macOS 权限。

有关智能体第一个真实回合期间 Gateway 主机上发生的事情,请参阅 引导启动。OpenClaw 之后仍可在设置 → OpenClaw下使用。

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw