Google Chat

状态：已准备好，通过 Google Chat API webhook 支持私聊 (DMs) + 空间 (Spaces)（仅限 HTTP）。

1. 创建一个 Google Cloud 项目并启用 Google Chat API。
   • 前往：Google Chat API 凭据
   • 如果尚未启用，请启用该 API。
2. 创建一个 服务账号 (Service Account)：
   • 点击 创建凭据 (Create Credentials) > 服务账号 (Service Account)。
   • 随意命名（例如 openclaw-chat）。
   • 权限留空（点击 继续 (Continue)）。
   • 拥有访问权限的主体留空（点击 完成 (Done)）。
3. 创建并下载 JSON 密钥 (JSON Key)：
   • 在服务账号列表中，点击你刚刚创建的账号。
   • 转到 密钥 (Keys) 选项卡。
   • 点击 添加密钥 (Add Key) > 创建新密钥 (Create new key)。
   • 选择 JSON 并点击 创建 (Create)。
4. 将下载的 JSON 文件存储在你的网关主机上（例如 ~/.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 端点 URL (HTTP endpoint URL)。
   • 在 触发器 (Triggers) 下，选择 为所有触发器使用通用的 HTTP 端点 URL 并将其设置为你的网关公共 URL，后跟 /googlechat。
     • 提示：运行 openclaw status 查找你的网关公共 URL。
   • 在 可见性 (Visibility) 下，勾选 让此 Chat 应用对 <Your Domain> 中的特定人员和群组可用。
   • 在文本框中输入你的电子邮件地址（例如 user@example.com）。
   • 点击底部的 保存 (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 受众类型 + 值（与你的 Chat 应用配置匹配）。
9. 启动网关。Google Chat 将 POST 到你的 webhook 路径。

一旦网关运行并且你的电子邮件已添加到可见性列表：

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

Google Chat webhooks 需要公共 HTTPS 端点。为了安全起见，仅将 /googlechat 路径暴露给互联网。将 OpenClaw 仪表板和其他敏感端点保留在你的私有网络上。

使用 Tailscale Serve 用于私有仪表板，使用 Funnel 用于公共 webhook 路径。这保持 / 私有，同时仅暴露 /googlechat。

1. 检查你的网关绑定到什么地址：

   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。

如果你使用像 Caddy 这样的反向代理，仅代理特定路径：

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

使用此配置，对 your-domain.com/ 的任何请求都将被忽略或返回 404，而 your-domain.com/googlechat 被安全地路由到 OpenClaw。

配置你的隧道入口规则以仅路由 webhook 路径：

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

1. Google Chat 发送 webhook POST 请求到网关。每个请求包含一个 Authorization: Bearer <token> 标头。
2. OpenClaw 针对配置的 audienceType + audience 验证令牌：
   • audienceType: "app-url" → audience 是你的 HTTPS webhook URL。
   • audienceType: "project-number" → audience 是 Cloud 项目编号。
3. 消息按空间路由：
   • 私聊 (DMs) 使用会话密钥 agent:<agentId>:googlechat:dm:<spaceId>。
   • 空间 (Spaces) 使用会话密钥 agent:<agentId>:googlechat:group:<spaceId>。
4. DM 访问默认是配对。未知发送者会收到配对码；批准使用：
   • 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", "name@example.com"]
      },
      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 限制）。

如果 Google Cloud Logs Explorer 显示如下错误：

status code: 405, reason phrase: HTTP error response: HTTP/1.1 405 Method Not Allowed

这意味着 webhook 处理程序未注册。常见原因：

1. 通道未配置：你的配置中缺少 channels.googlechat 部分。验证方式：

   openclaw config get channels.googlechat

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

2. 插件未启用：检查插件状态：

   openclaw plugins list | grep googlechat

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

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

   openclaw gateway restart

验证通道正在运行：

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

• 检查 openclaw channels status --probe 以查找身份验证错误或缺少的受众配置。
• 如果没有收到消息，请确认 Chat 应用的 webhook URL + 事件订阅。
• 如果提及门控阻止了回复，请将 botUser 设置为应用的用户资源名称并验证 requireMention。
• 发送测试消息时使用 openclaw logs --follow 查看请求是否到达网关。

相关文档：

• 网关配置
• 安全性
• 回应 (Reactions)