引導流程（macOS 應用程式）

本文件描述目前的首次啟動引導流程。目標是提供流暢的「第 0 天」體驗：選擇 Gateway 執行位置、連接驗證、執行嚮導，並讓 agent 自我啟動。

頁面順序（目前）

1. 歡迎頁面 + 安全性提醒
2. Gateway 選擇（本機 / 遠端 / 稍後設定）
3. 驗證（Anthropic OAuth） — 僅限本機
4. 設定嚮導（由 Gateway 驅動）
5. 權限（TCC 提示）
6. CLI（選用）
7. 引導對話（專屬 session）
8. 完成

1) 本機 vs 遠端

Gateway 要在哪裡執行？

• 本機（這台 Mac）： 引導可以執行 OAuth 流程並在本機寫入憑證。
• 遠端（透過 SSH/Tailnet）： 引導不會在本機執行 OAuth；憑證必須存在於 gateway 主機上。
• 稍後設定： 跳過設定，讓應用程式保持未設定狀態。

Gateway 驗證提示：

• 嚮導現在即使對 loopback 也會產生 token，因此本機 WS 客戶端必須驗證。
• 如果停用驗證，任何本機程序都可以連線；僅在完全信任的機器上使用。
• 對於多機器存取或非 loopback 繫結，請使用 token。

2) 本機專用驗證（Anthropic OAuth）

macOS 應用程式支援 Anthropic OAuth（Claude Pro/Max）。流程如下：

• 開啟瀏覽器進行 OAuth（PKCE）
• 要求使用者貼上 code#state 值
• 將憑證寫入 ~/.clawdbot/credentials/oauth.json

其他提供者（OpenAI、自訂 API）目前透過環境變數或設定檔進行設定。

3) 設定嚮導（由 Gateway 驅動）

應用程式可以執行與 CLI 相同的設定嚮導。這讓引導流程與 Gateway 端行為保持同步，避免在 SwiftUI 中重複邏輯。

4) 權限

引導會請求所需的 TCC 權限：

• 通知
• 輔助使用
• 螢幕錄製
• 麥克風 / 語音辨識
• 自動化（AppleScript）

5) CLI（選用）

應用程式可以透過 npm/pnpm 安裝全域 moltbot CLI，讓終端機工作流程和 launchd 任務可以直接使用。

6) 引導對話（專屬 session）

設定完成後，應用程式會開啟專屬的引導對話 session，讓 agent 可以自我介紹並引導後續步驟。這讓首次使用指南與一般對話分開。

Agent 啟動儀式

在 agent 首次執行時，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 you@gmail.com

詳見 /automation/gmail-pubsub。

遠端模式注意事項

當 Gateway 在另一台機器上執行時，憑證和工作區檔案位於該主機上。如果在遠端模式需要 OAuth，請建立：

• ~/.clawdbot/credentials/oauth.json

或使用 API key（存放在 ~/.clawdbot/credentials/anthropic.txt 等）並在設定中參照。