Markdown-Ausgabe

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

# Claude Code mit fünf Leseprüfungen an Google Workspace anbinden

> Eine dokumentierte Einrichtung, um das Google-Workspace-CLI-Konto von Claude Code, OAuth-Berechtigungen und Berechtigungsabfragen mit begrenzten Lesezugriffen auf Drive, Sheets, Docs und Gmail zu prüfen.

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 kann Google-Workspace-CLI-Befehle (`gws`) in einer lokalen Shell ausführen. Dabei nutzt es das in `gws` authentifizierte Google-Konto. Der berechtigte Kontoinhaber kann die Verbindung mit jeweils einem unbedenklichen Datensatz in Drive, Sheets, Docs und Gmail prüfen. Bestätigen Sie zuerst Konto und Berechtigungen. Diese Anleitung folgt der dokumentierten Schnittstelle des CLI-Repositorys, geprüft am 20. Oktober 2026. BIG CHANGE hat keines der Werkzeuge installiert und auf kein Konto zugegriffen.

## Die große Veränderung

- **Was sich geändert hat:** Die aktuelle `gws`-CLI stellt Methoden der Google-Workspace-APIs als Shell-Befehle bereit, die Claude Code ausführen kann. Ein authentifiziertes Konto kann mehrere Arbeitsdienste erschließen, begrenzt durch seine tatsächlichen Berechtigungen und die Shell-Berechtigungen des Agenten.
- **Warum das wichtig ist:** Dieselbe Verbindung, mit der ein Agent eine ausgewählte Datei oder Nachricht untersucht, kann andere Daten innerhalb seiner OAuth-Bereiche erreichen. Der Kontoinhaber kann kleine, bekannte Ergebnisse im Terminal und in Claude Code vergleichen, bevor er weitere Aufgaben delegiert.
- **Worauf zu achten ist:** Prüfen Sie die generierten Befehle der installierten CLI und die wirksamen Berechtigungsregeln der Sitzung, sobald sich diese Einrichtung ändert. Die CLI liegt vor Version 1.0; eine enge Beispielabfrage oder Feldmaske verkleinert nicht die kontoweite Berechtigung.

## Vor dem Verbinden

Verwenden Sie ein eigenes, genehmigtes Google-Testkonto ohne sensible Inhalte und ein Cloud-Projekt, in dem Sie OAuth konfigurieren dürfen. Fragen Sie den Administrator, ob die vier APIs und angeforderten Berechtigungen zulässig sind. Bereiten Sie eine vorhandene Drive-Datei mit eindeutigem Namen, eine Tabelle mit bekannten Werten in einem kleinen Bereich, ein kurzes Google Doc mit einfachem Text und einem Tab sowie eine unbedenkliche Gmail-Nachricht vor. Entnehmen Sie deren RFC-`Message-ID` aus **Show original**. Diese Originale vergleichen Sie mit den CLI-Ergebnissen. Die Prüfungen erstellen und versenden nichts.

