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
gwsatual 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 ou, com Node.js 18 ou posterior, utilize o comando documentado:
npm install -g @googleworkspace/cli
gws --version
gws --help
gws auth login --helpRegiste 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:
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 statusSelecione 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:
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:
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:
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:
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 |
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 aborda a edição de ficheiros abertos com aprovação através de outra via.
