Claude Code는 로컬 셸에서 Google Workspace CLI(gws) 명령을 실행할 수 있으며, gws에서 인증한 Google 계정을 사용합니다. 권한을 가진 계정 소유자는 Drive, Sheets, Docs, Gmail에 각각 준비한 무해한 기록 하나로 연결을 확인할 수 있습니다. 먼저 계정과 승인 범위를 확인하세요. 이 가이드는 2026년 10월 20일 확인한 CLI 저장소의 문서화된 인터페이스를 따릅니다. BIG CHANGE는 두 도구를 설치하거나 계정에 접근하지 않았습니다.

핵심 변화

  • 달라진 점: 현재 gws CLI는 Google Workspace API 메서드를 Claude Code가 실행할 수 있는 셸 명령으로 제공합니다. 인증된 계정 하나로 여러 업무 서비스에 접근할 수 있지만, 실제 승인 범위와 에이전트의 셸 권한이 적용됩니다.
  • 중요한 이유: 선택한 파일이나 메시지를 확인하는 연결은 OAuth 범위에 포함되는 다른 데이터에도 접근할 수 있습니다. 계정 소유자는 더 많은 업무를 위임하기 전에 터미널과 Claude Code에서 알려진 소량의 결과를 비교할 수 있습니다.
  • 주의할 점: 설정이 바뀔 때마다 설치된 CLI가 생성한 명령과 세션에 실제 적용되는 권한 규칙을 확인하세요. CLI는 아직 1.0 이전 버전입니다. 좁은 예제 쿼리나 필드 마스크가 계정 전체의 승인 범위를 줄여 주지는 않습니다.

연결 전 준비

민감한 내용이 없는 전용 승인된 Google 테스트 계정과 OAuth를 설정할 권한이 있는 Cloud 프로젝트를 사용하세요. 네 가지 API와 요청할 승인이 허용되는지 관리자에게 확인하세요. 이름이 고유한 기존 Drive 파일, 작은 범위에 알려진 값을 넣은 스프레드시트, 탭 하나의 짧은 일반 텍스트 Google Doc, 무해한 Gmail 메시지를 준비하세요. Gmail에서는 메시지의 RFC Message-ID를 Show original에서 확보하세요. 이 원본들을 CLI 결과와 비교합니다. 이 검사에서는 아무것도 만들거나 보내지 않습니다.

통제할 수 있는 컴퓨터에 Claude Code를 설치하세요. gws는 운영체제에 맞는 저장소 릴리스에서 설치하거나, Node.js 18 이상이 있으면 문서의 명령을 사용하세요.

Terminal
npm install -g @googleworkspace/cli
gws --version
gws --help
gws auth login --help

설치한 CLI와 Claude Code 버전을 비공개로 기록하세요. CLI는 아직 1.0 이전이며 Google API 검색 문서에서 명령을 생성합니다. 예제를 실행하기 전에 설치된 도움말과 아래 메서드 스키마를 확인하세요.

1. 제한된 OAuth 로그인 설정하기

승인된 Cloud 프로젝트에서 Drive, Sheets, Docs, Gmail API를 사용 설정하세요. OAuth 대상을 설정하고 Desktop app 클라이언트를 만드세요. 앱이 External이며 테스트 중이라면 선택한 계정을 테스트 사용자로 추가하세요. 다운로드한 클라이언트 JSON을 문서에 나온 ~/.config/gws/client_secret.json 위치에 저장하거나 GOOGLE_WORKSPACE_CLI_CONFIG_DIR로 선택한 별도 디렉터리를 사용하세요. 그 디렉터리는 Claude 프로젝트 밖에 두고 계정 소유자만 접근할 수 있게 하세요.

로그인 전에 GOOGLE_WORKSPACE_CLI_TOKEN 또는 GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE가 설정되어 있는지 비공개로 확인하세요. .env 파일을 통한 설정도 포함합니다. 이 출처들은 저장된 OAuth 자격 증명보다 우선합니다. 값을 출력하거나 Claude Code에 자격 증명 파일을 읽도록 요청하지 마세요. 불필요한 설정이 없는 환경과 의도한 클라이언트 구성을 사용하세요.

