Como Conectar Google Workspace CLI ao OpenClaw

TL;DR

Google Workspace CLI (gws) é uma ferramenta de linha de comando que dá aos agentes de IA acesso direto ao Gmail, Drive, Agenda, Planilhas, Documentos e a todas as APIs do Google Workspace através de saída JSON estruturada. Com suporte nativo ao OpenClaw e mais de 100 habilidades de agente pré-construídas, você pode automatizar todo o seu fluxo de trabalho do Workspace através de aplicativos de mensagens como WhatsApp ou Discord. A configuração leva 5 minutos com npm install -g @googleworkspace/cli seguido por gws auth setup.

Introdução

E se seu agente de IA pudesse ler seu Gmail, atualizar sua Agenda e organizar seu Google Drive sem que você movesse um dedo?

A maioria das ferramentas de automação do Google Workspace exige configurações complexas de API, código personalizado ou serviços caros de terceiros. Desenvolvedores gastam horas lutando com fluxos OAuth, limites de taxa e documentação desatualizada. Enquanto isso, agentes de IA ficam ociosos porque não têm acesso direto às ferramentas que usamos todos os dias.

Engenheiros do Google acabaram de lançar algo que muda tudo. O Google Workspace CLI (gws) já acumulou mais de 12.400 estrelas no GitHub e vem com mais de 100 habilidades de agente pré-construídas. Ele é construído em Rust, lê o Discovery Service do Google em tempo de execução e gera JSON estruturado que qualquer agente de IA pode analisar.

O que é Google Workspace CLI?

Google Workspace CLI (gws) é uma única ferramenta de linha de comando que empacota cada API do Google Workspace em comandos limpos e componíveis. Abrange Gmail, Google Drive, Agenda, Planilhas, Documentos, Apresentações, Chat, Tarefas, Meet, Formulários, Keep, Sala de Aula, Admin e basicamente todas as APIs do Google Workspace que existem.

Veja o que o torna diferente de outras ferramentas CLI que você já usou.

A maioria das ferramentas de desenvolvedor vem com uma lista fixa de comandos. Quando o Google adiciona um novo endpoint de API, alguém precisa atualizar manualmente a ferramenta, fazer um novo lançamento e esperar que todos atualizem. É uma esteira de manutenção que nunca termina. A maioria dos wrappers do Google Workspace que você já viu já estão desatualizados no momento em que você os instala.

gws resolve isso de uma maneira fundamentalmente diferente. Em vez de codificar comandos, ele se comunica diretamente com o Discovery Service do Google. Pense nisso como o catálogo ao vivo do Google de cada ação disponível em todos os seus aplicativos Workspace. Cada API, cada método, cada parâmetro. O Google mantém este catálogo por conta própria, e ele está sempre atualizado.

Quando você executa o gws, a primeira coisa que ele faz é puxar este catálogo ao vivo e construir toda a sua estrutura de comandos dinamicamente a partir do que o Google diz estar disponível no momento. Se o Google lançar um novo recurso de Planilhas às 14h de hoje, seu CLI já o suporta às 14h01. Sem atualização. Sem nova versão. Sem esperar por um mantenedor para se atualizar.

A ferramenta literalmente não consegue ficar desatualizada porque está lendo da fonte da verdade a cada vez.

Exemplo Rápido

# Listar os 10 arquivos mais recentes
gws drive files list --params '{"pageSize": 10}'

# Criar uma planilha
gws sheets spreadsheets create --json '{"properties": {"title": "Orçamento do Q1"}}'

# Enviar uma mensagem de Chat
gws chat spaces messages create \
  --params '{"parent": "spaces/xyz"}' \
  --json '{"text": "Implantação concluída."}'

Toda resposta retorna como JSON estruturado. Não HTML. Não texto formatado. Dados limpos, previsíveis e legíveis por máquina que um agente de IA pode imediatamente analisar e agir.

Por que o gws é importante para Agentes de IA

A comunidade de agentes de IA está entusiasmada com o gws por razões técnicas específicas.

