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 hoạt động dưới dạng plugin chính thức @openclaw/googlechat: hỗ trợ tin nhắn trực tiếp và không gian thông qua Webhook của Google Chat API (chỉ điểm cuối HTTP, không hỗ trợ Pub/Sub).

Cài đặt

bash
openclaw plugins install @openclaw/googlechat

Bản mã nguồn cục bộ (khi chạy từ kho git):

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

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

  1. Tạo một dự án Google Cloud và bật Google Chat API.
  2. Tạo một Service Account:
    • Nhấn Create Credentials > Service Account.
    • Đặt tên tùy ý (ví dụ: openclaw-chat).
    • Để trống quyền và chủ thể (Continue, sau đó Done).
  3. Tạo và tải xuống khóa JSON:
    • Nhấp vào tài khoản dịch vụ mới > thẻ Keys > Add Key > Create new key > JSON > Create.
  4. Lưu tệp JSON đã tải xuống trên máy chủ Gateway của bạn (ví dụ: ~/.openclaw/googlechat-service-account.json).
  5. Tạo ứng dụng Google Chat trong Cấu hình Chat trên Google Cloud Console:
    • Điền Application info (tên ứng dụng, URL ảnh đại diện, mô tả).
    • 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 Gateway công khai của bạn, theo sau là /googlechat (xem URL công khai).
    • Trong Visibility, chọn Make this Chat app available to specific people and groups in <Your Domain> và nhập địa chỉ email của bạn.
    • Nhấp Save.
  6. Bật trạng thái ứng dụng: làm mới trang, tìm App status, đặt thành Live - available to users, rồi Save lần nữa.
  7. Cấu hình OpenClaw bằng tài khoản dịch vụ và đối tượng nhận Webhook (phải khớp với cấu hình ứng dụng Chat):
    • Biến môi trường: GOOGLE_CHAT_SERVICE_ACCOUNT_FILE=/path/to/service-account.json (chỉ dành cho tài khoản mặc định), hoặc
    • Cấu hình: xem Các điểm chính về cấu hình. openclaw channels add --channel googlechat cũng chấp nhận --audience-type, --audience, --webhook-path và --webhook-url.
  8. Khởi động Gateway. Google Chat sẽ gửi yêu cầu POST đến đường dẫn Webhook của bạn (mặc định là /googlechat).

Thêm vào Google Chat

Sau khi Gateway đang chạy và email của bạn có trong danh sách hiển thị:

  1. Truy cập Google Chat.
  2. Nhấp vào biểu tượng + (dấu cộng) bên cạnh Direct Messages.
  3. Tìm kiếm theo App name mà bạn đã cấu hình trong Google Cloud Console.
    • Bot không xuất hiện trong danh sách duyệt Marketplace vì đây là ứng dụng riêng tư; hãy tìm kiếm theo tên.
  4. Chọn bot, nhấp Add hoặc Chat, rồi gửi tin nhắn.

URL công khai (chỉ Webhook)

Webhook của Google Chat yêu cầu một điểm cuối HTTPS công khai. Để bảo mật, chỉ công khai đường dẫn /googlechat trên Internet và giữ bảng điều khiển OpenClaw cùng các điểm cuối khác ở chế độ riêng tư.

Phương án A: Tailscale Funnel (Khuyên dùng)

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.

  1. Kiểm tra địa chỉ mà Gateway đang liên kết:

    bash
    ss -tlnp | grep 18789

    Ghi lại địa chỉ IP (ví dụ: 127.0.0.1, 0.0.0.0 hoặc địa chỉ Tailscale 100.x.x.x).

  2. Chỉ công khai bảng điều khiển trong tailnet (cổng 8443):

    bash
    # Nếu liên kết với localhost (127.0.0.1 hoặc 0.0.0.0):tailscale serve --bg --https 8443 http://127.0.0.1:18789 # Nếu chỉ liên kết với IP Tailscale:tailscale serve --bg --https 8443 http://100.x.x.x:18789

  3. Chỉ công khai đường dẫn Webhook:

    bash
    # Nếu liên kết với 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 chỉ liên kết với IP Tailscale:tailscale funnel --bg --set-path /googlechat http://100.x.x.x:18789/googlechat

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

  5. Xác minh:

    bash
    tailscale serve statustailscale funnel status

URL Webhook công khai của bạn là https://<node-name>.<tailnet>.ts.net/googlechat; bảng điều khiển vẫn chỉ khả dụng trong tailnet tại https://<node-name>.<tailnet>.ts.net:8443/. Sử dụng URL công khai (không có :8443) trong cấu hình ứng dụng Google Chat.

