Google Chat (Chat API)

状态：已支持通过 Google Chat API Webhook（仅 HTTP）实现 DM 和群组空间功能。

快速设置（新手向）

1. 创建 Google Cloud 项目并启用 Google Chat API。
   • 访问：Google Chat API Credentials
   • 如果 API 尚未启用，先启用它。
2. 创建 Service Account（服务账号）：
   • 点击 Create Credentials > Service Account。
   • 随便起个名字（比如 openclaw-chat）。
   • 权限留空（点击 Continue）。
   • 访问主体留空（点击 Done）。
3. 创建并下载 JSON Key（密钥文件）：
   • 在服务账号列表中，点击刚创建的那个。
   • 进入 Keys 标签页。
   • 点击 Add Key > Create new key。
   • 选择 JSON 并点击 Create。
4. 把下载的 JSON 文件保存到 Gateway 主机上（比如 ~/.openclaw/googlechat-service-account.json）。
5. 在 Google Cloud Console Chat Configuration 创建 Google Chat 应用：
   • 填写 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。
   • 在 Visibility 下，勾选 Make this Chat app available to specific people and groups in <Your Domain>（让此应用对特定人员和群组可用）。
   • 在文本框中输入你的邮箱地址（比如 [email protected]）。
   • 点击底部的 Save。
6. 启用应用状态：
   • 保存后，刷新页面。
   • 找到 App status 部分（通常在保存后的顶部或底部）。
   • 将状态改为 Live - available to users（上线 - 对用户可用）。
   • 再次点击 Save。
7. 配置 OpenClaw 的服务账号路径和 Webhook audience：
   • 环境变量：GOOGLE_CHAT_SERVICE_ACCOUNT_FILE=/path/to/service-account.json
   • 或配置文件：channels.googlechat.serviceAccountFile: "/path/to/service-account.json"。
8. 设置 Webhook audience 类型和值（与你的 Chat 应用配置匹配）。
9. 启动 Gateway。Google Chat 会向你的 Webhook 路径发送 POST 请求。

添加到 Google Chat

Gateway 运行后，且你的邮箱已添加到可见性列表：

1. 访问 Google Chat。
2. 点击 Direct Messages 旁边的 +（加号）图标。
3. 在搜索栏（通常用来添加联系人的地方）输入你在 Google Cloud Console 配置的 App name（应用名称）。
   • 注意：这个机器人不会出现在”Marketplace”浏览列表中，因为它是私有应用。你必须按名称搜索。
4. 从结果中选择你的机器人。
5. 点击 Add 或 Chat 开始一对一对话。
6. 发送”Hello”来触发助手！

公网 URL（仅 Webhook）

Google Chat Webhook 需要公网 HTTPS 端点。为了安全，只暴露 /googlechat 路径到互联网。把 OpenClaw 控制面板和其他敏感端点保留在私有网络中。

方案 A：Tailscale Funnel（推荐）

用 Tailscale Serve 提供私有控制面板，用 Funnel 提供公网 Webhook 路径。这样可以保持 / 私有，只暴露 /googlechat。

1. 检查 Gateway 绑定的地址：

   ss -tlnp | grep 18789

   记下 IP 地址（比如 127.0.0.1、0.0.0.0 或你的 Tailscale IP 如 100.x.x.x）。

2. 只向 tailnet 暴露控制面板（端口 8443）：

   # 如果绑定到 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 路径：

   # 如果绑定到 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 策略中为此节点启用 Funnel。

5. 验证配置：

   tailscale serve status
   tailscale funnel status

你的公网 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）

如果你使用 Caddy 等反向代理，只代理特定路径：

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

这样配置后，任何对 your-domain.com/ 的请求会被忽略或返回 404，而 your-domain.com/googlechat 会安全地路由到 OpenClaw。

方案 C：Cloudflare Tunnel

配置 tunnel 的入站规则，只路由 Webhook 路径：

• Path：/googlechat -> http://localhost:18789/googlechat
• Default Rule：HTTP 404 (Not Found)

工作原理

1. Google Chat 向 Gateway 发送 Webhook POST 请求。每个请求包含 Authorization: Bearer <token> 头。
2. OpenClaw 根据配置的 audienceType 和 audience 验证 token：
   • audienceType: "app-url" → audience 是你的 HTTPS Webhook URL。
   • audienceType: "project-number" → audience 是 Cloud 项目编号。
3. 消息按空间路由：
   • DM 使用 Session 键 agent:<agentId>:googlechat:dm:<spaceId>。
   • 群组空间使用 Session 键 agent:<agentId>:googlechat:group:<spaceId>。
4. DM 访问默认需要 Pairing。未知发送者会收到配对码；用以下命令批准：
   • openclaw pairing approve googlechat <code>
5. 群组空间默认需要 @-提及。如果提及检测需要应用的用户名，使用 botUser。

目标标识符

用于消息投递和白名单的标识符：

• 私信：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,
    },
  },
}

说明：

• 服务账号凭据也可以用 serviceAccount（JSON 字符串）内联传递。
• 如果没设置 webhookPath，默认 Webhook 路径是 /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 处理器未注册。常见原因：

1. Channel 未配置：配置中缺少 channels.googlechat 部分。验证：

   openclaw config get channels.googlechat

   如果返回”Config path not found”，添加配置（参见配置要点）。

2. Plugin 未启用：检查 Plugin 状态：

   openclaw plugins list | grep googlechat

   如果显示”disabled”，在配置中添加 plugins.entries.googlechat.enabled: true。

3. Gateway 未重启：添加配置后，重启 Gateway：

   openclaw gateway restart

验证 Channel 正在运行：

openclaw channels status
# 应该显示：Google Chat default: enabled, configured, ...

其他问题

• 运行 openclaw channels status --probe 检查认证错误或缺失的 audience 配置。
• 如果没有消息到达，确认 Chat 应用的 Webhook URL 和事件订阅。
• 如果提及限制阻止回复，将 botUser 设置为应用的用户资源名称并验证 requireMention。
• 发送测试消息时运行 openclaw logs --follow，查看请求是否到达 Gateway。

相关文档：

• Gateway 配置
• 安全
• 表情回应