跳到主要内容

Google Chat 机器人配置与使用指南

最近更新 2026/10/03

本文档介绍如何在 Agentic Engine 中接入 Google Chat 机器人，并说明管理员配置、普通用户绑定、私聊与群聊使用、文件处理和常见问题。内容以当前系统实现为准。

提示

当前推荐：新建 Google Chat 应用通常使用 Google Workspace Add-on 模式；旧项目仍可使用传统 Chat app 模式。Agentic Engine 同时兼容这两种 HTTP 回调格式。

只需要私聊时，不必开启“加入聊天室和群组对话”；需要 Space @提及和 Thread 会话时再开启。

一、当前支持的能力​

能力状态说明
Google Chat 私聊支持用户绑定后可直接发送消息，机器人通过编辑同一条消息持续更新回答。
Space @提及可选需要在 Google Chat API 配置中开启“加入聊天室和群组对话”；群聊必须明确 @机器人。
Thread 会话支持群聊中的不同 Thread 使用独立会话上下文，回复会回到原 Thread。
群聊能力分发支持管理员可配置默认 Agent/Team、调用指令和关键词；用户可按能力显式调用或自动匹配。
图片与文档输入支持读取用户直接上传到 Google Chat 的图片和常见办公文档；不读取 Google Drive 分享文件。
生成文件支持用户完成 OAuth 文件授权后发送原生附件；未授权或上传失败时自动回退为短期 HTTPS 下载链接。

二、配置前准备​

  • 有权管理目标 Google Cloud 项目和 Google Chat API Configuration
  • 使用可访问 Google Chat 的 Google Workspace 账号
  • Agentic Engine 已通过公网 HTTPS 域名访问
  • 有 Agentic Engine“系统管理 → 渠道管理”权限
  • 如需群聊，Workspace 管理员允许安装和使用组织内 Chat app
警告

接入必检：仅填写 Service Account JSON 不代表接入完成。还必须配置 Google Chat HTTP 回调、应用可见范围，并按需启用群聊和用户 OAuth。

实例与身份：同一个 Google Chat Bot 身份不要同时连接同一运行环境中的多个渠道实例，也不要同时连接多个集群，否则可能出现重复回复、会话漂移或取消命令命中错误任务。

两个 Service Account 的区别​

配置获取位置用途
Workspace Add-on 服务账号邮箱Google Chat API → Configuration → Connection settingsGoogle 调用 Agentic Engine Webhook 时，用于校验 OIDC 调用方身份。这里只填邮箱，不需要密钥。
回复消息用 Service Account JSONGoogle Cloud → IAM 与管理 → 服务账号 → 密钥Agentic Engine 使用 chat.bot Scope 调用 Google Chat API，发送和更新机器人消息。

这两个身份可能不是同一个账号。不要用 JSON 中的 client_email 猜测或替代 Configuration 页面显示的 Add-on 服务账号邮箱。

三、配置流程总览​

四、管理员配置​

1. 创建回复消息用 Service Account​

  1. 在 Google Cloud Console 创建或选择目标项目。
  2. 启用 Google Chat API。
  3. 进入 IAM 与管理 → 服务账号，创建仅供该机器人使用的 Service Account。
  4. 为 Service Account 创建 JSON 密钥并立即下载。
  5. 将 JSON 作为敏感凭据保管，不要发送到群聊、工单或提交到代码仓库。

Agentic Engine 只使用 https://www.googleapis.com/auth/chat.bot Scope。JSON 会被解析为必要字段并加密保存，管理接口不会回显私钥。

2. 在 Agentic Engine 新建渠道​

  1. 进入 系统管理 → 渠道管理，点击“新建渠道”。
  2. 渠道类型选择 Google Chat，填写渠道名称、模型和系统提示词。
  3. 如果使用 Workspace Add-on 模式，填写 Google Chat Configuration 页面显示的 Workspace Add-on 服务账号邮箱；传统 Chat app 模式可留空。
  4. 将回复消息用的完整 Service Account JSON 粘贴到配置框。
  5. 如需用户以自己的身份接收原生附件，开启“用户 OAuth 原生附件”，并填写 OAuth Client ID 与 Client Secret。
  6. 保存渠道。再次编辑该渠道，复制系统生成的只读 Webhook URL。
警告

Webhook URL 包含渠道 ID 和随机 callback token。必须从渠道管理页复制完整地址，不要手写、截断、修改域名、协议、basePath 或结尾斜杠。

