EL MUNDO NO SE DETIENE.RSS
BIG CHANGE.

Edición en Markdown

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

# Conectar Claude Code a Google Workspace con cinco comprobaciones de lectura

> Una configuración documentada para comprobar la cuenta de Google Workspace CLI de Claude Code, las autorizaciones OAuth y las solicitudes de permiso mediante lecturas limitadas de Drive, Sheets, Docs y 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.

Claude Code puede ejecutar comandos de Google Workspace CLI (`gws`) desde un shell local, usando la cuenta de Google autenticada en `gws`. El titular autorizado de la cuenta puede comprobar la conexión con un elemento inocuo de cada servicio: Drive, Sheets, Docs y Gmail. Primero confirma la cuenta y sus autorizaciones. Esta guía sigue la interfaz documentada del repositorio del CLI, examinada el 20 de octubre de 2026. BIG CHANGE no instaló ninguna de las dos herramientas ni accedió a una cuenta.

## El gran cambio

- **Qué cambió:** El CLI `gws` actual expone métodos de las API de Google Workspace como comandos de shell que Claude Code puede ejecutar. Una cuenta autenticada puede dar acceso a varios servicios de trabajo, según sus autorizaciones reales y los permisos del shell del agente.
- **Por qué importa:** La misma conexión que permite al agente consultar un archivo o mensaje seleccionado puede alcanzar otros datos cubiertos por sus ámbitos OAuth. El titular puede comparar resultados pequeños y conocidos en el terminal y en Claude Code antes de delegar más trabajo.
- **Qué vigilar:** Comprueba los comandos generados por el CLI instalado y las reglas de permiso efectivas de la sesión cada vez que cambie la configuración. El CLI es anterior a la versión 1.0; una consulta de ejemplo limitada o una máscara de campos no reduce la autorización de toda la cuenta.

## Antes de conectarte

Usa una cuenta de pruebas de Google dedicada y aprobada, sin contenido sensible, y un proyecto Cloud donde puedas configurar OAuth. Pregunta al administrador si están permitidas las cuatro API y las autorizaciones solicitadas. Prepara un archivo existente de Drive con nombre único, una hoja de cálculo con valores conocidos en un intervalo pequeño, un Google Doc breve de texto sin formato con una sola pestaña y un mensaje inocuo de Gmail. Para Gmail, obtén su identificador RFC `Message-ID` desde **Show original**. Compararás estos originales con los resultados del CLI. Estas comprobaciones no crean ni envían nada.