다음 네 가지 범위를 명시적으로 요청하세요.

Terminal
gws auth login --scopes 'https://www.googleapis.com/auth/drive.metadata.readonly,https://www.googleapis.com/auth/spreadsheets.readonly,https://www.googleapis.com/auth/documents.readonly,https://www.googleapis.com/auth/gmail.readonly'
gws auth status

계정 선택과 동의는 직접 완료하세요. 고정한 버전의 CLI 소스는 식별 범위인 openid, userinfo.email, userinfo.profile 도 추가합니다. 동의 화면과 gws auth status의 계정, 승인 범위, 토큰 유효성을 의도한 내용과 비공개로 비교하세요. 상태 필드가 없으면 미검증으로 남습니다. 계정이 다르거나 예상치 못한 더 넓은 승인이 남으면 중단하세요. 로그인 선택기에서 서비스를 고르는 것은 선택지를 거르는 작업이지, 이 네 가지 읽기 전용 범위를 설정하는 작업이 아닙니다.

승인 범위는 예제 요청보다 넓습니다. Drive 메타데이터 권한은 접근 가능한 파일의 메타데이터에, Sheets와 Docs 읽기 전용 권한은 접근 가능한 스프레드시트와 문서에 적용되며, Gmail 읽기 전용 권한은 메일함 내용에 접근할 수 있습니다. 이름, ID, 셀 범위, 쿼리, 필드 마스크는 개별 응답을 제한할 뿐 토큰 권한을 줄이지 않습니다. 셸 도구는 로컬 자격 증명에도 접근할 수 있으므로 파일 경로를 숨기거나 프롬프트로 지시하는 것만으로 격리할 수 없습니다.

2. 제한된 읽기를 직접 실행하기

먼저 각 메서드를 gws schema drive.files.list로 살펴보고, 다른 메서드에는 해당 스키마 이름을 사용하세요. 설치된 버전에서 매개변수가 다르면 생성된 --help를 확인하세요. 아래 명령은 Bash 작은따옴표 문법을 사용합니다. 다른 셸에서는 따옴표 처리를 의식적으로 조정하세요. 테스트 식별자와 이름만 바꾸세요. 한 번에 명령 하나를 실행하고 실제 응답이나 오류를 토큰과 민감한 내용 없이 비공개로 보관하세요.

이름으로 Drive 파일을 찾으세요. JSON의 \u0027는 Bash 따옴표 구조를 유지하면서 Drive 검색식 안의 아포스트로피를 이스케이프합니다.

Terminal
gws drive files list --params '{"pageSize":5,"q":"trashed = false and name = \u0027GWS connection check\u0027","fields":"files(id,name,mimeType),nextPageToken,incompleteSearch"}'

반환된 ID와 이름을 Drive 파일과 비교하세요. 일치 항목이 없거나 incompleteSearch가 있으면 의도한 파일에 접근했다는 증거가 아닙니다.

실제 스프레드시트 ID와 탭 이름으로 알려진 셀을 읽으세요.

Terminal
gws sheets spreadsheets values get --params '{"spreadsheetId":"SPREADSHEET_ID","range":"Sheet1!A1:C3","fields":"range,majorDimension,values"}'

반환된 값을 스프레드시트와 비교하세요. Google은 뒤쪽 빈 셀을 생략할 수 있으므로 비어 있지 않은 알려진 값을 준비하세요.

짧은 테스트 문서의 첫 번째 탭을 읽으세요.

Terminal
gws docs documents get --params '{"documentId":"DOCUMENT_ID","includeTabsContent":false,"fields":"documentId,title,body(content(paragraph(elements(textRun(content)))))"}'

ID, 제목, 알려진 텍스트를 대조하세요. 이 제한된 응답은 다른 탭, 댓글, 문서 전체 구조를 검사하지 않습니다.

Gmail에서는 기존 메시지의 RFC Message-ID로 검색한 다음 반환된 Gmail ID를 사용해 헤더 두 개를 요청하세요.

Terminal
gws gmail users messages list --params '{"userId":"me","maxResults":1,"q":"rfc822msgid:MESSAGE_ID_FROM_SHOW_ORIGINAL","fields":"messages(id,threadId),nextPageToken,resultSizeEstimate"}'
gws gmail users messages get --params '{"userId":"me","id":"GMAIL_MESSAGE_ID","format":"metadata","metadataHeaders":["Message-ID","Subject"],"fields":"id,threadId,payload(headers)"}'