Lưu ý: Cấu hình này vẫn được duy trì sau khi khởi động lại. Sau này, có thể xóa cấu hình bằng tailscale funnel reset và tailscale serve reset.

Phương án B: Proxy ngược (Caddy)

Chỉ chuyển tiếp đường dẫn Webhook:

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

Các yêu cầu đến your-domain.com/ sẽ bị bỏ qua hoặc trả về 404, trong khi your-domain.com/googlechat được định tuyến đến OpenClaw.

Phương án C: Cloudflare Tunnel

Cấu hình các quy tắc đầu vào của đường hầm để chỉ định tuyến đường dẫn Webhook:

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

Cách hoạt động

  1. Google Chat gửi JSON bằng phương thức POST đến đường dẫn Webhook của Gateway (chỉ POST, bắt buộc loại nội dung JSON và giới hạn tốc độ theo IP).
  2. OpenClaw xác thực mọi yêu cầu trước khi chuyển tiếp:
    • Các sự kiện của ứng dụng Chat mang Authorization: Bearer <token>; token được xác minh trước khi phân tích toàn bộ phần thân.
    • Các sự kiện Tiện ích bổ sung Google Workspace mang token trong phần thân (authorizationEventObject.systemIdToken) và được đọc theo hạn mức tiền xác thực nghiêm ngặt hơn (16 KB, 3 giây) trước khi xác minh.
  3. Token được kiểm tra dựa trên audienceType + audience:
    • audienceType: "app-url" → đối tượng nhận là URL Webhook HTTPS của bạn.
    • audienceType: "project-number" → đối tượng nhận là số dự án Cloud.
    • Token của tiện ích bổ sung khi dùng app-url còn yêu cầu appPrincipal được đặt thành mã máy khách OAuth 2.0 dạng số của ứng dụng (21 chữ số, không phải email); nếu không, quá trình xác minh sẽ thất bại và ghi cảnh báo vào nhật ký.
  4. Tin nhắn được định tuyến theo không gian:
    • Các không gian có phiên riêng cho từng không gian agent:<agentId>:googlechat:group:<spaceId>; phản hồi được gửi đến luồng tin nhắn.
    • Theo mặc định, các tin nhắn trực tiếp được gộp vào phiên chính của tác tử; đặt session.dmScope để sử dụng phiên tin nhắn trực tiếp riêng cho từng đối tác (xem Phiên).
  5. Theo mặc định, quyền truy cập tin nhắn trực tiếp sử dụng cơ chế ghép nối. Người gửi chưa xác định sẽ nhận mã ghép nối; phê duyệt bằng:
    • openclaw pairing approve googlechat <code>
  6. Theo mặc định, không gian nhóm yêu cầu đề cập bằng @. Các lượt đề cập được phát hiện từ chú thích USER_MENTION của Chat nhắm đến ứng dụng; đặt botUser (ví dụ: users/1234567890) nếu việc phát hiện cần tên tài nguyên người dùng của ứng dụng.
  7. Khi yêu cầu phê duyệt thực thi hoặc Plugin bắt đầu từ Google Chat và đã cấu hình người phê duyệt users/<id> ổn định, OpenClaw đăng một thẻ phê duyệt gốc (cardsV2) trong không gian hoặc luồng khởi nguồn. Các nút trên thẻ mang token gọi lại không rõ nghĩa; lời nhắc thủ công /approve <id> <decision> chỉ xuất hiện khi không thể phân phối theo cách gốc.

Đích

Sử dụng các mã định danh sau để phân phối và lập danh sách cho phép:

  • Tin nhắn trực tiếp: users/<userId> (khuyên dùng).
  • Không gian: spaces/<spaceId>.
  • Email thô name@example.com có thể thay đổi và chỉ được dùng để đối chiếu danh sách cho phép khi channels.googlechat.dangerouslyAllowNameMatching: true.
  • Không còn khuyến nghị: users/<email> được xem là mã định danh người dùng, không phải mục email trong danh sách cho phép.
  • Các tiền tố googlechat:, google-chat: và gchat: được chấp nhận và loại bỏ.

Các điểm chính về cấu hình

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",      appPrincipal: "123456789012345678901", // add-on verification only; numeric OAuth client ID      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.",        },      },      typingIndicator: "message",      mediaMaxMb: 20,    },  },}

