🦞 11. Gmail 연결

Gmail을 OpenClaw에 붙일 때 가장 많이 헷갈리는 지점은 “브라우저로 보는 일”과 “API로 자동화하는 일”을 한 덩어리로 생각하는 것이다. 실제로는 이 둘의 쓰임새가 꽤 다르다. 이 문서는 언제 Browser Relay를 쓰고, 언제 Gmail API OAuth를 쓰며, 어떤 보안 기준으로 운영해야 덜 깨지는지를 한 번에 정리한 실무 가이드다.

안내: 본문은 생성형 AI를 활용해 초안을 정리하고, 공식 문서 기준으로 사람이 검수해 보정했습니다.

flowchart LR
A[메일 관련 요청] --> B{무엇이 필요한가?}
B -->|화면 확인/버튼 클릭| C[Browser Relay]
B -->|검색/분류/정기 점검| D[Gmail API OAuth]
C --> E[탭 attach 기반 조작]
D --> F[토큰 기반 자동화]
E --> G[결과 보고]
F --> G

결론 먼저

Gmail 연결은 **“UI 확인은 Browser Relay, 반복 자동화는 Gmail API”**로 나누어 쓰는 것이 가장 안전하다.

왜 자꾸 헷갈리나

겉으로는 둘 다 “Gmail 연결”이지만 실제 동작은 완전히 다르다.

• Browser Relay는 Gmail 웹 화면을 직접 열어 보고 클릭하는 방식이다.
• Gmail API OAuth는 메일 목록, 본문, 첨부를 코드나 자동화 루틴으로 처리하는 방식이다.

이 차이를 먼저 고정하지 않으면,

• 화면은 보여야 하는데 API로만 해결하려 하거나
• 반복 자동화가 필요한데 Relay에만 의존하게 되어 작업이 자꾸 흔들린다.

칠판 판서형 치트시트

1. 받은편지함을 눈으로 확인해야 하면 Relay.
2. 정기 점검·검색·분류·첨부 탐색이면 Gmail API.
3. Gmail 권한은 기본 read-only부터 시작.
4. 삭제·외부 발송·권한 변경은 자동 실행 금지, 사람 승인 필수.

개념/원인/대응/실행 (MECE)

1) 개념: Gmail 연결은 2가지 경로다

구분	Browser Relay	Gmail API OAuth
핵심 역할	화면 확인·클릭·입력	검색·분류·조회·자동화
강한 작업	버튼 상태 확인, 실제 UI 조작	정기 모니터링, 대량 조회, 첨부 탐색
약한 작업	크론 기반 반복 작업	화면 요소 직접 검증
장애 포인트	탭 attach, 브라우저 상태	토큰, scope, OAuth 설정

한 줄로 말하면,

• 지금 눈으로 보고 눌러야 하는 일은 Relay
• 반복되거나 자동으로 굴려야 하는 일은 API다.

2) 원인: 현장에서 가장 많이 틀리는 4가지

1. Gmail 화면 확인이 필요한데 API만 붙여 놓고 “왜 버튼 상태를 못 보지?”라고 생각함
2. 정기 모니터링이 필요한데 Relay만 켜 두고 자동화를 기대함
3. gmail.readonly로 충분한데 처음부터 과한 권한을 요구함
4. 메일 본문/첨부를 신뢰해 자동 답장·외부 전송까지 연결하려 함

3) 대응: 가장 덜 깨지는 운영 기준선

• 기본 운영: Gmail API를 읽기 전용 중심으로 두고, 반복 업무는 여기로 고정한다.
• 예외 운영: 실제 화면 확인이 필요할 때만 Browser Relay를 쓴다.
• 보안 기준: 삭제, 외부 발송, 권한 변경, 대량 이동은 사람 승인 큐를 거친다.
• 판단 원칙: “읽기만 필요한가, 화면 클릭이 필요한가”를 먼저 묻는다.

4) 실행: 5분 안에 경로 고르는 법

A. Browser Relay를 고르면 좋은 순간

• Gmail 웹 UI가 실제로 어떻게 보이는지 확인해야 할 때
• 버튼, 라벨, 탭, 드롭다운 상태를 사람이 함께 검증해야 할 때
• 자동화보다 “지금 이 화면에서 뭘 눌러야 하는지”가 중요할 때

빠른 순서:

1. Gmail이 열린 탭에서 Relay 아이콘을 ON 한다.
2. attach된 탭인지 확인한다.
3. snapshot으로 UI가 보이는지 점검한다.
4. 필요한 확인·클릭·입력을 수행한다.
5. 끝나면 Relay를 끈다.

B. Gmail API OAuth를 고르면 좋은 순간

