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 berjalan sebagai plugin resmi @openclaw/googlechat: pesan langsung dan ruang melalui Webhook Google Chat API (hanya titik akhir HTTP, tanpa Pub/Sub).

Instalasi

bash
openclaw plugins install @openclaw/googlechat

Checkout lokal (saat dijalankan dari repositori git):

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

Penyiapan cepat (pemula)

  1. Buat proyek Google Cloud dan aktifkan Google Chat API.
  2. Buat Service Account:
    • Tekan Create Credentials > Service Account.
    • Beri nama sesuai keinginan (misalnya, openclaw-chat).
    • Biarkan izin dan prinsipal kosong (Continue, lalu Done).
  3. Buat dan unduh kunci JSON:
    • Klik akun layanan baru > tab Keys > Add Key > Create new key > JSON > Create.
  4. Simpan berkas JSON yang diunduh pada hos Gateway Anda (misalnya, ~/.openclaw/googlechat-service-account.json).
  5. Buat aplikasi Google Chat di Konfigurasi Chat Google Cloud Console:
    • Isi Application info (nama aplikasi, URL avatar, deskripsi).
    • Aktifkan Interactive features.
    • Di bagian Functionality, centang Join spaces and group conversations.
    • Di bagian Connection settings, pilih HTTP endpoint URL.
    • Di bagian Triggers, pilih Use a common HTTP endpoint URL for all triggers dan tetapkan ke URL Gateway publik Anda yang diikuti /googlechat (lihat URL publik).
    • Di bagian Visibility, centang Make this Chat app available to specific people and groups in <Your Domain> dan masukkan alamat email Anda.
    • Klik Save.
  6. Aktifkan status aplikasi: muat ulang halaman, temukan App status, tetapkan ke Live - available to users, lalu klik Save lagi.
  7. Konfigurasikan OpenClaw dengan akun layanan dan audiens Webhook (harus cocok dengan konfigurasi aplikasi Chat):
    • Variabel lingkungan: GOOGLE_CHAT_SERVICE_ACCOUNT_FILE=/path/to/service-account.json (hanya akun default), atau
    • Konfigurasi: lihat Sorotan konfigurasi. openclaw channels add --channel googlechat juga menerima --audience-type, --audience, --webhook-path, dan --webhook-url.
  8. Mulai Gateway. Google Chat akan mengirim POST ke jalur Webhook Anda (default /googlechat).

Tambahkan ke Google Chat

Setelah Gateway berjalan dan email Anda ada dalam daftar visibilitas:

  1. Buka Google Chat.
  2. Klik ikon + (tambah) di samping Direct Messages.
  3. Cari App name yang Anda konfigurasikan di Google Cloud Console.
    • Bot tidak muncul dalam daftar penelusuran Marketplace karena merupakan aplikasi privat; cari berdasarkan namanya.
  4. Pilih bot, klik Add atau Chat, lalu kirim pesan.

URL publik (khusus Webhook)

Webhook Google Chat memerlukan titik akhir HTTPS publik. Demi keamanan, paparkan hanya jalur /googlechat ke internet dan pertahankan dasbor OpenClaw serta titik akhir lainnya tetap privat.

Opsi A: Tailscale Funnel (Disarankan)

Gunakan Tailscale Serve untuk dasbor privat dan Funnel untuk jalur Webhook publik.

  1. Periksa alamat yang digunakan Gateway untuk mendengarkan:

    bash
    ss -tlnp | grep 18789

    Catat IP-nya (misalnya, 127.0.0.1, 0.0.0.0, atau alamat Tailscale 100.x.x.x).

  2. Paparkan dasbor hanya ke tailnet (port 8443):

    bash
    # Jika terikat ke localhost (127.0.0.1 atau 0.0.0.0):tailscale serve --bg --https 8443 http://127.0.0.1:18789 # Jika hanya terikat ke IP Tailscale:tailscale serve --bg --https 8443 http://100.x.x.x:18789

  3. Paparkan hanya jalur Webhook secara publik:

    bash
    # Jika terikat ke localhost (127.0.0.1 atau 0.0.0.0):tailscale funnel --bg --set-path /googlechat http://127.0.0.1:18789/googlechat # Jika hanya terikat ke IP Tailscale:tailscale funnel --bg --set-path /googlechat http://100.x.x.x:18789/googlechat

  4. Jika diminta, kunjungi URL otorisasi yang ditampilkan dalam keluaran untuk mengaktifkan Funnel bagi Node ini.

  5. Verifikasi:

    bash
    tailscale serve statustailscale funnel status

