Skip to Content
👋 欢迎来到 HowToUseMoltbot 快速入门
频道Google Chat

Google Chat（Chat API）

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

快速设置（入门）

  1. 创建 Google Cloud 项目并启用 Google Chat API。
  2. 创建 服务账号：
    • 点击 Create Credentials > Service Account。
    • 任意命名（如 moltbot-chat）。
    • 权限留空（点 Continue）。
    • 访问主体留空（点 Done）。
  3. 创建并下载 JSON 密钥：
    • 在服务账号列表中点击刚创建的那个。
    • 进入 Keys 标签。
    • 点击 Add Key > Create new key。
    • 选择 JSON 并点击 Create。
  4. 将下载的 JSON 文件存到网关主机（如 ~/.clawdbot/googlechat-service-account.json）。
  5. 在 Google Cloud Console Chat 配置  中创建 Google Chat 应用：
    • 填写 Application info：
      • App name：（如 Moltbot）
      • Avatar URL：（如 https://molt.bot/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，并设为网关公网 URL 加 /googlechat。
      • 提示：运行 moltbot status 可查看网关公网 URL。
    • 在 Visibility 下勾选 Make this Chat app available to specific people and groups in Your Domain。
    • 在文本框中输入你的邮箱（如 user@example.com）。
    • 点击底部 Save。
  6. 启用应用状态：
    • 保存后刷新页面。
    • 找到 App status 区域（通常在保存后顶部或底部附近）。
    • 将状态改为 Live - available to users。
    • 再次点击 Save。
  7. 用服务账号路径 + webhook audience 配置 Moltbot：
    • 环境变量：GOOGLE_CHAT_SERVICE_ACCOUNT_FILE=/path/to/service-account.json
    • 或配置：channels.googlechat.serviceAccountFile: "/path/to/service-account.json"。
  8. 设置 webhook audience 类型与值（与 Chat 应用配置一致）。
  9. 启动网关。Google Chat 会向你的 webhook 路径发送 POST。

添加到 Google Chat

网关运行且你的邮箱已加入可见列表后：

  1. 打开 Google Chat 。
  2. 在 Direct Messages 旁点击 +。
  3. 在搜索框（通常用来添加联系人）中输入你在 Google Cloud Console 中配置的 App name。
    • 说明：机器人不会出现在「Marketplace」浏览列表中，因为它是私有应用。必须按名称搜索。
  4. 在结果中选择你的机器人。
  5. 点击 Add 或 Chat 开始 1:1 对话。
  6. 发送「Hello」触发助手。

公网 URL（仅 Webhook）

Google Chat webhook 需要公网 HTTPS 端点。为安全起见，只将 /googlechat 路径暴露到互联网。将 Moltbot 控制台及其他敏感端点保留在私网。

方案 A：Tailscale Funnel（推荐）

用 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
  1. 仅公网暴露 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
  1. 为节点授权 Funnel 访问：若提示，访问输出中的授权 URL，在 tailnet 策略中为该节点启用 Funnel。
  2. 验证配置：
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

在隧道的 ingress 规则中仅路由 webhook 路径：

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

工作原理

  1. Google Chat 向网关发送 webhook POST。每个请求带 Authorization: Bearer <token> 头。
  2. Moltbot 用配置的 audienceType + audience 校验 token：
    • audienceType: "app-url" → audience 为你的 HTTPS webhook URL。
    • audienceType: "project-number" → audience 为 Cloud 项目编号。
  3. 消息按空间路由：
    • 私聊使用会话键 agent:<agentId>:googlechat:dm:<spaceId>。
    • 空间使用会话键 agent:<agentId>:googlechat:group:<spaceId>。
  4. 私聊默认配对。未知发件人收到配对码；用 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", // 可选；有助于提及检测
      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 限制）。

故障排查

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

若返回「Config path not found」，请添加配置（见 配置要点）。 2. 插件未启用：检查插件状态：

moltbot plugins list | grep googlechat

若显示「disabled」，在配置中加入 plugins.entries.googlechat.enabled: true。 3. 网关未重启：添加配置后重启网关：

moltbot gateway restart

确认频道在运行：

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

其他问题

  • 用 moltbot channels status --probe 检查认证错误或缺少 audience 配置。
  • 若无消息到达，确认 Chat 应用的 webhook URL 与事件订阅。
  • 若 @ 提及门控阻止回复，将 botUser 设为应用的 user resource name 并确认 requireMention。
  • 发送测试消息时用 moltbot logs --follow 查看请求是否到达网关。

相关文档：

最后更新于:
DiscordGrammy