文档
渠道（Channels）
Google Chat (Chat API)

Google Chat (Chat API)

适用范围

在以下情况使用此页面：

  • 在 Google Chat 通道功能上工作

状态：通过 Google Chat API webhooks（仅 HTTP）支持 DM + 空间。

快速设置（初学者）

  1. 创建一个 Google Cloud 项目并启用 Google Chat API。
  2. 创建服务帐户：
    • 按创建凭据 > 服务帐户。
    • 随意命名（例如，moltbot-chat）。
    • 将权限留空（按继续）。
    • 将具有访问权限的主体留空（按完成）。
  3. 创建并下载 JSON 密钥：
    • 在服务帐户列表中，单击您刚刚创建的帐户。
    • 转到密钥选项卡。
    • 单击添加密钥 > 创建新密钥。
    • 选择 JSON 并按创建。
  4. 将下载的 JSON 文件存储在网关主机上（例如，~/.moltbot/googlechat-service-account.json）。
  5. 在 Google Cloud Console Chat Configuration 中创建 Google Chat 应用：
    • 填写应用程序信息：
      • 应用名称：（例如 Moltbot）
      • 头像 URL：（例如 https://clawd.bot/logo.png）
      • 描述：（例如 Personal AI Assistant）
    • 启用交互式功能。
    • 在功能下，检查加入空间和群组对话。
    • 在连接设置下，选择 HTTP 端点 URL。
    • 在触发器下，选择为所有触发器使用通用 HTTP 端点 URL并将其设置为网关的公共 URL 后跟 /googlechat。
      • 提示：运行 moltbot status 以查找网关的公共 URL。
    • 在可见性下，检查使此 Chat 应用程序对 <您的域> 中的特定人员和组可用。
    • 在文本框中输入您的电子邮件地址（例如 [email protected]）。
    • 单击底部的保存。
  6. 启用应用程序状态：
    • 保存后，刷新页面。
    • 查找应用程序状态部分（通常在保存后靠近顶部或底部）。
    • 将状态更改为实时 - 对用户可用。
    • 再次单击保存。
  7. 使用服务帐户路径 + webhook 受众配置 Moltbot：
    • 环境：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 路径。

添加到 Google Chat

网关运行后，您的电子邮件被添加到可见性列表：

  1. 转到 Google Chat。
  2. 单击直接消息旁边的 +（加号）图标。
  3. 在搜索栏（您通常添加人员的地方）中，输入您在 Google Cloud Console 中配置的应用名称。
    • 注意：机器人不会出现在"Marketplace"浏览列表中，因为它是私人应用程序。您必须按名称搜索它。
  4. 从结果中选择您的机器人。
  5. 单击添加或聊天以开始 1:1 对话。
  6. 发送"Hello"以触发助手！

公共 URL（仅 Webhook）

Google Chat webhooks 需要公共 HTTPS 端点。为了安全起见，仅向互联网公开 /googlechat 路径。将 Moltbot 仪表板和其他敏感端点保留在您的专用网络上。

选项 A：Tailscale Funnel（推荐）

对专用仪表板使用 Tailscale Serve，对公共 webhook 路径使用 Funnel。这保持 / 专用，同时仅公开 /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。

选项 B：反向代理（Caddy）

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

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

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

选项 C：Cloudflare Tunnel

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

  • 路径：/googlechat -> http://localhost:18789/googlechat
  • 默认规则：HTTP 404（未找到）

工作原理

  1. Google Chat 向网关发送 webhook POST。每个请求包括 Authorization: Bearer <token> 标头。
  2. Moltbot 根据配置的 audienceType + audience 验证令牌：
    • audienceType: "app-url" → 受众是您的 HTTPS webhook URL。
    • audienceType: "project-number" → 受众是 Cloud 项目编号。
  3. 消息按空间路由：
    • DM 使用会话键 agent:<agentId>:googlechat:dm:<spaceId>。
    • 空间使用会话键 agent:<agentId>:googlechat:group:<spaceId>。
  4. DM 访问默认为配对。未知发送者收到配对代码；通过以下方式批准：
    • moltbot 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", // optional; helps mention detection
      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（反应需要用户 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 部分。验证：

    moltbot config get channels.googlechat

    如果返回"未找到配置路径"，请添加配置（请参阅 配置亮点）。

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

    moltbot plugins list | grep googlechat

    如果显示"disabled"，请将 plugins.entries.googlechat.enabled: true 添加到您的配置中。

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

    moltbot gateway restart

验证通道正在运行：

moltbot channels status
# Should show: Google Chat default: enabled, configured, ...

其他问题

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

相关文档：

Discord（Bot API）grammY Integration (Telegram Bot API)