반환된 Message-ID와 무해한 제목을 원본과 비교하세요. 첫 호출은 헤더가 아니라 메시지 ID를 반환합니다. 두 번째는 본문이 아니라 헤더 메타데이터를 요청합니다. 첫 응답이 비어 있으면 두 번째 검사를 진행할 수 없습니다. 더 좁은 Gmail 메타데이터 OAuth 범위는 이 검색 쿼리를 허용하지 않지만, 명시적인 Gmail 읽기 전용 승인은 허용합니다.

3. Claude Code에서 권한 요청과 함께 반복하기

동일한 승인된 계정 구성으로 직접 통제하는 프로젝트에서 Claude Code를 시작하세요. /permissions에서 실제 모드와 셸 규칙을 확인하세요. Manual(default라고도 함)과 실제 셸 도구에 대한 Ask 규칙을 사용하세요. 더 넓은 허용 또는 우회 규칙은 조직 정책에 따라 해소하세요. gws * 또는 셸 래퍼에 일괄 승인을 주지 마세요. 제안된 명령마다 전체 내용을 확인하고 의도한 제한적 읽기만 승인하세요.

Claude Code에 일상적인 말로 동일한 테스트 대상을 사용해 위 다섯 명령을 제안하고, 본인의 권한 결정 후에만 하나씩 실행하라고 요청하세요. 자격 증명을 읽거나 쿼리를 넓히거나 쓰기를 실행하지 않고 출력 또는 오류를 보고하도록 하세요. 각 결과를 직접 실행한 결과와 원본 객체 모두에 대조하세요. 프로젝트 지침은 작업을 설명할 수 있지만, 접근을 결정하는 것은 실제 도구 권한과 OAuth 승인입니다.

서비스

두 경로에서 필요한 완료 증거

Drive

같은 파일 ID와 이름, 완전한 검색.

Sheets

예상한 탭, 범위, 알려진 셀 값.

Docs

예상한 ID, 제목, 첫 번째 탭의 텍스트.

Gmail

목록에서 테스트 메시지를 찾고, 메타데이터 조회가 메시지의 Message-ID 및 제목과 일치함.

버전, 인증된 계정, 실제 승인 범위, 대상 ID, 직접 실행 결과, Claude 결과, 오류를 비공개 점검표에 기록하세요. 실패한 요청, 성공했지만 빈 응답, 검증된 객체는 서로 다른 결과입니다. 네 서비스 모두 두 경로에서 검증되어야 완료입니다.

검사가 실패하면

로그인할 때 Access blocked 오류가 나타나면 테스트 계정이 OAuth 앱의 테스트 사용자 목록에 없을 수 있습니다. API 또는 범위 오류에서는 승인된 재동의를 요청하기 전에 사용 설정된 API, 선택한 계정, 실제 승인을 확인하세요. 목록이 비어 있으면 정확한 대상, 쿼리, 계정을 확인하세요. 설치된 도움말이 예제와 다르면 현재 메서드 스키마를 먼저 사용하세요. Claude Code가 데이터를 바꾸거나 접근 범위를 넓히는 명령을 제안하면 권한 요청에서 거부하고 제한된 읽기로 돌아가세요.

CLI 저장소는 유료 패키지 없이 이용할 수 있습니다. 계정 또는 Workspace 요금제, Cloud 할당량, Claude Code 요금제나 API 사용에는 비용이 생길 수 있습니다. 가져온 내용은 Claude Code에 설정된 제공업체에서 처리될 수 있으므로 승인된 비민감 테스트 데이터만 사용하세요. CLI는 Google의 공식 지원 제품이 아니라고 명시하며 1.0 이전 변경을 경고합니다. BIG CHANGE는 성능이나 호환성을 테스트하지 않았습니다. 쓰기, 전송, 계정 변경 전에 중단하세요. Claude의 별도 Google Workspace 부가기능은 다른 경로를 통해 승인받고 열린 파일을 편집하는 방법을 다룹니다.