Saída JSON Estruturada: Cada resposta retorna como JSON estruturado. Seu agente não precisa analisar HTML ou adivinhar a formatação. Ele obtém dados limpos com os quais pode trabalhar imediatamente.

Nenhuma Ferramenta Personalizada Necessária: A maioria das configurações de agentes de IA exige que você construa ferramentas personalizadas para cada API que deseja acessar. Com o gws, as ferramentas já estão construídas. Seu agente só precisa saber como executar comandos shell.

Mais de 100 Habilidades de Agente Pré-construídas: O repositório vem com mais de 100 arquivos SKILL.md - um para cada API suportada, além de ajudas de nível superior para fluxos de trabalho comuns e 50 "receitas" curadas para Gmail, Drive, Docs, Agenda e Planilhas.

Suporte Nativo ao OpenClaw: O Google incluiu instruções de configuração do OpenClaw diretamente no README. Isso não é um hack ou solução alternativa da comunidade. É um suporte integrado e de primeira classe.

Servidor MCP Integrado: o gws inclui um servidor Model Context Protocol que expõe as APIs do Google Workspace como ferramentas estruturadas. Qualquer cliente compatível com MCP (Claude Desktop, Gemini CLI, VS Code) pode chamar essas ferramentas diretamente.

A Infraestrutura da Economia de Agentes

Estamos vendo a emergência de uma infraestrutura de agentes mais rápido do que a maioria das pessoas percebe. Ferramentas como o gws representam o encanamento que impulsionará fluxos de trabalho autônomos. Em vez de construir integrações personalizadas para cada plataforma SaaS, os agentes podem confiar em CLIs padronizadas com formatos de saída consistentes.

Isso importa porque diminui a barreira de entrada. Você não precisa de uma equipe de engenheiros para construir automação de IA para o seu Workspace. Você precisa de npm e 5 minutos.

Como o gws funciona: A Arquitetura

o gws usa uma estratégia de análise em duas fases que vale a pena entender.

Fase 1: Identificação do Serviço

Quando você executa gws drive files list, o CLI lê o primeiro argumento (drive) para identificar o serviço.

Fase 2: Construção Dinâmica de Comandos

O CLI busca o Discovery Document do serviço no Google (armazenado em cache por 24 horas). Ele constrói uma árvore `clap::Command` a partir dos recursos e métodos do documento. É aqui que a mágica acontece - toda a superfície de comando é gerada a partir da própria especificação da API do Google.

Fase 3: Execução da Requisição

O CLI reanalisa os argumentos restantes, autentica usando suas credenciais configuradas, constrói a requisição HTTP e a executa.

Toda a saída - respostas de sucesso, erros, metadados de download - é JSON estruturado.

┌─────────────────────────────────────────────────────────┐
│  argv[1] = "drive"                                      │
│       ↓                                                 │
│  Buscar Discovery Document (cache de 24h)               │
│       ↓                                                 │
│  Construir árvore clap::Command a partir de recursos e métodos │
│       ↓                                                 │
│  Reanalisar argumentos restantes                        │
│       ↓                                                 │
│  Autenticar → Construir Requisição HTTP → Executar      │
│       ↓                                                 │
│  Saída: JSON Estruturado                                │
└─────────────────────────────────────────────────────────┘

Esta arquitetura significa que o gws pode suportar todas as APIs do Google Workspace sem codificar um único comando. O Discovery Document é a fonte da verdade, e o gws o lê ao vivo toda vez.

Integração OpenClaw: Passo a Passo

OpenClaw é um framework de agente de IA auto-hospedado que se conecta a aplicativos de mensagens como WhatsApp, Telegram e Discord. Quando você integra o gws com o OpenClaw, você obtém um assistente de IA que pode gerenciar todo o seu Google Workspace através de mensagens de texto.

O Google literalmente incluiu instruções de configuração do OpenClaw no README. Veja como começar.

Opção 1: Symlink Todas as Habilidades (Recomendado para Desenvolvimento)

# Clonar o repositório
git clone https://github.com/googleworkspace/cli.git
cd cli

# Criar symlink de todas as habilidades para o seu diretório de habilidades do OpenClaw
ln -s $(pwd)/skills/gws-* ~/.openclaw/skills/

