Onboarding (ứng dụng macOS)

Tài liệu này mô tả quy trình onboarding lần đầu hiện tại. Mục tiêu là mang đến trải nghiệm “ngày 0” mượt mà: chọn nơi chạy Gateway, kết nối xác thực, chạy wizard, và để Agent tự bootstrap.

Thứ tự các bước (hiện tại)

  1. Chào mừng + thông báo bảo mật
  2. Chọn Gateway (Local / Remote / Cấu hình sau)
  3. Xác thực (Anthropic OAuth) — chỉ cho local
  4. Setup Wizard (do Gateway điều khiển)
  5. Quyền truy cập (TCC prompts)
  6. CLI (tùy chọn)
  7. Onboarding chat (session riêng)
  8. Hoàn tất

1) Chào mừng + thông báo bảo mật

Đọc thông báo bảo mật hiển thị và quyết định phù hợp.

2) Local vs Remote

Gateway chạy ở đâu?

  • Local (máy Mac này): onboarding có thể chạy OAuth flows và ghi credentials vào máy local.
  • Remote (qua SSH/Tailnet): onboarding không chạy OAuth ở local; credentials phải tồn tại trên gateway host.
  • Cấu hình sau: bỏ qua setup và để app chưa cấu hình.

Mẹo về xác thực Gateway:

  • Wizard giờ tạo token ngay cả cho loopback, nên các WS clients local phải xác thực.
  • Nếu các bạn tắt auth, bất kỳ process local nào cũng có thể kết nối; chỉ dùng cách này trên máy hoàn toàn tin cậy.
  • Dùng token cho truy cập đa máy hoặc binds không phải loopback.

3) Xác thực chỉ local (Anthropic OAuth)

Ứng dụng macOS hỗ trợ Anthropic OAuth (Claude Pro/Max). Quy trình:

  • Mở browser để OAuth (PKCE)
  • Yêu cầu người dùng paste giá trị code#state
  • Ghi credentials vào ~/.openclaw/credentials/oauth.json

Các providers khác (OpenAI, custom APIs) hiện được cấu hình qua biến môi trường hoặc config files.

4) Setup Wizard (do Gateway điều khiển)

App có thể chạy cùng setup wizard như CLI. Điều này giữ onboarding đồng bộ với hành vi phía Gateway và tránh trùng lặp logic trong SwiftUI.

5) Quyền truy cập

Onboarding yêu cầu các quyền TCC cần thiết cho:

  • Notifications
  • Accessibility
  • Screen Recording
  • Microphone / Speech Recognition
  • Automation (AppleScript)

6) CLI (tùy chọn)

App có thể cài đặt CLI openclaw toàn cục qua npm/pnpm để các workflows terminal và launchd tasks hoạt động ngay.

7) Onboarding chat (session riêng)

Sau khi setup, app mở một onboarding chat session riêng để Agent có thể tự giới thiệu và hướng dẫn các bước tiếp theo. Điều này giữ hướng dẫn lần đầu tách biệt khỏi cuộc trò chuyện thông thường của các bạn.

Agent bootstrap ritual

Ở lần chạy Agent đầu tiên, OpenClaw bootstraps một workspace (mặc định ~/.openclaw/workspace):

  • Tạo các file AGENTS.md, BOOTSTRAP.md, IDENTITY.md, USER.md
  • Chạy một ritual Q&A ngắn (từng câu hỏi một)
  • Ghi identity + preferences vào IDENTITY.md, USER.md, SOUL.md
  • Xóa BOOTSTRAP.md khi hoàn tất để nó chỉ chạy một lần

Tùy chọn: Gmail hooks (thủ công)

Gmail Pub/Sub setup hiện là bước thủ công. Dùng:

openclaw webhooks gmail setup --account [email protected]

Xem /automation/gmail-pubsub để biết chi tiết.

Lưu ý về remote mode

Khi Gateway chạy trên máy khác, credentials và workspace files nằm trên host đó. Nếu các bạn cần OAuth trong remote mode, hãy tạo:

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

trên gateway host.