---
read_when:
    - کار روی ویژگی‌های کانال Google Chat
summary: وضعیت پشتیبانی، قابلیت‌ها و پیکربندی برنامه Google Chat
title: Google Chat
x-i18n:
    generated_at: "2026-06-27T17:10:15Z"
    model: gpt-5.5
    postprocess_version: locale-links-v1
    provider: openai
    source_hash: 3d506f6e92bfb73940254ca906c7581f24ac49d3f498fcae213eae71c4449442
    source_path: channels/googlechat.md
    workflow: 16
---

وضعیت: Plugin قابل دانلود برای پیام‌های مستقیم + فضاها از طریق Webhookهای Google Chat API (فقط HTTP).

## نصب

پیش از پیکربندی کانال، Google Chat را نصب کنید:

```bash
openclaw plugins install @openclaw/googlechat
```

چک‌اوت محلی (هنگام اجرا از یک مخزن git):

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

## راه‌اندازی سریع (مبتدی)

1. یک پروژه Google Cloud بسازید و **Google Chat API** را فعال کنید.
   - بروید به: [اعتبارنامه‌های Google Chat API](https://console.cloud.google.com/apis/api/chat.googleapis.com/credentials)
   - اگر API از قبل فعال نیست، آن را فعال کنید.
2. یک **حساب سرویس** بسازید:
   - **ایجاد اعتبارنامه‌ها** > **حساب سرویس** را فشار دهید.
   - هر نامی که می‌خواهید برای آن بگذارید (مثلاً `openclaw-chat`).
   - مجوزها را خالی بگذارید (**ادامه** را فشار دهید).
   - اصول دارای دسترسی را خالی بگذارید (**انجام شد** را فشار دهید).
3. **کلید JSON** را بسازید و دانلود کنید:
   - در فهرست حساب‌های سرویس، روی حسابی که تازه ساخته‌اید کلیک کنید.
   - به زبانه **کلیدها** بروید.
   - روی **افزودن کلید** > **ایجاد کلید جدید** کلیک کنید.
   - **JSON** را انتخاب کنید و **ایجاد** را فشار دهید.
4. فایل JSON دانلودشده را روی میزبان Gateway خود ذخیره کنید (مثلاً `~/.openclaw/googlechat-service-account.json`).
5. یک برنامه Google Chat در [پیکربندی Chat در Google Cloud Console](https://console.cloud.google.com/apis/api/chat.googleapis.com/hangouts-chat) بسازید:
   - **اطلاعات برنامه** را پر کنید:
     - **نام برنامه**: (مثلاً `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](https://chat.google.com/) بروید.
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 شده است:**

   ```bash
   ss -tlnp | grep 18789
   ```

   به نشانی IP توجه کنید (مثلاً `127.0.0.1`، `0.0.0.0`، یا IP مربوط به Tailscale شما مانند `100.x.x.x`).

2. **داشبورد را فقط برای tailnet در معرض دسترس قرار دهید (پورت 8443):**

   ```bash
   # 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 را عمومی در معرض دسترس قرار دهید:**

   ```bash
   # 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. **پیکربندی را تأیید کنید:**

   ```bash
   tailscale serve status
   tailscale 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 استفاده می‌کنید، فقط مسیر مشخص را پراکسی کنید:

```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>`.

## نکات برجسته پیکربندی

```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",
      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` را تنظیم کنید، پیام‌های پذیرفته‌شده نوشته‌شده توسط ربات از [محافظت حلقه ربات](/fa/channels/bot-loop-protection) مشترک استفاده می‌کنند. `channels.defaults.botLoopProtection` را پیکربندی کنید، سپس وقتی یک فضا به بودجه متفاوتی نیاز دارد، با `channels.googlechat.botLoopProtection` یا `channels.googlechat.groups.<space>.botLoopProtection` بازنویسی کنید.

جزئیات مرجع رازها: [مدیریت رازها](/fa/gateway/secrets).

## عیب‌یابی

### 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` در پیکربندی شما وجود ندارد. با این دستور بررسی کنید:

   ```bash
   openclaw config get channels.googlechat
   ```

   اگر "Config path not found" برگرداند، پیکربندی را اضافه کنید (به [نکات برجسته پیکربندی](#config-highlights) مراجعه کنید).

2. **Plugin فعال نشده است**: وضعیت Plugin را بررسی کنید:

   ```bash
   openclaw plugins list | grep googlechat
   ```

   اگر "disabled" نشان می‌دهد، `plugins.entries.googlechat.enabled: true` را به پیکربندی خود اضافه کنید.

3. **Gateway راه‌اندازی مجدد نشده است**: پس از افزودن پیکربندی، Gateway را راه‌اندازی مجدد کنید:

   ```bash
   openclaw gateway restart
   ```

تأیید کنید کانال در حال اجرا است:

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

### مشکلات دیگر

- برای خطاهای احراز هویت یا پیکربندی مخاطب ناقص، `openclaw channels status --probe` را بررسی کنید.
- اگر هیچ پیامی نمی‌رسد، URL وب‌هوک برنامه Chat + اشتراک‌های رویداد را تأیید کنید.
- اگر دروازه mention پاسخ‌ها را مسدود می‌کند، `botUser` را روی نام منبع کاربری برنامه تنظیم کنید و `requireMention` را تأیید کنید.
- هنگام ارسال یک پیام آزمایشی، برای اینکه ببینید درخواست‌ها به Gateway می‌رسند یا نه، از `openclaw logs --follow` استفاده کنید.

اسناد مرتبط:

- [پیکربندی Gateway](/fa/gateway/configuration)
- [امنیت](/fa/gateway/security)
- [واکنش‌ها](/fa/tools/reactions)

## مرتبط

- [نمای کلی کانال‌ها](/fa/channels) — همه کانال‌های پشتیبانی‌شده
- [جفت‌سازی](/fa/channels/pairing) — جریان احراز هویت پیام مستقیم و جفت‌سازی
- [گروه‌ها](/fa/channels/groups) — رفتار گفت‌وگوی گروهی و محدودسازی بر اساس منشن
- [مسیریابی کانال](/fa/channels/channel-routing) — مسیریابی نشست برای پیام‌ها
- [امنیت](/fa/gateway/security) — مدل دسترسی و مقاوم‌سازی