헤르메스 구글 워크스페이스 연결 가이드 (gws 공식 스킬)

Sophie에게 진짜 손발을 달아줄 차례입니다. 지금까지는 페르소나와 기억을 심어 "어떤 비서인지"를 만들었다면, 이번에는 메일·일정·할 일을 직접 다루는 능력을 붙입니다. 구글 워크스페이스를 프로그램으로 다루는 공식 도구 gws와 그 공식 스킬을 연결하는 풀 코스입니다.

가장 까다로운 관문은 인증입니다. 그래서 이 가이드는 인증의 세 고비(동의 화면 게시·권한 403·화면 없는 환경)를 "막히고 푸는 자리"로 미리 안내합니다. 막힐 때마다 해당 단계를 펼쳐 그대로 따라오시면 됩니다.

💡 사전 준비: node와 gws가 필요합니다. npm install -g @googleworkspace/cli로 설치하고 gws --version이 보이면 준비된 것입니다. 설치했는데 gws 명령이 안 잡히면 바로 아래 "gws 명령이 안 잡힐 때"를 보세요.

이 가이드의 흐름 (다섯 고비)

💡 이 유닛의 한 줄: 코드를 직접 짜지 않고, 말로 시키고 승인만 합니다. 그것이 오케스트레이터입니다.

먼저 — gws 설치, 그리고 "gws 명령이 안 잡힐 때"

npm install -g @googleworkspace/cli로 깔았는데 gws 명령이 "command not found"로 안 잡히는 경우가 있습니다. 헤르메스가 자체 node를 함께 설치하면서, 그 node가 일반 터미널의 PATH를 가로채기 때문입니다.

💡 원인: 헤르메스 전용 node(~/.hermes/node/, ~/.local/bin/node 링크)가 우선되어, gws가 그쪽 node 아래 깔립니다. 해법은 nvm으로 node를 다시 깔아 우선순위를 잡고, gws를 다시 설치하는 것입니다.

1) nvm 설치 — 두 명령을 따로 실행합니다. (한 줄로 이어 붙이지 마세요.)

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash

설치가 끝나면 셸 설정을 다시 읽습니다.

source ~/.bashrc

2) node 설치하고 사용

nvm install --lts
nvm use --lts

3) 어느 node가 우선인지 확인

which node
which npm
npm prefix -g

~/.nvm 아래로 나오면 정상입니다.

/home/dante/.nvm/versions/node/v24.16.0/bin/node
/home/dante/.nvm/versions/node/v24.16.0/bin/npm
/home/dante/.nvm/versions/node/v24.16.0

4) gws 다시 설치

npm install -g @googleworkspace/cli
gws --help

이제 gws가 잡힙니다.

⚠️ 그래도 which npm이 헤르메스 쪽(~/.hermes 또는 ~/.local/bin)으로 나오면, 그때만 아래 링크를 지우고 셸을 다시 읽습니다. nvm 설치 후엔 보통 필요 없습니다.

rm ~/.local/bin/node ~/.local/bin/npm ~/.local/bin/npx
source ~/.bashrc

1단계. 구글 클라우드 준비 + 인증

Sophie에게 구글 손발(메일·일정·할 일)을 달려면 먼저 구글 클라우드에서 인증 기반을 만듭니다. 콘솔에서 동의 화면과 클라이언트를 손으로 만들고, 그다음 gcloud·gws로 API 활성화와 인증을 자동화합니다.

1-1. 가입 · 프로젝트 (콘솔)

console.cloud.google.com에 접속해 무료로 시작합니다(처음이면 300달러 크레딧이 주어지고, 이 실습은 무료 범위로 충분합니다). 상단 프로젝트 선택을 누르고, 모달 오른쪽 위 새 프로젝트를 클릭합니다.

프로젝트 이름을 넣고(예: inflearn-hermes) 만들기를 누른 뒤, 그 프로젝트를 선택합니다.

### 1-2. OAuth 동의 화면 · 클라이언트 · 게시 (콘솔)

이 구글 서비스를 프로그램으로 다루려면 OAuth 인증을 한 번 세팅해야 합니다. 햄버거 메뉴에서 API 및 서비스 → OAuth 동의 화면으로 들어가, 앱 이름(예: Hermes)과 지원 이메일을 넣고 사용자 유형은 외부로 만듭니다.

