Google Chat 接入——谷歌生态协作 | Easy Understand Hermes Agent

这篇教程将手把手带你把 Hermes Agent 接入 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 在聊天里主动汇报任务、定时发日报？下一篇讲 “定时任务与主动消息”，敬请期待。