Google Chat (Chat API)¶

Trạng thái: sẵn sàng cho DM + spaces thông qua webhook Google Chat API (chỉ HTTP).

Thiết lập nhanh (cho người mới)¶

Tạo một dự án Google Cloud và bật Google Chat API. - Truy cập: Google Chat API Credentials - Bật API nếu chưa được bật.
Tạo một Service Account: - Nhấn Create Credentials > Service Account. - Đặt tên tùy ý (ví dụ: openclaw-chat). - Để trống phần quyền (nhấn Continue). - Để trống phần principals có quyền truy cập (nhấn Done).
Tạo và tải xuống JSON Key: - Trong danh sách service accounts, nhấp vào account vừa tạo. - Vào tab Keys. - Nhấn Add Key > Create new key. - Chọn JSON và nhấn Create.
Lưu file JSON đã tải xuống trên máy chủ gateway của bạn (ví dụ: ~/.openclaw/googlechat-service-account.json).
Tạo một ứng dụng Google Chat trong Google Cloud Console Chat Configuration: - Điền Application info:
- App name: (ví dụ: OpenClaw)
- Avatar URL: (ví dụ: https://openclaw.ai/logo.png)
- Description: (ví dụ: Personal AI Assistant)
- Bật Interactive features.
- Trong Functionality, chọn Join spaces and group conversations.
- Trong Connection settings, chọn HTTP endpoint URL.
- Trong Triggers, chọn Use a common HTTP endpoint URL for all triggers và đặt thành URL công khai của gateway, theo sau là /googlechat.
- Mẹo: Chạy openclaw status để tìm URL công khai của gateway.
- Trong Visibility, chọn Make this Chat app available to specific people and groups in <Your Domain>.
- Nhập địa chỉ email của bạn (ví dụ: user@example.com) vào ô văn bản.
- Nhấn Save ở cuối trang.
Bật trạng thái ứng dụng: - Sau khi lưu, tải lại trang. - Tìm phần App status (thường ở gần đầu hoặc cuối trang sau khi lưu). - Đổi trạng thái thành Live - available to users. - Nhấn Save lần nữa.
Cấu hình OpenClaw với đường dẫn service account + webhook audience: - Biến môi trường: GOOGLE_CHAT_SERVICE_ACCOUNT_FILE=/path/to/service-account.json - Hoặc config: channels.googlechat.serviceAccountFile: "/path/to/service-account.json".
Thiết lập loại + giá trị webhook audience (khớp với cấu hình ứng dụng Chat của bạn).
Khởi động gateway. Google Chat will POST to your webhook path.

Thêm vào Google Chat¶

Khi gateway đang chạy và email của bạn đã được thêm vào danh sách hiển thị:

Truy cập Google Chat.
Nhấp vào biểu tượng + (dấu cộng) bên cạnh Direct Messages.
Trong thanh tìm kiếm (nơi bạn thường thêm người), nhập App name đã cấu hình trong Google Cloud Console. - Lưu ý: Bot sẽ không xuất hiện trong danh sách duyệt "Marketplace" vì đây là ứng dụng riêng tư. Bạn phải tìm kiếm theo tên của nó.
Chọn bot của bạn từ kết quả.
Nhấn Add hoặc Chat để bắt đầu cuộc trò chuyện 1:1.
Gửi "Hello" để kích hoạt trợ lý!

URL công khai (chỉ webhook)¶

Google Chat webhooks require a public HTTPS endpoint. Vì lý do bảo mật, chỉ mở đường dẫn /googlechat ra internet. Giữ bảng điều khiển OpenClaw và các endpoint nhạy cảm khác trong mạng riêng của bạn.

Tùy chọn A: Tailscale Funnel (Khuyến nghị)¶

Sử dụng Tailscale Serve cho bảng điều khiển riêng tư và Funnel cho đường dẫn webhook công khai. Điều này giữ cho / ở chế độ riêng tư trong khi chỉ mở /googlechat.

Kiểm tra địa chỉ mà gateway đang bind tới:

bash ss -tlnp | grep 18789

Ghi chú địa chỉ IP (ví dụ: 127.0.0.1, 0.0.0.0, hoặc IP Tailscale của bạn như 100.x.x.x).

Chỉ công khai dashboard cho tailnet (cổng 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 ```

Chỉ công khai đường dẫn 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 ```

Ủy quyền node cho quyền truy cập Funnel: Nếu được nhắc, hãy truy cập URL ủy quyền hiển thị trong đầu ra để bật Funnel cho node này trong chính sách tailnet của bạn.
Xác minh cấu hình:

bash tailscale serve status tailscale funnel status

URL webhook công khai của bạn sẽ là: https://<node-name>.<tailnet>.ts.net/googlechat`

Bảng điều khiển riêng tư của bạn chỉ khả dụng trong tailnet: https://<node-name>.<tailnet>.ts.net:8443/

Sử dụng URL công khai (không bao gồm :8443) trong cấu hình ứng dụng Google Chat.

Lưu ý: Cấu hình này sẽ được giữ nguyên sau khi khởi động lại. To remove it later, run tailscale funnel reset and tailscale serve reset.

Tùy chọn B: Reverse Proxy (Caddy)¶

Nếu bạn dùng reverse proxy như Caddy, chỉ proxy đường dẫn cụ thể:

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

Với cấu hình này, mọi request tới your-domain.com/ sẽ bị bỏ qua hoặc trả về 404, trong khi your-domain.com/googlechat được định tuyến an toàn tới OpenClaw.

Tùy chọn C: Cloudflare Tunnel¶

Cấu hình ingress rules của tunnel để chỉ định tuyến đường dẫn webhook:

Đường dẫn: /googlechat -> http://localhost:18789/googlechat
Quy tắc mặc định: HTTP 404 (Không tìm thấy)

Cách hoạt động¶

Google Chat gửi các POST webhook tới gateway. Each request includes an Authorization: Bearer <token> header.
OpenClaw xác minh token dựa trên audienceType + audience đã cấu hình: - audienceType: "app-url" → audience là URL webhook HTTPS của bạn. - audienceType: "project-number" → audience là số dự án Cloud.
Tin nhắn được định tuyến theo space: - DM dùng khóa phiên agent:<agentId>:googlechat:dm:<spaceId>. - Spaces dùng khóa phiên agent:<agentId>:googlechat:group:<spaceId>.
Quyền truy cập DM mặc định yêu cầu ghép nối. Người gửi chưa xác định sẽ nhận được mã ghép nối; phê duyệt bằng lệnh: - openclaw pairing approve googlechat <code>
Không gian nhóm mặc định yêu cầu @-mention. Sử dụng botUser nếu việc phát hiện mention cần tên người dùng của ứng dụng.

Targets¶

Sử dụng các định danh sau cho việc gửi và allowlist:

Tin nhắn trực tiếp: users/<userId> hoặc users/<email> (chấp nhận địa chỉ email).
Spaces: spaces/<spaceId>.

Điểm nổi bật về cấu hình¶

{
  channels: {
    googlechat: {
      enabled: true,
      serviceAccountFile: "/path/to/service-account.json",
      audienceType: "app-url",
      audience: "https://gateway.example.com/googlechat",
      webhookPath: "/googlechat",
      botUser: "users/1234567890", // optional; helps mention detection
      dm: {
        policy: "pairing",
        allowFrom: ["users/1234567890", "name@example.com"],
      },
      groupPolicy: "allowlist",
      groups: {
        "spaces/AAAA": {
          allow: true,
          requireMention: true,
          users: ["users/1234567890"],
          systemPrompt: "Short answers only.",
        },
      },
      actions: { reactions: true },
      typingIndicator: "message",
      mediaMaxMb: 20,
    },
  },
}

Ghi chú:

Thông tin xác thực service account cũng có thể truyền inline với serviceAccount (chuỗi JSON).
Đường dẫn webhook mặc định là /googlechat nếu webhookPath chưa được thiết lập.
Reactions khả dụng thông qua công cụ reactions và channels action khi actions.reactions được bật.
typingIndicator hỗ trợ none, message (mặc định) và reaction (reaction yêu cầu OAuth người dùng).
Tệp đính kèm được tải xuống thông qua Chat API và lưu trong media pipeline (kích thước bị giới hạn bởi mediaMaxMb).

Xử lý sự cố¶

405 Method Not Allowed¶

Nếu Google Cloud Logs Explorer hiển thị lỗi như:

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

This means the webhook handler isn't registered. Group system prompt: ở lượt đầu tiên của một phiên nhóm (và bất cứ khi nào /activation thay đổi chế độ), chúng tôi chèn một đoạn mô tả ngắn vào system prompt như You are replying inside the WhatsApp group "<subject>".

Channel not configured: The channels.googlechat section is missing from your config. Xác minh bằng:

bash openclaw config get channels.googlechat

Nếu trả về "Config path not found", hãy thêm cấu hình (xem Config highlights).

Plugin chưa được bật: Kiểm tra trạng thái plugin:

bash openclaw plugins list | grep googlechat

Nếu hiển thị "disabled", hãy thêm plugins.entries.googlechat.enabled: true vào config của bạn.

Gateway chưa được khởi động lại: Sau khi thêm config, hãy khởi động lại gateway:

bash openclaw gateway restart

Xác minh kênh đang chạy:

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

Vấn đề khác¶

Kiểm tra openclaw channels status --probe để tìm lỗi xác thực hoặc thiếu cấu hình audience.
Nếu không có tin nhắn đến, hãy xác nhận URL webhook + đăng ký sự kiện của ứng dụng Chat.
Nếu cơ chế chặn theo mention ngăn trả lời, hãy đặt botUser thành user resource name của ứng dụng và xác minh requireMention.
Dùng openclaw logs --follow trong khi gửi tin nhắn thử để xem request có tới gateway hay không.

Tài liệu liên quan:

Overview

Messaging platforms

Configuration

Google Chat