1) 데스크톱 클라이언트 만들기 — 사용자 인증 정보에서 OAuth 클라이언트 ID를 만들고, 애플리케이션 유형은 데스크톱 앱으로 고른 뒤 JSON을 다운로드합니다. 이 JSON 안의 클라이언트 ID와 시크릿을 뒤(1-3)에서 씁니다.

2) 프로덕션으로 게시 — 게시 상태에서 앱 게시를 누르고, "프로덕션으로 푸시하시겠어요?" 창에서 확인을 누릅니다. 상태가 "In production"이 되어야 합니다.

> ⚠️ 게시하지 않고 "테스트 중"으로 두면 7일마다 다시 로그인해야 합니다. 개인이 쓰는 용도이니 반드시 프로덕션으로 게시하세요.

💡 한 줄로 외울 것: 동의 화면은 꼭 프로덕션으로 게시합니다. 7일 함정을 예방하는 단 하나의 안전장치입니다.

1-3. gcloud 설치 + gws 인증

각 API를 콘솔에서 하나씩 켜는 대신, gws auth setup 한 번으로 자동화합니다. 이 명령은 gcloud가 필요하니 먼저 깝니다.

gcloud 설치 — macOS

brew install --cask gcloud-cli
gcloud --version

gcloud 설치 — Ubuntu · WSL (snap이 아니라 apt 공식 저장소를 씁니다)

sudo apt-get update
sudo apt-get install -y apt-transport-https ca-certificates gnupg curl
curl -fsSL https://packages.cloud.google.com/apt/doc/apt-key.gpg \
  | sudo gpg --dearmor -o /usr/share/keyrings/cloud.google.gpg
echo "deb [signed-by=/usr/share/keyrings/cloud.google.gpg] https://packages.cloud.google.com/apt cloud-sdk main" \
  | sudo tee /etc/apt/sources.list.d/google-cloud-sdk.list
sudo apt-get update
sudo apt-get install -y google-cloud-cli
gcloud --version

로그인 + 인증

gcloud init          # 로그인 + 프로젝트(inflearn-hermes) 선택
gws auth setup       # 쓸 API 자동 활성화 + 1-2에서 만든 클라이언트 ID·시크릿 입력
gws auth login --full   # 할 일까지 포함한 32개 권한으로 브라우저 동의

• gws auth setup은 쓸 API들을 골라 한 번에 켜 줍니다(콘솔에서 API마다 손으로 켜던 일을 대신합니다). 그리고 1-2에서 만든 클라이언트 ID와 시크릿(JSON에 들어 있음)을 붙여넣으라고 합니다.
• gws auth login에서 브라우저가 열리면 "고급 → 안전하지 않음(Hermes로 이동) → 계속"으로 진행하고 스코프를 모두 확인합니다(아직 검수 전이라 이 경고는 정상입니다).

💡 브라우저가 없는 서버라면 gcloud auth login --no-launch-browser를 쓰세요. 화면에 뜬 주소를 다른 기기 브라우저에서 열고, 받은 코드를 붙여넣으면 됩니다.

💡 참고 — 콘솔에서 API를 직접 켜는 화면입니다. gws auth setup이 자동으로 해주지만, 손으로 켜려면 API 라이브러리에서 각 API의 사용 버튼을 누릅니다.

2단계. 403 — 서비스 사용량 소비자 역할

gws 명령에서 403이 뜰 수 있습니다. 고장이 아니라 권한을 켜는 정상 단계이니 당황하지 마세요.

2-1. 무슨 에러인가

403 Caller does not have required permission to use project {PROJECT}.
Grant the caller the roles/serviceusage.serviceUsageConsumer role,
or a custom role with the serviceusage.services.use permission ...

2-2. 왜 나는가

프로젝트는 내가 만들었어도, 그 안의 API를 실제로 '사용'할 권한은 따로 켜야 합니다.

💡 건물 출입증은 받았는데, 특정 층은 따로 허가가 필요한 것과 같습니다.

2-3. 해결 — 맞춤 역할 만들어 부여하기

403 에러 메시지 안의 IAM 링크를 클릭해 콘솔로 들어간 뒤, 다음 순서로 권한을 켭니다.

1) 역할 찾기 — 왼쪽 역할 메뉴 → 사전 정의됨 탭에서 필터에 서비스 사용량 소비자를 넣어 찾고 체크합니다. (roles/serviceusage.serviceUsageConsumer)

2) 커스텀 역할로 복제 — 위쪽 선택한 역할로 커스텀 역할 만들기를 눌러 같은 권한의 맞춤 역할을 만듭니다.