更新同一渠道的 Service Account 时，Webhook URL 不变；删除渠道后重新创建会生成新地址，必须同步更新 Google Chat API Configuration。

3. 配置 Google Chat API：Workspace Add-on 模式​

新建 Chat 应用时，Google Cloud Console 可能自动启用“将此 Chat 应用构建为 Workspace 插件”，且无法关闭，这是正常现象。

  1. 填写应用名称、HTTPS 头像地址和描述。
  2. 在 Connection settings 中选择“为所有触发器使用通用 HTTP 端点网址”。
  3. 将 Agentic Engine 渠道管理页的完整 Webhook URL 粘贴为 HTTP endpoint。
  4. 记录同一区域显示的 Service Account email，并回填到 Agentic Engine 的“Workspace Add-on 服务账号邮箱”。
  5. 保留“用户可以直接在 Google Chat 中找到该应用并向其发送消息”，用于私聊。
  6. 如需 Space @提及和 Thread，开启“加入聊天室和群组对话”；仅需私聊时保持关闭。
  7. 在 Visibility 中先加入测试账号或 Google Group，并将应用状态设置为测试用户可用。
  8. 保存配置。

当前系统能识别 Add-on 的消息、加入/移除 Space、按钮、Widget 更新和 App Command 等事件；只有消息事件会进入 Agent，其余事件会安全确认但不触发对话。

4. 配置 Google Chat API：传统 Chat app 模式​

  1. 在 Interactive features 中启用 Receive 1:1 messages；需要群聊时同时允许加入 Spaces。
  2. Connection settings 选择 HTTP endpoint URL，填写完整 Webhook URL。
  3. Authentication audience 选择 HTTP endpoint URL，并确保与 Webhook URL 逐字符完全一致。
  4. Visibility 先限制为测试用户或测试群，保存配置。

传统模式不需要填写“Workspace Add-on 服务账号邮箱”；Agentic Engine 会校验 Google Chat 的系统服务身份。

5. 可选：配置用户 OAuth 原生附件​

Google Chat Media Upload API 不支持使用 chat.bot 应用身份上传文件。若希望生成文件以原生附件发送，需要额外配置用户 OAuth。

  1. 在同一 Google Cloud 项目中配置 OAuth consent screen，并加入测试用户或发布范围。
  2. 创建 Web application 类型的 OAuth Client。
  3. 将当前站点的完整回调地址加入 Authorized redirect URIs：https://{域名}{basePath}/api/google-chat-oauth/callback。
  4. 在 Agentic Engine 渠道管理中开启“用户 OAuth 原生附件”，填写 OAuth Client ID 与 Client Secret。

系统仅申请 openid 与 https://www.googleapis.com/auth/chat.messages.create。OAuth Token 与 Client Secret 会加密保存，不会通过管理接口或普通日志回显。

6. HTTPS、反向代理与本地联调​

  • Google Chat 回调必须是公网可访问的 HTTPS 地址，不能直接使用 http://localhost 或内网 HTTP 地址。
  • 本地联调可通过 Cloudflare Tunnel、ngrok 等 HTTPS 隧道转发到本地服务。
  • 若公开域名变化，需要同步更新 ALLOWED_ORIGINS、重启服务，并更新 Google Chat API 中的完整端点。
  • 反向代理应正确传递 Host、X-Forwarded-Host 和 X-Forwarded-Proto。

1. 在 Google Chat 中找到应用​

  1. 确认当前 Google Workspace 账号已加入应用的 Visibility 或测试用户范围。
  2. 打开 Google Chat，点击“发起新聊天”或“查找应用”。
  3. 搜索 Google Chat Configuration 中填写的完整应用名称，不要搜索 Cloud Project ID、Service Account 邮箱或 Agentic Engine 渠道名称。
  4. 选择带“应用”标识的结果并安装。只使用私聊时选择打开 1:1 对话，不要添加到 Space。
渠道状态用户操作
管理员已启用用户 OAuth进入 Agentic Engine 左下角账号菜单的“渠道绑定”，选择 Google Chat，点击绑定并授权；在 Google 页面选择正在使用 Google Chat 的同一账号并同意授权。
管理员未启用用户 OAuth在“渠道绑定”中复制一次性命令，例如 +bind ABC234，然后在 Google Chat 中私聊应用发送。绑定码有效期为 10 分钟，只能使用一次。
已绑定但未授权文件在“渠道绑定”中点击授权文件，并选择与既有 Google Chat 绑定一致的 Google 账号；账号不一致时不会改绑或保存凭证。
提示

