Google Chat（谷歌聊天）
Google Chat 通道：支持状态、能力与配置
状态：可用于私信（DM）与空间（spaces）。通过 Google Chat API webhooks 接入（仅 HTTP）。
新手快速配置
1. 创建 Google Cloud 项目并启用 Google Chat API：
- 打开：''Google Chat API Credentials''
- 若尚未启用，请先启用 API。
2. 创建 Service Account：
- 点击 Create Credentials > Service Account。
- 名称随意（例如 openclaw-chat）。
- 权限先留空（点击 Continue）。
- 可访问的 principals 留空（点击 Done）。
3. 创建并下载 JSON Key：
- 在 service accounts 列表中点击刚创建的账号。
- 打开 Keys tab。
- 点击 Add Key > Create new key。
- 选择 JSON 并点击 Create。
4. 把下载的 JSON 文件保存到 gateway 主机（例如 ~/.openclaw/googlechat-service-account.json）。
5. 在 ''Google Cloud Console 的 Chat Configuration'' 创建 Google Chat app：
- 填写 Application info：
- App name：（例如 OpenClaw）
- Avatar URL：（例如 https://openclaw.ai/logo.png）
- Description：（例如 Personal AI Assistant）
- 启用 Interactive features。
- 在 Functionality 中勾选 Join spaces and group conversations。
- 在 Connection settings 中选择 HTTP endpoint URL。
- 在 Triggers 中选择 Use a common HTTP endpoint URL for all triggers，并设置为你的 gateway 公网 URL + /googlechat。
- 提示：运行 openclaw status 可以看到你的 gateway 公网 URL（若已配置）。
- In Visibility, check Make this Chat app available to specific people and groups in <Your Domain>.
- 在文本框中输入你的邮箱（例如 [email protected]）。
- 点击页面底部 Save。
6. 启用 App status：
- 保存后 刷新页面。
- 找到 App status（通常保存后会出现在页面上方或下方）。
- 将状态改为 Live - available to users。
- 再点击 Save。
7. 在 OpenClaw 中配置 service account 路径与 webhook audience：
- Env：GOOGLE_CHAT_SERVICE_ACCOUNT_FILE=/path/to/service-account.json
- 或 config：channels.googlechat.serviceAccountFile: "/path/to/service-account.json";。
8. 设置 webhook audience 的 type 与 value（需要与你的 Chat app 配置一致）。
9. 启动 gateway。Google Chat 会向你的 webhook path 发送 POST 请求。
添加到 Google Chat
当 gateway 运行起来、并且你的邮箱已加入 visibility 列表后：
1. 打开 ''Google Chat''。
2. 在 Direct Messages 旁点击 +。
3. 在搜索框里输入你在 Google Cloud Console 里配置的 App name。
- 注意：这是私有 app，不会出现在 "Marketplace" 浏览列表里，只能通过名称搜索。
4. 从结果中选择你的 bot。
5. 点击 Add 或 Chat 开始 1:1 对话。
6. 发送 "Hello" 测试触发。
公网 URL（仅 Webhook）
Google Chat webhooks 需要一个公网可访问的 HTTPS endpoint。为了安全，只把 /googlechat 这一条路径暴露到公网。把 OpenClaw dashboard 与其他敏感端点留在私有网络中。
#
方案 A：Tailscale Funnel（推荐）
使用 Tailscale Serve 托管私有 dashboard，用 Funnel 只公开 webhook path。这样 / 保持私有，只对公网暴露 /googlechat。
1. 检查 gateway 绑定的地址：
`bash
ss -tlnp | grep 18789
`
记录 IP（例如 127.0.0.1、0.0.0.0，或 Tailscale IP：100.x.x.x）。
2. 把 dashboard 仅暴露给 tailnet（端口 8443）：
`bash
# 绑定在 localhost（127.0.0.1 或 0.0.0.0）：
tailscale serve --bg --https 8443 http://127.0.0.1:18789
# 仅绑定在 Tailscale IP（例如 100.106.161.80）：
tailscale serve --bg --https 8443 http://100.106.161.80:18789
`
3. 只把 webhook path 公开到公网：
`bash
# 绑定在 localhost（127.0.0.1 或 0.0.0.0）：
tailscale funnel --bg --set-path /googlechat http://127.0.0.1:18789/googlechat
# 仅绑定在 Tailscale IP（例如 100.106.161.80）：
tailscale funnel --bg --set-path /googlechat http://100.106.161.80:18789/googlechat
`
4. 为该节点授权 Funnel：
若命令提示需要授权，访问输出中的授权 URL，在 tailnet policy 中允许该节点使用 Funnel。
`bash
tailscale serve status
tailscale funnel status
`
公网 webhook URL：
https://<node-name>.<tailnet>.ts.net/googlechat
私有 dashboard（仅 tailnet）：
https://<node-name>.<tailnet>.ts.net:8443/
在 Google Chat app 配置中使用公网 URL（不带 :8443）。
说明
#
方案 B：反向代理（Caddy）
只代理特定路径：
your-domain.com {
reverse_proxy /googlechat* localhost:18789
}这样 your-domain.com/ 会被忽略或返回 404，而 your-domain.com/googlechat 会被安全转发给 OpenClaw。
#
方案 C：Cloudflare Tunnel
把 tunnel 的 ingress 规则设置为只路由 webhook path：
- Path：/googlechat -> http://localhost:18789/googlechat
- Default Rule：HTTP 404（Not Found）
工作方式
1. Google Chat sends a webhook POST to the gateway. Each request includes Authorization: Bearer <token>.
2. OpenClaw 会按配置的 audienceType + audience 校验 token：
- audienceType: "app-url"：audience 为你的 HTTPS webhook URL。
- audienceType: "project-number"：audience 为 Cloud project number。
3. 消息按 space 路由：
- 私信使用会话键 ''agent:''。
- Spaces 使用会话键 ''agent:''。
4. 私信默认 pairing：未知发送者会收到配对码；批准：
- ''openclaw pairing approve googlechat ''''
5. 群空间默认要求 @mention 才回复。如果 mention 检测需要 app 的用户名，可配置 botUser。
投递目标（Targets）
用于投递与 allowlists 的标识符：
- 私信：''users/'' 或 ''users/''（支持邮箱）
- Spaces：''spaces/''
配置要点
{
channels: {
googlechat: {
enabled: true,
serviceAccountFile: "/path/to/service-account.json",
audienceType: "app-url",
audience: "https://gateway.example.com/googlechat",
webhookPath: "/googlechat",
botUser: "users/1234567890",
dm: {
policy: "pairing",
allowFrom: ["users/1234567890", "[email protected]"],
},
groupPolicy: "allowlist",
groups: {
"spaces/AAAA": {
allow: true,
requireMention: true,
users: ["users/1234567890"],
systemPrompt: "Short answers only.",
},
},
actions: { reactions: true },
typingIndicator: "message",
mediaMaxMb: 20,
},
},
}说明：
- Service account 凭据也可以通过 serviceAccount 以内联 JSON 字符串提供。
- 未设置 webhookPath 时默认使用 /googlechat。
- 当 actions.reactions 启用时，可通过 reactions 工具与 channels action 使用 reactions。
- typingIndicator 支持 none、message（默认）、reaction（reaction 需要 user OAuth）。
- 附件会通过 Chat API 下载并进入媒体流水线（大小受 mediaMaxMb 限制）。
排障
#
405 Method Not Allowed
如果 Google Cloud Logs Explorer 出现类似错误：
status code: 405, reason phrase: HTTP error response: HTTP/1.1 405 Method Not Allowed
这通常意味着 webhook handler 没有注册。常见原因：
1. 通道未配置：配置中缺少 channels.googlechat。验证：
__CODE_BLOCK_1__bash
openclaw channels status
`
#
其他问题
- 运行 openclaw channels status --probe 检查鉴权错误或 audience 配置缺失。
- 如果没有消息到达，确认 Chat app 的 webhook URL 与事件订阅。
- 如果 mention 门禁挡住回复，设置 botUser 为 app 的 user resource name，并核对 requireMention。
- 发送测试消息时运行 openclaw logs --follow，确认请求是否到达 gateway。
相关文档：
- ''Security''
- ''Reactions''