跳转到内容
OpenClaw Docs

Google ChatGoogle Chat

状态：通过 Google Chat API webhook（仅 HTTP）为私信和聊天室提供的可下载插件。

安装

Section titled “安装”

在配置渠道之前安装 Google Chat：

Terminal window
openclaw plugins install @openclaw/googlechat

本地检出（当从 git 仓库运行时）：

Terminal window
openclaw plugins install ./path/to/local/googlechat-plugin

快速设置（初学者）

Section titled “快速设置（初学者）”
  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 文件存储在您的网关主机上（例如，~/.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 并将其设置为网关的公共 URL 后跟 /googlechat。
      • 提示：运行 openclaw status 以查找您网关的公共 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. 启动网关。Google Chat 将向您的 Webhook 路径发送 POST 请求。

添加到 Google Chat

Section titled “添加到 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）

Section titled “公开 URL（仅限 Webhook）”

Google Chat Webhook 需要一个公共 HTTPS 端点。为了安全起见，仅将 /googlechat 路径 暴露给互联网。请将 OpenClaw 仪表板和其他敏感端点保留在您的专用网络中。

选项 A：Tailscale Funnel（推荐）

Section titled “选项 A：Tailscale Funnel（推荐）”

对私有仪表板使用 Tailscale Serve，对公共 Webhook 路径使用 Funnel。这样可以保持 / 为私有状态，同时仅暴露 /googlechat。

  1. 检查您的网关绑定到哪个地址：

    Terminal window
    ss -tlnp | grep 18789

    记下 IP 地址（例如 127.0.0.1、0.0.0.0 或您的 Tailscale IP，如 100.x.x.x）。

  2. 仅将仪表板暴露给 tailnet（端口 8443）：

    Terminal window
    # If bound to localhost (127.0.0.1 or 0.0.0.0):
    tailscale serve --bg --https 8443 http://127.0.0.1:18789
    

    # If bound to Tailscale IP only (e.g., 100.106.161.80):
    tailscale serve --bg --https 8443 http://100.106.161.80:18789

  3. 仅公开暴露 Webhook 路径：

    Terminal window
    # If bound to localhost (127.0.0.1 or 0.0.0.0):
    tailscale funnel --bg --set-path /googlechat http://127.0.0.1:18789/googlechat
    

    # If bound to Tailscale IP only (e.g., 100.106.161.80):
    tailscale funnel --bg --set-path /googlechat http://100.106.161.80:18789/googlechat

  4. 授权节点以进行 Funnel 访问： 如果收到提示，请访问输出中显示的授权 URL，以在您的 tailnet 策略中为此节点启用 Funnel。

  5. 验证配置：

    Terminal window
    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)

Section titled “选项 B：反向代理 (Caddy)”

如果您使用 Caddy 之类的反向代理，请仅代理特定路径：

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

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

选项 C：Cloudflare Tunnel

Section titled “选项 C：Cloudflare Tunnel”

配置您的隧道入口规则，以仅路由 Webhook 路径：

  • 路径： /googlechat -> http://localhost:18789/googlechat
  • 默认规则： HTTP 404 (Not Found)

工作原理

Section titled “工作原理”
  1. Google Chat 向网关发送 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。

目标

Section titled “目标”

使用这些标识符进行投递和允许列表：

  • 私信：users/<userId>（推荐）。
  • 原始电子邮件 [email protected] 是可变的，仅用于在 channels.googlechat.dangerouslyAllowNameMatching: true 时进行直接允许列表匹配。
  • 已弃用：users/<email> 被视为用户 ID，而不是电子邮件允许列表。
  • 群组空间：spaces/<spaceId>。

配置要点

Section titled “配置要点”
{
  channels: {
    googlechat: {
      enabled: true,
      serviceAccountFile: "/path/to/service-account.json",
      // or serviceAccountRef: { source: "file", provider: "filemain", id: "/channels/googlechat/serviceAccount" }
      audienceType: "app-url",
      audience: "https://gateway.example.com/googlechat",
      webhookPath: "/googlechat",
      botUser: "users/1234567890", // optional; helps mention detection
      allowBots: false,
      dm: {
        policy: "pairing",
        allowFrom: ["users/1234567890"],
      },
      groupPolicy: "allowlist",
      groups: {
        "spaces/AAAA": {
          enabled: true,
          requireMention: true,
          users: ["users/1234567890"],
          systemPrompt: "Short answers only.",
        },
      },
      actions: { reactions: true },
      typingIndicator: "message",
      mediaMaxMb: 20,
    },
  },
}

说明：

  • 服务账号凭证也可以通过 serviceAccount（JSON 字符串）内联传递。
  • 还支持 serviceAccountRef（环境变量/文件 SecretRef），包括 channels.googlechat.accounts.<id>.serviceAccountRef 下的每个账号引用。
  • 如果未设置 webhookPath，则默认 webhook 路径为 /googlechat。
  • dangerouslyAllowNameMatching 重新为允许列表启用可变的电子邮件主体匹配（应急兼容模式）。
  • 当启用 actions.reactions 时，可以通过 reactions 工具和 channels action 使用反应（reactions）。
  • 消息操作为文本提供 send，为显式附件发送提供 upload-file。upload-file 接受 media / filePath / path 以及可选的 message、filename 和会话定位。
  • typingIndicator 支持 none、message（默认）和 reactionOAuth（反应需要用户 OAuth）。
  • 附件通过 Chat API 下载并存储在媒体管道中（大小受 APImediaMaxMb 限制）。
  • 默认情况下，忽略机器人发送的 Google Chat 消息。如果您有意设置了 allowBots: true，被接受的机器人发送的消息将使用共享的 bot loop protection。配置 channels.defaults.botLoopProtection，然后当某个空间需要不同的预算时，使用 channels.googlechat.botLoopProtection 或 channels.googlechat.groups.<space>.botLoopProtection 覆盖。

Secrets 参考详细信息：Secrets Management。

故障排除

Section titled “故障排除”

405 Method Not Allowed

Section titled “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 部分。请通过以下方式验证：

    Terminal window
    openclaw config get channels.googlechat

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

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

    Terminal window
    openclaw plugins list | grep googlechat

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

  3. Gateway(网关) 未重启：添加配置后，重启 gateway：

    Terminal window
    openclaw gateway restart

验证渠道是否正在运行：

Terminal window
openclaw channels status
# Should show: Google Chat default: enabled, configured, ...

其他问题

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

相关文档：

相关

Section titled “相关”