Instala Claude Code en un equipo controlado. Instala `gws` desde la [versión del repositorio para tu sistema operativo](https://github.com/googleworkspace/cli/releases) o, con Node.js 18 o posterior, utiliza el comando documentado:

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

Registra en privado las versiones instaladas del CLI y de Claude Code. El CLI sigue siendo anterior a la versión 1.0 y construye sus comandos a partir de los documentos de descubrimiento de las API de Google. Consulta la ayuda instalada y los esquemas de los métodos siguientes antes de ejecutar los ejemplos.

## 1. Configura un inicio de sesión OAuth limitado

En el proyecto Cloud aprobado, habilita las API de Drive, Sheets, Docs y Gmail. Configura el público de OAuth y crea un cliente **Desktop app**. Si la aplicación es External y está en pruebas, añade la cuenta elegida como usuario de prueba. Guarda el JSON descargado del cliente en la ubicación documentada `~/.config/gws/client_secret.json` o usa un directorio independiente seleccionado con `GOOGLE_WORKSPACE_CLI_CONFIG_DIR`. Mantén ese directorio fuera del proyecto Claude y privado para el titular de la cuenta.

Antes de iniciar sesión, comprueba en privado si `GOOGLE_WORKSPACE_CLI_TOKEN` o `GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE` está definida, incluso mediante un archivo `.env`. Estas fuentes tienen prioridad sobre las credenciales OAuth almacenadas. No muestres sus valores ni pidas a Claude Code que lea archivos de credenciales. Usa un entorno limpio y la configuración del cliente prevista.

Solicita explícitamente estos cuatro á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
```

Selecciona la cuenta y da el consentimiento personalmente. El código del CLI en la revisión indicada también añade los ámbitos de identidad `openid`, `userinfo.email` y `userinfo.profile`. Compara en privado el consentimiento y los datos de `gws auth status` sobre cuenta, autorizaciones y validez del token con lo que pretendías; un campo de estado ausente sigue sin verificarse. Detente si la cuenta es incorrecta o persiste una autorización más amplia e inesperada. Seleccionar servicios en el selector de inicio de sesión filtra las opciones; no establece estos cuatro ámbitos de solo lectura.

Los ámbitos son más amplios que las solicitudes de ejemplo. El acceso a metadatos de Drive alcanza los metadatos de archivos accesibles; el acceso de solo lectura de Sheets y Docs cubre hojas y documentos accesibles; Gmail de solo lectura puede acceder al contenido del buzón. Nombres, identificadores, intervalos, consultas y máscaras de campos limitan cada respuesta, no la autoridad del token. Una herramienta de shell también puede alcanzar credenciales locales; una ruta oculta o una instrucción en un prompt no las aísla.

## 2. Ejecuta directamente las lecturas limitadas

Primero examina cada método con `gws schema drive.files.list` y los nombres de esquema correspondientes de los demás métodos. Consulta la ayuda generada `--help` si un parámetro difiere en tu versión instalada. Los comandos siguientes usan comillas simples de Bash; adapta expresamente las comillas para otro shell. Sustituye solo los identificadores y el nombre de prueba. Ejecuta un comando cada vez y conserva en privado su respuesta o error real, sin tokens ni contenido sensible.

Busca el archivo de Drive por su nombre. La secuencia JSON `\u0027` escapa los apóstrofos de la expresión de búsqueda de Drive conservando las comillas 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"}'
```

Compara su identificador y nombre con el archivo en Drive. No encontrar una coincidencia o recibir `incompleteSearch` no demuestra acceso al archivo previsto.

Lee las celdas conocidas con el identificador real de la hoja de cálculo y el nombre de la pestaña:

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

Compara los valores devueltos con la hoja. Google puede omitir celdas vacías finales, así que prepara valores conocidos que no estén vacíos.

Lee la primera pestaña del documento de prueba breve:

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

Comprueba el identificador, el título y el texto conocido. Esta respuesta limitada no comprueba otras pestañas, comentarios ni la estructura completa del documento.

En Gmail, busca el mensaje existente por su identificador RFC `Message-ID` y usa después el identificador de Gmail devuelto para solicitar dos cabeceras:

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

Compara el `Message-ID` devuelto y el asunto inocuo con el original. La primera llamada devuelve identificadores de mensajes, no cabeceras. La segunda solicita metadatos de cabecera, no el cuerpo del mensaje. Una primera respuesta vacía no permite la segunda comprobación. El ámbito OAuth de metadatos de Gmail, más limitado, no permite la consulta de búsqueda usada aquí; la autorización explícita de Gmail de solo lectura sí.

## 3. Repite con Claude Code y las solicitudes de permiso

Inicia Claude Code en un proyecto que controles, con la misma configuración de cuenta aprobada. En `/permissions`, examina el modo efectivo y las reglas del shell. Usa Manual (también llamado `default`) y una regla **Ask** para la herramienta de shell real; resuelve cualquier regla más amplia de autorización o de omisión de controles según la política de tu organización. Evita la autorización general para `gws *` o para un programa que envuelva el shell. Ante cada comando propuesto, examina el comando completo y aprueba solo la lectura limitada que pretendes.

Pide a Claude Code en lenguaje natural que proponga los cinco comandos anteriores con los mismos elementos de prueba y los ejecute uno a uno solo después de tu decisión de permiso. Solicita la salida o los errores sin leer credenciales, ampliar consultas ni realizar escrituras. Después compara cada resultado con el resultado directo y el objeto original. Las instrucciones del proyecto pueden describir la tarea, pero los permisos efectivos de las herramientas y las autorizaciones OAuth determinan el acceso.

| Servicio | Evidencia de finalización por ambas vías |
| --- | --- |
| Drive | Mismo identificador y nombre del archivo; búsqueda completa. |
| Sheets | Pestaña, intervalo y valores conocidos esperados. |
| Docs | Identificador, título y texto de la primera pestaña esperados. |
| Gmail | La lista encuentra el mensaje de prueba; la consulta de metadatos coincide con su `Message-ID` y asunto. |

Registra versiones, cuenta autenticada, autorizaciones reales, identificadores de destino, resultado directo, resultado de Claude y errores en una hoja de comprobación privada. Una solicitud fallida, una respuesta correcta pero vacía y un objeto verificado son resultados diferentes. Termina solo cuando los cuatro servicios estén verificados por ambas vías.

## Si falla una comprobación

Un error **Access blocked** al iniciar sesión puede indicar que falta la cuenta de prueba en la lista de usuarios de prueba de la aplicación OAuth. Ante un error de API o ámbito, confirma la API habilitada, la cuenta elegida y las autorizaciones reales antes de solicitar un nuevo consentimiento aprobado. Para una lista vacía, comprueba el destino exacto, la consulta y la cuenta. Si la ayuda instalada difiere de estos ejemplos, usa el esquema actual del método antes de continuar. Si Claude Code propone un comando que modifique datos o amplíe el acceso, recházalo en la solicitud de permiso y vuelve a la lectura limitada.

El repositorio del CLI está disponible sin un paquete de pago. La cuenta o el plan Workspace, las cuotas Cloud y el plan Claude Code o el uso de su API pueden generar costes. El proveedor configurado en Claude Code puede procesar el contenido recuperado: usa datos de prueba no sensibles y aprobados. El CLI indica que no es un producto de Google con soporte oficial y advierte de cambios anteriores a la versión 1.0. BIG CHANGE no ha probado el rendimiento ni la compatibilidad. Detente antes de cualquier escritura, envío o cambio de cuenta. [El complemento independiente de Google Workspace de Claude](https://bigchange.ai/blog/claude-google-workspace-add-on-edit-open-files) permite editar archivos abiertos con aprobación por otra vía.

## Sources

- [README de Google Workspace CLI](https://github.com/googleworkspace/cli/blob/a3768d0e82ad83cca2da97724e46bea4ff0e6dbd/README.md) — Repositorio oficial en una revisión fijada, examinado el 20 de octubre de 2026. Documenta instalación, configuración manual de OAuth, comandos dinámicos, prioridad de credenciales, inestabilidad de versiones y aviso de producto sin soporte. No acredita una ejecución de BIG CHANGE.
- [Contexto de comandos de Google Workspace CLI](https://github.com/googleworkspace/cli/blob/a3768d0e82ad83cca2da97724e46bea4ff0e6dbd/CONTEXT.md) — Guía oficial en una revisión fijada sobre métodos anidados, --params, inspección de esquemas y selección limitada de campos; debe comprobarse la ayuda realmente instalada.
- [Implementación de autenticación de Google Workspace CLI](https://github.com/googleworkspace/cli/blob/a3768d0e82ad83cca2da97724e46bea4ff0e6dbd/crates/google-workspace-cli/src/auth_commands.rs) — El código de autenticación fijado confirma --scopes personalizados, el comportamiento independiente del selector de servicios y la incorporación de ámbitos de identidad. Examinar el código no muestra la autorización real del lector.
- [Guía de habilitación de las API de Google Workspace](https://developers.google.com/workspace/guides/enable-apis) — Instrucciones de Google para habilitar API en un proyecto Cloud; las políticas del proyecto y del administrador siguen determinando el acceso.
- [Referencia de Drive files.list](https://developers.google.com/workspace/drive/api/reference/rest/v3/files/list) — Confirma los parámetros Drive q, pageSize y los campos de respuesta usados para limitar la búsqueda de metadatos. Una solicitud limitada no limita la autoridad OAuth.
- [Referencia de Sheets spreadsheets.values.get](https://developers.google.com/workspace/sheets/api/reference/rest/v4/spreadsheets.values/get) — Confirma la lectura por identificador de hoja de cálculo e intervalo A1 y la estructura de respuesta; pueden omitirse las celdas vacías finales.
- [Referencia de Docs documents.get](https://developers.google.com/workspace/docs/api/reference/rest/v1/documents/get) — Confirma la recuperación de documentos y la limitación a la primera pestaña cuando includeTabsContent es false. El ejemplo corresponde a un documento de prueba de texto sin formato con una sola pestaña.
- [Referencias de Gmail messages.list y messages.get](https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.messages/list) — La referencia list documenta la búsqueda por identificador de mensaje y resultados que solo contienen identificadores; q no está disponible con gmail.metadata. La referencia get asociada es https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.messages/get y documenta metadataHeaders con el formato METADATA.
- [Permisos de Claude Code](https://code.claude.com/docs/en/permissions) — Referencia actual de Anthropic sobre el modo Manual/default, reglas Ask, permisos efectivos de herramientas y solicitudes de aprobación del shell. No demuestra que una sesión del lector tenga una regla concreta.