Google Chat (Chat API)

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

Cài đặt nhanh (dành cho người mới)

Tạo một Google Cloud project 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:
- Ấn Create Credentials > Service Account.
- Đặt tên tùy ý (ví dụ: openclaw-chat).
- Để trống phần permissions (ấn Continue).
- Để trống phần principals with access (ấn Done).
Tạo và tải về JSON Key:
- Trong danh sách service accounts, click vào cái vừa tạo.
- Vào tab Keys.
- Click Add Key > Create new key.
- Chọn JSON và ấn Create.
Lưu file JSON vừa tải về trên gateway host (ví dụ: ~/.openclaw/googlechat-service-account.json).
Tạo Google Chat app 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 phần Functionality, check Join spaces and group conversations.
- Trong phần Connection settings, chọn HTTP endpoint URL.
- Trong phần Triggers, chọn Use a common HTTP endpoint URL for all triggers và đặt thành URL công khai của gateway kèm theo /googlechat.
  - Mẹo: Chạy openclaw status để tìm URL công khai của gateway.
- Trong phần Visibility, check Make this Chat app available to specific people and groups in <Your Domain>.
- Nhập địa chỉ email của các bạn (ví dụ: [email protected]) vào ô text.
- Click Save ở cuối trang.
Bật app status:
- Sau khi save, refresh lại trang.
- Tìm phần App status (thường ở đầu hoặc cuối trang sau khi save).
- Đổi status thành Live - available to users.
- Click Save lần nữa.
Cấu hình OpenClaw với đường dẫn service account + webhook audience:
- Env: GOOGLE_CHAT_SERVICE_ACCOUNT_FILE=/path/to/service-account.json
- Hoặc config: channels.googlechat.serviceAccountFile: "/path/to/service-account.json".
Đặt webhook audience type + value (phải khớp với cấu hình Chat app).
Khởi động gateway. Google Chat sẽ POST đến webhook path.

Thêm vào Google Chat

Sau khi gateway đang chạy và email của các bạn đã được thêm vào visibility list:

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

URL công khai (chỉ Webhook)

Google Chat webhooks yêu cầu một public HTTPS endpoint. Để bảo mật, chỉ expose đường dẫn /googlechat ra internet. Giữ OpenClaw dashboard và các endpoints nhạy cảm khác trong mạng riêng.

Option A: Tailscale Funnel (Khuyên dùng)

Dùng Tailscale Serve cho private dashboard và Funnel cho public webhook path. Cách này giữ / ở chế độ riêng tư trong khi chỉ expose /googlechat.

Kiểm tra địa chỉ mà gateway đang bind:
```
ss -tlnp | grep 18789
```
Ghi nhớ địa chỉ IP (ví dụ: 127.0.0.1, 0.0.0.0, hoặc Tailscale IP như 100.x.x.x).

Expose dashboard chỉ trong tailnet (port 8443):

# Nếu bind vào localhost (127.0.0.1 hoặc 0.0.0.0):
tailscale serve --bg --https 8443 http://127.0.0.1:18789

# Nếu bind vào Tailscale IP (ví dụ: 100.106.161.80):
tailscale serve --bg --https 8443 http://100.106.161.80:18789

Expose chỉ webhook path ra công khai:

# Nếu bind vào localhost (127.0.0.1 hoặc 0.0.0.0):
tailscale funnel --bg --set-path /googlechat http://127.0.0.1:18789/googlechat

# Nếu bind vào Tailscale IP (ví dụ: 100.106.161.80):
tailscale funnel --bg --set-path /googlechat http://100.106.161.80:18789/googlechat

Authorize node để truy cập Funnel: Nếu được nhắc, truy cập URL authorization hiển thị trong output để bật Funnel cho node này trong tailnet policy.

Xác minh cấu hình:

tailscale serve status
tailscale funnel status

URL webhook công khai sẽ là: https://<node-name>.<tailnet>.ts.net/googlechat

Dashboard riêng tư chỉ trong tailnet: https://<node-name>.<tailnet>.ts.net:8443/

Dùng URL công khai (không có :8443) trong cấu hình Google Chat app.