Isso mantém tudo sincronizado com o repositório. Quando o Google atualiza as habilidades, você recebe as atualizações automaticamente.

Opção 2: Copiar Habilidades Específicas

# Pegue apenas o que você precisa
cp -r skills/gws-drive skills/gws-gmail ~/.openclaw/skills/

Opção 3: Usar o CLI de Habilidades

# Instalar todas as habilidades de uma vez
npx skills add https://github.com/googleworkspace/cli

# Ou escolha habilidades individuais
npx skills add https://github.com/googleworkspace/cli/tree/main/skills/gws-drive
npx skills add https://github.com/googleworkspace/cli/tree/main/skills/gws-gmail

A Habilidade gws-shared

A habilidade gws-shared é especialmente inteligente. Ela inclui um bloco de instalação que auto-instala o CLI via npm se o gws ainda não estiver no seu PATH. Seu agente OpenClaw pode se inicializar - ele verifica a ferramenta, a instala se necessário e começa a funcionar. Nenhuma configuração manual é necessária.

Usando gws Através do WhatsApp

Uma vez integrado, você pode enviar mensagens como:

"Verifique minha agenda para as reuniões de hoje"
"Encontre e-mails não lidos do meu chefe"
"Crie uma nova planilha chamada Orçamento do Q2"
"Envie este PDF para a pasta Projetos"

O OpenClaw recebe sua mensagem, determina qual comando gws executar, o executa e envia os resultados de volta - tudo via WhatsApp.

Detalhamento de Mais de 100 Habilidades de Agente

O repositório vem com mais de 100 arquivos SKILL.md organizados em quatro categorias. Se você não está familiarizado com o formato SKILL.md, ele é o padrão emergente para dar aos agentes de IA capacidades estruturadas e componíveis. Pense em habilidades como aplicativos, mas para o conhecimento do agente e acesso a ferramentas.

Habilidades de Serviço (25+)

Uma habilidade por API do Google Workspace. Estes são seus blocos de construção:

Habilidades adicionais cobrem Cloud Identity, Central de Alertas, Configurações de Grupo, Licenciamento, Revendedor e Model Armor para filtragem de segurança.

Habilidades de Persona (10 Papéis de Agente Pré-construídos)

O Google criou 10 pacotes de persona prontos para uso que definem papéis completos de agentes:

Cada persona agrupa as habilidades de serviço certas, comandos auxiliares e padrões de fluxo de trabalho para aquele papel específico. Você não precisa descobrir qual combinação de habilidades de Gmail + Agenda + Drive + Planilhas seu agente precisa. Apenas dê a ele a persona e ele saberá o que fazer.

Habilidades Auxiliares

Estes são comandos de atalho para as operações mais comuns:

• gws-drive-upload para uploads rápidos de arquivos
• gws-gmail-send para envio de e-mails
• gws-modelarmor-sanitize-prompt para limpar prompts antes que eles atinjam seu agente

Habilidades de "Receita" (50 Fluxos de Trabalho Curados)

Sequências de tarefas de várias etapas com comandos reais incorporados. Exemplos incluem:

• Auditoria de arquivos do Drive compartilhados externamente
• Envio de e-mails personalizados a partir de dados de Planilhas
• Criação de pautas de reunião a partir de eventos da Agenda
• Geração de relatórios de status semanais a partir de múltiplas fontes

Estes são os fluxos de trabalho de "copiar, colar e usar" que economizam horas de engenharia de prompt.

Fluxos de Trabalho de Automação do Mundo Real

Aqui estão exemplos concretos do que você pode automatizar com gws e OpenClaw.

Automação do Gmail

# Pesquise sua caixa de entrada por e-mails não lidos de um remetente específico
gws gmail users.messages list \
  --params '{"userId": "me", "q": "from:chefe@empresa.com é:não lido"}'

# Ler um e-mail específico
gws gmail users.messages get --params '{"userId": "me", "id": "ID_MENSAGEM"}'

# Enviar um e-mail (o auxiliar lida com toda a codificação)
gws gmail +send --to alice@empresa.com --subject 'Relatório do Q2 Pronto' \
  --body 'Olá Alice, o relatório do Q2 está pronto para revisão.'