绑定码只能私聊发送，避免一次性码泄露。同一个 Google Chat 账号只能绑定一个 Agentic Engine 用户；如提示已被其他用户绑定，请先在原账号解绑。

六、普通用户：对话与命令​

私聊​

  • 绑定成功后直接发送普通文本即可开始对话。
  • 机器人会先创建回复，再持续更新为完整答案。
  • 发送 +new 开始新的私聊会话；有正在执行或等待回答的任务时，应先完成交互或取消。
  • 发送 +cancel 停止当前任务。

Space 与 Thread​

仅当管理员在 Google Chat Configuration 中开启“加入聊天室和群组对话”时可用。

  • 在 Space 中通过 @机器人 + 问题 明确唤醒入口机器人。
  • 同一个 Thread 内保持同一会话上下文；不同 Thread 相互隔离。
  • 管理员配置群聊能力分发后，普通问题进入默认 Agent/Team；也可使用 +<调用指令> <问题>、@<调用指令> <问题> 或配置好的关键词选择能力。
  • 发送 +help 或“能力清单”查看当前可用能力。
  • 发送 +cancel 停止当前群聊任务。
  • 群聊不启用 +new；直接发送新任务，或先取消当前任务。

七、图片与文件​

用户发送给机器人​

  • 默认支持用户直接上传到 Google Chat 的 PNG、JPEG、GIF、WebP 图片。
  • 默认支持 txt、md、csv、json、pdf、doc、docx、xls、xlsx、ppt、pptx。
  • 默认单文件最大 2MB、单条消息最多 5 个附件、单附件下载超时 10 秒；管理员可在服务端配置中调整，但不能超过系统硬限制。
  • 只处理 Google Chat 的 UPLOADED_CONTENT。从 Google Drive 分享的文件会被跳过。
  • 图片和 PDF 会校验实际文件内容，声明类型与文件内容不一致时会拒绝处理。

机器人发送给用户​

  • 用户已完成文件 OAuth 授权时，生成文件会发送到原私聊或原 Space/Thread，并显示为当前用户通过应用发送。
  • 用户未授权、Token 刷新失败或 Google 上传失败时，系统自动发送带签名的短期 HTTPS 下载链接。
  • 下载链接默认 10 分钟失效；过期、源消息或运行被删除、文件内容发生变化后，需要重新生成。
  • 回答包含 Markdown 表格时，系统默认生成 result.csv；回答超过默认阈值 6000 字符或用户明确要求文件时，生成 result.txt。

八、常见问题​

现象优先检查
搜索不到应用Google Chat 与 Cloud Console 是否使用同一 Workspace 组织账号；账号是否在 Visibility 中；应用状态是否可用；配置是否已保存。修改后可能需要等待几分钟。
应用没有回应 / Webhook 401Workspace Add-on 服务账号邮箱是否与 Configuration 页面完全一致；传统模式的 Authentication audience 是否选择 HTTP endpoint；Webhook URL、HTTPS、反向代理和 ALLOWED_ORIGINS 是否正确。
Webhook 404渠道是否已禁用或删除；URL 中的渠道 ID 与 callback token 是否仍有效；删除重建渠道后是否同步更新了新 URL。
2xx 但没有机器人回复回复消息用 Service Account JSON 是否有效；Google Chat API 是否启用；服务端获取 Google OAuth Token、调用 Chat API或模型执行是否报错。
绑定失败绑定码是否在私聊发送、仍在 10 分钟有效期且未使用；Google Chat 身份是否已绑定其他用户；OAuth 是否选择了正在使用 Chat 的同一 Google 账号。
图片或文档未解析是否为用户直接上传而不是 Google Drive 文件；类型是否受支持；是否超过大小、数量或下载超时限制；服务端是否启用了文件接收。
只收到下载链接，没有原生附件管理员是否配置用户 OAuth；用户是否完成“授权文件”；OAuth Token 是否失效；上传失败时系统会自动回退下载链接。
Space 中没有响应是否已开启“加入聊天室和群组对话”；消息是否明确 @机器人；是否已配置并验证群聊空间与默认使用的 Agent/Team。

相关页面与下一步

这篇文档对你有帮助吗？
本页内容