词元广场TOKPUB.COM - 欢迎您，支持一个 Key 调用近 600+ 海内外模型，限时特价模型低至 1 折，欢迎上岸！
"Google Chat"
Google Chat 设置
Workspace 版本
@yourdomain.com）或拥有管理员权限可发布应用的企业 Workspace 中使用此集成。仅有 Gmail 账号的用户无法托管 Chat 应用。概览
| 组件 | 值 |
|---|---|
| 依赖库 | google-cloud-pubsub、google-api-python-client、google-auth |
| 入站传输 | Cloud Pub/Sub 拉取订阅（无需公网端点） |
| 出站传输 | Chat REST API（chat.googleapis.com） |
| 认证 | 在订阅上具有 roles/pubsub.subscriber 的 Service Account JSON |
| 用户标识 | Chat 资源名称（users/{id}）+ 邮箱 |
第一步：创建或选择 GCP 项目
my-chat-bot-123），后续每一步都会用到。第二步：启用两个 API
第三步：创建 Service Account
hermes-chat-bot~/.hermes/google-chat-sa.json，chmod 600）。一个常见错误是搜索 Chat 专属 IAM 角色并在项目级别授予。该角色并不存在。Chat 机器人的权限来自被安装到某个 space（空间），而非 IAM。你的 SA 只需要在下一步创建的订阅上具有 Pub/Sub subscriber 权限。
:::
第四步：创建 Pub/Sub topic 和订阅
hermes-chat-eventshermes-chat-events-sub第五步：在 topic 上配置 IAM 绑定（关键）
chat-api-push@system.gserviceaccount.comPub/Sub Publisher第六步：在订阅上配置 IAM 绑定
hermes-chat-bot@<your-project>.iam.gserviceaccount.comPub/Sub SubscriberPub/Sub Viewer——Hermes 在启动时会调用 subscription.get() 进行可达性检查。第七步：配置 Chat 应用
projects/<your-project>/topics/hermes-chat-events。第八步：在测试 space 中安装机器人
ADDED_TO_SPACE 事件，Hermes 用它来缓存机器人自身的 users/{id}，以便过滤自发消息。第九步：配置 Hermes
~/.hermes/.env 中添加 Google Chat 配置段：GOOGLE_CLOUD_PROJECT，SA 路径可回退到 GOOGLE_APPLICATION_CREDENTIALS——使用你偏好的约定即可。[GoogleChat] Connected; project=my-chat-bot-123, subscription=<redacted>,
bot_user_id=users/XXXX, flow_control(msgs=1, bytes=16777216)格式化与功能
| 支持 | 不支持 |
|---|---|
*粗体*、_斜体_、~删除线~、`代码` | 标题、列表 |
| 通过 URL 内联图片 | 交互式 Card v2 按钮（此 gateway 为 v1） |
原生文件附件（执行 /setup-files 后——见第十步） | 原生语音消息 / 圆形视频消息 |
thread.name 并在同一 thread 中发送回复，每个 thread 对应独立的 Hermes 会话。第十步：原生附件投递（可选）
为何需要单独的流程
media.upload 端点会硬拒绝 service account 认证：This method doesn't support app authentication with a service account.
Authenticate with a user account.
一次性宿主机设置
1.
2.
3.
4.
~/.hermes/google_chat_user_client_secret.json。这是共享基础设施——它标识 OAuth 应用，而非某个具体用户。无论后续有多少用户授权，每台宿主机只需一个文件。每用户授权（在 Chat 中操作）
1.
/setup-files，机器人回复当前状态和下一步操作。2.
/setup-files start，机器人回复一个 OAuth URL。3.
http://localhost:1/?...&code=... 并失败。这是预期行为——auth code 在地址栏的 URL 中。4.
code=... 的值），粘贴回 Chat 中作为 /setup-files <PASTED_URL>。机器人将其换取 refresh token。~/.hermes/google_chat_user_tokens/<sanitized_email>.json。该用户私信中后续的文件请求将使用其token，机器人以其身份上传，消息投递到其 space。/setup-files revoke 仅删除该用户的 token，其他用户的 token 不受影响。Scope
chat.messages.create。它同时覆盖 media.upload 和引用已上传 attachmentDataRef 的 messages.create。没有 Drive，没有更广泛的 Chat scope——这是有意为之的最小权限原则。多用户行为
~/.hermes/google_chat_user_token.json 中的旧版单用户 token（如果存在于多用户支持之前的安装中）。两者均不可用时，机器人会发送清晰的文字提示，告知请求者运行 /setup-files。故障排查
1.
GOOGLE_CHAT_SERVICE_ACCOUNT_JSON，并确认 SA 在订阅上具有 Pub/Sub Subscriber 角色。2.
chat-api-push@system.gserviceaccount.com 必须具有 Pub/Sub Publisher 角色。3.
hermes gateway 日志中是否有 [GoogleChat] Connected。如果看到 [GoogleChat] Config validation failed，错误信息会告诉你需要修复哪个环境变量。[GoogleChat] Pub/Sub stream died——如果反复出现，可能是 SA 凭据已轮换或订阅已被删除。重试 10 次后，适配器会将自身标记为致命错误。ADDED_TO_SPACE 事件会自动恢复消息发送功能）。/setup-files 并按照第十步操作。交换完成后，下次文件请求将原生上传，无需重启 gateway。/setup-files start 提示"No client credentials stored on the host."/setup-files start。/setup-files <PASTED_URL> 提示"Token exchange failed."/setup-files start 获取新 URL 后重试。安全说明
chat.bot 和 pubsub scope。IAM 应作为实际执行层——仅授予 SA 最小权限（订阅上的 roles/pubsub.subscriber + roles/pubsub.viewer），不要授予项目级或组织级 Pub/Sub 角色。googleapis.com、drive.google.com、lh[3-6].googleusercontent.com 等）。其他主机在发起 HTTP 请求前即被拒绝，以防范 SSRF 场景——即精心构造的事件将 bearer token 重定向到 GCE 元数据服务。agent/redact.py 从日志输出中剥离。调试信封转储（GOOGLE_CHAT_DEBUG_RAW=1）经过同一脱敏过滤器，以 DEBUG 级别记录。chat.messages.create——覆盖 media.upload 及后续 messages.create 所需的最小权限。token 以明文 JSON 形式持久化在 ~/.hermes/google_chat_user_tokens/<sanitized_email>.json（文件系统权限是保护手段——与 SA 密钥文件采用相同模型）。每个 token 归属于唯一一位用户；撤销操作仅限于该用户。