Lưu ý:

  • Thông tin xác thực tài khoản dịch vụ: serviceAccountFile (đường dẫn), serviceAccount (chuỗi hoặc đối tượng JSON nội tuyến) hoặc serviceAccountRef (SecretRef từ biến môi trường/tệp). Các biến môi trường GOOGLE_CHAT_SERVICE_ACCOUNT (JSON nội tuyến) và GOOGLE_CHAT_SERVICE_ACCOUNT_FILE (đường dẫn) chỉ áp dụng cho tài khoản mặc định. Thiết lập nhiều tài khoản sử dụng channels.googlechat.accounts.<id> với cùng các khóa, bao gồm serviceAccountRef riêng cho từng tài khoản.
  • Đường dẫn Webhook mặc định là /googlechat khi chưa đặt webhookPath; webhookUrl cũng có thể cung cấp đường dẫn.
  • Khóa nhóm phải là mã định danh không gian ổn định (spaces/<spaceId>). Khóa theo tên hiển thị không còn được khuyến nghị và sẽ được ghi nhận tương ứng trong nhật ký.
  • dangerouslyAllowNameMatching bật lại việc đối chiếu chủ thể email có thể thay đổi cho danh sách cho phép (chế độ tương thích khẩn cấp); doctor cảnh báo về các mục email.
  • Các thao tác phản ứng của Google Chat không được cung cấp. Plugin sử dụng xác thực bằng tài khoản dịch vụ, trong khi các điểm cuối phản ứng của Google Chat yêu cầu xác thực người dùng. Cấu hình actions.reactions hiện có được chấp nhận để tương thích nhưng không có tác dụng.
  • Thẻ phê duyệt gốc sử dụng lượt nhấp nút cardsV2 của Google Chat, không sử dụng sự kiện phản ứng. Người phê duyệt lấy từ dm.allowFrom hoặc defaultTo và phải là giá trị số ổn định users/<id>.
  • Các thao tác tin nhắn chỉ cung cấp send dạng văn bản. Tải tệp đính kèm lên Google Chat yêu cầu xác thực người dùng, trong khi Plugin này sử dụng xác thực bằng tài khoản dịch vụ, vì vậy không cung cấp tính năng tải tệp đi lên.
  • typingIndicator: message (mặc định) đăng phần giữ chỗ _&lt;Bot&gt; is typing..._ rồi chỉnh sửa thành phản hồi đầu tiên; none vô hiệu hóa tính năng này; reaction yêu cầu OAuth người dùng và hiện sẽ chuyển về message, đồng thời ghi lỗi vào nhật ký khi dùng xác thực bằng tài khoản dịch vụ.
  • Tệp đính kèm đến (tệp đầu tiên trong mỗi tin nhắn) được tải xuống thông qua Chat API vào quy trình xử lý phương tiện, với giới hạn mediaMaxMb (mặc định là 20).
  • Theo mặc định, tin nhắn do bot tạo bị bỏ qua. Với allowBots: true, tin nhắn bot được chấp nhận sử dụng cơ chế bảo vệ vòng lặp bot dùng chung: cấu hình channels.defaults.botLoopProtection, sau đó ghi đè bằng channels.googlechat.botLoopProtection hoặc channels.googlechat.groups.<space>.botLoopProtection.

Chi tiết tham chiếu bí mật: Quản lý bí mật.

Khắc phục sự cố

405 Phương thức không được phép

Nếu Trình khám phá nhật ký Google Cloud hiển thị các lỗi như:

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

Trình xử lý Webhook chưa được đăng ký. Các nguyên nhân thường gặp:

  1. Kênh chưa được cấu hình: thiếu phần channels.googlechat. Xác minh bằng:

    bash
    openclaw config get channels.googlechat

    Nếu lệnh trả về "Config path not found", hãy thêm cấu hình (xem Các điểm chính về cấu hình).

  2. 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 cấu hình.

  3. Gateway chưa được khởi động lại sau khi thay đổi cấu hình:

    bash
    openclaw gateway restart

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

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

Các sự cố khác

  • openclaw channels status --probe hiển thị lỗi xác thực và cấu hình đối tượng nhận còn thiếu (bắt buộc phải có cả audience và audienceType).
  • Nếu không nhận được tin nhắn, hãy xác nhận URL Webhook và cấu hình trình kích hoạt của ứng dụng Chat.
  • Nếu cơ chế kiểm soát đề cập chặn phản hồi, hãy đặt botUser thành tên tài nguyên người dùng của ứng dụng và kiểm tra requireMention.
  • Chạy openclaw logs --follow trong khi gửi tin nhắn thử nghiệm để biết yêu cầu có đến được Gateway hay không.

Liên quan

Was this useful?
On this page

On this page