Google Chat

الحالة: Plugin قابل للتنزيل للرسائل المباشرة + المساحات عبر Webhook الخاصة بـ Google Chat API (HTTP فقط).

# التثبيت

ثبّت Google Chat قبل إعداد القناة:

openclaw plugins install @openclaw/googlechat

نسخة محلية (عند التشغيل من مستودع git):

openclaw plugins install ./path/to/local/googlechat-plugin

# الإعداد السريع (للمبتدئين)

1. أنشئ مشروع Google Cloud وفعّل Google Chat API.
   • انتقل إلى: بيانات اعتماد Google Chat API
   • فعّل API إذا لم يكن مفعّلًا بالفعل.
2. أنشئ حساب خدمة:
   • اضغط إنشاء بيانات اعتماد > حساب خدمة.
   • سمّه بأي اسم تريده (مثل openclaw-chat).
   • اترك الأذونات فارغة (اضغط متابعة).
   • اترك الجهات الرئيسية ذات الوصول فارغة (اضغط تم).
3. أنشئ مفتاح JSON ونزّله:
   • في قائمة حسابات الخدمة، انقر على الحساب الذي أنشأته للتو.
   • انتقل إلى تبويب المفاتيح.
   • انقر إضافة مفتاح > إنشاء مفتاح جديد.
   • حدّد JSON واضغط إنشاء.
