​

Google Chat (Chat API)

​

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

1. أنشئ مشروعًا في Google Cloud وفعّل Google Chat API.
   • انتقل إلى: Google Chat API Credentials
   • فعّل واجهة برمجة التطبيقات إذا لم تكن مفعّلة بالفعل.
2. أنشئ حساب خدمة:
   • اضغط Create Credentials > Service Account.
   • سمّه بأي اسم تريده (مثلًا: openclaw-chat).
   • اترك الأذونات فارغة (اضغط Continue).
   • اترك الجهات ذات الوصول فارغة (اضغط Done).
3. أنشئ ونزّل مفتاح JSON:
   • في قائمة حسابات الخدمة، انقر على الحساب الذي أنشأته للتو.
   • انتقل إلى تبويب Keys.
   • انقر Add Key > Create new key.
   • اختر JSON واضغط Create.
4. خزّن ملف JSON الذي تم تنزيله على مضيف Gateway لديك (مثلًا: ~/.openclaw/googlechat-service-account.json).
5. أنشئ تطبيق Google Chat في Google Cloud Console Chat Configuration:
   • املأ Application info:
     • App name: (مثلًا: OpenClaw)
     • Avatar URL: (مثلًا: https://openclaw.ai/logo.png)
     • Description: (مثلًا: Personal AI Assistant)
   • فعّل Interactive features.
   • ضمن Functionality، حدّد Join spaces and group conversations.
   • ضمن Connection settings، اختر HTTP endpoint URL.
   • ضمن Triggers، اختر Use a common HTTP endpoint URL for all triggers واضبطه على عنوان Gateway العام متبوعًا بـ /googlechat.
     • تلميح: شغّل openclaw status للعثور على عنوان Gateway العام.
   • ضمن Visibility، حدّد Make this Chat app available to specific people and groups in <Your Domain>.
   • أدخل عنوان بريدك الإلكتروني (مثلًا: [email protected]) في مربع النص.
   • انقر Save في الأسفل.
6. تفعيل حالة التطبيق:
   • بعد الحفظ، حدّث الصفحة.
   • ابحث عن قسم App status (غالبًا قرب الأعلى أو الأسفل بعد الحفظ).
   • غيّر الحالة إلى Live - available to users.
   • انقر Save مرة أخرى.
7. هيّئ OpenClaw بمسار حساب الخدمة + جمهور الـ webhook:
   • متغير البيئة: GOOGLE_CHAT_SERVICE_ACCOUNT_FILE=/path/to/service-account.json
   • أو التهيئة: channels.googlechat.serviceAccountFile: "/path/to/service-account.json".
8. اضبط نوع وقيمة جمهور الـ webhook (يطابق إعداد تطبيق Chat).
9. ابدأ تشغيل Gateway. سيقوم Google Chat بإرسال طلبات POST إلى مسار الـ webhook لديك.

​

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

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

​

العنوان العام (Webhook فقط)

​

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

1. تحقق من العنوان الذي يرتبط به Gateway:
   ss -tlnp | grep 18789
   
   دوّن عنوان IP (مثلًا: 127.0.0.1، 0.0.0.0، أو عنوان Tailscale مثل 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. فوّض العُقدة للوصول عبر Funnel: إذا طُلب منك، زر عنوان التفويض الظاهر في المخرجات لتمكين Funnel لهذه العُقدة ضمن سياسة tailnet.
5. تحقق من التهيئة:
   tailscale serve status
   tailscale funnel status
   

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

​

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

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

​

الخيار C: نفق Cloudflare

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

​

كيف يعمل

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

​

الأهداف

• الرسائل المباشرة: users/<userId> أو users/<email> (تُقبل عناوين البريد الإلكتروني).
• مهمل: يُعامَل users/<email> كمعرّف مستخدم، وليس كقائمة سماح للبريد الإلكتروني.
• المساحات: spaces/<spaceId>.

​

أبرز نقاط التهيئة

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

• يمكن تمرير بيانات اعتماد حساب الخدمة أيضًا مضمنة باستخدام serviceAccount (سلسلة JSON).
• مسار الـ webhook الافتراضي هو /googlechat إذا لم يتم تعيين webhookPath.
• تتوفر التفاعلات عبر أداة reactions و channels action عند تمكين actions.reactions.
• يدعم typingIndicator كُلًا من none و message (الافتراضي) و reaction (يتطلب التفاعل OAuth للمستخدم).
• يتم تنزيل المرفقات عبر Chat API وتخزينها في خط أنابيب الوسائط (الحجم مُقيّد بواسطة mediaMaxMb).

​

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

​

405 Method Not Allowed

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

1. القناة غير مُهيّأة: قسم channels.googlechat مفقود من تهيئتك. تحقّق باستخدام:
   openclaw config get channels.googlechat
   
   إذا أعاد «Config path not found»، فأضِف التهيئة (انظر أبرز نقاط التهيئة).
2. الإضافة غير مُمكّنة: تحقّق من حالة الإضافة:
   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
• الأمان
• التفاعلات