OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

Mainstream messaging

Google Chat

يعمل Google Chat بوصفه Plugin الرسمي @openclaw/googlechat: الرسائل المباشرة والمساحات عبر Webhook ‏Google Chat API (نقطة نهاية HTTP فقط، دون Pub/Sub).

التثبيت

bash
openclaw plugins install @openclaw/googlechat

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

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

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

  1. أنشئ مشروع Google Cloud وفعّل Google Chat API.
  2. أنشئ Service Account:
    • اضغط 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 في إعدادات Chat ضمن Google Cloud Console:
    • املأ Application info (اسم التطبيق، وعنوان URL للصورة الرمزية، والوصف).
    • فعّل Interactive features.
    • ضمن Functionality، حدّد Join spaces and group conversations.
    • ضمن Connection settings، اختر HTTP endpoint URL.
    • ضمن Triggers، اختر Use a common HTTP endpoint URL for all triggers واضبطه على عنوان URL العام لـ Gateway متبوعًا بـ /googlechat (راجع عنوان URL العام).
    • ضمن Visibility، حدّد Make this Chat app available to specific people and groups in <Your Domain> وأدخل عنوان بريدك الإلكتروني.
    • انقر على Save.
  6. فعّل حالة التطبيق: حدّث الصفحة، وابحث عن App status، واضبطها على Live - available to users، ثم انقر على Save مجددًا.
  7. اضبط OpenClaw باستخدام حساب الخدمة وجمهور Webhook (يجب أن يتطابق مع إعداد تطبيق Chat):
    • متغير البيئة: GOOGLE_CHAT_SERVICE_ACCOUNT_FILE=/path/to/service-account.json (للحساب الافتراضي فقط)، أو
    • الإعداد: راجع أبرز الإعدادات. يقبل openclaw channels add --channel googlechat أيضًا الخيارات --audience-type و--audience و--webhook-path و--webhook-url.
  8. شغّل Gateway. سيرسل Google Chat طلبات POST إلى مسار Webhook لديك (الافتراضي /googlechat).

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

بمجرد تشغيل Gateway وإدراج بريدك الإلكتروني في قائمة الظهور:

  1. انتقل إلى Google Chat.
  2. انقر على أيقونة + (علامة الجمع) بجوار Direct Messages.
  3. ابحث عن App name الذي ضبطته في Google Cloud Console.
    • لا يظهر البوت في قائمة تصفح Marketplace لأنه تطبيق خاص؛ ابحث عنه بالاسم.
  4. اختر البوت، وانقر على Add أو Chat، ثم أرسل رسالة.

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

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

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

استخدم Tailscale Serve للوحة المعلومات الخاصة وFunnel لمسار Webhook العام.

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

    bash
    ss -tlnp | grep 18789

    دوّن عنوان IP (مثلًا، 127.0.0.1 أو 0.0.0.0 أو عنوان Tailscale بصيغة 100.x.x.x).

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

    bash
    # إذا كان مرتبطًا بالمضيف المحلي (127.0.0.1 أو 0.0.0.0):tailscale serve --bg --https 8443 http://127.0.0.1:18789 # إذا كان مرتبطًا بعنوان IP لـ Tailscale فقط:tailscale serve --bg --https 8443 http://100.x.x.x:18789

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

    bash
    # إذا كان مرتبطًا بالمضيف المحلي (127.0.0.1 أو 0.0.0.0):tailscale funnel --bg --set-path /googlechat http://127.0.0.1:18789/googlechat # إذا كان مرتبطًا بعنوان IP لـ Tailscale فقط:tailscale funnel --bg --set-path /googlechat http://100.x.x.x:18789/googlechat

  4. إذا طُلب منك ذلك، فانتقل إلى عنوان URL الخاص بالتخويل الظاهر في المخرجات لتمكين Funnel لهذه العقدة.

  5. تحقّق:

    bash
    tailscale serve statustailscale funnel status

