OpenClaw Google Chat 渠道
企业平台
中等
通过 Google Chat API 的 HTTP 端点将 OpenClaw 连接到 Google Chat。此企业级集成让你的 AI 助手可以在 Google Workspace 中运行 — 处理私聊消息和空间（Space）对话。机器人通过接收来自 Google Chat 的 HTTP POST 请求，使用服务账号验证 Bearer 令牌，并通过 OpenClaw Gateway 路由消息。
快速信息
难度中等
分类企业平台
支持功能数5 / 6
Google Chat 支持的功能
文本消息
支持
媒体与文件
支持
消息反应
支持
消息线程
支持
语音消息
不支持
群聊
支持
Google Chat 前置条件
- Google Workspace 账号（Business 或 Enterprise 版本）。域管理员权限可能在授权范围审批和应用可见性设置时需要
- 已启用 Google Chat API 的 Google Cloud 项目
- 已创建服务账号并生成 JSON 密钥文件
- OpenClaw Gateway 已运行并配置
- 可公开访问的 HTTPS 端点用于 Webhook（如 Tailscale Funnel、Caddy 或 Cloudflare Tunnel）
Google Chat 快速设置
1
启用 Google Chat API 并创建服务账号
前往 Google Cloud Console，启用 Google Chat API。创建新的服务账号（如 'openclaw-chat'），跳过权限配置，然后生成并下载 JSON 密钥文件。将文件存储在 Gateway 主机上（如 ~/.openclaw/googlechat-service-account.json）。
2
在 Google Cloud Console 配置 Chat 应用
在 Google Cloud Console 的 Chat 配置页面，设置应用名称、头像 URL 和描述。启用交互式功能，允许应用加入空间和群组对话。选择 'HTTP 端点 URL' 作为连接设置，输入 Gateway 的公网 URL 加上 '/googlechat'（使用 'openclaw status' 查看 Gateway URL）。
3
设置可见性、启用应用并测试
将应用可见性限制为域内的特定用户或群组。保存配置，刷新页面，将应用状态更改为「上线 — 对用户可用」。在 Google Chat 中，点击「私信」旁的「+」图标，搜索你的应用名称，发送测试消息。
Google Chat 配置示例
config.json
{
"channels": {
"googlechat": {
"serviceAccountFile": "~/.openclaw/googlechat-service-account.json",
"webhookPath": "/googlechat"
}
}
}Google Chat 深入了解
架构概述
OpenClaw 通过 HTTP 端点架构与 Google Chat 集成。工作流程如下：
1. Google Chat 向你的 Gateway 端点发送带有 'Authorization: Bearer <token>' 头部的 HTTP POST 请求。
2. OpenClaw 根据配置的受众设置验证 Bearer 令牌。当受众设为 app-url 时，令牌为 OIDC ID token；设为 project-number 时，为自签名 JWT。
3. 消息通过区分私聊和空间的会话密钥进行路由。
4. 默认情况下，私聊使用配对码进行访问控制，群组空间使用 @提及激活。
与基于 WebSocket 的渠道不同，Google Chat 需要一个可公开访问的 HTTPS 端点。Gateway 在配置的端点路径（默认：/googlechat）上监听传入的 POST 请求。
使用 'openclaw status' 查看 Gateway 的公网 URL，用于 Webhook 配置。
服务账号 JSON 密钥文件包含敏感凭据 — 请安全存储并限制文件权限。
服务账号设置
身份验证需要 Google Cloud 服务账号。按以下步骤操作：
1. 前往 Google Cloud Console → IAM 和管理 → 服务账号
2. 点击「创建服务账号」
3. 命名（如 'openclaw-chat'）并跳过可选的权限配置
4. 点击创建的服务账号 → 密钥选项卡 → 添加密钥 → 创建新密钥
5. 选择 JSON 格式并下载密钥文件
6. 将文件放置在 Gateway 主机的安全位置（如 ~/.openclaw/googlechat-service-account.json）
服务账号凭据用于验证来自 Google Chat 的 Webhook 请求，以及通过 Google Chat API 发送出站消息。
openclaw.json
{
"channels": {
"googlechat": {
"serviceAccountFile": "~/.openclaw/googlechat-service-account.json"
}
}
}切勿将服务账号 JSON 密钥文件提交到版本控制。将文件路径添加到 .gitignore，并将文件权限限制为 Gateway 进程用户。
Chat 应用配置
在 Google Cloud Console 中配置 Chat 应用：
1. 进入 Google Cloud Console → API 和服务 → Google Chat API → 配置
2. 设置应用名称、头像 URL 和描述
3. 在「交互式功能」下，启用交互式功能
4. 允许应用加入空间和群组对话
5. 将连接设置选择为「HTTP 端点 URL」
6. 输入 Gateway 的公网 Webhook URL（如 https://your-domain.com/googlechat）
7. 在「可见性」中，限制为域内的特定用户或群组
8. 保存配置，刷新页面，将应用状态设为「上线 — 对用户可用」
注意：私有应用不会出现在 Google Chat 应用市场中。用户需要搜索应用的确切名称才能找到并添加它。
保存配置后，可能需要刷新页面才能看到状态切换开关。
用户通过在 Google Chat 中点击「私信」旁的「+」图标并搜索配置的应用名称来添加机器人。
公网 URL 与 Webhook 配置
Google Chat 需要可公开访问的 HTTPS 端点来发送 Webhook 事件。推荐三种方案：
方案 A — Tailscale Funnel（推荐）：
• 检查 Gateway 绑定地址：ss -tlnp | grep 18789
• 公开暴露 Webhook：tailscale funnel --set-path=/googlechat localhost:18789
• 公网 URL 格式：https://<节点名>.<tailnet>.ts.net/googlechat
方案 B — Caddy 反向代理：
• 仅代理特定路径：reverse_proxy /googlechat* localhost:18789
方案 C — Cloudflare Tunnel：
• 配置入口规则，仅将 /googlechat 路径路由到 Gateway，其他请求返回 404。
无论选择哪种方案，生成的公网 URL 都应输入到 Google Chat 应用配置的 HTTP 端点 URL 中。
终端 / 配置文件
# Tailscale Funnel 示例：
tailscale funnel --set-path=/googlechat localhost:18789
# Caddy 示例：
reverse_proxy /googlechat* localhost:18789
# Cloudflare Tunnel 入口配置：
- hostname: your-domain.com
path: /googlechat
service: http://localhost:18789
- service: http_status:404推荐使用 Tailscale Funnel，因为它自动处理 HTTPS 证书且配置最简单。
仅公开暴露 /googlechat 路径 — 不要将整个 Gateway 暴露到互联网。
私聊与群组策略
OpenClaw 通过私聊和群组策略控制对 Google Chat 机器人的访问：
私聊策略（默认：pairing）：
• pairing — 新联系人需要通过配对流程，使用你在 CLI 中审批的配对码
• allowlist — 仅明确列出的用户可以给机器人发消息
• open — 任何人都可以给机器人发消息（谨慎使用）
群组策略：
• 默认情况下，机器人仅在群组空间中被 @提及时响应
• 可以配置特定空间的允许列表
• 每个空间配置支持自定义系统提示
私聊和空间的访问控制不同：私聊默认使用配对码，空间使用 @提及激活。
openclaw.json
{
"channels": {
"googlechat": {
"dmPolicy": "pairing",
"groupPolicy": "allowlist",
"groupAllowList": ["spaces/AAAA1234"]
}
}
}目标与会话路由
Google Chat 目标用于出站消息和会话标识：
• 私聊消息：users/<userId> 或 users/<email>
• 空间：spaces/<spaceId>
会话密钥区分私聊和空间，确保每个对话拥有独立的上下文。机器人用户标识符（botUser）用于群组空间中的 @提及检测。
你还可以为各个空间配置自定义设置，包括系统提示和访问控制。
openclaw.json
{
"channels": {
"googlechat": {
"botUser": "users/123456789",
"spaces": {
"spaces/AAAA1234": {
"systemPrompt": "你是工程团队的得力助手。"
}
}
}
}
}设置 botUser 字段以在群组空间中启用准确的 @提及检测。
空间 ID 可以在 Google Chat URL 中或 Gateway 日志中收到空间消息时找到。
Google Chat 配置参考
| Key | Type | Default | Description |
|---|---|---|---|
| serviceAccountFile | string | "" | Google Cloud 服务账号 JSON 密钥文件路径 |
| audience | string | "app-url" | Bearer 令牌验证的受众类型。设为 app-url 时，Google Chat 发送 OIDC ID token；设为 project-number 时，发送自签名 JWT。选项：app-url、project-number |
| audienceValue | string | "" | 用于令牌验证的受众值（URL 或项目编号） |
| webhookPath | string | "/googlechat" | 接收 Google Chat Webhook 的 HTTP 端点路径 |
| botUser | string | "" | 机器人用户标识符（users/<id>），用于空间中的 @提及检测 |
| dmPolicy | string | "pairing" | 控制谁可以给机器人发私信。选项：pairing、allowlist、open、disabled |
| allowFrom | string[] | [] | 允许给机器人发消息的用户 ID 或邮箱（dmPolicy 为 allowlist 时生效） |
| groupPolicy | string | "disabled" | 群组空间策略。选项：disabled、allowlist、open |
| groupAllowList | string[] | [] | groupPolicy 为 allowlist 时允许的空间 ID |
| spaces.<id>.systemPrompt | string | "" | 特定 Google Chat 空间的自定义 AI 系统提示 |
| mediaMaxMb | number | 20 | 最大媒体文件大小（兆字节） |
| actions.typing | boolean | true | AI 生成回复时发送输入指示器 |
serviceAccountFile
Type: stringDefault: ""
Google Cloud 服务账号 JSON 密钥文件路径
audience
Type: stringDefault: "app-url"
Bearer 令牌验证的受众类型。设为 app-url 时，Google Chat 发送 OIDC ID token；设为 project-number 时，发送自签名 JWT。选项：app-url、project-number
audienceValue
Type: stringDefault: ""
用于令牌验证的受众值（URL 或项目编号）
webhookPath
Type: stringDefault: "/googlechat"
接收 Google Chat Webhook 的 HTTP 端点路径
botUser
Type: stringDefault: ""
机器人用户标识符（users/<id>），用于空间中的 @提及检测
dmPolicy
Type: stringDefault: "pairing"
控制谁可以给机器人发私信。选项：pairing、allowlist、open、disabled
allowFrom
Type: string[]Default: []
允许给机器人发消息的用户 ID 或邮箱（dmPolicy 为 allowlist 时生效）
groupPolicy
Type: stringDefault: "disabled"
群组空间策略。选项：disabled、allowlist、open
groupAllowList
Type: string[]Default: []
groupPolicy 为 allowlist 时允许的空间 ID
spaces.<id>.systemPrompt
Type: stringDefault: ""
特定 Google Chat 空间的自定义 AI 系统提示
mediaMaxMb
Type: numberDefault: 20
最大媒体文件大小（兆字节）
actions.typing
Type: booleanDefault: true
AI 生成回复时发送输入指示器
Google Chat 常见问题
Google Chat 故障排查
Webhook 上出现 405 Method Not Allowed 错误
Google Chat 插件未启用、channels.googlechat 配置段缺失，或 Gateway 在配置更改后未重启。
验证配置：运行 'openclaw config get channels.googlechat' 检查配置是否存在。运行 'openclaw plugins list | grep googlechat' 验证插件是否激活。使用 'openclaw gateway restart' 重启 Gateway，并用 'openclaw channels status' 检查状态。
身份验证错误或令牌验证失败
服务账号文件路径不正确、受众设置不匹配，或 Bearer 令牌已过期。
运行 'openclaw channels status --probe' 诊断身份验证错误。验证 serviceAccountFile 路径指向有效的 JSON 密钥文件。检查受众类型和值是否与 Google Cloud 项目配置匹配。
机器人不响应空间中的消息
未配置机器人用户标识符用于 @提及检测，或空间不在允许列表中。
在配置中设置 botUser 字段以启用准确的 @提及检测。如果使用 groupPolicy: allowlist，确保空间 ID 已列入 groupAllowList。发送测试消息时使用 'openclaw logs --follow' 检查 Gateway 日志。
Webhook URL 无法从 Google Chat 访问
公网 URL 未正确配置、防火墙阻止了入站连接，或 SSL 证书无效。
验证 Chat 应用的 Webhook URL 与 Gateway 的公网端点匹配。测试 URL 是否可从互联网访问。如使用 Tailscale Funnel，运行 'tailscale funnel status' 验证配置。对于 Caddy 或 Cloudflare，检查反向代理日志。