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

# اربط Claude Code بـ Google Workspace عبر خمسة فحوص للقراءة

> إعداد موثّق لفحص حساب Google Workspace CLI الذي يستخدمه Claude Code، وأذونات OAuth وطلبات الموافقة، بقراءات محدودة من Drive وSheets وDocs و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 تشغيل أوامر Google Workspace CLI (`gws`) من صدفة محلية باستخدام حساب Google الذي جرت المصادقة عليه في `gws`. يستطيع مالك الحساب المخوّل فحص الاتصال بسجل واحد غير حساس في كل من Drive وSheets وDocs وGmail. أكّد الحساب والأذونات الممنوحة أولًا. يتبع هذا الدليل الواجهة الموثّقة في مستودع CLI كما فُحصت في 20 أكتوبر 2026. لم تثبّت BIG CHANGE أيًا من الأداتين ولم تدخل إلى أي حساب.

## التغيير الكبير

- **ما الذي تغيّر:** تتيح أداة `gws` CLI الحالية أساليب Google Workspace API على هيئة أوامر صدفة يستطيع Claude Code تشغيلها. يمكن لحساب واحد موثّق أن يتيح الوصول إلى عدة خدمات عمل، بحسب الأذونات الممنوحة فعلًا وأذونات الصدفة لدى الوكيل.
- **لماذا يهم ذلك:** الاتصال نفسه الذي يتيح للوكيل فحص ملف أو رسالة محددة قد يصل إلى بيانات أخرى تشملها نطاقات OAuth. يستطيع مالك الحساب مقارنة نتائج صغيرة ومعروفة من الطرفية ومن Claude Code قبل تقرير تفويض مزيد من العمل.
- **ما الذي ينبغي الانتباه إليه:** افحص الأوامر التي تولّدها نسخة CLI المثبّتة وقواعد الأذونات الفعلية للجلسة كلما تغيّر هذا الإعداد. الأداة لم تبلغ الإصدار 1.0 بعد؛ ولا يقلّص استعلام ضيق أو قناع حقول الإذن الممنوح على مستوى الحساب.

## قبل الاتصال

استخدم حساب اختبار Google مخصصًا ومعتمدًا يخلو من المحتوى الحساس، ومشروع Cloud يسمح لك بتهيئة OAuth. اسأل المسؤول إن كانت واجهات API الأربع والأذونات المطلوبة مسموحة. جهّز ملف Drive موجودًا ذا اسم فريد، وجدول بيانات بقيم معروفة ضمن نطاق صغير، ومستند Google Doc قصيرًا بنص عادي وعلامة تبويب واحدة، ورسالة Gmail غير حساسة. في Gmail، احصل على قيمة RFC `Message-ID` من **Show original**. ستقارن هذه الأصول بنتائج CLI. هذه الفحوص لا تنشئ شيئًا ولا ترسل شيئًا.

