Edição Markdown

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

# Ligue 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 através de 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`) numa shell local, utilizando a conta Google autenticada no `gws`. O titular autorizado da conta pode verificar a ligação com um registo 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 ferramentas nem acedeu a uma conta.

## A grande mudança

- **O que mudou:** O CLI `gws` atual disponibiliza métodos das API do Google Workspace como comandos de shell que o Claude Code pode executar. Uma conta autenticada pode permitir acesso a vários serviços de trabalho, sujeito às autorizações efetivas e às permissões da shell do agente.
- **Porque é importante:** A mesma ligação que permite ao agente consultar um ficheiro ou mensagem selecionada pode alcançar outros dados abrangidos pelos âmbitos OAuth. O titular da conta pode comparar resultados pequenos e conhecidos no terminal e no Claude Code antes de decidir delegar mais trabalho.
- **O que vigiar:** Verifique os comandos gerados pelo CLI instalado e as regras de permissão efetivas da sessão sempre que esta 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 de toda a conta.

## Antes de ligar

Utilize uma conta de teste Google dedicada e aprovada, sem conteúdo sensível, e um projeto Cloud onde possa configurar OAuth. Pergunte ao administrador se as quatro API e as autorizações pedidas são permitidas. Prepare um ficheiro existente no Drive com nome único, uma folha de cálculo com valores conhecidos num pequeno intervalo, um Google Doc curto de texto simples com um único separador e uma mensagem inofensiva no Gmail. Para o Gmail, obtenha o identificador RFC `Message-ID` em **Show original**. Irá comparar estes originais com os resultados do CLI. Estas verificações não criam nem enviam nada.

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

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

Registe em privado as versões instaladas do CLI e do Claude Code. O CLI continua a ser anterior à versão 1.0 e gera os comandos a partir dos documentos de descoberta das API do Google. Consulte a ajuda instalada e os esquemas dos métodos seguintes antes de executar os exemplos.

## 1. Configure um início de sessão OAuth restrito

No projeto Cloud aprovado, ative as API do Drive, Sheets, Docs e Gmail. Configure o público OAuth e crie um cliente **Desktop app**. Se a aplicação for External e estiver em testes, adicione a conta escolhida como utilizador de teste. Guarde o JSON transferido do cliente no local documentado `~/.config/gws/client_secret.json` ou utilize um diretório separado selecionado com `GOOGLE_WORKSPACE_CLI_CONFIG_DIR`. Mantenha esse diretório fora do projeto Claude e acessível apenas ao titular da conta.

Antes de iniciar sessão, verifique em privado se `GOOGLE_WORKSPACE_CLI_TOKEN` ou `GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE` está definida, incluindo através de um ficheiro `.env`. Estas fontes têm prioridade sobre as credenciais OAuth guardadas. Não apresente os valores nem peça ao Claude Code que leia ficheiros de credenciais. Utilize um ambiente limpo e a configuração do cliente pretendida.

Peça explicitamente estes quatro âmbitos:

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

Selecione a conta e dê o consentimento pessoalmente. O código-fonte do CLI na revisão indicada acrescenta também os âmbitos de identidade `openid`, `userinfo.email` e `userinfo.profile`. Compare em privado o consentimento e os dados de `gws auth status` sobre conta, autorizações e validade do token com o pretendido; um campo de estado ausente permanece por verificar. Pare se a conta estiver errada ou persistir uma autorização inesperada mais ampla. Escolher serviços no seletor de início de sessão filtra opções; não define estes quatro âmbitos só de leitura.

Os âmbitos são mais amplos do que os pedidos de exemplo. O acesso a metadados do Drive alcança metadados dos ficheiros acessíveis; o acesso só de leitura do Sheets e Docs abrange folhas de cálculo e documentos acessíveis; o Gmail só de leitura pode aceder ao conteúdo da caixa de correio. Nomes, ID, intervalos, consultas e máscaras de campos limitam cada resposta, não a autoridade do token. Uma ferramenta de shell pode também alcançar credenciais locais; ocultar um caminho ou escrever uma instrução num pedido não as isola.

## 2. Execute diretamente as leituras delimitadas

Examine primeiro cada método com `gws schema drive.files.list` e os nomes de esquema correspondentes dos outros métodos. Consulte a ajuda gerada `--help` se algum parâmetro diferir na versão instalada. Os comandos seguintes usam plicas de Bash; adapte deliberadamente as aspas para outra shell. Substitua apenas os identificadores e o nome de teste. Execute um comando de cada vez e conserve a resposta ou o erro real em privado, sem tokens nem conteúdo sensível.

Procure o ficheiro do Drive pelo nome. A sequência JSON `\u0027` escapa os apóstrofos na expressão de pesquisa do Drive, preservando as plicas de 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 ficheiro no Drive. A ausência de correspondência ou `incompleteSearch` não comprova o acesso ao ficheiro pretendido.

