DUNIA TERUS BERGERAK.RSS
BIG CHANGE.

Edisi Markdown

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

# Hubungkan Claude Code ke Google Workspace dengan lima pemeriksaan baca

> Penyiapan berdasarkan dokumentasi untuk memeriksa akun Google Workspace CLI yang digunakan Claude Code, izin OAuth, dan permintaan persetujuan melalui pembacaan terbatas di Drive, Sheets, Docs, dan 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 dapat menjalankan perintah Google Workspace CLI (`gws`) dari shell lokal menggunakan akun Google yang diautentikasi di `gws`. Pemilik akun yang berwenang dapat memeriksa sambungan dengan satu rekaman tidak sensitif di masing-masing layanan Drive, Sheets, Docs, dan Gmail. Konfirmasikan akun dan izin terlebih dahulu. Panduan ini mengikuti antarmuka yang didokumentasikan dalam repositori CLI, diperiksa pada 20 Oktober 2026. BIG CHANGE tidak memasang kedua alat tersebut atau mengakses akun.

## Perubahan besar

- **Apa yang berubah:** CLI `gws` saat ini menyediakan metode Google Workspace API sebagai perintah shell yang dapat dijalankan Claude Code. Satu akun terautentikasi dapat memberi akses ke beberapa layanan kerja, sesuai izin yang benar-benar diberikan dan izin shell agen.
- **Mengapa ini penting:** Sambungan yang memungkinkan agen memeriksa berkas atau pesan pilihan juga dapat menjangkau data lain dalam cakupan OAuth-nya. Pemilik akun dapat membandingkan hasil kecil yang sudah diketahui dari terminal dan Claude Code sebelum memutuskan untuk mendelegasikan pekerjaan lebih lanjut.
- **Yang perlu diperhatikan:** Periksa perintah yang dihasilkan CLI terpasang dan aturan izin efektif sesi setiap kali penyiapan ini berubah. CLI masih sebelum versi 1.0; kueri contoh yang sempit atau pembatasan bidang tidak mengurangi izin tingkat akun.

## Sebelum menghubungkan

Gunakan akun uji Google khusus yang disetujui dan tidak berisi konten sensitif, serta proyek Cloud tempat Anda boleh mengonfigurasi OAuth. Tanyakan kepada administrator apakah keempat API dan izin yang diminta diperbolehkan. Siapkan berkas Drive yang sudah ada dengan nama unik, spreadsheet berisi nilai yang diketahui dalam rentang kecil, Google Doc pendek berteks biasa dengan satu tab, dan pesan Gmail tidak sensitif. Untuk Gmail, dapatkan RFC `Message-ID` dari **Show original**. Anda akan membandingkan sumber asli tersebut dengan hasil CLI. Pemeriksaan ini tidak membuat atau mengirim apa pun.

