8.7 Google Chat集成 - OpenClaw中文社区

Google Chat（Chat API）已可用于私聊和空间（spaces），通过 HTTP webhook 接入。

状态：支持 DM + Spaces（仅 Webhook/HTTP）。

快速开始（新手）

创建 Google Cloud 项目并启用 Google Chat API。
- 入口：Google Chat API Credentials
- 如果未启用 API，请先启用。
创建 Service Account：
- 点击 Create Credentials > Service Account
- 名称随意（例如 openclaw-chat）
- 权限留空（Continue）
- 访问主体留空（Done）
创建并下载 JSON Key：
- 在 Service Account 列表中点击刚创建的账号
- 进入 Keys 标签
- Add Key > Create new key
- 选择 JSON 并创建
把下载的 JSON 放到网关主机（例如 ~/.openclaw/googlechat-service-account.json）。
在 Google Cloud Console 创建 Google Chat 应用：
- 填写应用信息（名称、头像 URL、描述）
- 启用 Interactive features
- Functionality 勾选 Join spaces and group conversations
- Connection settings 选择 HTTP endpoint URL
- Triggers 选择使用单一 HTTP endpoint，并填入网关的公网 URL + /googlechat
- Visibility 选择仅在域内可见，填入你的邮箱
- 保存
启用应用：保存后刷新页面，把 App status 改为 Live，然后再次保存。
配置 OpenClaw 的 service account 路径 + audience：
- 环境变量：GOOGLE_CHAT_SERVICE_ACCOUNT_FILE=/path/to/service-account.json
- 或配置：channels.googlechat.serviceAccountFile
设置 webhook audience（与 Chat app 配置一致）。
启动 Gateway，Google Chat 会向你的 webhook 发 POST。

添加到 Google Chat

打开 Google Chat。
在 Direct Messages 旁点击 “+”。
在搜索框输入你在控制台配置的 App 名称。
注意：这是私有应用，不会显示在 Marketplace，需要按名称搜索。
选择你的 bot，点击 Add 或 Chat 开始对话。
发送 “Hello” 触发回复。

公网 URL（仅 Webhook）

Google Chat 的 webhook 需要公网 HTTPS 入口。为安全起见，只暴露 /googlechat 路径，把 Dashboard 等敏感路径留在内网。

方案 A：Tailscale Funnel（推荐）

用 Tailscale Serve 暴露私有 Dashboard，用 Funnel 仅暴露 /googlechat。

确认网关绑定地址：
```
ss -tlnp | grep 18789
```
记录 IP（如 127.0.0.1、0.0.0.0 或 100.x.x.x）。

把 Dashboard 暴露给 tailnet（8443）：

# 绑定到 localhost
  tailscale serve --bg --https 8443 http://127.0.0.1:18789

  # 绑定到 Tailscale IP
  tailscale serve --bg --https 8443 http://100.106.161.80:18789

仅公开 webhook 路径：

# 绑定到 localhost
  tailscale funnel --bg --set-path /googlechat http://127.0.0.1:18789/googlechat
  # 绑定到 Tailscale IP
  tailscale funnel --bg --set-path /googlechat http://100.106.161.80:18789/googlechat

若提示授权，请在输出的 URL 中授权该节点使用 Funnel。

检查状态：

tailscale serve status
  tailscale funnel status

公网 URL：https://<node-name>.<tailnet>.ts.net/googlechat；私有 Dashboard：https://<node-name>.<tailnet>.ts.net:8443/。在 Chat 应用配置中使用公网 URL（不要带 :8443）。

注意：该配置会持久化。清理用 tailscale funnel reset 与 tailscale serve reset。

方案 B：反向代理（Caddy）

只代理指定路径：

your-domain.com {
    reverse_proxy /googlechat* localhost:18789
}

这样 / 会返回 404，/googlechat 才会转发到 OpenClaw。

方案 C：Cloudflare Tunnel

在 ingress 中只路由 webhook 路径：

Path：/googlechat → http://localhost:18789/googlechat
Default Rule：HTTP 404

工作原理

Google Chat 以 webhook POST 请求 Gateway，携带 Authorization: Bearer <token>。
OpenClaw 校验 token（基于 audienceType + audience）：
- audienceType: "app-url" → audience 为你的 webhook URL
- audienceType: "project-number" → audience 为 Cloud 项目编号
消息按 space 路由：
- DM 使用 agent:<agentId>:googlechat:dm:<spaceId>
- Space 使用 agent:<agentId>:googlechat:group:<spaceId>
DM 默认 pairing：未知用户会拿到配对码，审批：openclaw pairing approve googlechat <code>
Space 默认要求 @ 提及；可用 botUser 辅助提及识别。

Targets

用于投递与 allowlist 的目标格式：

私聊：users/<userId> 或 users/<email>（接受邮箱）
空间：spaces/<spaceId>

配置要点

{
  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 调用反应。
typingIndicator 支持 none、message（默认）与 reaction（reaction 需用户 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 未注册。常见原因：

未配置 channels.googlechat：
```
openclaw config get channels.googlechat
```
若返回 “Config path not found”，请按“配置要点”添加配置。
插件未启用：
```
openclaw plugins list | grep googlechat
```
若显示 disabled，请在配置中设置 plugins.entries.googlechat.enabled: true。
未重启 Gateway：
```
openclaw gateway restart
```
验证频道状态：openclaw channels status

其他问题

运行 openclaw channels status --probe 检查认证/ audience 配置。
无消息：确认 Chat app 的 webhook URL + 事件订阅。
提及门槛导致不响应：设置 botUser 并检查 requireMention。
用 openclaw logs --follow 观察是否有请求到达 Gateway。