3) 사용자에게 부여 — IAM의 액세스 권한 부여에서 본인 계정에 방금 만든 맞춤 서비스 사용량 소비자 역할을 추가하고 저장합니다.

4) 다시 실행 — 몇 분 전파를 기다린 뒤 명령을 다시 실행하면 작동합니다.

2-4. 확인

gws gmail users getProfile --params '{"userId":"me"}'
# 403이 안 나면 권한이 정상입니다

💡 한 줄로 외울 것: 403은 권한을 켜라는 신호입니다. 맞춤 서비스 사용량 소비자 역할을 만들어 부여합니다.

3단계. 공식 스킬 연결 — external_dirs 정확한 위치

gws 공식 스킬을 공용 허브에 깔았으면, 그 폴더를 Sophie가 보도록 프로필 설정에 한 줄을 등록합니다. 어디에 무엇을 넣는지 정확히 짚겠습니다.

3-1. 어디에 · 무엇을

⚠️ 전역 설정 ~/.hermes/config.yaml이 아니라 프로필별 폴더 아래 config.yaml입니다. 자리를 헷갈리지 마세요.

3-2. 설정 파일에서 이렇게

# 바꾸기 전
skills:
  template_vars: true

# 바꾼 뒤
skills:
  external_dirs:
    - ~/.agents/skills      # Codex와 공유하는 공용 허브
  template_vars: true

이미 external_dirs 목록이 있으면 줄을 지우지 말고 - ~/.agents/skills 한 줄만 보태면 됩니다.

3-3. 또는, 헤르메스 대시보드에서 직접 설정

파일을 직접 여는 게 번거롭다면, 헤르메스 대시보드에서 클릭 몇 번으로 같은 값을 넣을 수 있습니다.

1. 왼쪽 사이드패널에서 설정을 엽니다.
2. 가운데 섹션 필터에서 에이전트 탭을 고릅니다.
3. SKILLS 그룹의 EXTERNAL DIRS(skills.external_dirs) 입력 필드에 ~/.agents/skills를 넣습니다.

> 💡 파일(config.yaml)을 직접 고치든 대시보드에서 넣든 결과는 같습니다. 입력한 뒤에는 아래처럼 게이트웨이를 다시 시작해 반영합니다.

3-4. 적용하고 확인하기

hermes -p sophie gateway restart
hermes -p sophie skills list | grep gws
# 목록에 gws-calendar, gws-drive, gws-gmail이 보이면 성공입니다

3-5. 두 방식의 차이

⚠️ 외부 폴더가 쓰기 가능하면 에이전트가 그 안의 스킬을 고칠 수도 있습니다(쓰기 보호가 아닙니다). 공용 허브에는 신뢰하는 스킬만 둡니다.

3-6. 설치한 스킬, 믿어도 될까 — inspect와 audit

스킬은 결국 Sophie가 읽고 그대로 따르는 지시문입니다. 외부에서 받아온 스킬이라면 붙이기 전에 한 번 들여다보는 습관이 필요합니다. 헤르메스에는 이를 위한 명령이 두 가지 있습니다.

여기서 갈림길이 하나 있습니다. 자동 보안점검(audit)은 hermes skills install로 설치한 스킬에만 동작합니다. 이번 가이드처럼 skills.sh 유틸리티로 공용 허브(~/.agents/skills)에 깔고 external_dirs로 연결한 스킬은, 헤르메스가 설치 과정을 지켜본 스킬이 아니라서 자동 점검 대상이 아닙니다. 이 경우에는 inspect로 내용을 직접 확인합니다.

hermes skills inspect gws-gmail

같은 스킬을 hermes hub용으로 설치하면 자동 점검까지 됩니다

헤르메스 안에서 skills.sh 마켓을 바로 검색할 수 있습니다.

hermes skills search "gws" --source skills-sh

검색 결과의 Identifier를 골라 설치하면 hermes hub용 스킬로 들어옵니다.

hermes skills install skills-sh/googleworkspace/cli/gws-gmail

설치하는 순간에도 보안 스캔이 한 번 돌지만, 설치한 뒤에도 언제든 다시 점검할 수 있습니다.

hermes skills audit gws-gmail

보안점검이 통과된 모습입니다.

통과하지 못하는 경우도 있습니다

hermes skills audit minecraft-modpack-server --deep

위 스킬은 자동 차단됐습니다. 출력이 말하는 이유는 세 가지입니다.