Pasang Claude Code pada komputer yang Anda kendalikan. Pasang `gws` dari [rilis repositori untuk OS Anda](https://github.com/googleworkspace/cli/releases) atau, dengan Node.js 18 atau lebih baru, gunakan perintah yang didokumentasikan:

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

Catat versi yang terpasang dan versi Claude Code secara pribadi. CLI masih sebelum 1.0, dan perintahnya dibangun dari dokumen penemuan API Google. Periksa bantuan yang terpasang dan skema metode di bawah sebelum menjalankan contoh.

## 1. Konfigurasikan login OAuth dengan cakupan terbatas

Dalam proyek Cloud yang disetujui, aktifkan API Drive, Sheets, Docs, dan Gmail. Konfigurasikan audiens OAuth dan buat klien **Desktop app**. Jika aplikasi berstatus External dan dalam pengujian, tambahkan akun pilihan sebagai pengguna uji. Simpan JSON klien yang diunduh di lokasi terdokumentasi `~/.config/gws/client_secret.json` atau gunakan direktori terpisah yang dipilih dengan `GOOGLE_WORKSPACE_CLI_CONFIG_DIR`. Letakkan direktori itu di luar proyek Claude dan batasi aksesnya untuk pemilik akun.

Sebelum login, periksa secara pribadi apakah `GOOGLE_WORKSPACE_CLI_TOKEN` atau `GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE` telah ditetapkan, termasuk melalui berkas `.env`. Sumber tersebut diprioritaskan di atas kredensial OAuth tersimpan. Jangan mencetak nilainya atau meminta Claude Code membaca berkas kredensial. Gunakan lingkungan bersih dan konfigurasi klien yang dimaksud.

Minta keempat cakupan ini secara eksplisit:

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

Selesaikan pemilihan akun dan persetujuan sendiri. Sumber CLI pada revisi yang ditetapkan juga menambahkan cakupan identitas `openid`, `userinfo.email` dan `userinfo.profile`. Secara pribadi, bandingkan persetujuan dan informasi `gws auth status` tentang akun, izin, dan validitas token dengan yang Anda maksud; bidang status yang tidak ada tetap belum terverifikasi. Berhenti jika akunnya salah atau izin lebih luas yang tidak diharapkan masih ada. Memilih layanan dalam pemilih login hanya menyaring pilihan; itu tidak dengan sendirinya menetapkan empat cakupan baca-saja ini.

Cakupannya lebih luas daripada permintaan contoh. Akses metadata Drive menjangkau metadata berkas yang dapat diakses; akses baca-saja Sheets dan Docs meliputi spreadsheet serta dokumen yang dapat diakses; baca-saja Gmail dapat mengakses isi kotak surat. Nama, ID, rentang, kueri, dan pembatasan bidang membatasi setiap respons, bukan wewenang token. Alat shell juga dapat menjangkau kredensial lokal, sehingga jalur berkas tersembunyi atau instruksi dalam prompt tidak mengisolasinya.

## 2. Jalankan pembacaan terbatas secara langsung

Periksa dahulu setiap metode dengan `gws schema drive.files.list` dan nama skema yang sesuai untuk metode lainnya. Periksa bantuan yang dihasilkan `--help` jika ada parameter berbeda dalam versi yang terpasang. Perintah di bawah menggunakan sintaks tanda kutip tunggal Bash; sesuaikan pengutipan dengan sengaja untuk shell lain. Ganti hanya pengenal dan nama uji. Jalankan satu perintah setiap kali dan simpan respons atau galat sebenarnya secara pribadi, tanpa token atau konten sensitif.

Cari berkas Drive yang dinamai. JSON `\u0027` melakukan escape pada apostrof di dalam ekspresi pencarian Drive sambil mempertahankan pengutipan 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"}'
```

Cocokkan ID dan namanya dengan berkas di Drive. Tidak adanya kecocokan atau `incompleteSearch` tidak membuktikan akses ke berkas yang dimaksud.

Baca sel yang diketahui menggunakan ID spreadsheet dan nama tab sebenarnya:

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

Bandingkan nilai yang dikembalikan dengan spreadsheet. Google dapat menghilangkan sel kosong di bagian akhir, jadi siapkan nilai yang diketahui dan tidak kosong.

Baca tab pertama Doc uji yang pendek:

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

Cocokkan ID, judul, dan teks yang diketahui. Respons terbatas ini tidak memeriksa tab lain, komentar, atau struktur dokumen lengkap.

Untuk Gmail, cari berdasarkan RFC pesan yang sudah ada `Message-ID`, lalu gunakan ID Gmail yang dikembalikan untuk meminta dua header:

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

Bandingkan nilai `Message-ID` yang dikembalikan dan subjek tidak sensitif dengan aslinya. Panggilan pertama mengembalikan ID pesan, bukan header. Panggilan kedua meminta metadata header, bukan isi pesan. Respons pertama yang kosong tidak dapat mendukung pemeriksaan kedua. Cakupan OAuth metadata Gmail yang lebih sempit tidak mengizinkan kueri pencarian yang digunakan di sini; izin baca-saja Gmail yang eksplisit mengizinkannya.

## 3. Ulangi melalui Claude Code dengan permintaan izin

Mulai Claude Code dalam proyek yang Anda kendalikan, dengan konfigurasi akun disetujui yang sama. Di `/permissions`, periksa mode efektif dan aturan shell. Gunakan Manual, yang juga disebut `default`, serta aturan **Ask** untuk alat shell yang sebenarnya; selesaikan aturan izin atau bypass lebih luas sesuai kebijakan organisasi Anda. Hindari persetujuan menyeluruh untuk `gws *` atau pembungkus shell. Pada setiap usulan, periksa perintah lengkap dan setujui hanya pembacaan terbatas persis yang Anda maksud.

Beri tahu Claude Code dengan bahasa biasa agar mengusulkan lima perintah di atas menggunakan target uji yang sama, lalu menjalankannya satu per satu hanya setelah keputusan izin Anda. Minta agar ia melaporkan keluaran perintah atau galat tanpa membaca kredensial, memperluas kueri, atau melakukan penulisan. Lalu bandingkan setiap hasil dengan hasil langsung dan objek asli. Instruksi proyek dapat menjelaskan tugas ini, tetapi izin alat efektif dan izin OAuth menentukan akses.

| Layanan | Bukti penyelesaian dari kedua jalur |
| --- | --- |
| Drive | ID dan nama berkas bernama yang sama; pencarian tuntas. |
| Sheets | Tab, rentang, dan nilai sel yang diketahui sesuai harapan. |
| Docs | ID, judul, dan teks tab pertama sesuai harapan. |
| Gmail | Daftar menemukan pesan uji; pengambilan metadata cocok dengan `Message-ID` dan subjeknya. |

Catat versi, akun terautentikasi, izin aktual, ID target, hasil langsung, hasil Claude, dan galat apa pun dalam lembar pemeriksaan pribadi. Permintaan gagal, respons berhasil yang kosong, dan objek terverifikasi adalah hasil yang berbeda. Selesai hanya setelah keempat layanan terverifikasi melalui kedua jalur.

## Jika pemeriksaan gagal

Pesan **Access blocked** saat login dapat berarti akun uji tidak ada dalam daftar pengguna uji aplikasi OAuth. Untuk galat API atau cakupan, konfirmasikan API yang diaktifkan, akun pilihan, dan izin aktual sebelum meminta persetujuan ulang yang disetujui. Untuk daftar kosong, periksa target persis, kueri, dan akun. Jika bantuan yang terpasang berbeda dari contoh ini, gunakan skema metode terkini sebelum melanjutkan. Jika Claude Code mengusulkan perintah yang mengubah data atau lebih luas, tolak pada permintaan izin dan kembali ke pembacaan terbatas.

Repositori CLI tersedia tanpa paket berbayar. Akun atau paket Workspace, kuota Cloud, dan paket Claude Code atau penggunaan API dapat menimbulkan biaya. Konten yang diambil mungkin diproses penyedia yang dikonfigurasi di Claude Code, jadi gunakan hanya data uji tidak sensitif yang disetujui. CLI menyatakan bukan produk yang didukung resmi oleh Google dan memperingatkan perubahan sebelum 1.0. BIG CHANGE belum menguji kinerja atau kompatibilitas. Berhenti sebelum penulisan, pengiriman, atau perubahan akun apa pun. [Add-on Google Workspace Claude yang terpisah](https://bigchange.ai/blog/claude-google-workspace-add-on-edit-open-files) membahas penyuntingan berkas terbuka dengan persetujuan melalui jalur berbeda.

## Sources

- [README Google Workspace CLI](https://github.com/googleworkspace/cli/blob/a3768d0e82ad83cca2da97724e46bea4ff0e6dbd/README.md) — Repositori resmi pada revisi yang ditetapkan, diperiksa 20 Oktober 2026. Menetapkan pemasangan, penyiapan OAuth manual, perintah dinamis, prioritas kredensial, ketidakstabilan versi, dan pemberitahuan produk tanpa dukungan resmi. Tidak membuktikan hasil pelaksanaan oleh BIG CHANGE.
- [Konteks perintah Google Workspace CLI](https://github.com/googleworkspace/cli/blob/a3768d0e82ad83cca2da97724e46bea4ff0e6dbd/CONTEXT.md) — Panduan perintah resmi pada revisi yang ditetapkan untuk metode bertingkat, --params, pemeriksaan skema, dan pemilihan bidang terbatas; bantuan aktual yang terpasang harus diperiksa.
- [Implementasi autentikasi Google Workspace CLI](https://github.com/googleworkspace/cli/blob/a3768d0e82ad83cca2da97724e46bea4ff0e6dbd/crates/google-workspace-cli/src/auth_commands.rs) — Sumber autentikasi pada revisi yang ditetapkan mengonfirmasi --scopes khusus, perilaku pemilih layanan yang terpisah, serta penambahan cakupan identitas. Pemeriksaan sumber tidak dapat menunjukkan izin aktual pembaca.
- [Panduan pengaktifan Google Workspace API](https://developers.google.com/workspace/guides/enable-apis) — Petunjuk Google untuk mengaktifkan API dalam proyek Cloud; kebijakan proyek dan administrator tetap mengatur akses.
- [Referensi Drive files.list](https://developers.google.com/workspace/drive/api/reference/rest/v3/files/list) — Mengonfirmasi q, pageSize, dan bidang respons Drive yang digunakan untuk membatasi pencarian metadata. Permintaan sempit tidak mempersempit wewenang OAuth.
- [Referensi Sheets spreadsheets.values.get](https://developers.google.com/workspace/sheets/api/reference/rest/v4/spreadsheets.values/get) — Mengonfirmasi pembacaan dengan ID spreadsheet dan rentang A1 serta bentuk respons; sel kosong di bagian akhir dapat dihilangkan.
- [Referensi Docs documents.get](https://developers.google.com/workspace/docs/api/reference/rest/v1/documents/get) — Mengonfirmasi pengambilan dokumen dan batas tab pertama ketika includeTabsContent bernilai false. Contoh ini untuk dokumen uji teks biasa dengan satu tab.
- [Referensi Gmail messages.list dan messages.get](https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.messages/list) — Referensi daftar menetapkan pencarian ID pesan dan hasil daftar yang hanya memuat ID; q tidak tersedia dengan gmail.metadata. Referensi get pasangannya adalah https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.messages/get dan menetapkan metadataHeaders dengan format METADATA.
- [Izin Claude Code](https://code.claude.com/docs/en/permissions) — Referensi terkini Anthropic untuk mode Manual/default, aturan Ask, izin alat efektif, dan permintaan persetujuan shell. Tidak membuktikan bahwa sesi pembaca memiliki aturan tertentu.