يمكن لـ 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 من إصدار المستودع المخصص لنظام التشغيل لديك أو استخدم الأمر الموثّق التالي مع Node.js 18 أو أحدث:

Terminal
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 قراءة ملفات بيانات الاعتماد. استخدم بيئة خالية من الإعدادات غير المقصودة وتهيئة العميل المطلوبة.

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

Terminal
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:

Terminal
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 لا يثبت الوصول إلى الملف المقصود.

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

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

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

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

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

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

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

Terminal
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 تغطي تحرير الملفات المفتوحة بموافقة المستخدم عبر مسار مختلف.