# Triar sua caixa de entrada não lida (resumo amigável ao agente)
gws gmail +triage --max 5 --query 'de:chefe'

Gerenciamento de Agenda

# Veja o que está na sua agenda hoje
gws calendar +agenda

# Criar uma reunião com participantes
gws calendar +insert --summary 'Reunião Semanal' \
  --start '2026-03-10T09:00:00-07:00' \
  --end '2026-03-10T09:30:00-07:00'

# Criar um evento recorrente com todos os detalhes
gws calendar events insert \
  --params '{"calendarId": "primary"}' \
  --json '{
    "summary": "Reunião Semanal",
    "start": {"dateTime": "2026-03-10T09:00:00", "timeZone": "America/Vancouver"},
    "end": {"dateTime": "2026-03-10T09:30:00", "timeZone": "America/Vancouver"},
    "recurrence": ["RRULE:FREQ=WEEKLY;BYDAY=MO"],
    "attendees": [{"email": "equipe@empresa.com"}]
  }'

# Reagendar um evento e notificar os participantes
gws calendar events patch \
  --params '{"calendarId": "primary", "eventId": "ID_EVENTO", "sendUpdates": "all"}' \
  --json '{
    "start": {"dateTime": "2026-03-10T14:00:00", "timeZone": "America/Vancouver"},
    "end": {"dateTime": "2026-03-10T15:00:00", "timeZone": "America/Vancouver"}
  }'

Gerenciamento de Arquivos do Drive

# Listar seus 10 arquivos mais recentes
gws drive files list --params '{"pageSize": 10}'

# Enviar um arquivo para uma pasta específica
gws drive +upload --file ./relatorio.pdf --parent ID_PASTA

# Criar uma nova pasta de projeto
gws drive files create \
  --json '{"name": "Projeto Q2", "mimeType": "application/vnd.google-apps.folder"}'

# Baixar um arquivo
gws drive files get \
  --params '{"fileId": "ID_ARQUIVO", "alt": "media"}' -o relatorio.pdf

# Exportar um Google Doc como PDF
gws drive files export \
  --params '{"fileId": "ID_ARQUIVO", "mimeType": "application/pdf"}' -o documento.pdf

# Compartilhar uma pasta com um colega
gws drive permissions create \
  --params '{"fileId": "ID_PASTA"}' \
  --json '{"role": "writer", "type": "user", "emailAddress": "colega@empresa.com"}'

Operações de Planilhas

# Ler dados de um intervalo específico
gws sheets +read --spreadsheet-id ID_PLANILHA --range 'Contatos!A2:C'

# Adicionar uma nova linha de dados
gws sheets +append --spreadsheet-id ID_PLANILHA --range 'Planilha1' \
  --values '["2026-03-05", "Marketing", "Gasto com anúncios", "1500"]'

# Criar uma planilha totalmente nova
gws drive files create \
  --json '{"name": "Controle de Despesas 2026", "mimeType": "application/vnd.google-apps.spreadsheet"}'

Docs e Criação de Conteúdo

# Criar um novo documento
gws docs documents create --json '{"title": "Notas da Reunião - Março de 2026"}'

# Escrever conteúdo para um documento existente
gws docs +write --document-id ID_DOC \
  --text '## Projeto: Lançamento Q2\n\n### Objetivo\nLançar o novo recurso até o final do Q2.'

Chat, Meet, Formulários e Mais

# Enviar uma notificação da equipe no Google Chat
gws chat +send --space spaces/ESPACO_DA_EQUIPE \
  --text 'Importante: Por favor, verifique seu e-mail para a política atualizada.'

# Criar uma sala do Google Meet
gws meet spaces create --json '{"config": {"accessType": "OPEN"}}'

# Criar um formulário de feedback
gws forms forms create \
  --json '{"info": {"title": "Feedback do Evento", "documentTitle": "Formulário de Feedback do Evento"}}'

# Criar uma apresentação
gws slides presentations create --json '{"title": "Revisão Trimestral Q2"}'

