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. یک Service Account بسازید:
   • روی Create Credentials > Service Account بزنید.
   • هر نامی که می‌خواهید برای آن بگذارید (مثلاً openclaw-chat).
   • مجوزها را خالی بگذارید (روی Continue بزنید).
   • بخش principals با دسترسی را خالی بگذارید (روی Done بزنید).
3. JSON Key را بسازید و دانلود کنید:
   • در فهرست حساب‌های سرویس، روی حسابی که همین حالا ساختید کلیک کنید.
   • به زبانه Keys بروید.
   • روی Add Key > Create new key کلیک کنید.
   • JSON را انتخاب کنید و روی Create بزنید.
4. فایل JSON دانلودشده را روی میزبان Gateway خود ذخیره کنید (مثلاً ~/.openclaw/googlechat-service-account.json).
5. در پیکربندی Chat در Google Cloud Console یک برنامه Google Chat بسازید:
   • 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 را انتخاب کنید و آن را روی URL عمومی Gateway خود به‌همراه /googlechat تنظیم کنید.
     • نکته: برای پیدا کردن URL عمومی Gateway خود، openclaw status را اجرا کنید.
   • زیر 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 پیکربندی کنید:
   • 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. روی نماد + (بعلاوه) کنار Direct Messages کلیک کنید.
3. در نوار جست‌وجو (جایی که معمولاً افراد را اضافه می‌کنید)، App nameای را که در Google Cloud Console پیکربندی کرده‌اید تایپ کنید.
   • توجه: ربات در فهرست مرور «Marketplace» ظاهر نخواهد شد، چون یک برنامه خصوصی است. باید آن را با نام جست‌وجو کنید.
4. ربات خود را از نتایج انتخاب کنید.
5. برای شروع یک گفت‌وگوی یک‌به‌یک روی Add یا Chat کلیک کنید.
6. برای فعال کردن دستیار، «Hello» بفرستید!

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

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

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

از Tailscale Serve برای داشبورد خصوصی و از Funnel برای مسیر عمومی Webhook استفاده کنید. این کار / را خصوصی نگه می‌دارد و فقط /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 status
   tailscale funnel status
   

URL عمومی Webhook شما این خواهد بود: https://<node-name>.<tailnet>.ts.net/googlechat

داشبورد خصوصی شما فقط در tailnet باقی می‌ماند: https://<node-name>.<tailnet>.ts.net:8443/

در پیکربندی برنامه Google Chat از URL عمومی (بدون :8443) استفاده کنید.

توجه: این پیکربندی پس از راه‌اندازی مجدد هم باقی می‌ماند. برای حذف آن در آینده، 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 Webhook 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 استفاده کنید.

# هدف‌ها

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

• پیام‌های مستقیم: users/<userId> (پیشنهادی).
• ایمیل خام [email protected] قابل تغییر است و فقط وقتی channels.googlechat.dangerouslyAllowNameMatching: true باشد برای تطبیق allowlist مستقیم استفاده می‌شود.
• منسوخ‌شده: 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
      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)، از جمله refهای هر حساب زیر channels.googlechat.accounts.<id>.serviceAccountRef.
• اگر webhookPath تنظیم نشده باشد، مسیر پیش‌فرض Webhook برابر /googlechat است.
• dangerouslyAllowNameMatching تطبیق principal ایمیل قابل تغییر را برای allowlistها دوباره فعال می‌کند (حالت سازگاری اضطراری).
• وقتی actions.reactions فعال باشد، واکنش‌ها از طریق ابزار reactions و channels action در دسترس هستند.
• کنش‌های پیام send را برای متن و upload-file را برای ارسال صریح پیوست ارائه می‌کنند. upload-file مقدارهای media / filePath / path را به‌همراه message، filename، و هدف‌گیری thread اختیاری می‌پذیرد.
• typingIndicator از none، message (پیش‌فرض)، و reaction پشتیبانی می‌کند (reaction به OAuth کاربر نیاز دارد).
• پیوست‌ها از طریق Chat API دانلود می‌شوند و در خط لوله رسانه ذخیره می‌شوند (اندازه با mediaMaxMb محدود می‌شود).

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

# عیب‌یابی

# 405 روش مجاز نیست

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

مستندات مرتبط:

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

# مرتبط

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