Hubungkan Claude Code ke Google Workspace dengan lima pemeriksaan baca

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 atau, dengan Node.js 18 atau lebih baru, gunakan perintah yang didokumentasikan:

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:

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:

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:

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:

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:

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.

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 membahas penyuntingan berkas terbuka dengan persetujuan melalui jalur berbeda.