ثبّت Claude Code على حاسوب تتحكم فيه. ثبّت `gws` من [إصدار المستودع المخصص لنظام التشغيل لديك](https://github.com/googleworkspace/cli/releases) أو استخدم الأمر الموثّق التالي مع Node.js 18 أو أحدث:

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

دوّن إصدار الأداة المثبّت وإصدار Claude Code بصورة خاصة. ما تزال CLI قبل 1.0، وتُبنى أوامرها من مستندات اكتشاف API لدى Google. افحص المساعدة المثبّتة ومخططات الأساليب أدناه قبل تشغيل الأمثلة.

## 1. هيّئ تسجيل دخول OAuth بنطاقات محدودة

فعّل واجهات Drive وSheets وDocs وGmail API في مشروع Cloud المعتمد. هيّئ جمهور OAuth وأنشئ عميلًا من النوع **Desktop app**. إذا كان التطبيق External وفي وضع الاختبار، فأضف الحساب المختار كمستخدم اختبار. احفظ ملف JSON للعميل الذي نزّلته في الموضع الموثّق `~/.config/gws/client_secret.json` أو استخدم مجلدًا منفصلًا تحدده بواسطة `GOOGLE_WORKSPACE_CLI_CONFIG_DIR`. أبقِ هذا المجلد خارج مشروع Claude وخاصًا بمالك الحساب.

قبل تسجيل الدخول، افحص بصورة خاصة ما إذا كان قد ضُبط `GOOGLE_WORKSPACE_CLI_TOKEN` أو `GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE`، بما في ذلك عبر ملف `.env`. تتقدم هذه المصادر على بيانات اعتماد OAuth المخزنة. لا تطبع قيمها ولا تطلب من Claude Code قراءة ملفات بيانات الاعتماد. استخدم بيئة خالية من الإعدادات غير المقصودة وتهيئة العميل المطلوبة.

اطلب هذه النطاقات الأربعة صراحةً:

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

أكمل اختيار الحساب والموافقة بنفسك. يضيف مصدر CLI المثبّت على الإصدار المحدد نطاقات الهوية `openid`، `userinfo.email` و `userinfo.profile` أيضًا. قارن بصورة خاصة شاشة الموافقة ومعلومات `gws auth status` للحساب والأذونات وصلاحية الرمز بما قصدته؛ يظل حقل الحالة المفقود غير متحقّق منه. توقّف إن كان الحساب خاطئًا أو بقي إذن أوسع غير متوقّع. اختيار الخدمات في قائمة تسجيل الدخول يرشّح الخيارات؛ ولا يضبط بحد ذاته هذه النطاقات الأربعة المخصصة للقراءة فقط.

النطاقات أوسع من طلبات الأمثلة. يتيح إذن بيانات Drive الوصفية الوصول إلى البيانات الوصفية للملفات المتاحة؛ وتشمل قراءة Sheets وDocs جداول البيانات والمستندات المتاحة؛ وقد يصل إذن قراءة Gmail إلى محتويات صندوق البريد. تحدّ الأسماء والمعرّفات والنطاقات والاستعلامات وأقنعة الحقول من كل استجابة، لا من سلطة الرمز. وقد تصل أداة الصدفة أيضًا إلى بيانات الاعتماد المحلية، لذلك لا يعزلها مسار مخفي أو تعليمات في الطلب.

## 2. نفّذ القراءات المحدودة مباشرةً

افحص أولًا كل أسلوب باستخدام `gws schema drive.files.list` وأسماء المخططات المقابلة للأساليب الأخرى. افحص المساعدة المولّدة `--help` إذا اختلفت معلمة في نسختك المثبّتة. تستخدم الأوامر أدناه صياغة الاقتباس المفرد في Bash؛ عدّل الاقتباس بعناية إذا استخدمت صدفة أخرى. استبدل معرّفات الاختبار والاسم فقط. نفّذ أمرًا واحدًا في كل مرة واحتفظ باستجابته أو خطئه الفعلي بصورة خاصة، دون رموز وصول أو محتوى حساس.

ابحث عن ملف Drive المحدد بالاسم. تستخدم JSON القيمة `\u0027` للهروب من علامات الاقتباس المفردة داخل تعبير البحث في Drive مع الحفاظ على اقتباس 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"}'
```

طابق المعرّف والاسم مع الملف في Drive. عدم وجود تطابق أو وجود `incompleteSearch` لا يثبت الوصول إلى الملف المقصود.

اقرأ الخلايا المعروفة باستخدام معرّف جدول البيانات الفعلي واسم علامة التبويب:

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

قارن القيم المُعادة بجدول البيانات. قد تتجاهل Google الخلايا الفارغة في النهاية، لذا جهّز قيمًا معروفة غير فارغة.

اقرأ علامة التبويب الأولى في مستند الاختبار القصير:

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

طابق المعرّف والعنوان والنص المعروف. لا تفحص هذه الاستجابة المحدودة علامات التبويب الأخرى أو التعليقات أو بنية المستند كاملةً.

في Gmail، ابحث بقيمة RFC للرسالة الموجودة `Message-ID`، ثم استخدم معرّف Gmail المُعاد لطلب حقلين من الترويسة:

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

قارن القيمة المُعادة `Message-ID` والموضوع غير الحساس بالأصل. يعيد الاستدعاء الأول معرّفات الرسائل، لا الترويسات. ويطلب الثاني البيانات الوصفية للترويسة، لا متن الرسالة. الاستجابة الأولى الفارغة لا تسند الفحص الثاني. لا يسمح نطاق OAuth الأضيق للبيانات الوصفية في Gmail باستعلام البحث المستخدم هنا؛ أما إذن قراءة Gmail الممنوح صراحةً فيسمح به.

## 3. كرّر الفحوص عبر Claude Code مع طلبات الإذن

ابدأ Claude Code في مشروع تتحكم فيه وبتهيئة الحساب المعتمدة نفسها. في `/permissions`، افحص الوضع الفعلي وقواعد الصدفة. استخدم Manual، المسمى أيضًا `default`، وقاعدة **Ask** لأداة الصدفة المستخدمة فعلًا؛ عالج أي قاعدة سماح أو تجاوز أوسع وفق سياسة مؤسستك. تجنّب الموافقة الشاملة على `gws *` أو على برنامج وسيط للصدفة. افحص الأمر كاملًا عند كل اقتراح ووافق فقط على القراءة المحدودة الدقيقة التي تقصدها.

اطلب من Claude Code بلغة واضحة اقتراح الأوامر الخمسة أعلاه، بالأهداف الاختبارية نفسها، وتنفيذها واحدًا تلو الآخر بعد قرارك بشأن الإذن فقط. اطلب عرض الناتج أو الأخطاء دون قراءة بيانات الاعتماد أو توسيع الاستعلامات أو تنفيذ كتابة. ثم قارن كل نتيجة بالنتيجة المباشرة وبالعنصر الأصلي. يمكن لتعليمات المشروع وصف المهمة، لكن أذونات الأدوات الفعلية وأذونات OAuth هي التي تحكم الوصول.

| الخدمة | دليل الإكمال من المسارين |
| --- | --- |
| Drive | معرّف الملف المسمّى نفسه واسمه؛ والبحث مكتمل. |
| Sheets | علامة التبويب والنطاق وقيم الخلايا المعروفة المتوقعة. |
| Docs | المعرّف والعنوان ونص علامة التبويب الأولى المتوقع. |
| Gmail | تعثر القائمة على رسالة الاختبار؛ وتطابق قراءة البيانات الوصفية قيمة `Message-ID` وموضوعها. |

سجّل الإصدارات والحساب الذي جرت مصادقته والأذونات الفعلية ومعرّفات الأهداف والنتيجة المباشرة ونتيجة Claude وأي أخطاء في سجل فحص خاص. الطلب الفاشل، والاستجابة الناجحة الفارغة، والعنصر المتحقّق منه نتائج مختلفة. لا تنتهِ إلا بعد التحقّق من الخدمات الأربع عبر المسارين.

## إذا فشل أحد الفحوص

قد يعني ظهور **Access blocked** عند تسجيل الدخول أن حساب الاختبار غير موجود في قائمة مستخدمي الاختبار لتطبيق OAuth. عند خطأ API أو نطاق، أكّد تفعيل API والحساب المحدد والأذونات الفعلية قبل طلب موافقة جديدة معتمدة. إذا كانت القائمة فارغة، فافحص الهدف الدقيق والاستعلام والحساب. إن اختلفت المساعدة المثبّتة عن الأمثلة، فاستخدم مخطط الأسلوب الحالي قبل المتابعة. إن اقترح Claude Code أمرًا يغيّر بيانات أو يتجاوز النطاق، فارفضه عند طلب الإذن وعد إلى القراءة المحدودة.

يتاح مستودع CLI دون حزمة مدفوعة. قد تترتب تكاليف على الحساب أو خطة Workspace أو حصص Cloud أو خطة Claude Code أو استخدام API. قد يعالج المحتوى المسترجع مزوّد الخدمة المضبوط في Claude Code؛ لذا احصر الاختبارات في بيانات غير حساسة ومعتمدة. توضح CLI أنها ليست منتجًا تدعمه Google رسميًا وتحذّر من تغييرات ما قبل 1.0. لم تختبر BIG CHANGE الأداء أو التوافق. توقّف قبل أي كتابة أو إرسال أو تغيير للحساب. [إضافة Google Workspace المنفصلة في Claude](https://bigchange.ai/blog/claude-google-workspace-add-on-edit-open-files) تغطي تحرير الملفات المفتوحة بموافقة المستخدم عبر مسار مختلف.

## Sources

- [ملف README لـ Google Workspace CLI](https://github.com/googleworkspace/cli/blob/a3768d0e82ad83cca2da97724e46bea4ff0e6dbd/README.md) — مستودع رسمي مثبّت على مراجعة محددة، فُحص في 20 أكتوبر 2026. يثبت التثبيت وإعداد OAuth اليدوي والأوامر الديناميكية وأولوية بيانات الاعتماد وعدم استقرار الإصدارات وإشعار عدم الدعم الرسمي. لا يثبت نتيجة تنفيذ أجرتها BIG CHANGE.
- [سياق أوامر Google Workspace CLI](https://github.com/googleworkspace/cli/blob/a3768d0e82ad83cca2da97724e46bea4ff0e6dbd/CONTEXT.md) — إرشادات رسمية مثبّتة على مراجعة محددة للأساليب المتداخلة و--params وفحص المخططات واختيار الحقول المحدودة؛ يجب فحص المساعدة المثبّتة فعليًا.
- [تنفيذ المصادقة في Google Workspace CLI](https://github.com/googleworkspace/cli/blob/a3768d0e82ad83cca2da97724e46bea4ff0e6dbd/crates/google-workspace-cli/src/auth_commands.rs) — يؤكد مصدر المصادقة المثبّت على مراجعة محددة تخصيص --scopes، وسلوك اختيار الخدمات المنفصل، ونطاقات الهوية المضافة. لا يُظهر فحص المصدر الإذن الممنوح فعليًا للقارئ.
- [دليل تفعيل Google Workspace API](https://developers.google.com/workspace/guides/enable-apis) — تعليمات Google لتفعيل واجهات API في مشروع Cloud؛ ما تزال سياسات المشروع والمسؤول تحكم الوصول.
- [مرجع Drive files.list](https://developers.google.com/workspace/drive/api/reference/rest/v3/files/list) — يؤكد q وpageSize وحقول الاستجابة المستخدمة لتقييد البحث في البيانات الوصفية في Drive. الطلب الضيق لا يضيّق سلطة OAuth.
- [مرجع Sheets spreadsheets.values.get](https://developers.google.com/workspace/sheets/api/reference/rest/v4/spreadsheets.values/get) — يؤكد القراءة باستخدام معرّف جدول بيانات ونطاق A1 وشكل الاستجابة؛ قد تُحذف الخلايا الفارغة في النهاية.
- [مرجع Docs documents.get](https://developers.google.com/workspace/docs/api/reference/rest/v1/documents/get) — يؤكد جلب المستند وقصر النتيجة على علامة التبويب الأولى عندما تكون includeTabsContent بقيمة false. المثال مخصص لمستند اختبار بنص عادي وعلامة تبويب واحدة.
- [مرجعا Gmail messages.list وmessages.get](https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.messages/list) — يثبت مرجع القائمة البحث بمعرّف الرسالة ونتائج القائمة التي تحتوي المعرّفات فقط؛ لا تتاح q مع gmail.metadata. مرجع get المقابل هو https://developers.google.com/workspace/gmail/api/reference/rest/v1/users.messages/get ويثبت metadataHeaders مع التنسيق METADATA.
- [أذونات Claude Code](https://code.claude.com/docs/en/permissions) — مرجع Anthropic الحالي لوضع Manual/default وقواعد Ask وأذونات الأدوات الفعلية وطلبات الموافقة على الصدفة. لا يثبت أن جلسة القارئ تتبع قاعدة معينة.