Installieren Sie Claude Code auf einem kontrollierten Rechner. Installieren Sie `gws` aus der [Repository-Veröffentlichung für Ihr Betriebssystem](https://github.com/googleworkspace/cli/releases) oder verwenden Sie mit Node.js 18 oder neuer den dokumentierten Befehl:

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

Notieren Sie die installierte CLI-Version und die Claude-Code-Version vertraulich. Die CLI liegt noch vor Version 1.0; ihre Befehle werden aus Googles API-Discovery-Dokumenten erzeugt. Prüfen Sie die installierte Hilfe und die folgenden Methodenschemata, bevor Sie die Beispiele ausführen.

## 1. Eine begrenzte OAuth-Anmeldung einrichten

Aktivieren Sie im genehmigten Cloud-Projekt die APIs für Drive, Sheets, Docs und Gmail. Konfigurieren Sie die OAuth-Zielgruppe und erstellen Sie einen Client vom Typ **Desktop app**. Ist die Anwendung External und im Testbetrieb, fügen Sie das gewählte Konto als Testnutzer hinzu. Speichern Sie die heruntergeladene Client-JSON-Datei am dokumentierten Ort `~/.config/gws/client_secret.json` oder verwenden Sie ein separates Verzeichnis, ausgewählt mit `GOOGLE_WORKSPACE_CLI_CONFIG_DIR`. Halten Sie dieses Verzeichnis außerhalb des Claude-Projekts und nur für den Kontoinhaber zugänglich.

Prüfen Sie vor der Anmeldung vertraulich, ob `GOOGLE_WORKSPACE_CLI_TOKEN` oder `GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE` gesetzt ist, auch über eine `.env`-Datei. Diese Quellen haben Vorrang vor gespeicherten OAuth-Zugangsdaten. Geben Sie ihre Werte nicht aus und lassen Sie Claude Code keine Zugangsdaten-Dateien lesen. Verwenden Sie eine saubere Umgebung und die beabsichtigte Client-Konfiguration.

Fordern Sie diese vier Bereiche ausdrücklich an:

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

Führen Sie Kontowahl und Einwilligung selbst durch. Der festgelegte CLI-Quellstand ergänzt außerdem die Identitätsbereiche `openid`, `userinfo.email` und `userinfo.profile`. Vergleichen Sie vertraulich die Einwilligung und die Angaben von `gws auth status` zu Konto, Berechtigungen und Token-Gültigkeit mit Ihrer Absicht. Ein fehlendes Statusfeld bleibt ungeprüft. Stoppen Sie bei einem falschen Konto oder einer unerwartet umfassenderen Berechtigung. Die Dienstauswahl bei der Anmeldung filtert Optionen; sie legt diese vier reinen Lesebereiche nicht selbst fest.

Die Bereiche sind umfassender als die Beispielanfragen. Drive-Metadatenzugriff erreicht Metadaten zugänglicher Dateien; Sheets- und Docs-Lesezugriff umfasst zugängliche Tabellen und Dokumente; Gmail-Lesezugriff kann auf Postfachinhalte zugreifen. Namen, IDs, Bereiche, Abfragen und Feldmasken begrenzen die einzelne Antwort, nicht die Befugnis des Tokens. Ein Shell-Werkzeug kann auch lokale Zugangsdaten erreichen. Ein verborgener Dateipfad oder eine Prompt-Anweisung isoliert sie nicht.

## 2. Die begrenzten Lesezugriffe direkt ausführen

Untersuchen Sie zunächst jede Methode mit `gws schema drive.files.list` und den entsprechenden Schemanamen für die anderen Methoden. Prüfen Sie die generierte Hilfe `--help`, falls ein Parameter in Ihrer installierten Version abweicht. Die folgenden Befehle verwenden einfache Bash-Anführungszeichen; passen Sie die Maskierung für eine andere Shell bewusst an. Ersetzen Sie nur die Testkennungen und den Namen. Führen Sie jeweils einen Befehl aus und bewahren Sie die tatsächliche Antwort oder Fehlermeldung vertraulich auf, ohne Tokens oder sensible Inhalte.

Suchen Sie die benannte Drive-Datei. Die JSON-Sequenz `\u0027` maskiert Apostrophe im Drive-Suchausdruck und erhält dabei die Bash-Anführungszeichen:

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

Vergleichen Sie ID und Namen mit der Datei in Drive. Ein fehlender Treffer oder `incompleteSearch` beweist keinen Zugriff auf die beabsichtigte Datei.

Lesen Sie die bekannten Zellen mit der tatsächlichen Tabellen-ID und dem Tabnamen:

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

Vergleichen Sie die zurückgegebenen Werte mit der Tabelle. Google kann leere Zellen am Ende weglassen; bereiten Sie daher bekannte, nichtleere Werte vor.

Lesen Sie den ersten Tab des kurzen Testdokuments:

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

Prüfen Sie ID, Titel und bekannten Text. Diese begrenzte Antwort prüft weder andere Tabs noch Kommentare oder die gesamte Dokumentstruktur.

Suchen Sie in Gmail nach der RFC-`Message-ID` der vorhandenen Nachricht. Fordern Sie anschließend mit der zurückgegebenen Gmail-ID zwei Kopfzeilen an:

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

Vergleichen Sie die zurückgegebene `Message-ID` und den unbedenklichen Betreff mit dem Original. Der erste Aufruf liefert Nachrichten-IDs, keine Kopfzeilen. Der zweite fordert Kopfzeilen-Metadaten an, nicht den Nachrichtentext. Eine leere erste Antwort ermöglicht die zweite Prüfung nicht. Der engere Gmail-OAuth-Bereich für Metadaten erlaubt die hier verwendete Suchabfrage nicht; die ausdrückliche reine Gmail-Leseberechtigung dagegen schon.

## 3. In Claude Code mit Berechtigungsabfragen wiederholen

Starten Sie Claude Code in einem von Ihnen kontrollierten Projekt mit derselben genehmigten Kontokonfiguration. Prüfen Sie unter `/permissions` den wirksamen Modus und die Shell-Regeln. Verwenden Sie Manual (auch `default` genannt) und eine **Ask**-Regel für das tatsächlich verwendete Shell-Werkzeug. Klären Sie umfassendere Freigaben oder Umgehungsregeln gemäß den Vorgaben Ihrer Organisation. Vermeiden Sie pauschale Freigaben für `gws *` oder einen Shell-Wrapper. Prüfen Sie jeden vorgeschlagenen Befehl vollständig und genehmigen Sie nur den beabsichtigten begrenzten Lesezugriff.

Bitten Sie Claude Code in normaler Sprache, die fünf obigen Befehle mit denselben Testzielen vorzuschlagen und einzeln erst nach Ihrer Berechtigungsentscheidung auszuführen. Verlangen Sie Befehlsausgaben oder Fehler, ohne Zugangsdaten zu lesen, Abfragen auszuweiten oder Schreibzugriffe auszuführen. Vergleichen Sie jedes Ergebnis mit dem direkten Ergebnis und dem Originalobjekt. Projektanweisungen können die Aufgabe beschreiben; die wirksamen Werkzeugberechtigungen und OAuth-Freigaben regeln den Zugriff.

| Dienst | Abschlussnachweis über beide Wege |
| --- | --- |
| Drive | Gleiche Datei-ID und gleicher Name; vollständige Suche. |
| Sheets | Erwarteter Tab, Bereich und bekannte Zellwerte. |
| Docs | Erwartete ID, Titel und Text des ersten Tabs. |
| Gmail | Die Liste findet die Testnachricht; der Metadatenabruf bestätigt ihre `Message-ID` und ihren Betreff. |

Notieren Sie Versionen, authentifiziertes Konto, tatsächliche Berechtigungen, Ziel-IDs, direktes Ergebnis, Claude-Ergebnis und Fehler in einer privaten Prüfliste. Eine fehlgeschlagene Anfrage, eine erfolgreiche leere Antwort und ein verifiziertes Objekt sind unterschiedliche Ergebnisse. Beenden Sie die Prüfung erst, wenn alle vier Dienste über beide Wege verifiziert sind.

## Wenn eine Prüfung scheitert

Ein Anmeldefehler **Access blocked** kann bedeuten, dass das Testkonto nicht in der Testnutzerliste der OAuth-Anwendung steht. Bestätigen Sie bei einem API- oder Bereichsfehler die aktivierte API, das gewählte Konto und die tatsächlichen Freigaben, bevor Sie eine genehmigte erneute Einwilligung anfordern. Prüfen Sie bei einer leeren Liste das genaue Ziel, die Abfrage und das Konto. Weicht die installierte Hilfe von den Beispielen ab, verwenden Sie vor dem Fortfahren das aktuelle Methodenschema. Schlägt Claude Code einen verändernden oder umfassenderen Befehl vor, lehnen Sie ihn bei der Berechtigungsabfrage ab und kehren Sie zum begrenzten Lesezugriff zurück.

Das CLI-Repository ist ohne kostenpflichtiges Paket verfügbar. Konto oder Workspace-Tarif, Cloud-Kontingente sowie Claude-Code-Tarif oder API-Nutzung können Kosten verursachen. Abgerufene Inhalte können vom in Claude Code konfigurierten Anbieter verarbeitet werden; verwenden Sie genehmigte, nicht sensible Testdaten. Die CLI weist darauf hin, kein offiziell unterstütztes Google-Produkt zu sein, und warnt vor Änderungen vor Version 1.0. BIG CHANGE hat weder Leistung noch Kompatibilität getestet. Stoppen Sie vor jedem Schreibzugriff, Versand oder jeder Kontoänderung. [Claudes separates Google-Workspace-Add-on](https://bigchange.ai/blog/claude-google-workspace-add-on-edit-open-files) behandelt das Bearbeiten geöffneter Dateien mit Freigabe über einen anderen Weg.

## Sources

- [README von Google Workspace CLI](https://github.com/googleworkspace/cli/blob/a3768d0e82ad83cca2da97724e46bea4ff0e6dbd/README.md) — Offizielles Repository mit festgelegtem Quellstand, geprüft am 20. Oktober 2026. Belegt Installation, manuelle OAuth-Einrichtung, dynamische Befehle, Vorrang der Zugangsdaten, Versionsinstabilität und den Hinweis auf fehlenden Produktsupport. Belegt kein Ausführungsergebnis von BIG CHANGE.
- [Befehlskontext von Google Workspace CLI](https://github.com/googleworkspace/cli/blob/a3768d0e82ad83cca2da97724e46bea4ff0e6dbd/CONTEXT.md) — Offizielle Anleitung mit festgelegtem Quellstand zu verschachtelten Methoden, --params, Schema-Inspektion und begrenzter Feldauswahl; prüfen Sie die tatsächlich installierte Hilfe.
- [Authentifizierungsimplementierung von Google Workspace CLI](https://github.com/googleworkspace/cli/blob/a3768d0e82ad83cca2da97724e46bea4ff0e6dbd/crates/google-workspace-cli/src/auth_commands.rs) — Der festgelegte Authentifizierungsquellstand bestätigt eigene --scopes, die getrennte Dienstauswahl und ergänzte Identitätsbereiche. Eine Quellprüfung zeigt nicht die tatsächliche Berechtigung eines Lesers.
- [Anleitung zum Aktivieren der Google-Workspace-APIs](https://developers.google.com/workspace/guides/enable-apis) — Googles Anleitung zum Aktivieren von APIs in einem Cloud-Projekt; Projekt- und Administratorrichtlinien bestimmen weiterhin den Zugriff.
- [Referenz für Drive files.list](https://developers.google.com/workspace/drive/api/reference/rest/v3/files/list) — Bestätigt Drive q, pageSize und Antwortfelder zur Begrenzung der Metadatensuche. Eine begrenzte Anfrage begrenzt nicht die OAuth-Befugnis.
- [Referenz für Sheets spreadsheets.values.get](https://developers.google.com/workspace/sheets/api/reference/rest/v4/spreadsheets.values/get) — Bestätigt das Lesen über Tabellen-ID und A1-Bereich sowie die Antwortstruktur; leere Zellen am Ende können fehlen.
- [Referenz für Docs documents.get](https://developers.google.com/workspace/docs/api/reference/rest/v1/documents/get) — Bestätigt den Dokumentabruf und die Beschränkung auf den ersten Tab bei includeTabsContent gleich false. Das Beispiel betrifft ein Testdokument mit einfachem Text und genau einem Tab.
- [Referenzen für Gmail messages.list und messages.get](https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.messages/list) — Die list-Referenz belegt die Suche nach Nachrichten-ID und reine ID-Ergebnisse; q ist mit gmail.metadata nicht verfügbar. Die zugehörige get-Referenz lautet https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.messages/get und belegt metadataHeaders im Format METADATA.
- [Claude-Code-Berechtigungen](https://code.claude.com/docs/en/permissions) — Aktuelle Anthropic-Referenz zu Manual/default-Modus, Ask-Regeln, wirksamen Werkzeugberechtigungen und Shell-Freigabeabfragen. Belegt nicht, dass eine bestimmte Sitzung des Lesers eine konkrete Regel besitzt.