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)
     • URL آواتار: (مثلاً https://openclaw.ai/logo.png)
     • توضیحات: (مثلاً Personal AI Assistant)
   • قابلیت‌های تعاملی را فعال کنید.
   • زیر عملکرد، پیوستن به فضاها و گفت‌وگوهای گروهی را تیک بزنید.
   • زیر تنظیمات اتصال، URL نقطه پایانی HTTP را انتخاب کنید.
   • زیر محرک‌ها، استفاده از یک URL نقطه پایانی HTTP مشترک برای همه محرک‌ها را انتخاب کنید و آن را روی URL عمومی Gateway خود به‌همراه /googlechat تنظیم کنید.
     • نکته: برای پیدا کردن URL عمومی Gateway خود، openclaw status را اجرا کنید.
   • زیر دیدپذیری، در دسترس قرار دادن این برنامه Chat برای افراد و گروه‌های مشخص در <Your Domain> را تیک بزنید.
   • نشانی ایمیل خود را (مثلاً user@example.com) در کادر متن وارد کنید.
   • در پایین روی ذخیره کلیک کنید.
6. وضعیت برنامه را فعال کنید:
   • پس از ذخیره، صفحه را بازآوری کنید.
   • بخش وضعیت برنامه را پیدا کنید (معمولاً پس از ذخیره نزدیک بالا یا پایین صفحه است).
   • وضعیت را به زنده - در دسترس کاربران تغییر دهید.
   • دوباره روی ذخیره کلیک کنید.
7. OpenClaw را با مسیر حساب سرویس + مخاطب Webhook پیکربندی کنید:
   • Env: 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 به مسیر Webhook شما POST می‌کند.

افزودن به Google Chat

پس از اینکه Gateway در حال اجرا بود و ایمیل شما به فهرست دیدپذیری اضافه شد:

1. به Google Chat بروید.
2. روی نماد + (بعلاوه) کنار پیام‌های مستقیم کلیک کنید.
3. در نوار جست‌وجو (جایی که معمولاً افراد را اضافه می‌کنید)، نام برنامه‌ای را که در Google Cloud Console پیکربندی کرده‌اید تایپ کنید.
   • نکته: ربات در فهرست مرور «Marketplace» ظاهر نمی‌شود چون یک برنامه خصوصی است. باید آن را با نام جست‌وجو کنید.
4. ربات خود را از نتایج انتخاب کنید.
5. برای شروع گفت‌وگوی ۱:۱ روی افزودن یا گپ کلیک کنید.
6. برای فعال کردن دستیار، "Hello" بفرستید!

URL عمومی (فقط Webhook)

Webhookهای Google Chat به یک نقطه پایانی HTTPS عمومی نیاز دارند. برای امنیت، فقط مسیر /googlechat را در اینترنت در معرض دسترس قرار دهید. داشبورد OpenClaw و سایر نقاط پایانی حساس را روی شبکه خصوصی خود نگه دارید.

گزینه A: Tailscale Funnel (پیشنهادی)

برای داشبورد خصوصی از Tailscale Serve و برای مسیر Webhook عمومی از Funnel استفاده کنید. این کار / را خصوصی نگه می‌دارد و فقط /googlechat را در معرض دسترس قرار می‌دهد.

1. بررسی کنید Gateway شما به چه نشانی‌ای bind شده است:

   ss -tlnp | grep 18789

   به نشانی IP توجه کنید (مثلاً 127.0.0.1، 0.0.0.0، یا IP مربوط به 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. Node را برای دسترسی Funnel مجاز کنید: اگر درخواست شد، برای فعال کردن Funnel برای این Node در سیاست tailnet خود، از URL مجوزدهی نشان‌داده‌شده در خروجی بازدید کنید.

5. پیکربندی را تأیید کنید:

   tailscale serve statustailscale funnel status

URL عمومی 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 را اجرا کنید.

گزینه B: پراکسی معکوس (Caddy)

اگر از پراکسی معکوس مانند Caddy استفاده می‌کنید، فقط مسیر مشخص را پراکسی کنید:

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

با این پیکربندی، هر درخواست به your-domain.com/ نادیده گرفته می‌شود یا به‌صورت 404 برگردانده می‌شود، در حالی که your-domain.com/googlechat به‌صورت ایمن به OpenClaw هدایت می‌شود.

گزینه C: Cloudflare Tunnel

قواعد ingress تونل خود را طوری پیکربندی کنید که فقط مسیر Webhook را مسیریابی کند:

• مسیر: /googlechat -> http://localhost:18789/googlechat
• قاعده پیش‌فرض: HTTP 404 (یافت نشد)

نحوه کار

1. Google Chat درخواست‌های POST مربوط به Webhook را به Gateway می‌فرستد. هر درخواست شامل سرآیند Authorization: Bearer <token> است.
   • OpenClaw قبل از خواندن/تجزیه کامل بدنه‌های Webhook، در صورت وجود سرآیند، احراز هویت bearer را تأیید می‌کند.
   • درخواست‌های Google Workspace Add-on که authorizationEventObject.systemIdToken را در بدنه حمل می‌کنند، از طریق بودجه بدنه پیش‌احراز سخت‌گیرانه‌تر پشتیبانی می‌شوند.
2. OpenClaw توکن را در برابر audienceType + audience پیکربندی‌شده تأیید می‌کند:
   • audienceType: "app-url" → مخاطب، URL وب‌هوک HTTPS شما است.
   • audienceType: "project-number" → مخاطب، شماره پروژه Cloud است.
3. پیام‌ها بر اساس فضا مسیریابی می‌شوند:
   • پیام‌های مستقیم از کلید نشست agent:<agentId>:googlechat:direct:<spaceId> استفاده می‌کنند.
   • فضاها از کلید نشست agent:<agentId>:googlechat:group:<spaceId> استفاده می‌کنند.
4. دسترسی پیام مستقیم به‌صورت پیش‌فرض با جفت‌سازی است. فرستندگان ناشناس یک کد جفت‌سازی دریافت می‌کنند؛ با این دستور تأیید کنید:
   • openclaw pairing approve googlechat <code>
5. فضاهای گروهی به‌صورت پیش‌فرض به @-mention نیاز دارند. اگر تشخیص mention به نام کاربری برنامه نیاز دارد، از botUser استفاده کنید.
6. وقتی یک درخواست تأیید exec یا Plugin از Google Chat آغاز می‌شود و یک تأییدکننده پایدار users/<id> پیکربندی شده است، OpenClaw یک کارت تأیید بومی Google Chat را در فضای یا thread مبدأ ارسال می‌کند. دکمه‌های کارت از توکن‌های callback مبهم استفاده می‌کنند، و درخواست دستی /approve <id> <decision> فقط وقتی نمایش داده می‌شود که تحویل تأیید بومی در دسترس نباشد.

هدف‌ها

از این شناسه‌ها برای تحویل و allowlistها استفاده کنید:

• پیام‌های مستقیم: users/<userId> (پیشنهادی).
• ایمیل خام name@example.com قابل تغییر است و فقط زمانی برای تطبیق allowlist مستقیم استفاده می‌شود که channels.googlechat.dangerouslyAllowNameMatching: true.
• منسوخ‌شده: users/<email> به‌عنوان شناسه کاربر تلقی می‌شود، نه allowlist ایمیل.
• فضاها: 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      allowBots: false,      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 نیز پشتیبانی می‌شود (SecretRef env/file)، شامل refs هر حساب زیر channels.googlechat.accounts.<id>.serviceAccountRef.
• اگر webhookPath تنظیم نشده باشد، مسیر پیش‌فرض Webhook برابر /googlechat است.
• dangerouslyAllowNameMatching تطبیق principal ایمیل قابل تغییر را برای allowlistها دوباره فعال می‌کند (حالت سازگاری اضطراری).
• واکنش‌ها از طریق ابزار reactions و channels action در دسترس هستند، وقتی actions.reactions فعال باشد.
• کارت‌های تأیید بومی از کلیک‌های دکمه Google Chat cardsV2 استفاده می‌کنند، نه رویدادهای واکنش. تأییدکنندگان از dm.allowFrom یا defaultTo می‌آیند و باید مقادیر پایدار عددی users/<id> باشند.
• کنش‌های پیام، send را برای متن و upload-file را برای ارسال‌های صریح پیوست در معرض دسترس قرار می‌دهند. upload-file، media / filePath / path را به‌همراه message، filename، و هدف‌گیری thread اختیاری می‌پذیرد.
• typingIndicator از message (پیش‌فرض)، none، و reaction پشتیبانی می‌کند (reaction به OAuth کاربر نیاز دارد).
• پیوست‌ها از طریق Chat API دانلود می‌شوند و در pipeline رسانه ذخیره می‌شوند (اندازه با mediaMaxMb محدود می‌شود).
• پیام‌های Google Chat نوشته‌شده توسط ربات به‌صورت پیش‌فرض نادیده گرفته می‌شوند. اگر عمداً allowBots: true را تنظیم کنید، پیام‌های پذیرفته‌شده نوشته‌شده توسط ربات از محافظت حلقه ربات مشترک استفاده می‌کنند. channels.defaults.botLoopProtection را پیکربندی کنید، سپس وقتی یک فضا به بودجه متفاوتی نیاز دارد، با channels.googlechat.botLoopProtection یا channels.googlechat.groups.<space>.botLoopProtection بازنویسی کنید.

جزئیات مرجع رازها: مدیریت رازها.

عیب‌یابی

405 Method Not Allowed

اگر Google Cloud Logs Explorer خطاهایی مانند این نشان می‌دهد:

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

یعنی handler مربوط به 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 را بررسی کنید.
• اگر هیچ پیامی نمی‌رسد، URL وب‌هوک برنامه Chat + اشتراک‌های رویداد را تأیید کنید.
• اگر دروازه mention پاسخ‌ها را مسدود می‌کند، botUser را روی نام منبع کاربری برنامه تنظیم کنید و requireMention را تأیید کنید.
• هنگام ارسال یک پیام آزمایشی، برای اینکه ببینید درخواست‌ها به Gateway می‌رسند یا نه، از openclaw logs --follow استفاده کنید.

اسناد مرتبط:

• پیکربندی Gateway
• امنیت
• واکنش‌ها

مرتبط

• نمای کلی کانال‌ها — همه کانال‌های پشتیبانی‌شده
• جفت‌سازی — جریان احراز هویت پیام مستقیم و جفت‌سازی
• گروه‌ها — رفتار گفت‌وگوی گروهی و محدودسازی بر اساس منشن
• مسیریابی کانال — مسیریابی نشست برای پیام‌ها
• امنیت — مدل دسترسی و مقاوم‌سازی