1. OS 패키지 설치, 방화벽 설정 변경처럼 관리자 권한이 필요한 작업이 있어 privilege_escalation HIGH로 분류됐습니다.
2. crontab을 조작해 주기적으로 도는 백업 스크립트를 등록하는 패턴이 보였습니다.
3. 유니코드 escape 문자가 섞여 있어 스캐너가 난독화(obfuscation) 가능성을 의심했습니다.

결정적으로 헤르메스는 스킬의 Verdict 프론트매터를 차단 기준으로 크게 봅니다. verdict는 SAFE / CAUTION / DANGEROUS 세 가지가 있고, 공식 퍼블리셔의 스킬은 CAUTION까지 허용됩니다. 이 스킬은 커뮤니티 소스인데 verdict까지 CAUTION이라 차단된 것입니다.

⚠️ 점검하고 나서도 본인 판단에 괜찮다면 --force 옵션으로 강제 설치할 수 있습니다. 여기부터는 사람의 직접 보안 영역입니다. hermes skills inspect 명령으로 내용을 하나하나 따져 본 뒤에 결정하세요.

4단계. headless file backend 영구 설정

헤르메스나 서버처럼 화면이 없는 환경은 macOS Keychain을 열지 못합니다. 인증을 파일 방식(file backend)으로 바꿔야 합니다. 명령마다 붙이지 말고 한 번 영구로 설정하세요.

4-1. 내 환경에 맞는 영구 파일

4-2. 설정 — 자기 환경 한 줄만

# macOS (zsh)
echo 'export GOOGLE_WORKSPACE_CLI_KEYRING_BACKEND=file' >> ~/.zshenv

# WSL · Linux (bash)
echo 'export GOOGLE_WORKSPACE_CLI_KEYRING_BACKEND=file' >> ~/.bashrc

# 지금 이 터미널에도 즉시 적용
export GOOGLE_WORKSPACE_CLI_KEYRING_BACKEND=file

4-3. 이 방식으로 재인증하고 확인

gws auth setup
gws auth status
# auth_method: oauth2 / encrypted_credentials_exists: true 면 성공입니다

4-4. 헤르메스(에이전트)도 함께

• sophie 프로필 .env에 한 줄 추가합니다: GOOGLE_WORKSPACE_CLI_KEYRING_BACKEND=file
• bash의 ~/.bashrc는 화면 없는 실행에서 안 읽힐 수 있어, 헤르메스는 .env를 병행하는 편이 안전합니다.

💡 한 줄로 외울 것: 화면 없는 환경(헤르메스·서버)은 file backend입니다. 한 번 영구로 설정합니다.

4-5. Sophie가 인증을 못 찾을 때 — 인증 위치 고정

헤르메스에서 Sophie 챗에 접속하면 셸이 Sophie 전용 홈(~/.hermes/profiles/sophie/home)에서 시작됩니다. 그래서 gws가 그 홈 아래에서 인증 파일을 찾다가 "인증 정보가 없다"고 합니다. 인증은 여러분이 터미널에서 만든 ~/.config/gws에 있는데, Sophie의 홈은 그 자리를 못 보는 것이죠.

💡 영상에서는 Sophie에게 인증 파일을 복사하라고 시켰습니다. 그 방법도 되지만, 재인증할 때마다 어긋날 수 있어 더 확실한 길은 인증 위치를 절대경로로 고정하는 것입니다.

결정론적 해법 — Sophie 프로필 .env에 인증 디렉토리를 한 줄 더 박습니다. (앞의 KEYRING_BACKEND=file과 함께)

# ~/.hermes/profiles/sophie/.env
GOOGLE_WORKSPACE_CLI_KEYRING_BACKEND=file
GOOGLE_WORKSPACE_CLI_CONFIG_DIR=/home/dante/.config/gws

/home/dante는 여러분의 실제 사용자 홈으로 바꿉니다. (맥이면 /Users/이름/.config/gws) 저장한 뒤 게이트웨이를 다시 시작합니다.

hermes -p sophie gateway restart

이제 Sophie가 여러분의 터미널과 같은 인증을 그대로 씁니다. 복사본이 아니라 한 곳을 가리키므로, 나중에 재인증해도 어긋나지 않습니다.

💡 한 줄로 외울 것: Sophie는 전용 홈에서 시작합니다. .env에 GOOGLE_WORKSPACE_CLI_CONFIG_DIR를 절대경로로 고정하면 인증을 그대로 공유합니다.