Lưu ý: Cấu hình này tồn tại qua các lần reboot. Để xóa sau này, chạy tailscale funnel reset và tailscale serve reset.

Option B: Reverse Proxy (Caddy)

Nếu các 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 config này, mọi request đến your-domain.com/ sẽ bị bỏ qua hoặc trả về 404, trong khi your-domain.com/googlechat được route an toàn đến OpenClaw.

Option C: Cloudflare Tunnel

Cấu hình ingress rules của tunnel để chỉ route webhook path:

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

Cách hoạt động

Google Chat gửi webhook POSTs đến gateway. Mỗi request bao gồm header Authorization: Bearer <token>.
OpenClaw xác minh token với audienceType + audience đã cấu hình:
- audienceType: "app-url" → audience là HTTPS webhook URL.
- audienceType: "project-number" → audience là Cloud project number.
Messages được route theo space:
- DMs dùng session key agent:<agentId>:googlechat:dm:<spaceId>.
- Spaces dùng session key agent:<agentId>:googlechat:group:<spaceId>.
DM access mặc định là pairing. Người gửi không xác định sẽ nhận pairing code; phê duyệt bằng:
- openclaw pairing approve googlechat <code>
Group spaces mặc định yêu cầu @-mention. Dùng botUser nếu mention detection cần tên user của app.

Targets

Dùng các identifier này cho delivery và allowlists:

Direct messages: users/<userId> hoặc users/<email> (chấp nhận địa chỉ email).
Spaces: spaces/<spaceId>.

Các điểm nổi bật trong config

{
  channels: {
    googlechat: {
      enabled: true,
      serviceAccountFile: "/path/to/service-account.json",
      audienceType: "app-url",
      audience: "https://gateway.example.com/googlechat",
      webhookPath: "/googlechat",
      botUser: "users/1234567890", // tùy chọn; giúp mention detection
      dm: {
        policy: "pairing",
        allowFrom: ["users/1234567890", "[email protected]"],
      },
      groupPolicy: "allowlist",
      groups: {
        "spaces/AAAA": {
          allow: true,
          requireMention: true,
          users: ["users/1234567890"],
          systemPrompt: "Short answers only.",
        },
      },
      actions: { reactions: true },
      typingIndicator: "message",
      mediaMaxMb: 20,
    },
  },
}

Lưu ý:

Service account credentials cũng có thể được truyền inline với serviceAccount (JSON string).
Webhook path mặc định là /googlechat nếu không đặt webhookPath.
Reactions có sẵn qua reactions tool và channels action khi actions.reactions được bật.
typingIndicator hỗ trợ none, message (mặc định), và reaction (reaction yêu cầu user OAuth).
Attachments được tải về qua Chat API và lưu trong media pipeline (giới hạn kích thước bởi mediaMaxMb).

Troubleshooting

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

Điều này có nghĩa là webhook handler chưa được đăng ký. Nguyên nhân thường gặp:

Channel chưa được cấu hình: Phần channels.googlechat bị thiếu trong config. Kiểm tra bằng:
```
openclaw config get channels.googlechat
```
Nếu trả về “Config path not found”, thêm cấu hình (xem Các điểm nổi bật trong config).
Plugin chưa được bật: Kiểm tra trạng thái plugin:
```
openclaw plugins list | grep googlechat
```
Nếu hiển thị “disabled”, thêm plugins.entries.googlechat.enabled: true vào config.
Gateway chưa được restart: Sau khi thêm config, restart gateway:
```
openclaw gateway restart
```

Xác minh channel đang chạy:

openclaw channels status
# Nên hiển thị: Google Chat default: enabled, configured, ...

Các vấn đề khác

Kiểm tra openclaw channels status --probe để tìm lỗi auth hoặc thiếu audience config.
Nếu không nhận được messages, xác nhận webhook URL + event subscriptions của Chat app.
Nếu mention gating chặn replies, đặt botUser thành resource name của app user và kiểm tra requireMention.
Dùng openclaw logs --follow trong khi gửi test message để xem requests có đến gateway không.

Tài liệu liên quan: