本文档描述了当前的首次运行入门流程。目标是流畅的“第 0 天”体验：选择网关运行位置，连接认证，运行向导，并让代理引导自己。

1. 欢迎 + 安全提示
2. 网关选择 (本地 / 远程 / 稍后配置)
3. 认证 (Anthropic OAuth) — 仅限本地
4. 设置向导 (网关驱动)
5. 权限 (TCC 提示)
6. CLI (可选)
7. 入门聊天 (专用会话)
8. 就绪

网关在哪里运行？

• 本地 (此 Mac)： 入门向导可以运行 OAuth 流程并在本地写入凭据。
• 远程 (通过 SSH/Tailnet)： 入门向导不在本地运行 OAuth；凭据必须存在于网关主机上。
• 稍后配置： 跳过设置，保持应用未配置状态。

网关认证提示：

• 向导现在甚至为环回接口生成一个令牌，因此本地 WS 客户端必须进行身份验证。
• 如果你禁用认证，任何本地进程都可以连接；仅在完全受信任的机器上使用此功能。
• 对于多机器访问或非环回绑定，请使用令牌。

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

• 打开浏览器进行 OAuth (PKCE)
• 要求用户粘贴 code#state 值
• 将凭据写入 ~/.openclaw/credentials/oauth.json

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

该应用可以运行与 CLI 相同的设置向导。这保持了入门向导与网关侧行为的同步，并避免了在 SwiftUI 中重复逻辑。

入门向导请求所需的 TCC 权限：

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

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

设置完成后，应用会打开一个专用的入门聊天会话，以便代理自我介绍并指导后续步骤。这将首次运行指导与你的正常对话分开。

在第一次代理运行时，OpenClaw 引导一个工作区（默认为 ~/.openclaw/workspace）：

• 播种 AGENTS.md, BOOTSTRAP.md, IDENTITY.md, USER.md
• 运行一个简短的问答仪式（一次一个问题）
• 将身份 + 偏好写入 IDENTITY.md, USER.md, SOUL.md
• 完成后删除 BOOTSTRAP.md，使其只运行一次

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

openclaw webhooks gmail setup --account you@gmail.com

详情参见 /docs/automation/gmail-pubsub。

当网关在另一台机器上运行时，凭据和工作区文件位于该主机上。如果你需要在远程模式下使用 OAuth，请在网关主机上创建：

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