配置指南（macOS 应用）
适用范围
在以下情况使用此页面：
- 设计 macOS 配置助手
- 实现认证或身份设置
此文档描述当前的首次运行配置流程。目标是流畅的"第 0 天"体验：选择网关运行位置、连接认证、运行向导、让代理自我引导。
页面顺序（当前）
- 欢迎 + 安全提示
- 网关选择（本地 / 远程 / 稍后配置）
- 认证（Anthropic OAuth） — 仅本地
- 设置向导（网关驱动）
- 权限（TCC 提示）
- CLI（可选）
- 配置聊天（专用会话）
- 就绪
1) 本地 vs 远程
网关在哪里运行？
- 本地（此 Mac）：配置可以运行 OAuth 流程并在本地写入凭证。
- 远程（通过 SSH/Tailnet）：配置不在本地运行 OAuth；凭证必须存在于网关主机上。
- 稍后配置：跳过设置并让应用保持未配置状态。
网关认证提示：
- 向导现在即使对于环回也会生成令牌，因此本地 WS 客户端必须进行身份验证。
- 如果你禁用认证，任何本地进程都可以连接；仅在全信任的机器上使用。
- 对多机器访问或非环回绑定使用令牌。
2) 仅本地认证（Anthropic OAuth）
macOS 应用支持 Anthropic OAuth（Claude Pro/Max）。流程：
- 打开浏览器进行 OAuth（PKCE）
- 要求用户粘贴
code#state值 - 将凭证写入
~/.moltbot/credentials/oauth.json
其他提供商（OpenAI、自定义 API）目前通过环境变量或配置文件配置。
3) 设置向导（网关驱动）
应用可以运行与 CLI 相同的设置向导。这使得配置与网关端行为保持同步，并避免在 SwiftUI 中重复逻辑。
4) 权限
配置请求以下所需的 TCC 权限：
- 通知
- 辅助功能
- 屏幕录制
- 麦克风 / 语音识别
- 自动化（AppleScript）
5) CLI（可选）
应用可以通过 npm/pnpm 安装全局 moltbot CLI，以便终端工作流和 launchd 任务开箱即用。
6) 配置聊天（专用会话）
设置完成后，应用会打开一个专用的配置聊天会话，以便代理可以自我介绍并指导后续步骤。这将首次运行指导与正常对话分开。
代理引导仪式
在首次代理运行时，Moltbot 会引导一个工作空间（默认 ~/clawd）：
- 播种
AGENTS.md、BOOTSTRAP.md、IDENTITY.md、USER.md - 运行简短的问答仪式（一次一个问题）
- 将身份 + 偏好写入
IDENTITY.md、USER.md、SOUL.md - 完成后删除
BOOTSTRAP.md，使其只运行一次
可选：Gmail hooks（手动）
Gmail Pub/Sub 设置目前是一个手动步骤。使用：
moltbot webhooks gmail setup --account [email protected]详情请参见 /automation/gmail-pubsub。
远程模式说明
当网关在另一台机器上运行时，凭证和工作空间文件位于该主机上。如果你在远程模式下需要 OAuth，请在网关主机上创建：
~/.moltbot/credentials/oauth.json~/.moltbot/agents/<agentId>/agent/auth-profiles.json