에이전트에게 구글 워크스페이스 열쇠를 쥐여주다
무엇을 만들려는가
사무실로 들어오는 서류는 대부분 스캔을 거친다. 스캐너가 찍은 파일은 구글 드라이브의 한 폴더(Ai Test > SCAN)로 올라간다. 지금까지는 이 파일들을 사람이 하나씩 열어 분류하고, 기일이 있으면 손으로 캘린더에 옮겨 적었다.
이걸 에이전트에게 맡기고 싶었다. 그림은 이렇다.
매일 정해진 시각에 로컬 모델이 SCAN 폴더를 확인한다. 새로 올라온 파일을 읽고, 종류에 맞춰 정해진 일을 한다.
첫 대상으로는 가장 단순한 문서, **형사 사건의 기일지정서(공판기일통지서)**를 골랐다. 목표 동작은 이렇게 정했다.
- SCAN 폴더의 새 파일을 로컬 모델이 읽는다.
- 공판기일통지서로 인식하면, 그 파일을 피고인 이름으로 된 폴더로 옮긴다.
- 통지서 내용에 맞춰 구글 캘린더에 기일을 등록한다.
- 처리 결과를 텔레그램으로 통보한다.
이를 실현하려면 대충 새 파일 감지, 다운로드, 모델 판독, 종류 판별, 정보 추출, 파일 이동, 일정 등록, 텔레그램 통보가 이뤄져야 한다. 일단은 에이전트가 애초에 구글 드라이브와 캘린더에 손을 댈 수 있어야 한다. 이번 화는 그 열쇠를 만드는 과정이다.
gog — 구글 워크스페이스를 터미널에서 다루는 도구
드라이브에서 파일을 가져오고 캘린더에 일정을 넣으려면, 구글 API를 호출할 수단이 필요하다. 직접 코드를 짜서 구글 API를 두드릴 수도 있지만, 인증 처리부터 페이지네이션까지 손이 많이 간다.
찾아보니 gog(gogcli)라는 오픈소스 도구가 있었다. Gmail, 캘린더, 드라이브, Docs, Sheets, Tasks 같은 구글 워크스페이스 서비스를 터미널 명령 한 줄로 다루게 해주는 CLI다. Go로 작성된 단일 실행파일이고, openclaw/gogcli 저장소에서 받을 수 있다. 공식 문서는 gogcli.sh에 있다.
여러 도구를 비교해본 끝에 gog를 골랐다. 깃허브 별이 7천 개를 넘고, 터미널·스크립트·코딩 에이전트에서 쓰기 위해 설계됐다는 점, 그리고 인증과 사용이 안정적이라는 후기가 많다는 점이 선택의 이유였다.
다만 gog는 구글 공식 제품이 아니라 서드파티 오픈소스 프로젝트다. 사용 전 저장소와 설치 패키지를 한 번 확인해두는 편이 좋다.
또 하나. gog는 두 가지 방식으로 쓸 수 있다. 하나는 사람이나 스크립트가 터미널에서 gog drive ls 같은 명령을 직접 실행하는 CLI 방식이고, 다른 하나는 에이전트(LLM)가 읽고 알아서 호출하도록 안내하는 에이전트 스킬(SKILL.md) 방식이다. 이번 화에서는 스킬은 붙이지 않고, 모든 것을 CLI 명령으로 직접 확인한다. 에이전트에 물리는 것은 검증이 끝난 뒤의 일이다.
설치
ATOM은 ARM64 아키텍처이므로, 그에 맞는 리눅스 바이너리를 받는다. 받기 전에 파일이 제대로 내려받아졌는지부터 확인하는 습관이 중요하다. URL이 틀리면 “Not Found”라고 적힌 몇 바이트짜리 텍스트 파일이 받아지는데, 그걸 모르고 실행하면 엉뚱한 에러로 한참 헤매게 된다.
cd /tmp
curl -fsSL -o gog.tar.gz "https://github.com/openclaw/gogcli/releases/download/v0.28.0/gogcli_0.28.0_linux_arm64.tar.gz"
file gog.tar.gzfile은 파일의 실제 종류를 알려주는 명령이다. 출력에 gzip compressed data라고 나오면 압축파일을 제대로 받은 것이다. ASCII text라고 나오면 받기에 실패한 것이니 멈춰야 한다.
압축을 풀고 실행 위치로 옮긴다.
tar -xzf gog.tar.gz
sudo mv gog /usr/local/bin/ && sudo chmod +x /usr/local/bin/gog
gog --versiontar -xzf는 gzip 압축된 tar 묶음을 푸는 명령이고, mv로 /usr/local/bin(어디서든 명령으로 부를 수 있는 위치)에 옮긴 뒤 chmod +x로 실행 권한을 준다. 마지막 gog --version에서 버전이 찍히면 설치가 끝난 것이다.
v0.28.0 (6bc67d7d 2026-06-15T...)도구는 준비됐다. 그런데 도구만 있다고 구글 데이터에 접근할 수 있는 건 아니다. 구글에게 “이 도구가 내 데이터를 만질 수 있게 허락한다”는 절차, 즉 OAuth 인증이 필요하다. 여기가 이번 화의 본론이다.
구글 클라우드 프로젝트 만들기
gog 같은 외부 도구가 내 구글 계정 데이터에 접근하려면, 그 통로를 구글 클라우드 콘솔에서 직접 열어줘야 한다. 절차는 세 단계다. ① 프로젝트를 만들고 ② 쓸 API를 켜고 ③ 인증용 자격증명을 발급한다.
구글 클라우드 콘솔에 접속해, 상단 프로젝트 드롭다운에서 새 프로젝트를 만들었다. 이름은 law-local로 했다.
여기서 짚고 갈 개념이 하나 있다. 프로젝트는 “API를 켜두는 그릇”이고, 그 안에 여러 도구가 각자의 자격증명으로 들어와 같은 API를 공유한다. 즉 도구를 새로 붙일 때마다 프로젝트를 새로 만들 필요가 없다. law-local 하나에 API를 켜두면, 앞으로 어떤 도구를 붙이든 그 도구용 자격증명만 발급해 같은 프로젝트에 물리면 된다.
필요한 API 켜기
콘솔의 API 및 서비스 > 라이브러리에서, 앞으로 법무 에이전트가 쓸 만한 API를 미리 켜뒀다. API를 켜는 것 자체는 비용도 위험도 없으니, 용도가 그려지는 것까지 넉넉히 켜두는 편이 나중에 편하다.
- Google Drive API — 스캔 파일을 읽어올 때
- Google Calendar API — 기일을 등록할 때
- Gmail API — 송달·통지 메일을 다룰 때
- Google Docs API — 서면·의견서를 문서 단위로 다룰 때
- Google Sheets API — 사건·기일 관리표를 다룰 때
- Google Tasks API — 마감 할 일을 관리할 때
검색창에서 하나씩 찾아 “사용” 버튼을 눌렀다. 주의할 점은, “drive”로 검색하면 Drive MCP API, Drive Labels API, Drive Activity API 같은 비슷한 이름이 여럿 뜬다는 것이다. 우리가 켤 것은 정확히 Google Drive API처럼 정직한 이름의 카드다. 나머지는 우리 작업과 무관하다.
여기서 구분해둘 점. API를 켜는 것과, 실제로 내 데이터에 접근할 권한(스코프)을 받는 것은 별개다. API는 “이 프로젝트가 이 서비스를 쓸 수 있다”는 선언일 뿐이고, 실제 어디까지 손대는지는 뒤에서 인증할 때 정해진다. 그러니 API는 넉넉히 켜두되, 실제 권한은 필요한 만큼만 받는 것이 안전하다.
OAuth 동의 화면과 클라이언트
API 및 서비스 > OAuth 동의 화면(최신 콘솔에서는 “Google 인증 플랫폼”)으로 들어가 앱 정보를 구성했다. 새 프로젝트라 비어 있어서, 안내에 따라 앱 이름·지원 이메일·사용자 유형(외부)·연락처를 채웠다.
그다음 클라이언트 메뉴에서 OAuth 클라이언트를 만들었다. 여기서 애플리케이션 유형을 고르는데, 반드시 데스크톱 앱을 선택해야 한다. gog는 터미널에서 도는 CLI다. 브라우저로 인증을 받은 뒤 그 결과를 로컬에서 돌려받는 구조인데, 데스크톱 앱 유형이 바로 이 흐름(localhost로 인증 코드를 받는 방식)에 맞게 설계돼 있다. 웹 애플리케이션 유형을 고르면 리디렉션 주소를 직접 등록해야 하는 등 설정이 번거롭고 gog의 방식과도 맞지 않는다.
클라이언트를 만들면 client_id와 client_secret이 표시되고, 그 화면에서 JSON 다운로드 버튼이 뜬다. 이 버튼이 중요하다. 화면을 닫으면 secret을 다시 볼 수 없고, gog에 등록할 것이 바로 이 JSON 파일이기 때문이다. 닫기 전에 반드시 JSON을 받아둬야 한다.
참고로 데스크톱 앱 유형의 client_secret은 구글도 완전한 비밀로 취급하지 않는다. 설치형 앱에 내장돼 배포되는 값이라 본질적으로 추출 가능하다고 보기 때문이다. 그래서 이 secret 하나만으로 누가 계정 데이터에 접근할 수 있는 것은 아니다. 실제 접근에는 본인이 브라우저에서 직접 승인하는 동의 절차와 그 결과로 발급되는 토큰이 따로 필요하다. 그렇더라도 자격증명은 노출되면 교체하는 것이 기본 위생이다.
자격증명을 gog에 등록하기
받은 JSON 파일을 gog에 등록한다. id와 secret을 따로 입력하는 게 아니라, 파일을 통째로 먹이는 방식이다.
gog auth credentials ~/다운로드/client_secret_OOOO.jsonpath /home/rocklassic/.local/share/gogcli/credentials.json
client default
client_secret_in_keyring true마지막 줄 client_secret_in_keyring true가 눈에 띈다. secret이 JSON에 평문으로 남는 게 아니라, 키링에 암호화되어 저장됐다는 뜻이다. gog는 토큰과 secret을 OS 키링에 암호화해 보관한다. 다만 ATOM처럼 화면 없이 SSH로만 붙는 서버 환경에서는 데스크톱용 키링이 없을 수 있어, 파일 기반 키링으로 동작한다. 이 부분은 자동화 단계에서 다시 다룰 일이 있을 것이다.
인증: 브라우저에서 직접 허락하기
이제 실제 인증이다. 내 계정으로 gog에게 접근을 허락하는 단계다.
gog auth add 본인이메일 --services calendar,docs,drive,gmail,sheets,tasks--services에 적은 것이 gog가 요청할 권한 범위다. 앞서 켜둔 API와 맞췄다. 명령을 실행하면 브라우저가 열리고 구글 로그인·동의 화면으로 이어진다.
여기서 처음 보면 당황스러운 화면이 하나 뜬다. **“Google에서 확인하지 않은 앱”**이라는 빨간 경고다. 내가 만든 앱이 아직 구글의 정식 검증을 받지 않았기 때문에 나오는 것이다. 본인이 만든, 본인만 쓰는 앱이므로 안전하다. “고급” → “(앱 이름)으로 이동(안전하지 않음)“을 눌러 통과하면 된다.
동의 화면을 통과하면 브라우저가 127.0.0.1의 콜백 주소로 인증 결과를 받고, “You’re connected — gog is now authorized to access Google Workspace”라는 화면으로 바뀐다. 터미널에도 인증된 계정·서비스가 출력된다.
7일 만료와 프로덕션 전환
인증은 됐지만, 여기서 끝내면 며칠 뒤 다시 인증을 해야 하는 상황이 온다. 이유가 있다.
외부 앱이 테스트 상태이고 구글 검증을 받지 않았을 때는, 발급되는 토큰(refresh token)의 수명이 7일로 제한된다. 7일이 지나면 토큰이 만료돼 처음부터 다시 로그인해야 한다. 한 번 세팅하고 계속 쓸 자동화 도구에서는 곤란한 일이다.
그래서 앱의 게시 상태를 프로덕션으로 올린다. 그러면 이 7일 제한이 사라진다. 콘솔의 대상 메뉴에서 “앱 게시”를 누르면 된다. 이것은 게시 상태만 바꾸는 것이지 구글에 검증을 신청하는 것이 아니다. 검증받지 않은 개인 앱도 프로덕션으로 돌릴 수 있다. 다만 민감한 권한에는 앞서 본 “확인되지 않은 앱” 경고가 계속 따라붙고, 권한을 부여할 수 있는 사용자가 100명으로 제한되는데, 혼자 쓰는 도구이므로 무관하다.
한 가지 더 유의할 점이 있다. 프로덕션으로 올린다고 이미 발급된 토큰이 자동으로 갱신되지는 않는다. 테스트 상태에서 받은 토큰은 여전히 7일 만료가 걸려 있다. 그래서 프로덕션 전환 후에 토큰을 한 번 다시 받아야 한다.
gog auth add 본인이메일 --services calendar,docs,drive,gmail,sheets,tasks --force-consent--force-consent는 동의를 강제로 다시 받게 하는 옵션이다. 이번에는 프로덕션 상태에서 인증하므로, 만료 없는 토큰이 발급되어 기존 것을 덮어쓴다. 인증 URL을 뜯어보면 access_type=offline과 prompt=consent가 들어 있는데, 이것이 “만료되지 않는 갱신용 토큰을 새로 발급받겠다”는 요청이다.
순서가 중요하다. 프로덕션 전환이 먼저, 토큰 재발급이 나중이다. 순서가 바뀌면 여전히 테스트 상태에서 토큰을 받게 되어 7일 만료가 그대로 남는다.
인증이 진짜로 작동하는가
인증이 “됐다”고 말하는 것과, 실제로 내 데이터를 읽어오는 것은 별개다. 검증한다.
gog auth doctor --checkok keyring.open opened
ok tokens 1 readable OAuth token of 1 stored token account
ok refresh.default.본인이메일 refresh token exchange succeededrefresh token exchange succeeded가 핵심이다. 저장된 토큰으로 실제 갱신 교환에 성공했다는 뜻이다. (이와 별개로 config.json (missing)이라는 경고가 뜰 수 있는데, 이는 선택적 설정 파일이 아직 없다는 안내일 뿐 인증과 무관하다.)
그런데 doctor는 “토큰 교환이 된다”까지만 확인한다. 정말로 내 캘린더를 읽어오는지는 직접 호출해 봐야 한다.
gog calendar events 본인캘린더 --from ... --to ...ID START END SUMMARY
67938opp2qag0fiubv3dsu6mc6 2026-06-26 2026-06-27 변리사 강의 듣기내 캘린더에 실제로 들어 있는 일정이 그대로 나왔다. 이것으로 인증이 말뿐이 아니라 실제로 작동한다는 것이 확인됐다. 14화에서 마커 파일로 환각과 진짜 실행을 갈랐던 것과 같은 발상이다 — 실재하는 데이터가 나와야 진짜 호출이라고 믿을 수 있다. 도구가 “연결됐다”고 표시하는 것만으로는 부족하다.
오늘의 정리
- gog는 구글 워크스페이스를 터미널에서 다루는 오픈소스 CLI 도구다(openclaw/gogcli). 구글 공식 제품이 아니며, 이름이 비슷한
gws(googleworkspace/cli)와는 다른 도구다. 에이전트용 스킬도 함께 제공하지만, 이번에는 스킬 없이 CLI를 직접 호출해 검증했다. - OAuth 인증 절차: 구글 클라우드 프로젝트 생성 → 필요한 API 활성화 → 데스크톱 앱 유형으로 OAuth 클라이언트 생성 → JSON을 gog에 등록(
gog auth credentials) → 인증(gog auth add). - 7일 만료와 프로덕션 전환: 외부 앱이 테스트 상태이면 토큰이 7일 만에 만료된다. 게시 상태를 프로덕션으로 올리면 만료가 사라지되, 전환 후
--force-consent로 토큰을 한 번 다시 받아야 한다. 순서는 프로덕션 전환이 먼저다.
이로써 에이전트가 구글 드라이브와 캘린더에 손을 뻗을 열쇠가 마련됐다. 다음 화에서는 이 열쇠로 SCAN 폴더의 기일지정서를 실제로 가져와, 로컬 모델에게 읽히고 캘린더에 일정을 만드는 데까지 가본다.