🦞 16. Gmail 트러블슈팅 7가지

아침 8시에 자동 메일 정리를 돌렸는데, 조회는 되는데 Draft 저장만 실패하는 날이 있습니다. 이런 경우 대부분은 코드 문제가 아니라 권한 스코프, 실행 위치, 토큰 상태 3축에서 터집니다. 이 문서는 실제로 자주 만나는 7가지를 “상황 → 원인 → 바로 조치”로 정리한 실전판입니다.

안내: 본문은 생성형 AI를 활용해 정리했으며, 민감정보(토큰/개인식별자)는 예시에서 제거했습니다.

flowchart TD
A[Gmail 동작 이상] --> B{조회는 되는가?}
B -- 아니오 --> C[토큰/인증 점검]
B -- 예 --> D{Draft 저장 되는가?}
D -- 아니오 --> E[compose 스코프 점검]
D -- 예 --> F{콜백/실행환경 정상?}
F -- 아니오 --> G[포트포워딩/실행위치 점검]
F -- 예 --> H[검색조건/기간 최적화]

먼저 60초 체크

openclaw status
openclaw gateway status
python3 - <<'PY'
import json
from pathlib import Path
p=Path('~/.openclaw/gmail/token.json').expanduser()
print('token_exists=', p.exists())
if p.exists():
    print('scopes=', json.loads(p.read_text()).get('scopes'))
PY

여기서 바로 볼 핵심:

gmail.compose가 없으면 Draft 저장 실패 가능성 큼
토큰 파일이 있어도 스코프가 틀리면 동작이 반쪽만 됨

Gmail 트러블슈팅 7가지

1) 조회는 되는데 Draft 저장 시 403

상황: 메일 목록은 읽히는데 임시보관 생성만 실패
원인: gmail.compose 스코프 누락
바로 조치: OAuth 재인증 후 readonly + compose로 통일

2) 어제는 됐는데 오늘 갑자기 readonly로 회귀

상황: 자동화 돌린 뒤 권한이 다시 줄어듦
원인: 일부 스크립트가 readonly 단독 토큰을 덮어씀
바로 조치: Gmail 관련 스크립트 전체 스코프 정책을 하나로 고정

3) OAuth 브라우저가 안 열리거나 콜백 실패

상황: 인증 시작은 되는데 마지막 승인 단계에서 멈춤
원인: 원격 환경에서 loopback 포트 미연결
바로 조치:

ssh -N -L 8765:127.0.0.1:8765 <server>

포트 연결 후 로컬 브라우저에서 인증 재시도

4) Browser Relay가 들쭉날쭉

상황: 어떤 날은 되고 어떤 날은 실패
원인: OpenClaw 실행 머신과 브라우저 실행 머신 불일치
바로 조치: “같은 로컬 머신”에서 확장 + OpenClaw 동시 운영

5) 특정 발신자 메일만 안 잡힘

상황: 일부 중요 메일 누락
원인: 검색 범위를 너무 좁게 걸어둠
바로 조치: 먼저 넓게(newer_than:3d) 확인 후 점진적으로 좁히기

6) 토큰 파일은 있는데 인증 오류 반복

상황: token.json 존재하지만 계속 실패
원인: 손상/구버전 토큰
바로 조치:

mv ~/.openclaw/gmail/token.json ~/.openclaw/gmail/token.backup.$(date +%s).json

백업 후 재발급

7) 알림 자동화는 되는데 메일 제안 작성만 실패

상황: 읽기 파이프라인 OK, 쓰기 파이프라인 FAIL
원인: 조회 스크립트와 Draft 스크립트의 권한 정책 분리
바로 조치: 같은 토큰/같은 스코프 기준으로 운영 통합

오늘 바로 적용할 운영 룰 3개

토큰 경로 고정: ~/.openclaw/gmail/token.json
공통 스코프 고정: readonly + compose
배포 전 스모크 테스트 2개 고정
- 최근 메일 조회 1회
- Draft 저장 1회

5분 복구 체크리스트

openclaw status/gateway status 확인
token.json 존재 + compose 포함 확인
OAuth 콜백 포트(8765) 경로 확인
조회 테스트 성공
Draft 저장 테스트 성공

일하는 ai

탐색기