Observe o padrão. Cada ação é uma linha. Os comandos auxiliares + (como +send, +upload, +agenda, +triage, +read, +append, +write) lidam com toda a codificação e formatação complexas que normalmente levariam 10 linhas de código repetitivo. Seu agente não precisa saber sobre a formatação de e-mail RFC 2822 ou codificação base64. Ele apenas diz o que quer fazer e o gws cuida do resto.

Segurança e Model Armor

Aqui está algo que não recebe atenção suficiente. O repositório inclui integração com o Google Cloud Model Armor para higienização de respostas.

O que é Model Armor?

Quando seu agente lê dados do Gmail ou Drive, esses dados podem conter ataques de injeção de prompt. Alguém poderia criar um e-mail especificamente projetado para manipular o comportamento do seu agente. O Model Armor escaneia as respostas da API antes que elas cheguem ao seu agente e filtra conteúdo potencialmente malicioso.

gws gmail users messages get --params '...' \
  --sanitize "projects/P/locations/L/templates/T"

Modos de Higienização

Por que isso é Importante

A equipe de segurança de IA da Cisco descobriu que 26% das mais de 31.000 habilidades no ClawHub contêm vulnerabilidades. A SecurityScorecard relatou que 63% das instâncias expostas do OpenClaw estão mal configuradas. A segurança do agente não é um problema teórico. Está acontecendo agora mesmo.

Ter filtragem de segurança integrada ao pipeline de dados é uma jogada inteligente do Google.

Variáveis de Ambiente para Segurança

# Modelo padrão do Model Armor
export GOOGLE_WORKSPACE_CLI_SANITIZE_TEMPLATE="projects/P/locations/L/templates/T"

# Modo de higienização (alertar ou bloquear)
export GOOGLE_WORKSPACE_CLI_SANITIZE_MODE="block"

gws vs Alternativas

Vamos comparar o gws com outras abordagens que você pode considerar.

gws vs gcloud CLI

Use gcloud para gerenciamento de infraestrutura. Use gws para automação do Workspace.

gws vs Google Apps Script

Apps Script é excelente para automatizar fluxos de trabalho dentro do Google Workspace. gws é excelente para dar a ferramentas externas e agentes de IA acesso ao Workspace.

gws vs Ferramentas de Terceiros (Zapier, Make)

Ferramentas de terceiros fazem sentido para usuários não técnicos. gws faz sentido para desenvolvedores e configurações de agentes de IA.

Guia de Início Rápido

Pronto para experimentar? Aqui está o caminho mais rápido para uma configuração funcional.

Pré-requisitos

• Node.js 18+ (para npm install)
• Um projeto do Google Cloud (para credenciais OAuth)
• Uma conta Google com acesso ao Google Workspace
• gcloud CLI instalado (opcional, mas recomendado para a configuração mais rápida)

Passo 1: Instalar gws

npm install -g @googleworkspace/cli

O pacote npm agrupa binários nativos pré-construídos para seu SO e arquitetura. Nenhuma toolchain Rust é necessária.

Passo 2: Configurar Autenticação

gws auth setup

Isso o guiará pela configuração do projeto do Google Cloud. Ele cria um projeto Cloud, ativa APIs e faz login.

Se você não tiver o gcloud instalado, pode configurar o OAuth manualmente através do Google Cloud Console.

Passo 3: Fazer Login

gws auth login

Isso abre um navegador para seleção de escopo OAuth e login.

Passo 4: Testar Sua Configuração

gws drive files list --params '{"pageSize": 5}'

Você deverá ver uma resposta JSON com seus arquivos recentes.

Passo 5: Integrar com OpenClaw

# Clonar o repositório
git clone https://github.com/googleworkspace/cli.git
cd cli

# Criar symlink de todas as habilidades
ln -s $(pwd)/skills/gws-* ~/.openclaw/skills/

Passo 6: Começar a Usar Através de Mensagens

Envie uma mensagem através da sua plataforma de mensagens OpenClaw configurada:

"Listar meus 5 arquivos mais recentes do Drive"

O OpenClaw executará o comando gws apropriado e enviará os resultados de volta.

