온보딩 (macOS 앱)
이 문서는 현재 첫 실행 온보딩 플로우를 설명합니다. 목표는 원활한 "0일차" 경험입니다: Gateway가 실행될 위치를 선택하고, 인증을 연결하고, 마법사를 실행하고, 에이전트가 스스로 부트스트랩하도록 합니다.
페이지 순서 (현재)
- 환영 + 보안 공지
- Gateway 선택 (Local / Remote / 나중에 구성)
- Auth (Anthropic OAuth) — 로컬만 해당
- Setup Wizard (Gateway 주도)
- 권한 (TCC 프롬프트)
- CLI (선택사항)
- 온보딩 채팅 (전용 세션)
- 준비 완료
1) Local vs Remote
Gateway는 어디에서 실행됩니까?
- Local (this Mac): 온보딩은 OAuth 플로우를 실행하고 자격 증명을 로컬에 작성할 수 있습니다.
- Remote (SSH/Tailnet을 통해): 온보딩은 로컬에서 OAuth를 실행하지 않습니다; 자격 증명이 gateway 호스트에 존재해야 합니다.
- 나중에 구성: 설정을 건너뛰고 앱을 구성하지 않은 상태로 둡니다.
Gateway 인증 팁:
- 마법사는 이제 루프백에서도 토큰을 생성하므로, 로컬 WS 클라이언트가 인증해야 합니다.
- 인증을 비활성화하면, 모든 로컬 프로세스가 연결할 수 있습니다; 완전히 신뢰할 수 있는 머신에서만 사용하세요.
- 다중 머신 액세스 또는 루프백이 아닌 바인드에는 토큰을 사용하세요.
2) 로컬 전용 인증 (Anthropic OAuth)
macOS 앱은 Anthropic OAuth (Claude Pro/Max)를 지원합니다. 플로우:
- OAuth를 위한 브라우저 열기 (PKCE)
- 사용자에게 code#state 값 붙여넣기 요청
- ~/.openclaw/credentials/oauth.json에 자격 증명 작성
다른 제공자 (OpenAI, 커스텀 API)는 현재 환경 변수 또는 구성 파일을 통해 구성됩니다.
3) Setup Wizard (Gateway 주도)
앱은 CLI와 동일한 설정 마법사를 실행할 수 있습니다. 이는 온보딩을 Gateway 측 동작과 동기화하고 SwiftUI에서 로직을 복제하는 것을 방지합니다.
4) 권한
온보딩은 다음에 필요한 TCC 권한을 요청합니다:
- 알림
- 접근성
- 화면 녹화
- 마이크 / Speech Recognition
- Automation (AppleScript)
5) CLI (선택사항)
앱은 npm/pnpm을 통해 전역 openclaw CLI를 설치할 수 있으므로 터미널 워크플로우와 launchd 작업이 즉시 작동합니다.
6) 온보딩 채팅 (전용 세션)
설정 후, 앱은 전용 온보딩 채팅 세션을 열어 에이전트가 자신을 소개하고 다음 단계를 안내할 수 있도록 합니다. 이는 첫 실행 가이드를 일반 대화와 분리합니다.
에이전트 부트스트랩 의식
첫 번째 에이전트 실행 시, OpenClaw는 워크스페이스를 부트스트랩합니다 (기본값 ~/.openclaw/workspace):
- AGENTS.md, BOOTSTRAP.md, IDENTITY.md, USER.md를 시드
- 짧은 Q&A 의식 실행 (한 번에 하나의 질문)
- ID + 선호도를 IDENTITY.md, USER.md, SOUL.md에 작성
- 완료되면 BOOTSTRAP.md를 제거하여 한 번만 실행되도록 함
선택사항: Gmail 훅 (수동)
Gmail Pub/Sub 설정은 현재 수동 단계입니다. 사용:
openclaw webhooks gmail setup --account [email protected]
자세한 내용은 /automation/gmail-pubsub를 참조하세요.
Remote 모드 참고사항
Gateway가 다른 머신에서 실행될 때, 자격 증명 및 워크스페이스 파일은 해당 호스트에 있습니다. remote 모드에서 OAuth가 필요하면 다음을 생성하세요:
- ~/.openclaw/credentials/oauth.json
- ~/.openclaw/agents/<agentId>/agent/auth-profiles.json
gateway 호스트에.