4. خزّن ملف JSON الذي تم تنزيله على مضيف Gateway لديك (مثل ~/.openclaw/googlechat-service-account.json).
5. أنشئ تطبيق Google Chat في إعدادات Chat في Google Cloud Console:
   • املأ معلومات التطبيق:
     • اسم التطبيق: (مثل OpenClaw)
     • رابط الصورة الرمزية: (مثل https://openclaw.ai/logo.png)
     • الوصف: (مثل Personal AI Assistant)
   • فعّل الميزات التفاعلية.
   • ضمن الوظائف، حدّد الانضمام إلى المساحات والمحادثات الجماعية.
   • ضمن إعدادات الاتصال، حدّد رابط نقطة نهاية HTTP.
   • ضمن المشغّلات، حدّد استخدام رابط نقطة نهاية HTTP مشتركة لكل المشغّلات واضبطه على الرابط العام لـ Gateway لديك متبوعًا بـ /googlechat.
     • نصيحة: شغّل openclaw status للعثور على الرابط العام لـ Gateway لديك.
   • ضمن الرؤية، حدّد إتاحة تطبيق Chat هذا لأشخاص ومجموعات محددة في <Your Domain>.
   • أدخل عنوان بريدك الإلكتروني (مثل [email protected]) في مربع النص.
   • انقر حفظ في الأسفل.
6. فعّل حالة التطبيق:
   • بعد الحفظ، حدّث الصفحة.
   • ابحث عن قسم حالة التطبيق (غالبًا قرب الأعلى أو الأسفل بعد الحفظ).
   • غيّر الحالة إلى مباشر - متاح للمستخدمين.
   • انقر حفظ مرة أخرى.
7. اضبط OpenClaw بمسار حساب الخدمة + جمهور Webhook:
   • Env: GOOGLE_CHAT_SERVICE_ACCOUNT_FILE=/path/to/service-account.json
   • أو config: channels.googlechat.serviceAccountFile: "/path/to/service-account.json".
8. اضبط نوع جمهور Webhook + القيمة (يطابق إعداد تطبيق Chat لديك).
9. ابدأ Gateway. سيرسل Google Chat طلب POST إلى مسار Webhook لديك.

# الإضافة إلى Google Chat

بعد تشغيل Gateway وإضافة بريدك الإلكتروني إلى قائمة الرؤية:

1. انتقل إلى Google Chat.
2. انقر أيقونة + (زائد) بجانب الرسائل المباشرة.
3. في شريط البحث (حيث تضيف الأشخاص عادةً)، اكتب اسم التطبيق الذي أعددته في Google Cloud Console.
   • ملاحظة: لن يظهر البوت في قائمة تصفح "Marketplace" لأنه تطبيق خاص. يجب البحث عنه بالاسم.
4. حدّد البوت من النتائج.
5. انقر إضافة أو دردشة لبدء محادثة 1:1.
6. أرسل "مرحبًا" لتشغيل المساعد!

# الرابط العام (Webhook فقط)

تتطلب Webhook الخاصة بـ Google Chat نقطة نهاية HTTPS عامة. للأمان، اعرض مسار /googlechat فقط على الإنترنت. أبقِ لوحة تحكم OpenClaw ونقاط النهاية الحساسة الأخرى على شبكتك الخاصة.

# الخيار أ: Tailscale Funnel (موصى به)

استخدم Tailscale Serve للوحة التحكم الخاصة وFunnel لمسار Webhook العام. هذا يُبقي / خاصًا مع عرض /googlechat فقط.

1. تحقق من العنوان الذي يرتبط به Gateway لديك:

   ss -tlnp | grep 18789
   

   لاحظ عنوان IP (مثل 127.0.0.1 أو 0.0.0.0 أو عنوان Tailscale IP لديك مثل 100.x.x.x).

2. اعرض لوحة التحكم على tailnet فقط (المنفذ 8443):

   # If bound to localhost (127.0.0.1 or 0.0.0.0):
   tailscale serve --bg --https 8443 http://127.0.0.1:18789
   
   # If bound to Tailscale IP only (e.g., 100.106.161.80):
   tailscale serve --bg --https 8443 http://100.106.161.80:18789
   

3. اعرض مسار Webhook فقط للعامة:

   # If bound to localhost (127.0.0.1 or 0.0.0.0):
   tailscale funnel --bg --set-path /googlechat http://127.0.0.1:18789/googlechat
   
   # If bound to Tailscale IP only (e.g., 100.106.161.80):
   tailscale funnel --bg --set-path /googlechat http://100.106.161.80:18789/googlechat
   

4. خوّل Node للوصول إلى Funnel: إذا طُلب منك ذلك، زُر رابط التخويل المعروض في المخرجات لتمكين Funnel لهذا Node في سياسة tailnet لديك.

5. تحقق من الإعداد:

   tailscale serve status
   tailscale funnel status
   

سيكون رابط Webhook العام لديك: https://<node-name>.<tailnet>.ts.net/googlechat

تبقى لوحة التحكم الخاصة لديك محصورة على tailnet: https://<node-name>.<tailnet>.ts.net:8443/

استخدم الرابط العام (من دون :8443) في إعدادات تطبيق Google Chat.

ملاحظة: يستمر هذا الإعداد عبر عمليات إعادة التشغيل. لإزالته لاحقًا، شغّل tailscale funnel reset وtailscale serve reset.

# الخيار ب: وكيل عكسي (Caddy)

إذا كنت تستخدم وكيلًا عكسيًا مثل Caddy، فمرّر المسار المحدد فقط:

your-domain.com {
    reverse_proxy /googlechat* localhost:18789
}

مع هذا الإعداد، سيتم تجاهل أي طلب إلى your-domain.com/ أو إرجاعه كـ 404، بينما يتم توجيه your-domain.com/googlechat بأمان إلى OpenClaw.

# الخيار ج: Cloudflare Tunnel

اضبط قواعد الدخول للنفق بحيث تمرّر مسار Webhook فقط:

• المسار: /googlechat -> http://localhost:18789/googlechat
• القاعدة الافتراضية: HTTP 404 (غير موجود)

# طريقة العمل

1. يرسل Google Chat طلبات POST الخاصة بـ Webhook إلى Gateway. يتضمن كل طلب ترويسة Authorization: Bearer <token>.
   • يتحقق OpenClaw من مصادقة bearer قبل قراءة/تحليل أجسام Webhook الكاملة عندما تكون الترويسة موجودة.
   • طلبات Google Workspace Add-on التي تحمل authorizationEventObject.systemIdToken في الجسم مدعومة عبر ميزانية جسم أكثر صرامة قبل المصادقة.
2. يتحقق OpenClaw من الرمز مقابل audienceType + audience المكوّنين:
   • audienceType: "app-url" → الجمهور هو رابط HTTPS الخاص بـ Webhook لديك.
   • audienceType: "project-number" → الجمهور هو رقم مشروع Cloud.
3. تُوجّه الرسائل حسب المساحة:
   • تستخدم الرسائل المباشرة مفتاح جلسة agent:<agentId>:googlechat:direct:<spaceId>.
   • تستخدم المساحات مفتاح جلسة agent:<agentId>:googlechat:group:<spaceId>.
4. يكون الوصول إلى الرسائل المباشرة بالاقتران افتراضيًا. يتلقى المرسلون غير المعروفين رمز اقتران؛ وافق عليه باستخدام:
   • openclaw pairing approve googlechat <code>
5. تتطلب المساحات الجماعية ذكر @ افتراضيًا. استخدم botUser إذا كان كشف الذكر يحتاج إلى اسم مستخدم التطبيق.

# الأهداف

استخدم هذه المعرّفات للتسليم وقوائم السماح:

• الرسائل المباشرة: users/<userId> (موصى به).
• البريد الإلكتروني الخام [email protected] قابل للتغيير ولا يُستخدم إلا لمطابقة قائمة السماح المباشرة عندما يكون channels.googlechat.dangerouslyAllowNameMatching: true.
• مهمل: يُعامل users/<email> كمعرّف مستخدم، وليس كقائمة سماح للبريد الإلكتروني.
• المساحات: spaces/<spaceId>.

# أبرز الإعدادات

{
  channels: {
    googlechat: {
      enabled: true,
      serviceAccountFile: "/path/to/service-account.json",
      // or serviceAccountRef: { source: "file", provider: "filemain", id: "/channels/googlechat/serviceAccount" }
      audienceType: "app-url",
      audience: "https://gateway.example.com/googlechat",
      webhookPath: "/googlechat",
      botUser: "users/1234567890", // optional; helps mention detection
      dm: {
        policy: "pairing",
        allowFrom: ["users/1234567890"],
      },
      groupPolicy: "allowlist",
      groups: {
        "spaces/AAAA": {
          enabled: true,
          requireMention: true,
          users: ["users/1234567890"],
          systemPrompt: "Short answers only.",
        },
      },
      actions: { reactions: true },
      typingIndicator: "message",
      mediaMaxMb: 20,
    },
  },
}

ملاحظات:

• يمكن أيضًا تمرير بيانات اعتماد حساب الخدمة داخلية باستخدام serviceAccount (سلسلة JSON).
• serviceAccountRef مدعوم أيضًا (env/file SecretRef)، بما في ذلك المراجع لكل حساب ضمن channels.googlechat.accounts.<id>.serviceAccountRef.
• مسار Webhook الافتراضي هو /googlechat إذا لم يتم ضبط webhookPath.
• يعيد dangerouslyAllowNameMatching تمكين مطابقة هوية البريد الإلكتروني القابلة للتغيير لقوائم السماح (وضع توافق للطوارئ).
• التفاعلات متاحة عبر أداة reactions وchannels action عندما يكون actions.reactions مفعّلًا.
• تكشف إجراءات الرسائل send للنص وupload-file لإرسال المرفقات الصريح. يقبل upload-file القيم media / filePath / path بالإضافة إلى message وfilename اختياريين واستهداف السلاسل.
• يدعم typingIndicator القيم none وmessage (الافتراضي) وreaction (يتطلب التفاعل OAuth للمستخدم).
• يتم تنزيل المرفقات عبر Chat API وتخزينها في مسار الوسائط (الحجم محدود بـ mediaMaxMb).

تفاصيل مراجع الأسرار: إدارة الأسرار.

# استكشاف الأخطاء وإصلاحها

# 405 Method Not Allowed

إذا أظهر Google Cloud Logs Explorer أخطاء مثل:

status code: 405, reason phrase: HTTP error response: HTTP/1.1 405 Method Not Allowed

فهذا يعني أن معالج Webhook غير مسجّل. الأسباب الشائعة:

1. القناة غير مكوّنة: قسم channels.googlechat مفقود من إعداداتك. تحقق باستخدام:

   openclaw config get channels.googlechat
   

   إذا أعاد "Config path not found"، فأضف الإعداد (راجع أبرز الإعدادات).

2. Plugin غير مفعّل: تحقق من حالة Plugin:

   openclaw plugins list | grep googlechat
   

   إذا أظهر "disabled"، فأضف plugins.entries.googlechat.enabled: true إلى إعداداتك.

3. لم تتم إعادة تشغيل Gateway: بعد إضافة الإعداد، أعد تشغيل Gateway:

   openclaw gateway restart
   

تحقق من أن القناة تعمل:

openclaw channels status
# Should show: Google Chat default: enabled, configured, ...

# مشكلات أخرى

• تحقق من openclaw channels status --probe لأخطاء المصادقة أو إعداد جمهور مفقود.
• إذا لم تصل أي رسائل، فتحقق من رابط Webhook لتطبيق Chat + اشتراكات الأحداث.
• إذا منع حاجز الذكر الردود، فاضبط botUser على اسم مورد مستخدم التطبيق وتحقق من requireMention.
• استخدم openclaw logs --follow أثناء إرسال رسالة اختبار لمعرفة ما إذا كانت الطلبات تصل إلى Gateway.

مستندات ذات صلة:

• إعداد Gateway
• الأمان
• التفاعلات

# ذو صلة

• نظرة عامة على القنوات — كل القنوات المدعومة
• الاقتران — مصادقة الرسائل المباشرة وتدفق الاقتران
• المجموعات — سلوك الدردشة الجماعية وحاجز الذكر
• توجيه القنوات — توجيه الجلسات للرسائل
• الأمان — نموذج الوصول والتقوية