URL Webhook publik Anda adalah https://<node-name>.<tailnet>.ts.net/googlechat; dasbor tetap hanya dapat diakses melalui tailnet di https://<node-name>.<tailnet>.ts.net:8443/. Gunakan URL publik (tanpa :8443) dalam konfigurasi aplikasi Google Chat.

Catatan: Konfigurasi ini tetap tersimpan setelah dimulai ulang. Hapus nanti dengan tailscale funnel reset dan tailscale serve reset.

Opsi B: Proksi Terbalik (Caddy)

Proksikan hanya jalur Webhook:

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

Permintaan ke your-domain.com/ diabaikan atau menghasilkan 404, sedangkan your-domain.com/googlechat dirutekan ke OpenClaw.

Opsi C: Cloudflare Tunnel

Konfigurasikan aturan masuk tunnel agar hanya merutekan jalur Webhook:

  • Path: /googlechat -> http://localhost:18789/googlechat
  • Default rule: HTTP 404 (Not Found)

Cara kerjanya

  1. Google Chat mengirim JSON melalui POST ke jalur Webhook Gateway (hanya POST, jenis konten JSON wajib, dibatasi lajunya per IP).
  2. OpenClaw mengautentikasi setiap permintaan sebelum meneruskannya:
    • Peristiwa aplikasi Chat membawa Authorization: Bearer <token>; token diverifikasi sebelum seluruh isi permintaan diurai.
    • Peristiwa Add-on Google Workspace membawa token dalam isi permintaan (authorizationEventObject.systemIdToken) dan dibaca dengan batas praautentikasi yang lebih ketat (16 KB, 3 detik) sebelum verifikasi.
  3. Token diperiksa terhadap audienceType + audience:
    • audienceType: "app-url" → audiens adalah URL Webhook HTTPS Anda.
    • audienceType: "project-number" → audiens adalah nomor proyek Cloud.
    • Token Add-on dengan app-url juga mengharuskan appPrincipal ditetapkan ke ID klien OAuth 2.0 numerik aplikasi (21 digit, bukan email); jika tidak, verifikasi gagal dan peringatan dicatat.
  4. Pesan dirutekan berdasarkan ruang:
    • Ruang mendapatkan sesi per ruang agent:<agentId>:googlechat:group:<spaceId>; balasan dikirim ke utas pesan.
    • Pesan langsung secara default digabungkan ke sesi utama agen; tetapkan session.dmScope untuk sesi pesan langsung per rekan (lihat Sesi).
  5. Akses pesan langsung menggunakan pemasangan secara default. Pengirim yang tidak dikenal menerima kode pemasangan; setujui dengan:
    • openclaw pairing approve googlechat <code>
  6. Ruang grup secara default memerlukan penyebutan @. Penyebutan dideteksi dari anotasi USER_MENTION Chat yang ditujukan ke aplikasi; tetapkan botUser (misalnya, users/1234567890) jika pendeteksian memerlukan nama sumber daya pengguna aplikasi.
  7. Saat persetujuan eksekusi atau Plugin dimulai dari Google Chat dan pemberi persetujuan users/<id> yang stabil dikonfigurasikan, OpenClaw memposting kartu persetujuan native (cardsV2) di ruang atau utas asal. Tombol kartu membawa token panggilan balik buram; perintah manual /approve <id> <decision> hanya muncul saat pengiriman native tidak tersedia.

Tujuan

Gunakan pengenal berikut untuk pengiriman dan daftar yang diizinkan:

  • Pesan langsung: users/<userId> (disarankan).
  • Ruang: spaces/<spaceId>.
  • Email mentah name@example.com dapat berubah dan hanya digunakan untuk pencocokan daftar yang diizinkan saat channels.googlechat.dangerouslyAllowNameMatching: true.
  • Tidak digunakan lagi: users/<email> diperlakukan sebagai ID pengguna, bukan entri email dalam daftar yang diizinkan.
  • Awalan googlechat:, google-chat:, dan gchat: diterima dan dihapus.

Sorotan konfigurasi