5단계. Sophie에게 자연어로 시키기 10선

인증이 끝났으면 Sophie에게 말로 시켜보세요. 읽기는 알아서 처리하고, 쓰기는 승인을 받은 뒤에 실행됩니다.

읽기 — 바로 됩니다

1. 오늘 내 구글 캘린더 일정 알려줘.
2. 이번 주 일정 요약해줘.
3. 최근 하루 메일 중 중요한 것 3개만 제목으로 알려줘.
4. 안 읽은 메일 몇 개야?
5. 내 구글 할 일 목록 보여줘.
6. 이번 주 마감인 할 일 있어?

쓰기 — 사람 승인 후 실행

7. 내일 오전 10시에 "강의 녹화" 30분짜리 일정 잡아줘.
8. "장보기" 할 일 추가해줘.
9. ○○님께 회신 초안 써줘. (초안만, 발송은 내가)
10. 이 일정 참석자에게 안내 메일 초안 만들어줘.

⚠️ 쓰기(일정 생성·메일 발송·삭제)는 Sophie가 먼저 묻고, 여러분이 승인해야 실행됩니다.

💡 한 줄로 외울 것: 읽기는 맡기고, 쓰기는 승인합니다. 그것이 오케스트레이터입니다.

셋업 명령 한 장 (빠른 참조)

# 1) node + gws
nvm install --lts
nvm use --lts
npm install -g @googleworkspace/cli

# 2) gcloud (mac)
brew install --cask gcloud-cli
# 2) gcloud (ubuntu·wsl) — 본문 1-1 참고

# 3) 로그인 + 인증
gcloud init
gws auth setup
gws auth login --full

# 4) 화면 없는 환경이면 file backend (자기 셸 파일에)
echo 'export GOOGLE_WORKSPACE_CLI_KEYRING_BACKEND=file' >> ~/.zshenv   # bash면 ~/.bashrc
export GOOGLE_WORKSPACE_CLI_KEYRING_BACKEND=file
gws auth setup

# 5) 공식 스킬 연결 확인
hermes -p sophie gateway restart
hermes -p sophie skills list | grep gws

자주 만나는 문제

• gws 명령이 안 잡힘 (command not found) — 헤르메스 전용 node가 PATH를 가로챈 경우입니다. 위 "gws 명령이 안 잡힐 때"의 nvm 재설치 후 gws를 다시 설치하세요.
• gcloud CLI not found — gcloud가 안 깔렸습니다. 1-1단계로 설치하세요. WSL에서는 snap 대신 apt 공식 저장소를 씁니다.
• 403 forbidden — 권한을 켜는 정상 단계입니다. 2단계의 맞춤 서비스 사용량 소비자 역할을 만들어 부여합니다.
• 헤르메스에서만 인증이 안 됨 — 화면 없는 환경이라 Keychain을 못 엽니다. 4단계 file backend로 재인증하세요.
• Sophie가 gws 인증을 못 찾음 — Sophie 셸은 전용 홈에서 시작해 인증 위치를 못 봅니다. 4-5단계처럼 .env에 GOOGLE_WORKSPACE_CLI_CONFIG_DIR를 절대경로로 고정하세요.
• *skills list에 gws-가 안 보임 — 프로필별 config.yaml의 skills.external_dirs를 확인하고 게이트웨이를 재시작하세요.
• skills.sh로 깐 스킬에 audit이 안 됨 — 자동 보안점검은 hermes skills install로 설치한 스킬만 대상입니다. 공용 허브로 연결한 스킬은 3-6처럼 hermes skills inspect로 직접 확인하세요.

마무리

여기까지 끝나면 Sophie는 메일을 읽고, 일정을 잡고, 할 일을 정리하는 손발을 갖춥니다. 그리고 같은 공용 허브를 Codex도 함께 보기 때문에, 한 번 깔아둔 스킬을 두 도구가 같이 씁니다. 동의 화면 게시·403 권한·화면 없는 환경, 이 세 문턱은 다른 클라우드 도구를 붙일 때도 똑같이 만납니다. 오늘 한 번 넘어두면 다음부터는 훨씬 수월합니다.

여러분은 API를 직접 짜지 않았습니다. 말로 시키고, 쓰기는 승인했을 뿐입니다. 그것이 오케스트레이터입니다.

진행하시다가 막히는 부분이 생기면 언제든 인프런 질문 게시판에 질문을 남겨주세요.