18. Google을 연결하고 실제 자료로 확인하기
프로그램을 설치하는 것과 연결하는 것은 다릅니다
앞 글에서는 메일과 일정, 시트의 자료를 제 업무와 연결하는 이야기를 했습니다. 이제 실제로 연결할 차례입니다.
카페 POS를 설치했다고 카드 결제가 바로 되는 것은 아닙니다. 단말기를 등록하고 결제할 수 있는 상태로 만들어야 하죠. Google 연결도 비슷합니다. 컴퓨터에 도구를 설치하는 것과, 그 도구가 내 계정의 자료에 접근하도록 허용하는 것은 다른 단계입니다.
이번에는 Google Workspace CLI인 gws를 사용합니다. 예전에 제가 만들었던 인증 프로그램을 그대로 만들 필요는 없습니다. 기존 도구로 연결하고, 원하는 자료를 읽을 수 있는지 확인하겠습니다.
설정 화면이 낯설어도 전체 지도를 먼저 보면 덜 헷갈립니다.
| 단계 | 하는 일 | 무엇을 확인하나 |
|---|---|---|
| 1. 도구 설치 | 컴퓨터에 gws 설치 | 명령을 실행할 수 있는가 |
| 2. 앱 등록 | Google Cloud에서 사용할 API와 앱 설정 | 어떤 앱이 무슨 기능을 요청하는가 |
| 3. 계정 연결 | 브라우저 로그인과 접근 동의 | 어느 계정의 어떤 범위인가 |
| 4. 실제 조회 | 적은 자료로 연결 확인 | 원하는 계정의 자료를 정말 읽었는가 |
AI가 설치 상태를 확인하고 명령과 오류를 해석하도록 도울 수 있습니다. 계정과 앱, 접근 범위는 제가 확인합니다. 처음부터 모든 서비스를 연결하려 하지 말고 필요한 것부터 해보세요. 이 글은 개인 Google 계정에서 읽기부터 시작하는 경로를 기준으로 합니다. 회사 계정은 조직의 앱 사용 정책과 관리자 권한이 관련됩니다.
Step 1. gws를 설치합니다
Orca의 Claude Code에 이렇게 요청할 수 있습니다.
Google Workspace CLI gws를 연결해서 쓰고 싶어.
현재 공식 안내와 내 컴퓨터 환경을 확인하고 설치를 도와줘.
이미 설치돼 있으면 중복 설치하지 말고 버전부터 확인해줘.
로그인과 접근 범위 선택은 내가 확인하면서 진행할게.
설치 방법은 여러 가지입니다. 여기서는 npm이라는 프로그램 설치 도구를 쓰겠습니다. 이 경로에는 Node.js 18 이상이 필요합니다. 새로 설치한다면 Node.js 공식 다운로드의 지원 중인 LTS 버전을 선택하면 됩니다. 어떤 운영체제용 파일을 받아야 하는지 모르겠다면 AI에게 물어보세요.
AI가 설치 상태를 확인할 때 쓰는 명령은 다음과 같습니다. Claude Code 대화 안의 한국어 요청과, 셸에서 실행하는 명령은 구별하면 됩니다. 이미 설치된 것은 다시 설치할 필요가 없습니다.
node --version
npm --version
Node.js와 npm이 준비되면 셸에서 다음 명령으로 설치합니다. AI가 실행하게 해도 됩니다.
npm install -g @googleworkspace/cli
gws --version
@googleworkspace/cli는 설치할 패키지 이름이고, gws는 설치한 뒤 실행할 프로그램 이름입니다. -g는 현재 폴더 안에서만 쓰는 패키지가 아니라 명령으로 사용할 수 있게 설치하는 옵션입니다. 버전이 나오면 프로그램을 실행할 수 있는 상태입니다. 아직 Google 자료에 접근한 것은 아닙니다.
이 프로젝트는 Google 조직의 공개 저장소에 있지만 Google이 공식 지원하는 제품은 아닙니다. 업데이트로 동작이 바뀔 수 있으니 프로젝트 설치·인증 안내를 함께 확인합니다.
gws auth setup이라는 자동 설정도 있습니다. 이 방법은 별도 Google Cloud CLI인 gcloud가 필요합니다. 여기서는 도구를 하나 더 설치하기보다, 브라우저에서 앱을 등록하는 경로로 진행하겠습니다.
Step 2. Google Cloud에 앱을 등록합니다
등록할 것은 ‘내 컴퓨터에서 Google 자료에 접근하는 앱’입니다. 설정은 Google Cloud 프로젝트 안에 묶입니다. 업무 폴더와 이름은 같지만, 여기서 프로젝트는 Google의 API와 인증 설정을 관리하는 단위입니다.
2-1. 프로젝트를 만들고 선택합니다
Google Cloud Console에 로그인합니다. 프로젝트 선택 메뉴에서 새 프로젝트를 만들고, 구별할 수 있는 이름을 붙입니다. 예를 들어 my-workspace-tools처럼 정할 수 있습니다.
만든 뒤에는 상단에서 지금 선택된 프로젝트가 맞는지 확인하세요. 다른 프로젝트에서 API를 켜거나 앱을 만들면 뒤에서 설정이 맞지 않을 수 있습니다. 회사 환경에서 만들 권한이 없다면 관리자에게 확인해야 합니다. 공식 프로젝트 만들기
2-2. 필요한 API를 켭니다
프로젝트에서 API 및 서비스 → 라이브러리로 들어가 필요한 API를 검색하고 ‘사용’을 선택합니다.
이번 예시는 Gmail, Calendar, Drive 읽기입니다.
| 쓸 자료 | 켤 API |
|---|---|
| 메일 | Gmail API |
| 일정 | Google Calendar API |
| 파일 | Google Drive API |
메일만 먼저 볼 분은 Gmail부터 시작해도 됩니다. Sheets나 Tasks는 필요해졌을 때 해당 API와 접근 범위를 추가할 수 있습니다. 모든 서비스를 처음부터 켜야 하는 것은 아닙니다. API 사용 설정 안내
API를 켰다는 것은 프로젝트에서 그 기능을 요청할 준비를 한 것입니다. 제 메일을 읽어도 된다는 동의까지 받은 것은 아닙니다.
2-3. 앱 정보와 사용 대상을 정합니다
Google Auth Platform의 Branding으로 갑니다. 처음이면 Get Started 안내가 나올 수 있습니다. 앱 이름과 지원 이메일, 연락처 정보를 입력하고 사용 대상을 정합니다.
- Branding: 로그인할 때 어떤 앱인지 알아볼 이름과 연락처입니다.
- Audience: 누가 이 앱을 사용할 수 있는지 정합니다.
- Data Access: 어떤 데이터 접근 범위를 요청할지 정합니다.
개인 Gmail 계정으로 시험하는 경우에는 External 대상에서 진행하고, Audience → Test users에 실제로 로그인할 본인 이메일을 추가합니다. 회사 메일이라는 이유만으로 무조건 Internal을 선택하는 것은 아닙니다. 프로젝트의 조직과 허용된 사용자 범위에 맞춰야 합니다.
이 설정은 ‘안전한 앱이라는 인증서’를 만드는 과정이 아닙니다. 앱의 정체와 사용 대상, 요청 범위를 알리는 것입니다. 현재 동의 화면 설정 안내
2-4. 읽을 범위를 정합니다
Data Access → Add or Remove Scopes에서 필요한 범위를 고릅니다. 범위, 즉 scope는 ‘어떤 자료를 어느 수준까지 쓸 것인가’를 나타냅니다.
이번처럼 메일·일정·파일을 읽을 때 참고할 대표 범위는 다음과 같습니다.
https://www.googleapis.com/auth/gmail.readonly
https://www.googleapis.com/auth/calendar.readonly
https://www.googleapis.com/auth/drive.readonly
readonly는 읽기 범위입니다. 쓰지 않을 서비스까지 한꺼번에 고르거나 수정·발송 권한을 추가할 필요는 없습니다. 뒤에서 gws로 로그인할 때도 필요한 서비스와 읽기 범위를 선택해 두 설정을 맞춥니다.
API 활성화, 앱이 요청하는 범위, 사용자가 동의한 권한은 서로 관련되지만 같은 설정은 아닙니다. 읽으려는 파일이 다른 사람 소유라면 그 계정에 공유돼 있는지도 별도 조건입니다.
2-5. Desktop app 클라이언트를 만듭니다
Google Auth Platform → Clients → Create Client에서 Desktop app을 선택하고 구별할 이름으로 만듭니다. 클라이언트 설정 JSON을 다운로드합니다. 화면 문구나 위치는 언어와 업데이트에 따라 조금 달라질 수 있습니다. Desktop 앱 인증 정보 만들기
이 파일은 ‘어떤 앱의 요청인가’를 식별하는 설정입니다. 사용자 본인이 Google 계정 접근에 동의하는 과정은 다음 단계에 있습니다. JSON을 받았다는 것만으로 메일을 읽을 수 있는 것은 아닙니다.
gws의 기본 파일 이름과 위치는 다음과 같습니다.
~/.config/gws/client_secret.json
경로를 외워 직접 옮길 필요는 없습니다. Claude Code에게 다운로드한 파일을 gws가 읽을 위치에 정리해달라고 하면 됩니다. 기존 파일이 있다면 어떤 설정인지 확인한 뒤 처리하게 하세요.
방금 Desktop app의 클라이언트 JSON을 다운로드했어.
gws 공식 안내의 로컬 설정 위치에 맞춰 정리해줘.
기존 설정이 있으면 덮어쓰기 전에 알려줘.
파일 안의 비밀 값이나 인증 정보는 대화에 출력하지 마.
이 파일이나 나중에 생성될 인증 정보는 일반 업무 자료나 공유 저장소에 넣지 않습니다. 내용 전체를 대화에 붙여넣을 필요도 없습니다. gws 수동 OAuth 설정
Step 3. 계정에 로그인하고 동의합니다
앱 등록을 마쳤다면 gws로 로그인합니다. 이 명령은 브라우저 로그인과 접근 동의가 일어나는 명령입니다.
gws auth login --readonly -s gmail,calendar,drive
--readonly는 읽기 범위를 요청하고, -s 뒤에는 필요한 서비스만 적습니다. Gmail만 시작한다면 -s gmail로 줄이면 됩니다. 이것이 이미 다른 연결에 준 쓰기 권한까지 자동 회수한다는 뜻은 아닙니다.
브라우저가 열리면 사용할 계정과 앱 이름, 요청 범위를 확인합니다. 테스트 사용자로 넣은 이메일과 실제 로그인 계정도 맞아야 합니다. 모든 항목을 무조건 선택하는 대신 의도한 범위인지 보고 동의합니다.
검증되지 않은 앱이라는 경고가 나오면 등록한 앱과 클라이언트가 맞는지 확인하세요. 본인이 만들었다는 이유만으로 어떤 권한이든 안전한 것은 아닙니다. 회사 정책으로 차단된 경우도 우회하기보다 관리자 안내를 받아야 합니다.
로그인 결과는 컴퓨터에서 기다리는 gws로 돌아옵니다. 현재 Desktop 흐름에서는 로컬 콜백을 사용하므로, 예전 방식처럼 Google 인증 코드를 복사해 AI 대화에 붙일 필요는 없습니다. 브라우저가 자동으로 열리지 않으면 gws가 안내한 주소를 직접 엽니다. Google Desktop OAuth 흐름
OAuth의 접근 토큰은 동의한 범위로 API를 요청할 때 쓰는 자격입니다. AI 모델의 글자 사용량을 셀 때 말하는 토큰과는 다른 의미입니다. gws가 이 자격을 관리합니다. 비밀번호나 접근 토큰을 채팅에 적어주며 연결하는 방식이 아닙니다.
Step 4. 실제 자료로 확인합니다
로그인 안내가 끝났다고 모든 기능을 확인한 것은 아닙니다. 원하는 계정에서 적은 자료부터 읽어봅니다.
방금 연결한 gws로 내 메일 목록을 3개만 확인해줘.
보낸 사람과 제목을 확인할 만큼만 읽고, 본문 전체는 아직 읽지 마.
연결한 계정이 맞는지도 확인해줘. 메일을 수정하거나 보내지는 마.
메일 목록과 본문은 다릅니다. 내부에서 어떤 요청이 오가는지 보면 이해하기 쉽습니다. 아래는 명령 형식을 설명하는 Mac의 Bash/Zsh 기준 예시입니다. Windows 등 자기 셸에 맞는 실행은 AI에게 맡겨도 됩니다.
gws gmail users messages list --params '{"userId":"me","maxResults":3}'
gmail users messages list는 메일 목록을 요청합니다. --params 뒤의 JSON에서 userId: "me"는 인증한 사용자, maxResults: 3은 한 페이지에서 최대 3개를 뜻합니다.
다음은 설명을 위한 가상 응답입니다. 실제 계정에서 가져온 결과가 아닙니다.
{
"messages": [
{"id": "example-message-id", "threadId": "example-thread-id"}
],
"nextPageToken": "example-next-page-token"
}
목록에는 메시지의 id와 대화 묶음의 threadId가 들어갑니다. 이것만으로 발신자나 본문을 읽었다고 할 수는 없습니다. nextPageToken이 있으면 더 가져올 페이지가 있다는 뜻입니다. ‘3개를 봤다’와 ‘전체 메일을 확인했다’도 다릅니다. Gmail 목록 요청
선택한 메시지의 제목과 발신자 같은 헤더를 읽으려면 상세 요청을 합니다.
gws gmail users messages get --params '{"userId":"me","id":"example-message-id","format":"metadata"}'
여기서 example-message-id는 위 가상 예시의 자리표시자입니다. 실제로는 목록에서 받은 ID를 사용합니다. metadata는 헤더 중심의 정보를 확인하는 형식이고 본문 전체를 읽는 것과는 다릅니다. 나중에 업무상 본문이 필요하면 필요한 메일을 선택해 추가로 읽게 하면 됩니다. Gmail 상세 요청
명령을 외우는 것이 목적은 아닙니다. AI가 무엇을 요청했고 어디까지 확인했는지 구별할 수 있으면 됩니다.
일정과 파일도 각각 확인합니다
연결한 서비스만 읽어봅니다. Calendar라면 오늘 일정, Drive라면 본인이 알고 있는 파일 한 개부터 확인하면 됩니다. 어떤 계정과 기간, 어떤 파일을 읽었는지 함께 봅니다.
일정이나 파일이 없다는 정상 결과가 나올 수도 있습니다. 오류 때문에 못 읽은 것과 자료가 없는 것은 다릅니다. 예상했던 파일이 안 보인다면 계정, 공유 권한, 검색 범위, 다음 페이지 여부를 확인합니다.
Gmail 하나가 됐다고 Sheets나 Tasks, 수정·발송까지 모두 성공한 것은 아닙니다. 이번에 읽기를 확인했다면 그 범위에서 다음 업무를 시작하면 됩니다.
막히면 어느 단계인지부터 봅니다
수업에서도 설치나 인증 결과가 영어로 나오면 혼자 해석하려 하지 말고 AI에게 현재 상태를 물어보게 합니다. ‘안 돼’에서 멈추는 대신 어떤 단계까지 됐는지 같이 보는 겁니다.
이 오류가 어느 단계의 문제인지 설명해줘.
설치, 앱 등록, 로그인 동의, 실제 자료 조회 중 어디까지 된 건지 확인하고,
기존 설정을 지우거나 권한을 넓히기 전에 원인부터 찾아줘.
오류 문구를 전달할 때 비밀 값과 인증 토큰은 빼세요. 대표적으로는 다음을 확인할 수 있습니다.
| 상황 | 먼저 볼 것 |
|---|---|
| gws 명령을 못 찾음 | 설치 완료 여부, 새 터미널, 실행 파일 위치 |
| 클라이언트 JSON을 못 찾음 | 파일 이름·위치, 다른 환경에 저장한 것은 아닌지 |
| Access blocked / 403 | 로그인 계정·테스트 사용자·요청 범위·조직 정책 |
| redirect 관련 오류 | Desktop 클라이언트와 실제 로그인 흐름이 맞는지 |
| API not enabled | 해당 클라이언트의 프로젝트에서 필요한 API를 켰는지 |
| 조회는 됐지만 자료가 안 보임 | 계정·공유 권한·조회 조건·페이지 범위 |
비슷한 오류 이름이라도 원인이 하나로 정해지지는 않습니다. 앱이나 토큰을 무조건 삭제하고 다시 만드는 것보다 현재 요청과 설정을 대조하는 게 먼저입니다.
한 번 연결하면 계속 쓸 수 있나요?
접근 토큰의 유효 기간이 끝나면 갱신 자격을 사용해 새로 받아오는 과정이 있습니다. 하지만 계정에서 권한을 철회하거나 정책이 바뀌면 다시 로그인해야 할 수 있습니다.
특히 External 앱을 Testing 상태로 두고 Gmail 같은 범위를 요청하면 갱신 토큰에 7일 만료 조건이 있습니다. 파일이 남아 있다고 영구 연결되는 것은 아닙니다. 다시 동의가 필요한 상태인지와 앱 등록 자체가 잘못된 상태인지를 구별하세요. Google 토큰 만료 조건
사용하지 않을 때는 Google 계정의 연결된 앱 관리에서 접근을 철회할 수 있습니다. 나중에 쓰기 기능이 필요해지면 그때 필요한 범위를 검토해서 연결을 갱신하면 됩니다.
연결 뒤 자료는 어디로 가나요?
로컬의 gws가 Google API에 요청하는 것과, 받은 내용을 Claude 모델이 처리하는 것은 다른 경로입니다. 메일 내용이나 문서를 모델이 읽으면 그 자료가 모델 서비스에 전달될 수 있습니다. 로컬에서 실행한다는 이유로 모든 처리가 컴퓨터 안에서만 이뤄지는 것은 아닙니다. Claude Code 데이터 흐름
업무 자료를 쓸 때는 계정과 접근 권한뿐 아니라 회사의 자료 처리 기준에도 맞춰야 합니다. 처음부터 전체 메일함을 읽게 하기보다 필요한 자료와 범위를 정하는 이유이기도 합니다.
연결을 확인했다면
이번에 한 일은 프로그램 설치, 앱 등록, 사용자 동의, 실제 조회입니다. 이 네 단계가 구분되면 어디서 막혔는지, 무엇을 더 확인해야 하는지도 보입니다.
이제 ‘메일을 읽을 수 있나?’에서 ‘이 자료로 무슨 일을 할까?’로 넘어갈 차례입니다. 매번 같은 방식으로 확인하고 정리하는 일이 생기면 그 절차와 판단을 남길 수 있습니다.
다음으로는 반복하는 업무 방식을 스킬로 정리한다는 것이 무엇인지 살펴보겠습니다. 기존 번호로는 12편입니다. 지금은 외부 연결을 먼저 익힌 뒤 스킬로 넘어가는 추천 순서로 읽고 있습니다.