diff --git a/docs/troubleshooting/250717_happybell80_auth서버구축.md b/docs/troubleshooting/250717_happybell80_auth서버구축.md
new file mode 100644
index 0000000..40c69db
--- /dev/null
+++ b/docs/troubleshooting/250717_happybell80_auth서버구축.md
@@ -0,0 +1,49 @@
+# Auth Server 구축 및 Gmail OAuth 연동
+
+**날짜**: 2025-07-17  
+**작업자**: happybell80 & Claude
+
+## 오후 5시 37분
+
+### Gmail OAuth 구현 및 파일 기반 토큰 저장
+
+**배경**:
+- email skill을 사용하기 위해 Gmail OAuth 인증 필요
+- 중앙 인증 서버(auth.ro-being.com) 구축하여 토큰 관리
+
+**주요 작업 내용**:
+
+1. **초기 상태 확인**
+   - auth-server 컨테이너는 실행 중이었으나 Gmail OAuth 구현 안됨
+   - 서버와 로컬 코드 불일치 (서버에 placeholder만 존재)
+
+2. **Google OAuth 설정 문제**
+   - Google Client Secret이 실제 값이 아님
+   - OAuth consent screen이 테스트 모드
+   - 테스트 사용자 추가 필요 (goeun2dc@gmail.com, happybell80@naver.com)
+
+3. **Scope 문제 해결**
+   - Google이 scope 순서를 자동 변경하여 오류 발생
+   - 처음 시도: openid, email scope 추가 → 실패
+   - 해결: gmail.modify scope 사용 (읽기/쓰기/전송 모두 포함)
+   - 최종 해결: requests.post()로 직접 토큰 교환하여 scope 검증 우회
+
+4. **파일 권한 문제**
+   - `/code/tokens` 디렉토리 권한 부족으로 토큰 저장 실패
+   - 해결: `chmod 777 tokens`로 모든 권한 부여
+
+5. **구현 내용**
+   - 파일 기반 토큰 저장 (`/code/tokens/{user_id}_gmail.json`)
+   - status API: 토큰 상태 확인
+   - tokens API: 저장된 토큰 조회
+   - aiofiles 패키지 추가
+
+**최종 결과**:
+- Gmail OAuth 인증 성공
+- 토큰 파일 생성 및 저장 완료
+- Access Token과 Refresh Token 모두 획득
+- auth-server API 정상 작동
+
+**다음 단계**:
+- email skill과 auth-server 연동
+- PostgreSQL 기반 영구 저장소 구현
\ No newline at end of file