Solução de Problemas Comuns

"Acesso bloqueado" ou 403 durante o login

Seu aplicativo OAuth está em modo de teste e sua conta não está listada como um usuário de teste.

Solução: Abra a tela de consentimento OAuth em seu projeto GCP, vá para Usuários de teste, adicione o e-mail da sua conta Google e, em seguida, tente novamente gws auth login.

"O Google não verificou este aplicativo"

Esperado quando seu aplicativo está em modo de teste. Clique em Avançado e depois em "Ir para (não seguro)" para prosseguir. Isso é seguro para uso pessoal.

Erro de muitos escopos

Aplicativos não verificados (modo de teste) são limitados a cerca de 25 escopos OAuth. O preset de escopo recomendado inclui muitos escopos e excederá esse limite.

Solução: Selecione apenas os escopos que você precisa:

gws auth login --scopes drive,gmail,calendar

API não ativada

Se uma API do Google necessária não estiver ativada para o seu projeto GCP, você verá um erro 403 com o motivo accessNotConfigured.

o gws imprime uma dica acionável com um link para ativar a API. Clique no link, ative-o, espere cerca de 10 segundos e tente novamente.

Conclusão

O Google Workspace CLI representa algo significativo para o ecossistema de agentes de IA. Não é apenas mais um wrapper CLI. É uma infraestrutura que torna a automação de IA acessível a qualquer pessoa com npm instalado.

A arquitetura é sólida. A cobertura de habilidades é impressionante. O fato de o Google ter construído compatibilidade com o OpenClaw desde o primeiro dia mostra para onde eles acreditam que o ecossistema de agentes está indo.

Para desenvolvedores que constroem no OpenClaw, Claude Code ou qualquer plataforma de agente, o gws é uma daquelas ferramentas que você desejará ter em seu conjunto. Ele lida com a complexidade das APIs do Google Workspace para que seu agente possa se concentrar no que importa – realizar o trabalho.

A economia de agentes está recebendo sua infraestrutura. E está acontecendo mais rápido do que a maioria das pessoas percebe.

FAQ

P: O gws é gratuito para usar?

R: Sim, o gws é de código aberto sob a licença Apache-2.0. Você só paga pelo uso da API do Google se exceder as cotas gratuitas.

P: Preciso de uma conta do Google Workspace?

R: Uma conta Google padrão funciona para a maioria dos recursos. Algumas APIs de Administrador exigem uma assinatura do Workspace.

P: Posso usar o gws sem o OpenClaw?

R: Com certeza. O gws funciona como uma ferramenta CLI autônoma. A integração com o OpenClaw é opcional para acesso baseado em mensagens.

P: Como atualizo o gws?

R: Execute npm update -g @googleworkspace/cli para obter a versão mais recente. O CLI lê o Discovery Service do Google em tempo de execução, então ele sempre tem acesso às APIs mais recentes.

P: Meus dados estão seguros com o gws?

R: O gws armazena credenciais criptografadas em repouso usando AES-256-GCM com chaves no seu keyring do sistema operacional. A integração do Model Armor oferece segurança adicional para fluxos de trabalho de agentes.

P: Posso usar o gws em pipelines de CI/CD?

R: Sim. Exporte suas credenciais com gws auth export --unmasked > credentials.json e defina GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE em seu ambiente de CI.

P: Qual a diferença entre o gws e o Google APIs Explorer?

R: O gws é uma ferramenta CLI projetada para automação e integração de agentes de IA. O APIs Explorer é uma ferramenta de teste baseada na web. O gws gera JSON estruturado e suporta scripts.

P: O gws funciona com contas de serviço?

R: Sim. Defina GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE para o seu arquivo de chave JSON da conta de serviço. Não é necessário login interativo.

P: Posso contribuir para o gws?

R: Sim, o projeto é de código aberto no GitHub. Observe que pull requests de não colaboradores estão temporariamente desabilitados, conforme os mantenedores do repositório.

P: Quais plataformas o gws suporta?

R: O gws fornece binários pré-compilados para macOS, Linux e Windows. O pacote npm lida com a instalação de binários nativos automaticamente.