Google Chat
Google Chat 以官方 @openclaw/googlechat 插件形式运行:通过 Google Chat API webhook 处理私信和空间(仅 HTTP 端点,不使用 Pub/Sub)。
安装¶
本地检出(从 git 仓库运行时):
快速设置(初学者)¶
- 创建 Google Cloud 项目并启用 Google Chat API。
- 前往:Google Chat API 凭据
- 如果 API 尚未启用,请启用它。
- 创建 服务账号:
- 点击 创建凭据 > 服务账号。
- 名称可任意设置(例如
openclaw-chat)。 - 权限和主体留空(点击 继续,然后 完成)。
- 创建并下载 JSON 密钥:
- 点击新建的服务账号 > 密钥 选项卡 > 添加密钥 > 创建新密钥 > JSON > 创建。
- 将下载的 JSON 文件保存在网关主机上(例如
~/.openclaw/googlechat-service-account.json)。 - 在 Google Cloud Console 的 Chat 配置 中创建 Google Chat 应用:
- 填写 应用信息(应用名称、头像 URL、描述)。
- 启用 交互式功能。
- 在 功能 下,勾选 加入空间和群聊。
- 在 连接设置 下,选择 HTTP 端点 URL。
- 在 触发器 下,选择 为所有触发器使用通用 HTTP 端点 URL,并将其设置为你的公共网关 URL 后跟
/googlechat(参见 公共 URL)。 - 在 可见性 下,勾选 将此 Chat 应用提供给
<Your Domain>中的特定人员和群组,并输入你的电子邮件地址。 - 点击 保存。
- 启用应用状态:刷新页面,找到 应用状态,将其设置为 已上线 - 可供用户使用,并再次 保存。
- 使用服务账号和 webhook 受众配置 OpenClaw(必须与 Chat 应用配置匹配):
- 环境变量:
GOOGLE_CHAT_SERVICE_ACCOUNT_FILE=/path/to/service-account.json(仅限默认账号),或 - 配置:参见 配置要点。
openclaw channels add --channel googlechat还支持--audience-type、--audience、--webhook-path和--webhook-url。 - 启动网关。Google Chat 会向你的 webhook 路径发送 POST 请求(默认
/googlechat)。
添加到 Google Chat¶
当网关正在运行且你的电子邮件在可见性列表中时:
- 前往 Google Chat。
- 点击 直接消息 旁边的 +(加号)图标。
- 搜索你在 Google Cloud Console 中配置的 应用名称。
- 该机器人 不 会出现在 Marketplace 浏览列表中,因为这是一个私有应用。请按名称搜索。
- 选择该机器人,点击 添加 或 聊天,然后发送一条消息。
公共 URL(仅 Webhook)¶
Google Chat webhook 需要一个公共 HTTPS 端点。出于安全考虑,仅将 /googlechat 路径 暴露到互联网,并保持 OpenClaw 仪表板和其他端点为私有。
选项 A:Tailscale Funnel(推荐)¶
使用 Tailscale Serve 处理私有仪表板,使用 Funnel 处理公共 webhook 路径。
- 检查网关绑定到哪个地址:
记下 IP(例如 127.0.0.1、0.0.0.0 或 Tailscale 100.x.x.x 地址)。
- 仅将仪表板暴露到 tailnet(端口 8443):
# If bound to localhost (127.0.0.1 or 0.0.0.0):
tailscale serve --bg --https 8443 http://127.0.0.1:18789
# If bound to a Tailscale IP only:
tailscale serve --bg --https 8443 http://100.x.x.x:18789
- 仅将 webhook 路径公开暴露:
# If bound to localhost (127.0.0.1 or 0.0.0.0):
tailscale funnel --bg --set-path /googlechat http://127.0.0.1:18789/googlechat
# If bound to a Tailscale IP only:
tailscale funnel --bg --set-path /googlechat http://100.x.x.x:18789/googlechat
-
如果提示,请访问输出中显示的授权 URL,以为此节点启用 Funnel。
-
验证:
你的公共 webhook URL 是 https://<node-name>.<tailnet>.ts.net/googlechat。仪表板仍仅限 tailnet 访问,地址为 https://<node-name>.<tailnet>.ts.net:8443/。在 Google Chat 应用配置中使用公共 URL(不带 :8443)。
注意:此配置在重启后仍会保留。之后可使用
tailscale funnel reset和tailscale serve reset移除。
选项 B:反向代理(Caddy)¶
仅代理 webhook 路径:
对 your-domain.com/ 的请求会被忽略或返回 404,而 your-domain.com/googlechat 会路由到 OpenClaw。
选项 C:Cloudflare Tunnel¶
配置隧道入口规则,仅路由 webhook 路径:
- 路径:
/googlechat->http://localhost:18789/googlechat - 默认规则:HTTP 404(未找到)
工作原理¶
- Google Chat 向网关 webhook 路径 POST JSON(仅 POST,要求 JSON 内容类型,按 IP 限流)。
- OpenClaw 在分发前对每个请求进行身份验证:
- Chat 应用事件携带
Authorization: Bearer <token>。在解析完整请求体之前会先验证该 token。 - Google Workspace Add-on 事件在请求体中携带 token(
authorizationEventObject.systemIdToken)。OpenClaw 在验证前以更严格的预认证预算(16 KB、3 秒)读取它们。 - 该 token 会根据
audienceType+audience进行检查: audienceType: "app-url"→ audience 是你的 HTTPS webhook URL。audienceType: "project-number"→ audience 是 Cloud 项目编号。app-url下的 Add-on token 还要求将appPrincipal设置为应用的数字 OAuth 2.0 客户端 ID(21 位数字,不是电子邮件)。否则验证会失败并记录警告。- 消息按空间路由:
- 空间获得按空间划分的会话
agent:<agentId>:googlechat:group:<spaceId>。当replyToMode: "first"或"all"时,自动回复会保留在入站线程中。默认模式和显式"off"模式都会让回复保持为顶级,无论是否启用输入指示器。 - 私信默认合并到代理的主会话中。设置
session.dmScope可为每个对端创建私信会话(参见 会话)。 - 私信访问默认使用配对。未知发送者会收到配对码。使用以下命令批准:
openclaw pairing approve googlechat <code>- 群空间默认需要 @提及。提及通过指向该应用的 Chat
USER_MENTION注释检测。如果检测需要应用的用户资源名称,请设置botUser(例如users/1234567890)。 - 当 exec 或插件审批从 Google Chat 发起,并且已配置稳定的
users/<id>审批者时,OpenClaw 会在源空间或线程中发布原生审批卡片(cardsV2)。卡片按钮携带不透明回调 token。仅当原生投递不可用时,才会出现手动/approve <id> <decision>提示。
入站持久性¶
请求身份验证后,OpenClaw 会从存储中移除附加组件授权对象,并在返回 200 之前将 Google Chat MESSAGE 事件持久化入队。持久化失败会返回 503,使 Google Chat 能够重试,而不是确认一个可能丢失的事件。持久化入队的 200 会携带 x-openclaw-delivery-accepted: durable。非消息操作的确认和错误响应会省略该标记,因此反向代理可以要求该标记,以区分持久化接受和普通的 200。
待处理或可重试的消息会在 Gateway 重启后保留,按空间保持串行化,并使用 Google Chat 消息资源名称来抑制重复队列条目,只要活动或保留的完成记录存在。非消息操作保留其现有的分离 webhook 路径,并且不会获得此持久化队列保证。在队列到代理的边界上,投递仍保持至少一次,因此交接期间的崩溃可能会重放一轮对话。
目标¶
使用这些标识符进行投递和允许列表:
- 直接消息:
users/<userId>(推荐)。 - 空间:
spaces/<spaceId>。 - 原始电子邮件
name@example.com是可变的,仅当channels.googlechat.dangerouslyAllowNameMatching: true时用于允许列表匹配。 - 已弃用:
users/<email>被视为用户 ID,而不是电子邮件允许列表条目。 - 前缀
googlechat:、google-chat:和gchat:会被接受并移除。
配置要点¶
{
channels: {
googlechat: {
enabled: true,
serviceAccountFile: "/path/to/service-account.json",
// or serviceAccount: { 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,
dmPolicy: "pairing",
allowFrom: ["users/1234567890"],
groupPolicy: "allowlist",
groups: {
"spaces/AAAA": {
enabled: true,
requireMention: true,
users: ["users/1234567890"],
systemPrompt: "Short answers only.",
},
},
typingIndicator: "message",
mediaMaxMb: 20,
},
},
}
说明:
- 服务账号凭据:
serviceAccountFile(路径)或serviceAccount(内联 JSON 字符串、对象,或 env/file/exec/store SecretRef)。环境变量GOOGLE_CHAT_SERVICE_ACCOUNT(内联 JSON)和GOOGLE_CHAT_SERVICE_ACCOUNT_FILE(路径)仅适用于默认账号。多账号设置使用channels.googlechat.accounts.<id>,并采用相同的键,包括每个账号的serviceAccountSecretRef。 - 省略的账号
dmPolicy和groupPolicy继承频道根。显式账号策略优先。根默认分别为pairing和allowlist。来自accounts.default的共享设置的优先级低于根。其凭据、enabled和dangerouslyAllowNameMatching不会被命名账号继承。 - 当
webhookPath未设置时,默认 webhook 路径为/googlechat。webhookUrl可以代替提供路径。 - 组键必须是稳定的空间 ID(
spaces/<spaceId>)。显示名称键已弃用,并会记录日志。 dangerouslyAllowNameMatching重新启用允许列表的可变电子邮件主体匹配(紧急兼容模式)。Doctor 会警告电子邮件条目。- Google Chat 反应操作未公开。该插件使用服务账号身份验证,而 Google Chat 反应端点需要用户身份验证。使用
openclaw doctor --fix移除不支持的旧版反应设置。 - 原生审批卡片使用 Google Chat
cardsV2按钮点击,而不是反应事件。审批者来自allowFrom或defaultTo,并且必须是稳定的数字users/<id>值。 - 消息操作仅公开文本
send。Google Chat 附件上传需要用户身份验证,而此插件使用服务账号身份验证,因此未公开出站文件上传。 typingIndicator:message(默认)发布_<Bot> is typing..._占位符,并将其编辑为第一条回复。none禁用它。reaction需要用户 OAuth,目前在服务账号身份验证下回退到message并记录错误。- OpenClaw 通过 Chat API 将每条消息的第一个入站附件下载到媒体管道中。
mediaMaxMb限制该下载(默认 20)。Google Drive 文件不会被下载。代理会收到一个附件不可用通知,要求改为直接上传文件。其他不支持的附件来源会收到相同的上传指导。包含多个附件的消息会包含一个计数通知,说明未处理的额外附件。超大附件会保留其大小限制通知。 - 默认情况下,机器人创建的消息会被忽略。使用
allowBots: true时,接受的机器人消息使用共享 机器人循环保护:配置channels.defaults.botLoopProtection,然后使用channels.googlechat.botLoopProtection或channels.googlechat.groups.<space>.botLoopProtection覆盖。
自定义表情符号列表不可用,因为 Google Chat 的 customEmojis.list 端点需要使用 chat.customemojis 或 chat.customemojis.readonly 范围进行用户身份验证。此插件仅以服务账号身份验证,具有 chat.bot 范围,无法访问该端点。
密钥引用详情:密钥管理。
故障排查¶
405 方法不允许¶
如果 Google Cloud Logs Explorer 显示如下错误:
webhook 处理程序未注册。常见原因:
- 频道未配置:缺少
channels.googlechat部分。使用以下命令验证:
如果返回 "Config path not found",请添加配置(参见 配置要点)。
- 插件未启用:检查插件状态:
如果显示 "disabled",请运行 openclaw plugins enable googlechat,并检查 应用结果。
- 配置未应用:检查 热重载 状态和 Gateway 日志。如果 Gateway 离线,请启动 Gateway。如果更改了服务环境,请重启 Gateway 以加载更改。
验证通道是否正在运行:
其他问题¶
openclaw channels status --probe会显示认证错误和缺失的 audience 配置(audience和audienceType均为必填项)。- 如果没有收到消息,请确认 Chat 应用的 webhook URL 和触发器配置。
- 如果提及门控阻止了回复,请将
botUser设置为应用的用户资源名称,并检查requireMention。 - 在发送测试消息时运行
openclaw logs --follow,可查看请求是否到达 gateway。
相关¶
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw