라즈베리파이5 AI 머신 세팅 5: Hermes Google OAuth 연결

4편에서는 라즈베리파이5의 Hermes에 Plugins, Tools, Skills를 필요한 만큼 추가했습니다. Discord에서 Hermes를 호출하고 웹 검색·이미지 생성·개발 절차를 사용할 준비는 끝났지만, 아직 Gmail·Calendar·Drive·Sheets·Docs 같은 Google Workspace 데이터에는 접근할 수 없습니다.

이번 5편에서는 Google Cloud에서 OAuth 클라이언트를 만들고, Hermes의 Google Workspace Skill에 Gmail·Calendar·Drive·Sheets·Docs·Contacts 권한을 연결합니다. 설정이 끝나면 Discord에서 메일을 찾고, 이번 주 일정을 읽고, Drive 파일을 검색하는 작업을 자연어로 요청할 수 있습니다.

아직 4편을 완료하지 않았다면 아래 글부터 진행하세요.

라즈베리파이5 AI 머신 세팅 · 4편 Hermes Plugins·Tools·Skills 확장 설정 보안·디스크 정리 Plugin부터 검색·이미지 Tool, 개발용 Skill과 Gateway 반영까지 먼저 진행합니다. 4편 먼저 보기 →

이번 5편에서 진행할 것

1. Google Cloud 프로젝트를 만들거나 기존 업무용 프로젝트를 선택합니다.
2. Google Workspace API 여섯 개를 활성화합니다.
3. Google Auth Platform의 앱 정보와 대상을 설정합니다.
4. Desktop app 유형의 OAuth 클라이언트를 만들고 JSON을 다운로드합니다.
5. PowerShell의 scp로 JSON을 라즈베리파이에 복사합니다.
6. Discord에서 Hermes에게 전체 Workspace 서비스 등록을 요청합니다.
7. 브라우저 승인 뒤 localhost 리디렉션 URL을 Hermes에 전달합니다.
8. AUTHENTICATED와 실제 Google API 호출 결과를 확인합니다.

완료하면 Google 계정 비밀번호를 Hermes에 알려주지 않고도, 사용자가 승인한 OAuth 범위 안에서 Google Workspace API를 호출할 수 있습니다.

보안 주의: OAuth 클라이언트 JSON과 google_token.json은 비밀번호처럼 다뤄야 합니다. 공개 Git 저장소, 블로그 첨부, Discord 공개 채널에 올리지 마세요. 캡처에서 가리는 것만으로는 이미 노출된 secret이나 token이 안전해지지 않습니다. 노출됐다면 Google Cloud에서 클라이언트를 교체하고 Google 계정의 연결된 앱 권한도 해제한 뒤 다시 인증하세요.

시작 전 준비 사항

• 4편까지 완료한 Raspberry Pi 5와 실행 중인 Hermes Gateway
• Google Cloud 프로젝트를 만들 수 있는 Google 계정
• 연결할 Gmail 또는 Google Workspace 계정
• Windows PowerShell에서 pi-office로 SSH 접속할 수 있는 환경
• JSON을 내려받을 Windows 브라우저

이번 글은 Gmail뿐 아니라 Calendar, Drive, Sheets, Docs까지 사용할 전체 Workspace 연결을 기준으로 합니다. 이메일만 필요하다면 Google Cloud 프로젝트 없이 Gmail App Password를 사용하는 더 단순한 구성이 나을 수 있습니다.

1. Google Cloud 프로젝트 만들기

브라우저에서 Google Cloud 프로젝트 선택을 엽니다. 기존 업무용 프로젝트가 있다면 선택하고, 이번 라즈베리파이용 연결을 분리하고 싶다면 프로젝트 만들기를 누릅니다.

프로젝트 이름은 역할을 알아보기 쉽게 정합니다.

pi-hermes

프로젝트 이름은 표시용이고, 내부 프로젝트 ID와 프로젝트 번호는 Google이 별도로 관리합니다. 여러 OAuth 실험을 한 프로젝트에 계속 쌓기보다 라즈베리파이 Hermes용 프로젝트를 분리하면 나중에 API와 자격 증명을 정리하기 쉽습니다.

2. Google Workspace API 6개 활성화하기

프로젝트가 선택된 상태에서 왼쪽 메뉴의 API 및 서비스 → 사용 설정된 API 및 서비스로 이동합니다.

상단의 API 및 서비스 사용 설정을 누릅니다.

API 라이브러리 검색창에서 다음 여섯 개를 하나씩 검색합니다.

• Gmail API
• Google Calendar API
• Google Drive API
• Google Sheets API
• Google Docs API
• People API

검색 결과에서 API를 열고 사용을 누릅니다. 아래 캡처는 Gmail API를 활성화하는 화면입니다.

나머지 다섯 개도 같은 방식으로 활성화합니다. 모두 끝나면 사용 설정된 API 목록에서 여섯 개를 확인합니다.

People API는 Google Contacts 읽기에 사용됩니다. 이번 인증 완료 화면에 Google Contacts: 읽기가 표시되는 이유도 이 API와 연락처 범위가 포함되기 때문입니다.

HttpError 403: Access Not Configured가 나오면 OAuth 자체보다 해당 API가 프로젝트에서 활성화됐는지 먼저 확인하세요. API를 켠 직후에는 설정 반영에 잠시 시간이 걸릴 수도 있습니다.

3. Google Auth Platform 동의 화면 설정하기

API 및 서비스 화면에서 OAuth 동의 화면을 선택합니다. 현재 Google Cloud UI에서는 이 메뉴가 Google 인증 플랫폼으로 이어집니다.

처음 구성하는 프로젝트라면 시작하기를 누릅니다.

앱 정보에는 다음처럼 입력할 수 있습니다.

• 앱 이름: Hermes Workspace 또는 pi-hermes
• 사용자 지원 이메일: 연결을 관리할 본인 이메일
• 대상: 개인 Gmail 또는 조직 외부 사용자라면 External
• 연락처 정보: Google의 변경 알림을 받을 이메일

화면의 다음을 눌러 대상, 연락처 정보, 정책 동의까지 진행하고 마지막에 만들기를 선택합니다.

External과 테스트 사용자를 구분하기

개인 Gmail은 조직 내부 앱이 아니므로 External을 선택합니다. Google Workspace 회사 계정에서 Internal을 사용할 수 있는지는 해당 Cloud 프로젝트의 조직 소속과 관리자 정책에 따라 달라집니다.

External 앱의 게시 상태가 Testing이라면 Google 인증 플랫폼 → 대상 → 테스트 사용자 추가에서 실제로 승인할 Google 계정을 넣습니다. 이 단계가 빠지면 Error 403: access_denied가 나타날 수 있습니다.

24시간 서버 운영 전 확인: Google 공식 문서에 따르면 External 앱이 Testing 상태에서 Gmail·Drive 같은 Workspace 데이터 범위를 요청하면 테스트 사용자의 승인과 refresh token이 7일 뒤 만료될 수 있습니다. 잠깐 시험할 때는 Testing으로 진행할 수 있지만, 장기 운영은 Google의 현재 게시·검증 요구 사항과 회사 관리자 정책을 확인해야 합니다. 자동 갱신은 유효한 refresh token이 남아 있는 동안 동작합니다.

4. Desktop app OAuth 클라이언트 만들기

동의 화면 구성이 끝나면 API 및 서비스 → 사용자 인증 정보로 이동합니다. Google 인증 플랫폼의 클라이언트 메뉴에서도 같은 클라이언트를 만들 수 있습니다.

상단의 사용자 인증 정보 만들기 → OAuth 클라이언트 ID를 선택합니다.

클라이언트 설정은 다음처럼 입력합니다.

• 애플리케이션 유형: 데스크톱 앱
• 이름: Hermes on pi-office 또는 pi-hermes on pi-office

이름은 Google Cloud Console에서 클라이언트를 구분하기 위한 표시값입니다. 라즈베리파이에 GUI가 없더라도 Hermes의 headless 승인 흐름은 설치형 앱용 OAuth와 PKCE를 사용하므로 Desktop app을 선택합니다.

만들기를 누르면 클라이언트 ID와 클라이언트 보안 비밀번호가 표시됩니다. 여기서 JSON 다운로드를 눌러 파일을 저장합니다.

이 JSON에는 client_secret이 들어 있으므로 화면에 공개하거나 Git에 커밋하면 안 됩니다. 클라이언트 ID는 비밀번호와 같은 단독 secret은 아니지만, 공개 캡처에서는 프로젝트 식별 정보까지 함께 가리는 편이 안전합니다.

5. OAuth JSON을 pi-office로 복사하기

다운로드한 JSON을 Windows PowerShell에서 라즈베리파이로 전송합니다. 2편에서 만든 SSH 키 파일명이 id_ed25519_pi라면 다음처럼 실행합니다.

scp -i "$env:USERPROFILE\.ssh\id_ed25519_pi" `
  "C:\Users\사용자명\Downloads\client_secret_다운로드한파일명.json" `
  calvin@192.168.0.8:/home/calvin/hermes-google-client-secret.json

기본 키 이름을 id_ed25519로 만들었다면 -i 뒤 경로만 실제 파일명으로 바꿉니다.

2편의 SSH config에 pi-office 별칭을 등록했다면 IP·사용자·키 경로를 다시 적지 않아도 됩니다.