عنوان Webhook العام لديك هو https://<node-name>.<tailnet>.ts.net/googlechat؛ وتظل لوحة المعلومات مقتصرة على tailnet على العنوان https://<node-name>.<tailnet>.ts.net:8443/. استخدم عنوان URL العام (من دون :8443) في إعداد تطبيق Google Chat.

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

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

مرّر مسار Webhook فقط عبر الوكيل:

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 بيانات JSON عبر POST إلى مسار Webhook الخاص بـ Gateway (طلبات POST فقط، ونوع محتوى JSON مطلوب، مع تقييد المعدل لكل عنوان IP).
  2. يصادق OpenClaw على كل طلب قبل تمريره:
    • تحمل أحداث تطبيق Chat الترويسة Authorization: Bearer <token>؛ ويجري التحقق من الرمز المميز قبل تحليل النص الكامل للطلب.
    • تحمل أحداث إضافات Google Workspace الرمز المميز داخل النص (authorizationEventObject.systemIdToken) وتُقرأ ضمن ميزانية أشد صرامة قبل المصادقة (16 كيلوبايت، و3 ثوانٍ) قبل التحقق.
  3. يُفحص الرمز المميز مقابل audienceType + audience:
    • audienceType: "app-url" ← الجمهور هو عنوان HTTPS الخاص بـ Webhook.
    • audienceType: "project-number" ← الجمهور هو رقم مشروع Cloud.
    • تتطلب رموز الإضافات ضمن app-url أيضًا ضبط appPrincipal على معرّف عميل OAuth 2.0 الرقمي للتطبيق (21 رقمًا، وليس عنوان بريد إلكتروني)؛ وإلا يفشل التحقق مع تسجيل تحذير.
  4. تُوجّه الرسائل حسب المساحة:
    • تحصل المساحات على جلسات مستقلة لكل مساحة agent:<agentId>:googlechat:group:<spaceId>؛ وتُرسل الردود إلى سلسلة الرسالة.
    • تُدمج الرسائل المباشرة افتراضيًا في الجلسة الرئيسية للوكيل؛ اضبط session.dmScope للحصول على جلسات رسائل مباشرة مستقلة لكل نظير (راجع الجلسة).
  5. يعتمد الوصول عبر الرسائل المباشرة على الاقتران افتراضيًا. يتلقى المرسلون غير المعروفين رمز اقتران؛ وافق عليه باستخدام:
    • openclaw pairing approve googlechat <code>
  6. تتطلب المساحات الجماعية إشارة @ افتراضيًا. تُكتشف الإشارات من تعليقات Chat التوضيحية من نوع USER_MENTION التي تستهدف التطبيق؛ اضبط botUser (مثلًا، users/1234567890) إذا احتاج الاكتشاف إلى اسم مورد المستخدم الخاص بالتطبيق.
  7. عند بدء موافقة على تنفيذ أمر أو Plugin من Google Chat مع ضبط مُعتمِد ثابت بصيغة users/<id>، ينشر OpenClaw بطاقة موافقة أصلية (cardsV2) في المساحة أو السلسلة الأصلية. تحمل أزرار البطاقة رموز استدعاء مبهمة؛ ولا تظهر مطالبة /approve <id> <decision> اليدوية إلا عندما يتعذر التسليم الأصلي.

الوجهات

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

  • الرسائل المباشرة: users/<userId> (موصى به).
  • المساحات: spaces/<spaceId>.
  • عنوان البريد الإلكتروني الخام name@example.com قابل للتغيير، ولا يُستخدم لمطابقة قائمة السماح إلا عندما تكون channels.googlechat.dangerouslyAllowNameMatching: true.
  • مهمل: تُعامل users/<email> بوصفها معرّف مستخدم، لا إدخال بريد إلكتروني في قائمة السماح.
  • تُقبل البادئات googlechat: وgoogle-chat: وgchat: وتُزال.

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

