Google Chat（Chat API）

状态：通过 Google Chat API webhook（仅 HTTP）支持私信和空间。

快速开始

  1. 创建 Google Cloud 项目并启用 Google Chat API。
  2. 创建服务账号：
    • 点击 Create Credentials > Service Account。
    • 名称随意（如 openclaw-chat）。
    • 权限留空（点 Continue）。
    • 主体访问权限留空（点 Done）。
  3. 创建并下载 JSON 密钥：
    • 在服务账号列表中，点击刚创建的账号。
    • 进入 Keys 页签。
    • 点击 Add Key > Create new key。
    • 选择 JSON 并点击 Create。
  4. 将下载的 JSON 文件存放在 Gateway 主机上（如 ~/.openclaw/googlechat-service-account.json）。
  5. 在 Google Cloud Console Chat 配置 中创建 Google Chat 应用：
    • 填写应用信息：
      • 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. 使用服务账号路径 + webhook 受众配置 OpenClaw：
    • 环境变量：GOOGLE_CHAT_SERVICE_ACCOUNT_FILE=/path/to/service-account.json
    • 或配置：channels.googlechat.serviceAccountFile: "/path/to/service-account.json"。
  8. 设置 webhook 受众类型和值（与 Chat 应用配置匹配）。
  9. 启动 Gateway。Google Chat 将向你的 webhook 路径发送 POST 请求。

添加到 Google Chat

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

  1. 前往 Google Chat。
  2. 点击直接消息旁的 +（加号）图标。
  3. 在搜索栏中输入你在 Google Cloud Console 配置的应用名称。
    • 注意：该机器人不会出现在”市场”浏览列表中，因为它是私有应用。你必须按名称搜索。
  4. 从结果中选择你的机器人。
  5. 点击 Add 或 Chat 开始一对一对话。
  6. 发送”Hello”触发助手！

公网 URL（仅 Webhook）

Google Chat webhook 需要公网 HTTPS 端点。出于安全考虑，仅暴露 /googlechat 路径到公网，Dashboard 和其他敏感端点保留在内网。

方案 A：Tailscale Funnel（推荐）

使用 Tailscale Serve 托管私有 Dashboard，使用 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. 将 Dashboard 仅暴露给 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，为该节点启用 Funnel。

  5. 验证配置：

    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 应用配置中使用公开 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

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

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

工作原理

  1. Google Chat 向 Gateway 发送 webhook POST 请求。每个请求都包含 Authorization: Bearer <token> 头。
    • OpenClaw 在存在该头时，会在读取/解析完整 webhook 请求体前先验证 Bearer 认证。
    • 在请求体中携带 authorizationEventObject.systemIdToken 的 Google Workspace 插件请求通过更严格的预认证请求体预算得到支持。
  2. OpenClaw 根据配置的 audienceType + audience 验证令牌：
    • audienceType: "app-url" -> 受众为你的 HTTPS webhook URL。
    • audienceType: "project-number" -> 受众为 Cloud 项目编号。
  3. 消息按空间路由：
    • 私信使用会话键 agent:<agentId>:googlechat:direct:<spaceId>。
    • 空间使用会话键 agent:<agentId>:googlechat:group:<spaceId>。
  4. 私信默认使用配对模式。未知发送者收到配对码；审批命令：
    • openclaw pairing approve googlechat <code>
  5. 群组空间默认需要 @提及。如果提及检测需要应用的用户名，请使用 botUser。

目标格式

在投递和白名单中使用以下标识符：

  • 私信：users/<userId>（推荐）。
  • 原始邮箱 [email protected] 是可变的，仅在 channels.googlechat.dangerouslyAllowNameMatching: true 时用于直接白名单匹配。
  • 已弃用：users/<email> 被视为用户 ID 而非邮箱白名单。
  • 空间：spaces/<spaceId>。

配置要点

{
  channels: {
    googlechat: {
      enabled: true,
      serviceAccountFile: "/path/to/service-account.json",
      // 或 serviceAccountRef: { source: "file", provider: "filemain", id: "/channels/googlechat/serviceAccount" }
      audienceType: "app-url",
      audience: "https://gateway.example.com/googlechat",
      webhookPath: "/googlechat",
      botUser: "users/1234567890", // 可选；辅助提及检测
      dm: {
        policy: "pairing",
        allowFrom: ["users/1234567890"],
      },
      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 字符串）内联传递。
  • 同时支持 serviceAccountRef（env/file SecretRef），包括 channels.googlechat.accounts.<id>.serviceAccountRef 的按账户引用。
  • 如未设置 webhookPath，默认 webhook 路径为 /googlechat。
  • dangerouslyAllowNameMatching 重新启用可变的邮箱主体匹配（应急兼容模式）。
  • 启用 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. 频道未配置：配置中缺少 channels.googlechat 部分。验证方法：

    openclaw config get channels.googlechat

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

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

    openclaw plugins list | grep googlechat

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

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

    openclaw gateway restart

验证频道是否在运行：

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

其他问题

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

相关文档：

arrow_back
上一页
Feishu
下一页
Imessage
arrow_forward