上手引导
OpenClaw 首次运行上手引导流程（macOS 应用）。
本文档描述 **当前** 的首次运行上手引导流程。目标是获得顺滑的 “第 0 天” 体验：选择 Gateway 运行位置、连接鉴权、运行向导，并让 Agent 自动完成自举。
页面顺序（当前）
1. 欢迎页 + 安全提示
2. **Gateway 选择**（本机 / 远程 / 稍后配置）
3. **鉴权（Anthropic OAuth）** — 仅本机模式
4. **设置向导**（由 Gateway 驱动）
5. **权限**（TCC 授权弹窗）
6. **CLI**（可选）
7. **上手引导聊天**（专用会话）
8. 完成
1）欢迎页 + 安全提示
阅读界面展示的安全提示，并据此决定是否继续。
2）本机 vs 远程
Gateway 运行在哪里？
- **本机（当前 Mac）：** 上手引导可以运行 OAuth 流程，并把凭据写入本机。
- **远程（通过 SSH/Tailnet）：** 上手引导 **不会** 在本机运行 OAuth；凭据必须已存在于 gateway 主机上。
- **稍后配置：** 跳过设置，让应用保持未配置状态。
Gateway 鉴权提示：
- 现在即使是 loopback，也会由向导生成 **token**，因此本地 WS 客户端也必须认证。
- 如果你禁用鉴权，任意本地进程都可以连接；只应在完全可信的机器上使用。
- 多机器访问或非 loopback 绑定时，使用 **token**。
3）仅本机模式的鉴权（Anthropic OAuth）
macOS 应用支持 Anthropic OAuth（Claude Pro/Max）。流程如下：
- 打开浏览器进行 OAuth（PKCE）
- 要求用户粘贴 `code#state` 值
- 将凭据写入 `~/.openclaw/credentials/oauth.json`
其他提供商（OpenAI、自定义 API）目前仍通过环境变量或配置文件来配置。
4）设置向导（由 Gateway 驱动）
应用可以运行与 CLI 相同的设置向导。这样可以让上手引导与 Gateway 端行为保持一致，避免在 SwiftUI 中重复实现逻辑。
5）权限
上手引导会请求 OpenClaw 所需的 TCC 权限，包括：
- 通知
- 辅助功能（Accessibility）
- 屏幕录制
- 麦克风 / 语音识别
- 自动化（AppleScript）
6）CLI（可选）
应用可以通过 npm/pnpm 安装全局 `openclaw` CLI，让终端工作流与 launchd 任务开箱即用。
7）上手引导聊天（专用会话）
完成设置后，应用会打开一个专用的上手引导聊天会话，让 Agent 自我介绍并指导下一步。这可以把首次运行的引导与日常对话分离开来。
Agent 自举仪式
首次运行 Agent 时，OpenClaw 会自举一个工作区（默认 `~/.openclaw/workspace`）：
- 生成 `AGENTS.md`、`BOOTSTRAP.md`、`IDENTITY.md`、`USER.md`
- 进行一个简短的问答仪式（一次一个问题）
- 将身份与偏好写入 `IDENTITY.md`、`USER.md`、`SOUL.md`
- 完成后删除 `BOOTSTRAP.md`，确保它只运行一次
可选：Gmail hooks（手动）
Gmail Pub/Sub 目前仍需手动设置。使用：
openclaw webhooks gmail setup --account [email protected]
远程模式说明
当 Gateway 运行在另一台机器上时，凭据与工作区文件都位于 **那台主机** 上。如果你需要在远程模式下使用 OAuth，请在 gateway 主机上创建：
- `~/.openclaw/credentials/oauth.json`
- `<code2>~/.openclaw/agents/<agentId>/agent/auth-profiles.json</code2>`