scp "C:\Users\사용자명\Downloads\client_secret_다운로드한파일명.json" `
  pi-office:/home/calvin/hermes-google-client-secret.json

SSH config의 별칭을 pi로 정한 독자는 pi-office 대신 pi를 사용하면 됩니다. 대상 경로의 calvin도 실제 Ubuntu 사용자명이 다르면 함께 바꿔야 합니다.

전송이 끝나면 SSH에서 파일 존재와 권한을 확인할 수 있습니다.

test -f ~/hermes-google-client-secret.json && echo "JSON copied"
chmod 600 ~/hermes-google-client-secret.json
ls -l ~/hermes-google-client-secret.json

chmod 600은 파일 소유자만 읽고 쓸 수 있게 제한합니다. 파일 내용을 cat으로 출력하거나 Discord에 첨부해서 확인하지 마세요.

6. Discord에서 Hermes에게 Workspace 등록 요청하기

이제 Discord에서 Hermes Bot을 멘션하고 다음처럼 요청합니다.

Google OAuth JSON 파일을 ~/hermes-google-client-secret.json에 복사했어.
Gmail, Calendar, Drive, Sheets, Docs 전체 서비스로 Hermes에 등록하고
OAuth 인증을 진행해줘.

Hermes는 google-workspace Skill의 설정 절차를 읽고 다음 작업을 진행합니다.

1. 전달한 JSON 파일이 있는지 확인합니다.
2. Hermes 내부 자격 증명 경로로 복사합니다.
3. 원본과 내부 JSON의 권한을 600으로 제한합니다.
4. 전체 서비스 범위로 OAuth 승인 URL을 생성합니다.
5. 인증 코드 교환 뒤 API 연결 상태를 확인합니다.

이번 글의 ~/hermes-google-client-secret.json은 Windows에서 복사해 둔 임시 입력 파일입니다. 인증 뒤 Hermes가 실제로 사용하는 기본 경로는 설치된 Skill 버전에 따라 안내되며, 이번 캡처에서는 다음 두 파일이 표시됐습니다.

~/.hermes/google_client_secret.json
~/.hermes/google_token.json

두 파일 모두 공개 백업이나 Git 동기화 대상에서 제외합니다.

7. Hermes가 보낸 Google OAuth 승인 링크 열기

준비가 끝나면 Hermes가 https://accounts.google.com/o/oauth2/auth?... 형태의 긴 승인 링크를 보냅니다.

링크를 브라우저에서 열고 연결할 Google 계정으로 로그인합니다. 동의 화면에는 앱 이름과 요청 권한이 표시됩니다. 요청한 계정과 권한 범위를 확인한 뒤 승인합니다.

이번 전체 서비스 구성에서 요청되는 대표 범위는 다음과 같습니다.

• Gmail: 읽기, 전송, 수정
• Calendar: 일정 전체 접근
• Drive: 파일 접근
• Sheets: 스프레드시트 읽기·쓰기
• Docs: 문서 읽기·쓰기
• Contacts: 연락처 읽기

필요하지 않은 서비스까지 무조건 승인하는 것이 정답은 아닙니다. 예를 들어 Calendar와 Drive만 쓸 계획이라면 Hermes에게 해당 서비스만 지정해 더 좁은 범위로 인증을 요청할 수 있습니다.

회사 계정 주의: 조직 관리자가 제3자 앱을 제한하거나 Advanced Protection을 사용하면 개인이 동의해도 인증이 차단될 수 있습니다. 이 경우 OAuth 클라이언트 ID와 요청 scope 목록을 Workspace 관리자에게 전달해 허용 여부를 확인해야 합니다.

8. localhost 접속 실패 화면에서 전체 URL 복사하기

승인이 끝나면 브라우저가 다음과 같은 주소로 이동합니다.

http://localhost:1/?code=...

라즈베리파이에 브라우저를 직접 띄운 것이 아니므로 Windows 브라우저에서는 사이트에 연결할 수 없음 또는 ERR_UNSAFE_PORT가 표시될 수 있습니다.

이 화면은 승인 자체가 실패했다는 뜻이 아닙니다. 주소 표시줄의 http://localhost:1/?... 전체 URL을 복사해 Discord의 같은 Hermes 대화에 붙여 넣습니다.

http://localhost:1/?code=...&scope=...

Hermes는 앞에서 저장한 임시 PKCE 세션과 이 URL의 일회용 authorization code를 이용해 Google token으로 교환합니다.

• 가장 최근에 열린 승인 탭의 URL을 사용합니다.
• authorization code는 짧은 시간만 유효하고 한 번 사용하면 다시 쓸 수 없습니다.
• 공개 채널에 URL을 붙이지 말고 허용된 개인 채널이나 제한된 스레드에서 진행합니다.
• 코드가 만료되거나 이미 사용됐다면 Hermes가 만든 새 승인 URL로 처음부터 다시 승인합니다.

9. AUTHENTICATED와 실제 API 호출 확인하기

코드 교환이 끝나면 Hermes가 서비스별 권한과 인증 상태를 정리합니다.

이번 실제 결과에서는 다음 상태를 확인했습니다.

인증 상태: AUTHENTICATED
실제 Google API 호출: LIVE_CHECK_OK
토큰 자동 갱신: 활성화

AUTHENTICATED는 token 파일이 만들어지고 필요한 scope가 들어 있다는 뜻입니다. LIVE_CHECK_OK는 저장만 끝난 것이 아니라 실제 Google API 요청까지 성공했다는 확인입니다.

자동 갱신은 refresh token이 유효한 동안 동작합니다. External 앱의 Testing 7일 제한, 사용자가 Google 계정에서 접근 권한을 해제한 경우, 조직 관리자가 정책을 바꾼 경우에는 다시 인증해야 할 수 있습니다.

원한다면 SSH에서 Hermes Skill의 자체 확인 명령을 실행할 수도 있습니다.

GSETUP="python ${HERMES_HOME:-$HOME/.hermes}/skills/productivity/google-workspace/scripts/setup.py"
$GSETUP --check

정상 연결이면 AUTHENTICATED가 표시됩니다. 설치 경로나 Skill 구조는 Hermes 업데이트로 달라질 수 있으므로 Discord에서 Hermes에게 상태 확인을 맡기는 방식도 가능합니다.

Google Workspace 연결 후 바로 써볼 요청 예시

처음부터 메일 전송이나 파일 공유처럼 외부 결과를 남기는 작업을 맡기지 말고 읽기 → 초안 → 승인 후 실행 순서로 범위를 넓히는 편이 안전합니다.

Gmail: 안 읽은 메일 요약

최근 7일간 받은 안 읽은 메일 중 첨부파일이 있는 것만 찾아줘.
보낸 사람, 제목, 날짜, 핵심 내용만 표로 정리하고
읽음 처리나 답장 전송은 하지 마.

검색 조건을 더 정확히 지정하려면 Gmail 검색 문법을 자연어에 함께 넣을 수 있습니다.

Gmail에서 newer_than:7d has:attachment filename:pdf 조건으로 최대 10개만 찾아줘.
메일 내용은 요약하되 외부 전송은 하지 마.

Gmail: 답장 초안만 만들기

오늘 받은 거래처 메일을 읽고 답장 초안을 작성해줘.
받는 사람, 제목, 본문을 먼저 보여주고 내가 승인하기 전에는 보내지 마.

Hermes Google Workspace Skill의 기본 운영 규칙도 이메일 전송 전 사용자 확인을 요구합니다. 그래도 요청문에 보내지 마를 명시하면 작업 경계가 더 분명해집니다.

Calendar: 이번 주 일정과 빈 시간 찾기

한국 시간 기준으로 이번 주 일정을 날짜별로 정리해줘.
30분 이상 비어 있는 시간 세 곳을 찾아주되 새 일정은 만들지 마.

새 일정을 만들 때는 시간대와 참석자를 먼저 확인합니다.

내일 오후 2시부터 2시 30분까지 '주간 점검' 일정 초안을 만들어줘.
시간대는 Asia/Seoul이고, 실제 생성 전 제목·시간·참석자를 보여줘.

Drive: 업무 문서 검색

Google Drive에서 이름에 '분기 보고서'가 들어간 파일을 최대 10개 찾아줘.
파일명, 종류, 수정일, 링크만 보여주고 다운로드·공유·삭제는 하지 마.

Sheets: 새 행 추가 전 미리보기

재고 스프레드시트의 Stock 시트에서 마지막 10행을 읽어줘.
내가 줄 데이터를 추가할 위치와 예상 결과를 먼저 보여주고
승인 전에는 셀을 수정하지 마.

Docs: 회의록 초안 만들기

오늘 회의 내용을 결정사항, 담당자, 마감일로 정리해 Google Docs 초안을 만들어줘.
새 문서를 만들기 전에 제목과 본문을 먼저 보여줘.

읽기 작업이 정상이라면 그다음에 생성·수정 작업을 한 가지씩 시험합니다. Gmail 전송, Calendar 일정 생성·삭제, Drive 공유·삭제, Sheets·Docs 수정은 실제 외부 상태를 바꾸므로 대상과 내용을 확인한 뒤 실행하세요.

연결이 안 될 때 확인 순서

Error 403: access_denied

1. Google 인증 플랫폼의 대상이 계정 유형과 맞는지 확인합니다.
2. External + Testing이면 대상 → 테스트 사용자에 승인 계정을 추가합니다.
3. 회사 Workspace 계정이면 관리자의 제3자 앱 제한을 확인합니다.
4. Advanced Protection 사용자는 관리자의 allowlist가 필요할 수 있습니다.

HttpError 403: Access Not Configured

오류 메시지에 나온 API가 Google Cloud 프로젝트에서 활성화됐는지 확인합니다. Gmail만 켜고 Drive 요청을 보내면 Drive API에서 막힐 수 있습니다.

Insufficient Permission 또는 token missing scopes

처음 승인할 때 일부 권한을 빼거나 나중에 서비스 범위를 늘리면 기존 token에 필요한 scope가 없을 수 있습니다. 기존 연결을 해제하고 필요한 서비스 범위로 다시 승인합니다.

GSETUP="python ${HERMES_HOME:-$HOME/.hermes}/skills/productivity/google-workspace/scripts/setup.py"
$GSETUP --revoke

그다음 Hermes에게 새 OAuth 인증을 요청합니다.

authorization code expired 또는 already used

이전 탭의 localhost URL을 다시 보내면 안 됩니다. Hermes가 반환한 최신 승인 URL을 열고 다시 동의한 뒤, 가장 최근 리디렉션 URL을 전달합니다.

7일 뒤 갑자기 REFRESH_FAILED

External 앱의 Publishing status가 Testing인지 확인합니다. Workspace 데이터 scope를 요청한 Testing 앱의 refresh token은 7일 뒤 만료될 수 있습니다. 테스트를 계속한다면 재인증하고, 장기 운영이라면 Google의 현재 Production·검증 요구 사항과 조직 정책을 확인합니다.

운영 전 보안 체크리스트

다음 글: Hermes Notion API 연결

Google Workspace 연결까지 마쳤다면 6편에서는 회사 Notion 업무 페이지를 Hermes에 연결합니다. Workspace Owner에게 Internal Integration 생성을 요청하고, 필요한 콘텐츠 권한과 페이지 접근 범위만 지정한 뒤 라즈베리파이의 환경 파일에 토큰을 저장합니다.

읽기 검증은 공식 ntn CLI 인증, 페이지 검색, Markdown 읽기, 데이터베이스 조회 순서로 진행합니다. 쓰기 테스트는 생성할 제목·본문·부모 페이지를 먼저 확인하고 승인한 뒤 페이지 하나만 만들며, 마지막에는 생성된 페이지를 다시 조회하고 Gateway를 재시작합니다.

라즈베리파이5 AI 머신 세팅 · 6편 Hermes Notion API 연결과 읽기·쓰기 검증 회사 관리자에게 내부 연결을 요청하는 과정부터 최소 권한, 페이지 공유, 토큰 등록과 승인 후 쓰기 테스트까지 진행합니다. 6편 이어서 보기 →

공식 자료

• Hermes Agent Google Workspace Skill 공식 문서
• Hermes Agent Google Workspace bundled Skill 상세 문서
• Google Workspace OAuth 동의 화면 구성
• Google Workspace 액세스 자격 증명 만들기
• Google OAuth 2.0 for Desktop Apps
• Google Auth Platform 대상과 Testing 상태
• Google Cloud 프로젝트 선택
• Google Cloud API 라이브러리
• Google Cloud 사용자 인증 정보

정리

이번 5편에서는 Google Cloud 프로젝트를 준비하고 Gmail, Calendar, Drive, Sheets, Docs, People API를 활성화했습니다. Google Auth Platform의 앱 정보와 External 대상을 설정한 뒤 Desktop app OAuth 클라이언트를 만들고 JSON을 다운로드했습니다.

JSON은 2편에서 만든 SSH 키 또는 pi-office 별칭을 이용해 라즈베리파이로 복사했습니다. Discord에서 Hermes에게 전체 Workspace 서비스 등록을 요청하고, Google 승인 링크를 연 뒤 localhost 접속 실패 화면의 전체 리디렉션 URL을 다시 전달했습니다.

마지막으로 AUTHENTICATED와 LIVE_CHECK_OK를 확인했습니다. 이제 Hermes는 사용자가 승인한 범위 안에서 Gmail 검색·답장 초안, Calendar 일정 조회, Drive 파일 검색, Sheets 읽기·쓰기, Docs 문서 작업, Contacts 조회를 수행할 수 있습니다.

가장 안전한 시작 순서는 읽기 요청 → 결과 확인 → 초안 작성 → 승인 후 쓰기 실행입니다. Google 계정이 연결됐다는 이유만으로 메일 전송, 일정 생성, 파일 공유와 삭제를 한 번에 자동화하지 말고, 실제 업무 흐름을 한 단계씩 검증하세요.