Onboarding（macOS 应用）

本文档介绍当前的首次运行引导流程。目标是提供流畅的”第 0 天”体验：选择 Gateway 运行位置、连接认证、运行向导，让 Agent 自动完成初始化。

页面顺序（当前）

  1. 欢迎 + 安全提示
  2. Gateway 选择（本地 / 远程 / 稍后配置）
  3. 认证（Anthropic OAuth） — 仅限本地
  4. 设置向导（Gateway 驱动）
  5. 权限（TCC 提示）
  6. CLI（可选）
  7. Onboarding 对话（专用 Session）
  8. 就绪

1) 欢迎 + 安全提示

阅读显示的安全提示，并根据情况决定。

2) 本地 vs 远程

Gateway 运行在哪里？

  • 本地（这台 Mac）： 引导流程可以运行 OAuth 流程，并在本地写入凭证。
  • 远程（通过 SSH/Tailnet）： 引导流程不会在本地运行 OAuth；凭证必须存在于 Gateway 主机上。
  • 稍后配置： 跳过设置，让应用保持未配置状态。

Gateway 认证提示：

  • 向导现在即使对于本地回环也会生成 Token，所以本地 WS 客户端必须进行认证。
  • 如果你禁用认证，任何本地进程都可以连接；只在完全可信的机器上这样做。
  • 使用 Token 进行多机访问或非回环绑定。

3) 仅限本地的认证（Anthropic OAuth）

macOS 应用支持 Anthropic OAuth（Claude Pro/Max）。流程如下：

  • 打开浏览器进行 OAuth（PKCE）
  • 要求你粘贴 code#state 值
  • 将凭证写入 ~/.openclaw/credentials/oauth.json

其他 Provider（OpenAI、自定义 API）目前通过环境变量或配置文件进行配置。

4) 设置向导（Gateway 驱动）

应用可以运行与 CLI 相同的设置向导。这让引导流程与 Gateway 端行为保持同步，避免在 SwiftUI 中重复逻辑。

5) 权限

引导流程会请求以下所需的 TCC 权限：

  • 通知
  • 辅助功能
  • 屏幕录制
  • 麦克风 / 语音识别
  • 自动化（AppleScript）

6) CLI（可选）

应用可以通过 npm/pnpm 安装全局 openclaw CLI，这样终端工作流和 launchd 任务就能开箱即用。

7) Onboarding 对话（专用 Session）

设置完成后，应用会打开一个专用的引导对话 Session，让 Agent 介绍自己并引导后续步骤。这让首次运行指导与你的正常对话分开。

Agent Bootstrap 仪式

在 Agent 首次运行时，OpenClaw 会初始化一个 Workspace（默认 ~/.openclaw/workspace）：

  • 生成 AGENTS.md、BOOTSTRAP.md、IDENTITY.md、USER.md
  • 运行简短的问答仪式（一次一个问题）
  • 将身份 + 偏好写入 IDENTITY.md、USER.md、SOUL.md
  • 完成后删除 BOOTSTRAP.md，这样它只运行一次

可选：Gmail 钩子（手动）

Gmail Pub/Sub 设置目前是手动步骤。使用：

openclaw webhooks gmail setup --account [email protected]

详见 /automation/gmail-pubsub。

远程模式注意事项

当 Gateway 运行在另一台机器上时，凭证和 Workspace 文件存储在该主机上。如果你在远程模式下需要 OAuth，请在 Gateway 主机上创建：

  • ~/.openclaw/credentials/oauth.json
  • ~/.openclaw/agents/<agentId>/agent/auth-profiles.json