入门:macOS App
macOS 应用的首次运行流程:选择 Gateway 的运行位置,安装任何缺失的本地运行时,并连接经过验证的 AI 后端。然后,应用会在仪表板中打开引导式入门,以进行可选设置并完成向你的智能体的交接。有关 CLI 入门以及两条路径的对比,请参阅 入门概述。
Tip
还没有该应用?下载适用于 macOS 的 OpenClaw,然后返回此处进行首次运行设置。
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.tokenSecretRef 值会保留,直到你替换它们。 - 稍后配置: 跳过设置并保持应用未配置。
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