json5
{  channels: {    googlechat: {      enabled: true,      serviceAccountFile: "/path/to/service-account.json",      // atau serviceAccountRef: { source: "file", provider: "filemain", id: "/channels/googlechat/serviceAccount" }      audienceType: "app-url",      audience: "https://gateway.example.com/googlechat",      appPrincipal: "123456789012345678901", // hanya verifikasi add-on; ID klien OAuth numerik      webhookPath: "/googlechat",      botUser: "users/1234567890", // opsional; membantu pendeteksian penyebutan      allowBots: false,      dm: {        policy: "pairing",        allowFrom: ["users/1234567890"],      },      groupPolicy: "allowlist",      groups: {        "spaces/AAAA": {          enabled: true,          requireMention: true,          users: ["users/1234567890"],          systemPrompt: "Hanya jawaban singkat.",        },      },      typingIndicator: "message",      mediaMaxMb: 20,    },  },}

Catatan:

  • Kredensial akun layanan: serviceAccountFile (jalur), serviceAccount (string atau objek JSON sebaris), atau serviceAccountRef (SecretRef variabel lingkungan/berkas). Variabel lingkungan GOOGLE_CHAT_SERVICE_ACCOUNT (JSON sebaris) dan GOOGLE_CHAT_SERVICE_ACCOUNT_FILE (jalur) hanya berlaku untuk akun default. Penyiapan multiakun menggunakan channels.googlechat.accounts.<id> dengan kunci yang sama, termasuk serviceAccountRef per akun.
  • Jalur Webhook default adalah /googlechat saat webhookPath tidak ditetapkan; webhookUrl dapat menyediakan jalur sebagai gantinya.
  • Kunci grup harus berupa ID ruang yang stabil (spaces/<spaceId>). Kunci nama tampilan tidak digunakan lagi dan dicatat sebagai demikian.
  • dangerouslyAllowNameMatching mengaktifkan kembali pencocokan prinsipal email yang dapat berubah untuk daftar yang diizinkan (mode kompatibilitas darurat); doctor memperingatkan tentang entri email.
  • Tindakan reaksi Google Chat tidak diekspos. Plugin menggunakan autentikasi akun layanan, sedangkan titik akhir reaksi Google Chat memerlukan autentikasi pengguna. Konfigurasi actions.reactions yang ada diterima untuk kompatibilitas, tetapi tidak berpengaruh.
  • Kartu persetujuan native menggunakan klik tombol cardsV2 Google Chat, bukan peristiwa reaksi. Pemberi persetujuan berasal dari dm.allowFrom atau defaultTo dan harus berupa nilai numerik users/<id> yang stabil.
  • Tindakan pesan hanya mengekspos send teks. Pengunggahan lampiran Google Chat memerlukan autentikasi pengguna, sedangkan Plugin ini menggunakan autentikasi akun layanan, sehingga pengunggahan berkas keluar tidak diekspos.
  • typingIndicator: message (default) memposting placeholder _&lt;Bot&gt; sedang mengetik..._ dan mengubahnya menjadi balasan pertama; none menonaktifkannya; reaction memerlukan OAuth pengguna dan saat ini kembali ke message dengan kesalahan yang dicatat ketika menggunakan autentikasi akun layanan.
  • Lampiran masuk (lampiran pertama per pesan) diunduh melalui Chat API ke alur media, dengan batas mediaMaxMb (default 20).
  • Pesan yang dibuat bot diabaikan secara default. Dengan allowBots: true, pesan bot yang diterima menggunakan perlindungan perulangan bot bersama: konfigurasikan channels.defaults.botLoopProtection, lalu timpa dengan channels.googlechat.botLoopProtection atau channels.googlechat.groups.<space>.botLoopProtection.

Detail referensi rahasia: Pengelolaan Rahasia.

Pemecahan masalah

405 Metode Tidak Diizinkan

Jika Google Cloud Logs Explorer menampilkan kesalahan seperti:

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

Penangan Webhook tidak terdaftar. Penyebab umum:

  1. Saluran belum dikonfigurasikan: bagian channels.googlechat tidak ada. Verifikasi dengan:

    bash
    openclaw config get channels.googlechat

    Jika mengembalikan "Config path not found", tambahkan konfigurasi (lihat Sorotan konfigurasi).

  2. Plugin tidak diaktifkan: periksa status Plugin:

    bash
    openclaw plugins list | grep googlechat

    Jika menampilkan "disabled", tambahkan plugins.entries.googlechat.enabled: true ke konfigurasi Anda.

  3. Gateway belum dimulai ulang setelah perubahan konfigurasi:

    bash
    openclaw gateway restart

Verifikasi bahwa saluran sedang berjalan:

bash
openclaw channels status# Seharusnya menampilkan: Google Chat default: enabled, configured, ...

Masalah lainnya

  • openclaw channels status --probe menampilkan kesalahan autentikasi dan konfigurasi audiens yang tidak ada (audience dan audienceType keduanya wajib).
  • Jika tidak ada pesan yang masuk, konfirmasikan URL Webhook dan konfigurasi pemicu aplikasi Chat.
  • Jika gerbang penyebutan memblokir balasan, tetapkan botUser ke nama sumber daya pengguna aplikasi dan periksa requireMention.
  • Jalankan openclaw logs --follow saat mengirim pesan percobaan untuk melihat apakah permintaan mencapai Gateway.

Terkait

Was this useful?
On this page

On this page