Leia as células conhecidas com o ID real da folha de cálculo e o nome do separador:

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

Compare os valores devolvidos com a folha. O Google pode omitir células vazias no fim; prepare valores conhecidos que não estejam vazios.

Leia o primeiro separador 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)))))"}'
```

Confirme o ID, o título e o texto conhecido. Esta resposta limitada não verifica outros separadores, comentários ou a estrutura completa do documento.

No Gmail, pesquise pelo identificador RFC `Message-ID` da mensagem existente e utilize o ID do Gmail devolvido para pedir 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` devolvido e o assunto inofensivo com o original. A primeira chamada devolve ID de mensagens, não cabeçalhos. A segunda pede metadados dos cabeçalhos, não o corpo da mensagem. Uma primeira resposta vazia não permite a segunda verificação. O âmbito OAuth mais restrito de metadados do Gmail não permite a consulta de pesquisa aqui usada; a autorização explícita só de leitura do Gmail permite.

## 3. Repita através do Claude Code com pedidos de permissão

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

Peça ao Claude Code, em linguagem corrente, que proponha os cinco comandos anteriores com os mesmos alvos de teste e os execute um de cada vez, só depois da sua decisão de permissão. Peça a saída ou os erros sem ler credenciais, alargar consultas ou executar escritas. Compare depois 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 regem o acesso.

| Serviço | Prova de conclusão pelas duas vias |
| --- | --- |
| Drive | Mesmo ID e nome do ficheiro; pesquisa completa. |
| Sheets | Separador, intervalo e valores conhecidos esperados. |
| Docs | ID, título e texto do primeiro separador esperados. |
| Gmail | A lista encontra a mensagem de teste; a consulta de metadados corresponde ao seu `Message-ID` e assunto. |

Registe versões, conta autenticada, autorizações efetivas, ID dos alvos, resultado direto, resultado do Claude e erros numa folha de verificação privada. Um pedido que falhou, uma resposta bem-sucedida mas vazia e um objeto verificado são resultados diferentes. Termine apenas quando os quatro serviços estiverem verificados pelas duas vias.

## Se uma verificação falhar

Um erro **Access blocked** no início de sessão pode significar que a conta não consta da lista de utilizadores de teste da aplicação OAuth. Perante um erro de API ou âmbito, confirme a API ativada, a conta selecionada e as autorizações efetivas antes de pedir novo consentimento aprovado. Para uma lista vazia, confirme o alvo exato, a consulta e a conta. Se a ajuda instalada diferir dos exemplos, use o esquema atual do método antes de continuar. Se o Claude Code propuser um comando que altere dados ou alargue o acesso, recuse-o no pedido de permissão e volte à leitura delimitada.

O repositório do CLI está disponível sem um pacote pago. A conta ou o plano Workspace, as quotas Cloud e o plano Claude Code ou o uso da API podem ter custos. O conteúdo obtido pode ser processado pelo fornecedor configurado no Claude Code; utilize dados de teste aprovados e não sensíveis. O CLI informa que não é um produto Google com suporte oficial e alerta para alterações anteriores à versão 1.0. O BIG CHANGE não testou o desempenho nem a compatibilidade. Pare antes de qualquer escrita, envio ou alteração da conta. [O suplemento separado do Google Workspace do Claude](https://bigchange.ai/blog/claude-google-workspace-add-on-edit-open-files) aborda a edição de ficheiros abertos com aprovação através de outra via.

## Sources

- [README do Google Workspace CLI](https://github.com/googleworkspace/cli/blob/a3768d0e82ad83cca2da97724e46bea4ff0e6dbd/README.md) — Repositório oficial numa 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 numa revisão fixa para métodos aninhados, --params, inspeção de esquemas e seleção limitada de campos; é necessário consultar a ajuda efetivamente 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 âmbitos de identidade acrescentados. Examinar o código não revela a autorização real de um leitor.
- [Guia de ativação das API do Google Workspace](https://developers.google.com/workspace/guides/enable-apis) — Instruções do Google para ativar API num projeto Cloud; as políticas do projeto e do administrador continuam a reger 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 pesquisa de metadados. Um pedido restrito 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 folha de cálculo e pelo intervalo A1, assim como a estrutura da resposta; podem ser omitidas células vazias no fim.
- [Referência de Docs documents.get](https://developers.google.com/workspace/docs/api/reference/rest/v1/documents/get) — Confirma a obtenção do documento e a limitação ao primeiro separador quando includeTabsContent é false. O exemplo usa um documento de teste de texto simples com um único separador.
- [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 documenta a pesquisa por ID de mensagem e resultados que só contêm ID; 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 documenta 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 da shell. Não comprova que a sessão de um leitor tenha uma regra específica.