Edição em Markdown

AI-translated from English; not yet reviewed by a fluent editor.

# Conecte o Claude Code ao Google Workspace com cinco verificações de leitura

> Uma configuração documentada para verificar a conta do Google Workspace CLI usada pelo Claude Code, as autorizações OAuth e os pedidos de permissão com leituras delimitadas no Drive, Sheets, Docs e Gmail.

By BIG CHANGE Editorial

Published: 2026-10-20T09:34:40.461Z
Updated: 2026-10-20T09:34:40.461Z
Canonical: https://bigchange.ai/blog/claude-code-google-workspace-cli-read-checks

![Conceptual charcoal illustration of one person studying abstract command lines on a desktop monitor, with a plain folder, grid sheet, document and sealed envelope on the table.](https://bigchange.ai/api/media/file/gws-claude-read-check-workstation-hero-v1.png)
AI-generated conceptual illustration by BIG CHANGE.

O Claude Code pode executar comandos do Google Workspace CLI (`gws`) em um shell local, usando a conta Google autenticada no `gws`. O titular autorizado da conta pode verificar a conexão com um registro inofensivo em cada serviço: Drive, Sheets, Docs e Gmail. Primeiro, confirme a conta e as autorizações. Este guia segue a interface documentada do repositório do CLI, examinada em 20 de outubro de 2026. O BIG CHANGE não instalou nenhuma das duas ferramentas nem acessou uma conta.

## A grande mudança

- **O que mudou:** O CLI `gws` atual disponibiliza métodos das APIs do Google Workspace como comandos de shell que o Claude Code pode executar. Uma conta autenticada pode oferecer acesso a vários serviços de trabalho, sujeito às autorizações reais e às permissões de shell do agente.
- **Por que isso importa:** A mesma conexão que permite ao agente consultar um arquivo ou mensagem selecionada pode alcançar outros dados cobertos pelos escopos OAuth. O titular pode comparar resultados pequenos e conhecidos no terminal e no Claude Code antes de decidir delegar mais trabalho.
- **O que observar:** Confira os comandos gerados pelo CLI instalado e as regras de permissão efetivas da sessão sempre que essa configuração mudar. O CLI ainda é anterior à versão 1.0; uma consulta de exemplo restrita ou uma máscara de campos não reduz a autorização da conta inteira.

## Antes de conectar

Use uma conta de teste Google dedicada e aprovada, sem conteúdo sensível, e um projeto Cloud em que você possa configurar OAuth. Pergunte ao administrador se as quatro APIs e as autorizações solicitadas são permitidas. Prepare um arquivo existente no Drive com nome único, uma planilha com valores conhecidos em um pequeno intervalo, um Google Doc curto de texto simples com uma única aba e uma mensagem inofensiva no Gmail. Para o Gmail, obtenha o identificador RFC `Message-ID` em **Show original**. Você comparará esses originais com os resultados do CLI. As verificações não criam nem enviam nada.

Instale o Claude Code em um computador controlado. Instale `gws` a partir da [versão do repositório para seu sistema operacional](https://github.com/googleworkspace/cli/releases) ou, com Node.js 18 ou posterior, use o comando documentado:

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

Registre em particular as versões instaladas do CLI e do Claude Code. O CLI ainda é anterior à versão 1.0 e gera seus comandos a partir dos documentos de descoberta das APIs do Google. Confira a ajuda instalada e os esquemas dos métodos abaixo antes de executar os exemplos.

## 1. Configure um login OAuth restrito

No projeto Cloud aprovado, ative as APIs do Drive, Sheets, Docs e Gmail. Configure o público do OAuth e crie um cliente **Desktop app**. Se o aplicativo for External e estiver em teste, adicione a conta escolhida como usuário de teste. Salve o JSON baixado do cliente no local documentado `~/.config/gws/client_secret.json` ou use um diretório separado selecionado com `GOOGLE_WORKSPACE_CLI_CONFIG_DIR`. Mantenha esse diretório fora do projeto Claude e acessível somente ao titular da conta.

Antes de entrar, verifique em particular se `GOOGLE_WORKSPACE_CLI_TOKEN` ou `GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE` está definida, inclusive por meio de um arquivo `.env`. Essas fontes têm prioridade sobre as credenciais OAuth armazenadas. Não exiba os valores nem peça ao Claude Code para ler arquivos de credenciais. Use um ambiente limpo e a configuração de cliente pretendida.

Solicite explicitamente estes quatro escopos:

```bash
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
```

Faça pessoalmente a seleção da conta e o consentimento. O código-fonte do CLI na revisão indicada também adiciona os escopos de identidade `openid`, `userinfo.email` e `userinfo.profile`. Compare em particular o consentimento e as informações de `gws auth status` sobre conta, autorizações e validade do token com o que pretendia; um campo de status ausente continua sem verificação. Pare se a conta estiver errada ou restar uma autorização inesperada mais ampla. Selecionar serviços na tela de login filtra opções; isso não define os quatro escopos de somente leitura.

Os escopos são mais amplos que as solicitações de exemplo. O acesso aos metadados do Drive alcança metadados dos arquivos acessíveis; o acesso de somente leitura do Sheets e Docs abrange planilhas e documentos acessíveis; o Gmail de somente leitura pode acessar o conteúdo da caixa postal. Nomes, IDs, intervalos, consultas e máscaras de campos limitam cada resposta, não a autoridade do token. Uma ferramenta de shell também pode alcançar credenciais locais; ocultar um caminho ou escrever uma instrução no prompt não as isola.

## 2. Execute diretamente as leituras delimitadas

Primeiro examine cada método com `gws schema drive.files.list` e os nomes de esquema correspondentes dos demais métodos. Consulte a ajuda gerada `--help` se algum parâmetro for diferente na versão instalada. Os comandos abaixo usam aspas simples do Bash; adapte as aspas de propósito para outro shell. Substitua apenas os identificadores e o nome de teste. Execute um comando por vez e retenha a resposta ou o erro real em particular, sem tokens nem conteúdo sensível.

Localize o arquivo do Drive pelo nome. A sequência JSON `\u0027` escapa os apóstrofos na expressão de busca do Drive preservando as aspas do Bash:

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

Compare o ID e o nome com o arquivo no Drive. Uma correspondência ausente ou `incompleteSearch` não comprova acesso ao arquivo pretendido.

Leia as células conhecidas usando o ID real da planilha e o nome da aba:

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

Compare os valores retornados com a planilha. O Google pode omitir células vazias ao final; prepare valores conhecidos não vazios.

Leia a primeira aba do documento de teste curto:

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

Confira o ID, o título e o texto conhecido. Essa resposta limitada não verifica outras abas, comentários ou a estrutura completa do documento.

No Gmail, busque pelo identificador RFC `Message-ID` da mensagem existente e use o ID do Gmail retornado para solicitar dois cabeçalhos:

```bash
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)"}'
```

Compare o `Message-ID` retornado e o assunto inofensivo com o original. A primeira chamada retorna IDs de mensagens, não cabeçalhos. A segunda solicita metadados dos cabeçalhos, não o corpo da mensagem. Uma primeira resposta vazia não permite a segunda verificação. O escopo OAuth mais restrito de metadados do Gmail não permite a consulta de busca usada aqui; a autorização explícita de somente leitura do Gmail permite.

## 3. Repita pelo Claude Code com pedidos de permissão

Inicie o Claude Code em um projeto sob seu controle, com a mesma configuração de conta aprovada. Em `/permissions`, examine o modo efetivo e as regras do shell. Use Manual (também chamado `default`) e uma regra **Ask** para a ferramenta de shell real; resolva regras mais amplas de autorização ou desvio de controles conforme a política da organização. Evite aprovação geral para `gws *` ou para um programa que envolva o shell. A cada comando proposto, confira o comando completo e aprove apenas a leitura delimitada pretendida.

Peça ao Claude Code, em linguagem comum, que proponha os cinco comandos acima com os mesmos alvos de teste e os execute um por vez, somente após sua decisão de permissão. Solicite a saída ou os erros sem ler credenciais, ampliar consultas ou executar gravações. Compare cada resultado com o resultado direto e com o objeto original. As instruções do projeto podem descrever a tarefa, mas as permissões efetivas das ferramentas e as autorizações OAuth determinam o acesso.

| Serviço | Evidência de conclusão pelas duas rotas |
| --- | --- |
| Drive | Mesmo ID e nome de arquivo; busca completa. |
| Sheets | Aba, intervalo e valores de células conhecidos esperados. |
| Docs | ID, título e texto da primeira aba esperados. |
| Gmail | A lista encontra a mensagem de teste; a consulta de metadados corresponde ao seu `Message-ID` e assunto. |

Registre versões, conta autenticada, autorizações reais, IDs dos alvos, resultado direto, resultado do Claude e erros em uma ficha privada. Uma solicitação que falhou, uma resposta bem-sucedida vazia e um objeto verificado são resultados diferentes. Conclua apenas quando os quatro serviços forem verificados pelas duas rotas.

## Se uma verificação falhar

Um erro **Access blocked** no login pode significar que falta a conta na lista de usuários de teste do aplicativo OAuth. Em caso de erro de API ou escopo, confirme a API ativada, a conta selecionada e as autorizações reais antes de pedir um novo consentimento aprovado. Para uma lista vazia, confira o alvo exato, a consulta e a conta. Se a ajuda instalada diferir destes exemplos, use o esquema atual do método antes de continuar. Se o Claude Code propuser um comando que altere dados ou amplie o acesso, recuse no pedido de permissão e retorne à leitura delimitada.

O repositório do CLI está disponível sem um pacote pago. A conta ou o plano Workspace, as cotas Cloud e o plano Claude Code ou o uso da API podem gerar custos. O conteúdo obtido pode ser processado pelo provedor configurado no Claude Code; mantenha os testes em dados aprovados e não sensíveis. O CLI informa que não é um produto Google com suporte oficial e alerta sobre mudanças anteriores à versão 1.0. O BIG CHANGE não testou desempenho ou compatibilidade. Pare antes de qualquer gravação, envio ou alteração da conta. [O complemento separado do Google Workspace do Claude](https://bigchange.ai/blog/claude-google-workspace-add-on-edit-open-files) trata da edição de arquivos abertos com aprovação por outra rota.

## Sources

- [README do Google Workspace CLI](https://github.com/googleworkspace/cli/blob/a3768d0e82ad83cca2da97724e46bea4ff0e6dbd/README.md) — Repositório oficial em revisão fixa, examinado em 20 de outubro de 2026. Documenta instalação, configuração manual de OAuth, comandos dinâmicos, prioridade de credenciais, instabilidade de versões e aviso de produto sem suporte oficial. Não comprova um resultado de execução do BIG CHANGE.
- [Contexto de comandos do Google Workspace CLI](https://github.com/googleworkspace/cli/blob/a3768d0e82ad83cca2da97724e46bea4ff0e6dbd/CONTEXT.md) — Orientações oficiais em revisão fixa para métodos aninhados, --params, inspeção de esquemas e seleção limitada de campos; é necessário conferir a ajuda realmente instalada.
- [Implementação de autenticação do Google Workspace CLI](https://github.com/googleworkspace/cli/blob/a3768d0e82ad83cca2da97724e46bea4ff0e6dbd/crates/google-workspace-cli/src/auth_commands.rs) — O código de autenticação fixado confirma --scopes personalizados, o comportamento separado do seletor de serviços e os escopos de identidade acrescentados. Inspecionar o código não revela a autorização real de um leitor.
- [Guia de ativação das APIs do Google Workspace](https://developers.google.com/workspace/guides/enable-apis) — Instruções do Google para ativar APIs em um projeto Cloud; as políticas do projeto e do administrador continuam determinando o acesso.
- [Referência de Drive files.list](https://developers.google.com/workspace/drive/api/reference/rest/v3/files/list) — Confirma Drive q, pageSize e os campos de resposta usados para limitar a busca de metadados. Uma solicitação restrita não reduz a autoridade OAuth.
- [Referência de Sheets spreadsheets.values.get](https://developers.google.com/workspace/sheets/api/reference/rest/v4/spreadsheets.values/get) — Confirma a leitura pelo ID da planilha e pelo intervalo A1 e o formato de resposta; células vazias ao final podem ser omitidas.
- [Referência de Docs documents.get](https://developers.google.com/workspace/docs/api/reference/rest/v1/documents/get) — Confirma a recuperação do documento e a limitação à primeira aba quando includeTabsContent é false. O exemplo é para um documento de teste de texto simples com uma única aba.
- [Referências de Gmail messages.list e messages.get](https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.messages/list) — A referência list estabelece a busca por ID de mensagem e resultados contendo apenas IDs; q não está disponível com gmail.metadata. A referência get associada é https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.messages/get e estabelece metadataHeaders com o formato METADATA.
- [Permissões do Claude Code](https://code.claude.com/docs/en/permissions) — Referência atual da Anthropic para o modo Manual/default, regras Ask, permissões efetivas das ferramentas e pedidos de aprovação do shell. Não demonstra que uma sessão do leitor tenha determinada regra.