json5
{  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",      appPrincipal: "123456789012345678901", // add-on verification only; numeric OAuth client ID      webhookPath: "/googlechat",      botUser: "users/1234567890", // optional; helps mention detection      allowBots: false,      dm: {        policy: "pairing",        allowFrom: ["users/1234567890"],      },      groupPolicy: "allowlist",      groups: {        "spaces/AAAA": {          enabled: true,          requireMention: true,          users: ["users/1234567890"],          systemPrompt: "Short answers only.",        },      },      typingIndicator: "message",      mediaMaxMb: 20,    },  },}

ملاحظات:

  • بيانات اعتماد حساب الخدمة: serviceAccountFile (مسار)، أو serviceAccount (سلسلة JSON مضمنة أو كائن)، أو serviceAccountRef ‏(SecretRef لمتغير بيئة/ملف). ينطبق متغيرا البيئة GOOGLE_CHAT_SERVICE_ACCOUNT ‏(JSON مضمن) وGOOGLE_CHAT_SERVICE_ACCOUNT_FILE (مسار) على الحساب الافتراضي فقط. تستخدم إعدادات الحسابات المتعددة channels.googlechat.accounts.<id> مع المفاتيح نفسها، بما فيها serviceAccountRef لكل حساب.
  • مسار Webhook الافتراضي هو /googlechat عند عدم ضبط webhookPath؛ ويمكن لـwebhookUrl توفير المسار بدلًا منه.
  • يجب أن تكون مفاتيح المجموعات معرّفات مساحات ثابتة (spaces/<spaceId>). مفاتيح أسماء العرض مهملة ويجري تسجيلها على هذا الأساس.
  • يعيد dangerouslyAllowNameMatching تمكين مطابقة كيان البريد الإلكتروني القابل للتغيير لقوائم السماح (وضع توافق للطوارئ)؛ ويحذّر الطبيب من إدخالات البريد الإلكتروني.
  • إجراءات تفاعلات Google Chat غير مكشوفة. يستخدم Plugin مصادقة حساب الخدمة، بينما تتطلب نقاط نهاية تفاعلات Google Chat مصادقة المستخدم. يُقبل إعداد actions.reactions الحالي للتوافق، لكنه بلا تأثير.
  • تستخدم بطاقات الموافقة الأصلية نقرات أزرار Google Chat ‏cardsV2، لا أحداث التفاعل. يأتي المعتمدون من dm.allowFrom أو defaultTo، ويجب أن تكون قيمهم رقمية ثابتة بصيغة users/<id>.
  • لا تكشف إجراءات الرسائل سوى الإجراء النصي send. يتطلب رفع مرفقات Google Chat مصادقة المستخدم، بينما يستخدم هذا Plugin مصادقة حساب الخدمة، لذلك لا يُكشف رفع الملفات الصادرة.
  • typingIndicator: تنشر القيمة message (الافتراضية) عنصرًا نائبًا _&lt;Bot&gt; is typing..._ وتعدّله ليصبح الرد الأول؛ وتعطّله القيمة none؛ أما reaction فتتطلب OAuth للمستخدم وترجع حاليًا إلى message مع تسجيل خطأ عند استخدام مصادقة حساب الخدمة.
  • تُنزّل المرفقات الواردة (أول مرفق في كل رسالة) عبر Chat API إلى مسار معالجة الوسائط، مع حد أقصى تحدده mediaMaxMb (الافتراضي 20).
  • تُتجاهل الرسائل التي ينشئها البوت افتراضيًا. مع allowBots: true، تستخدم رسائل البوت المقبولة الحماية المشتركة من حلقات البوت: اضبط channels.defaults.botLoopProtection، ثم تجاوزها باستخدام channels.googlechat.botLoopProtection أو channels.googlechat.groups.<space>.botLoopProtection.

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

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

405 الطريقة غير مسموح بها

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

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

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

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

    bash
    openclaw config get channels.googlechat

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

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

    bash
    openclaw plugins list | grep googlechat

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

  3. لم يُعَد تشغيل Gateway بعد تغييرات الإعداد:

    bash
    openclaw gateway restart

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

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

مشكلات أخرى

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

ذو صلة

Was this useful?
On this page

On this page