🤖HermesBlog
Hermes 訊息平台接入 · 第18篇2026/8/9· Easy Understand Hermes Agent

Google Chat 接入——谷歌生态协作

Hermes 消息平台接入第18篇：Google Chat。在谷歌工作区里用 AI。

這篇教學將手把手帶你把 Hermes Agent 接入 Google Chat，讓它像同事一樣在聊天視窗裡為你幹活。

messaging-google-chat

先打個比方

想像 Google Chat 是一個公司前台，你的 Hermes 機器人是住在外地的員工。它不需要每天來公司坐班（不需要公網 IP），只需要訂閱一份「內部通訊錄」（Pub/Sub 訂閱），前台一有新訊息就透過這份通訊錄通知它。它再透過「公司信箱」（Chat REST API）把回覆發回去。整個過程不需要你開連接埠、設定憑證，就像微信機器人一樣簡單。

注意：你需要一個 Google Workspace 帳號（個人付費版或公司版都行），一般 Gmail 信箱無法建立 Chat 應用程式。

第1步：建立 GCP 專案

前往 console.cloud.google.com 新建一個專案，記下專案 ID（類似 my-chat-bot-123）。個人免費額度足夠機器人日常使用。

第2步：開啟兩個 API

在 API 和服務 → 程式庫 中，搜尋並啟用：

  • Google Chat API
  • Cloud Pub/Sub API

第3步：建立服務帳號

進入 IAM 和管理 → 服務帳號，建立一個名為 hermes-chat-bot 的帳號。不要在「授予此服務帳號存取專案權限」那一步做任何操作。建立後，進入該帳號 → 金鑰 → 新增金鑰 → 建立新金鑰 → JSON，下載金鑰檔案，儲存到 ~/.hermes/google-chat-sa.json，並執行 chmod 600 限制權限。

⚠️ 沒有「Chat 機器人呼叫者」這個 IAM 角色。別在專案層級亂授權，機器人能不能說話取決於它是否被安裝到聊天室，而不是 IAM 權限。

第4步：建立 Pub/Sub 主題和訂閱

進入 Pub/Sub → 主題，建立主題 hermes-chat-events。然後在主題詳情頁的 訂閱 標籤頁建立訂閱：

  • 訂閱 ID：hermes-chat-events-sub
  • 投遞方式：拉取
  • 訊息保留期：7天（防止 Hermes 重新啟動期間遺失訊息）

第5步：給主題綁定發布權限（關鍵！）

在主題（不是訂閱）的 IAM 設定中，新增：

  • 主體：chat-api-push@system.gserviceaccount.com
  • 角色：Pub/Sub 發布者

沒有這一步，Google Chat 無法把訊息推送給你，機器人永遠收不到任何東西。

第6步：給訂閱綁定訂閱權限

在訂閱的 IAM 設定中，新增你自己的服務帳號：

  • 主體：hermes-chat-bot@<你的專案>.iam.gserviceaccount.com
  • 角色：Pub/Sub 訂閱者

另外再加一個 Pub/Sub 檢視者 角色——Hermes 啟動時會檢查訂閱是否可達。

第7步：設定 Chat 應用程式

進入 API 和服務 → Google Chat API → 設定：

  • 應用程式名稱：隨便填，使用者看到的名字（比如「Hermes」）
  • 頭像 URL：任意公開 PNG 圖片
  • 功能：勾選「接收 1:1 訊息」和「加入空間和群組對話」
  • 連線設定：選擇 Cloud Pub/Sub，填入 projects/<你的專案>/topics/hermes-chat-events
  • 可見範圍：先限制為僅你自己或少數測試使用者

儲存。

第8步：在測試空間安裝機器人

開啟 Google Chat，在 + 新聊天 中搜尋你的應用程式名字，發一則訊息。Google 會發送一個 ADDED_TO_SPACE 事件，Hermes 會用它快取自己的使用者 ID。

第9步：設定 Hermes

編輯 ~/.hermes/.env：

# 必填
GOOGLE_CHAT_PROJECT_ID=my-chat-bot-123
GOOGLE_CHAT_SUBSCRIPTION_NAME=projects/my-chat-bot-123/subscriptions/hermes-chat-events-sub
GOOGLE_CHAT_SERVICE_ACCOUNT_JSON=/home/你/.hermes/google-chat-sa.json

# 授權——只允許這些信箱的人跟機器人說話
GOOGLE_CHAT_ALLOWED_USERS=you@yourdomain.com,coworker@yourdomain.com

# 選用
GOOGLE_CHAT_HOME_CHANNEL=spaces/AAAA...   # 定時任務的預設傳送目標
GOOGLE_CHAT_MAX_MESSAGES=1                # 每次只處理一則訊息，避免並發混亂

安裝依賴並啟動：

python -m plugins.platforms.google_chat.oauth --install-deps
hermes gateway

看到 [GoogleChat] Connected 就成功了。在測試聊天裡發一句「你好」，機器人會先顯示「Hermes is thinking…」，然後原地編輯成真正的回覆——不會有「訊息已刪除」的痕跡。

想改這個提示文字？在 ~/.hermes/config.yaml 裡設定 typing_status_text，比如 "正在撲向鍵盤… 🐾"。不想要就直接設 typing_indicator: false。

第10步（選用）：原生檔案傳送

Google Chat 的 media.upload 介面只認使用者身分，不認服務帳號。所以要讓機器人傳送原生檔案，每個使用者需要單獨授權一次。按文件指引在 API 和服務 → 憑證 中完成 OAuth 流程即可。

小總結

Google Chat 接入的核心就三步：建主題、綁權限、設應用程式。最難理解的是 IAM 權限分配——記住一句話：主題給 Google 發訊息的權限，訂閱給你機器人收訊息的權限。搞定這兩個綁定，剩下的都是填表。

下篇預告：接入完成後，怎麼讓 Hermes 在聊天裡主動回報任務、定時發日報？下一篇講 「定時任務與主動訊息」，敬請期待。

📖 官方文档

本文根据 Hermes Agent 官方文档编写，原文见：官方文档 › user-guide/messaging/google_chat

← 返回全部文章