• 신규 메일을 30분마다 확인하는 크론이 필요할 때
• 특정 발신자/제목/첨부 조건으로 자동 검색해야 할 때
• 브라우저를 열지 않고도 안정적으로 메일을 읽고 분류해야 할 때

빠른 순서:

1. Google Cloud에서 Desktop OAuth client를 만든다.
2. 필요한 scope를 정한다. 처음은 gmail.readonly가 기본이다.
3. OAuth 승인 후 토큰을 발급받는다.
4. 메일 조회 테스트를 먼저 한다.
5. 테스트가 안정적이면 cron/자동화에 붙인다.

보안: Gmail 권한은 편의성이 아니라 공격면도 같이 연다

메일 본문과 첨부에는 사람에게는 평범해 보이지만, 에이전트에게는 행동 지시처럼 해석될 수 있는 내용이 섞일 수 있다. 그래서 Gmail 연결은 “연결 성공”보다 권한을 어디까지 열었는지가 더 중요하다.

기본 보안 원칙 5개

1. 최소 권한 원칙
   기본은 gmail.readonly부터 시작한다.
2. 고위험 액션 승인제
   삭제, 외부 전송, 대량 이동은 자동 실행하지 않는다.
3. allowlist 우선
   신뢰 발신자/도메인/검색 조건만 자동화 대상으로 묶는다.
4. 첨부·링크는 단계 분리
   바로 열지 말고, 검사→판단→실행으로 나눈다.
5. UI 확인 경로 유지
   의심 건은 Relay로 사람이 최종 확인한다.

10초 체크

• 이 작업은 읽기 전용 권한만으로 가능한가?
• 지금 필요한 건 “클릭”인가, “검색/분류”인가?
• 삭제·외부 발송 같은 위험 액션이 자동으로 이어지지 않는가?

바로 적용 가능한 대표 유즈케이스

사례 A. 교육요청 메일 모니터링

• 목적: 신규 문의를 놓치지 않기
• 권장 경로: Gmail API OAuth
• 이유: 30분 주기 감시, 필터링, 요약은 API가 더 안정적이다.

사례 B. 메일 화면에서 실제 버튼 상태 확인

• 목적: “이 라벨이 보이는지”, “이 버튼이 활성화됐는지” 확인
• 권장 경로: Browser Relay
• 이유: API는 화면을 보여주지 못한다.

사례 C. 특정 발신자 + 첨부 확장자 탐색

• 목적: 예를 들어 pptx 첨부만 모아 보고 싶을 때
• 권장 경로: Gmail API OAuth
• 이유: 필터, 검색, 반복 처리에 강하다.

사례 D. 의심 메일 최종 확인

• 목적: 링크/첨부가 수상한 메일을 실제 화면으로 검토
• 권장 경로: API로 1차 분류 + Relay로 최종 확인
• 이유: 속도와 안전을 같이 챙길 수 있다.

자주 나는 문제와 대응

문제	보통 원인	먼저 할 대응
no tab is connected	Relay ON 탭이 없음	Gmail 탭에서 Relay 아이콘 ON 후 다시 확인
redirect_uri_mismatch	OAuth client 타입/설정 불일치	Desktop OAuth client 기준으로 재생성
token not found	OAuth 승인 미완료 또는 저장 실패	승인 흐름 완료 후 토큰 경로 재확인
읽기는 되는데 자동화가 불안정함	Relay에 반복 작업을 억지로 태움	정기 작업을 API 경로로 분리
권한이 과하게 열림	처음부터 쓰기 권한까지 허용	read-only로 다시 시작하고 승인제 적용

도입 우선순위 (누가/무엇/순서)

1. 운영 담당자: 팀 기본값을 “반복 업무는 Gmail API, UI 확인은 Relay”로 문서화한다.
2. 자동화 담당자: gmail.readonly 기준으로 첫 테스트를 만들고, allowlist 조건을 먼저 고정한다.
3. 실사용자: 의심 메일·민감 메일은 자동 실행하지 않고 Relay로 눈으로 확인하는 습관을 둔다.

적용 체크리스트

• Gmail UI 확인과 반복 자동화 경로를 분리했다.
• 정기 점검/분류는 Gmail API 중심으로 설계했다.
• Gmail 권한은 read-only에서 시작했다.
• 삭제/외부 발송/권한 변경은 승인 큐를 거치게 했다.
• 신뢰 발신자/도메인 allowlist를 정의했다.
• 의심 메일은 Relay로 최종 확인하도록 남겨 뒀다.

다음 읽기

• 12. 브라우저 릴레이 연동 구조
• 16. Gmail 트러블슈팅 7가지
• 06. Cron Job
• 34. 세션툴로 블로그 검수 자동화

AI 생성 결과물을 포함한 문서입니다. 배포 전 OAuth 범위, 토큰 저장 위치, 승인 정책은 각 운영 환경에 맞게 최종 확인하세요.