首页
介绍
教程
Skills
技术博客
GitHub
返回教程中心
消息渠道接入

OpenClaw Google Chat 接入教程，Cloud 配置和消息回传指南

O
OpenClaw AI
2026-03-25

Google Chat 是 OpenClaw 官方支持的 HTTP 渠道之一，适合已经在 Google Workspace 里协作的团队。它和 Telegram、Discord 这类长连接 Bot 渠道不同，核心思路是让 Google Chat 通过 HTTPS webhook 把消息推送到你的 Gateway，所以这条链路的重点不是扫码登录，而是云端应用配置、服务账号和安全暴露公网路径。

先理解 Google Chat 在 OpenClaw 里的工作方式

根据官方文档，Google Chat 渠道有几个关键特点：

  • 使用 Google Chat API webhook 接入，只支持 HTTP 模式
  • 已支持私信和空间消息
  • 默认私信采用配对机制，陌生用户第一次发消息会先拿到配对码
  • 群组空间通常要求 @提及 才触发，避免机器人在空间里频繁打断交流
  • OpenClaw 会根据 audienceType 和 audience 校验 Google 发送来的 Bearer Token

这意味着，Google Chat 接入成功与否，取决于三件事是否都正确：

  1. Google Cloud 项目和 Chat 应用是否配置完整
  2. Gateway 是否能读到服务账号 JSON，并正确验证 webhook 身份
  3. 你的公网 URL 是否真的能把 /googlechat 请求送到 Gateway

适合什么场景

Google Chat 更适合下面这几类用户：

  • 团队日常已经全部在 Google Workspace 内协作
  • 希望把 OpenClaw 放进空间里做问答、通知或审批辅助
  • 不想依赖扫码登录类渠道，而是想用更标准的企业 API 接入

如果你现在还在第一阶段摸索，我更建议先用 Telegram 跑通基础链路，再接 Google Chat。因为 Google Chat 同时牵涉 Google Cloud、应用可见性、HTTPS webhook 和 Gateway 暴露策略，排障面会更大。

你需要提前准备的内容

开始前，先准备好：

  1. 一个 Google Cloud 项目
  2. 已启用 Google Chat API
  3. 一个服务账号
  4. 该服务账号的 JSON 密钥文件
  5. 一个可用的公网 HTTPS 地址，用来接收 /googlechat webhook

官方示例里，服务账号 JSON 可以放在：

text
~/.openclaw/googlechat-service-account.json

如果 Gateway 跑在远程 Linux、VPS 或家用主机上，建议把这个文件放在只有 OpenClaw 运行用户可读的位置，不要随手丢进公开仓库或同步盘。

第一步：创建 Google Cloud 项目并启用 Google Chat API

在 Google Cloud Console 中：

  1. 创建新项目，或选择一个已有项目
  2. 打开 Google Chat API 页面
  3. 确认已经启用该 API

如果 API 没启用，后面的 Chat 应用配置页面即使能打开，也无法完整保存聊天事件设置。

第二步：创建服务账号并下载 JSON 密钥

官方流程是：

  1. 点击 Create Credentials > Service Account
  2. 给服务账号起一个名字，例如 openclaw-chat
  3. 权限先留空，继续创建
  4. 进入该服务账号的详情页
  5. 打开 Keys
  6. 选择 Add Key > Create new key
  7. 选择 JSON
  8. 下载生成的密钥文件

建议把它保存到 Gateway 主机，例如：

bash
mkdir -p ~/.openclaw
mv ~/Downloads/<downloaded-file>.json ~/.openclaw/googlechat-service-account.json
chmod 600 ~/.openclaw/googlechat-service-account.json

这里的文件名可以自定义，但后面配置 serviceAccountFile 或环境变量时要保持一致。

第三步：在 Google Cloud Console 中创建 Chat 应用

这一段是 Google Chat 渠道最容易漏配置的地方。根据官方文档，至少要完成下面几项：

  • 填写 App name
  • 填写头像和说明
  • 开启 Interactive features
  • 在 Functionality 中勾选 Join spaces and group conversations
  • 在 Connection settings 里选择 HTTP endpoint URL
  • 在 Triggers 里启用统一 webhook 地址，并把它设为你的公网地址加 /googlechat
  • 在 Visibility 中把应用开放给你自己或指定组织成员
  • 保存后把应用状态改成 Live - available to users

如果你的 Gateway 公网地址是：

text
https://gateway.example.com

那么 Chat 应用里应该填写：

text
https://gateway.example.com/googlechat

不要把 Dashboard 首页地址误填进来，也不要漏掉 /googlechat 路径。

第四步：配置 OpenClaw 渠道

官方给出的关键配置项大致如下：

json
{
  "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."
        }
      }
    }
  }
}

这段配置里最重要的是：

  • serviceAccountFile：服务账号 JSON 的实际路径
  • audienceType 和 audience：决定 OpenClaw 如何验证 Google 发来的 Bearer Token
  • webhookPath：默认就是 /googlechat
  • dm.policy: "pairing"：私聊陌生用户先配对
  • groupPolicy 与 requireMention：控制空间消息边界

如果你想简单起步，可以先不做复杂 allowlist，只保留：

  • enabled
  • serviceAccountFile
  • audienceType
  • audience
  • webhookPath

先跑通 webhook，再慢慢补群组规则。

audienceType 应该怎么选

官方文档给了两种主要思路：

  • audienceType: "app-url"：audience 写你的 HTTPS webhook 完整地址
  • audienceType: "project-number"：audience 写 Google Cloud 项目编号

对大多数自建部署来说，app-url 更直观，也更容易和 Chat 应用配置保持一致。你只要确保 Chat 应用里填的 HTTP endpoint URL 和这里的 audience 是同一个地址即可。

第五步：安全地暴露公网地址

Google Chat webhook 必须命中一个公网 HTTPS 地址，但这不等于你要把整个 Dashboard 都暴露出去。官方文档强调，只需要暴露 /googlechat 这条路径，其他敏感入口最好仍然保留在私有网络内。

官方给了三种常见方案：

方案 A：Tailscale Funnel

这是官方更推荐的做法。思路是：

  • 用 tailscale serve 让 Dashboard 只在 tailnet 内可见
  • 用 tailscale funnel --set-path /googlechat 只公开 webhook 路径

示例：

bash
tailscale serve --bg --https 8443 http://127.0.0.1:18789
tailscale funnel --bg --set-path /googlechat http://127.0.0.1:18789/googlechat

验证方式：

bash
tailscale serve status
tailscale funnel status

方案 B：反向代理

如果你用 Caddy、Nginx 或其他反向代理，原则也一样：只转发 /googlechat。

Caddy 示例：

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

方案 C：Cloudflare Tunnel

入口规则只允许：

  • /googlechat -> http://localhost:18789/googlechat
  • 其他默认返回 404

这个思路的重点不是“能访问就行”，而是“只暴露 webhook 必要路径”。

第六步：启动 Gateway 并完成首次验证

先启动 Gateway：

bash
openclaw gateway --port 18789

然后建议按下面顺序验证：

  1. 访问 Chat 应用配置里填写的 HTTP endpoint URL
  2. 确认反向代理或 Funnel 已经生效
  3. 在 Google Chat 里按应用名搜索你的机器人
  4. 发一条简单消息，例如 Hello
  5. 同时观察 Gateway 日志

如果机器人根本搜不到，优先检查：

  • Visibility 是否只给了其他用户，没给自己
  • App status 是否还停留在草稿或未上线
  • 你是否在 Google Chat 里按应用名搜索，而不是在 Marketplace 里找

私聊和空间消息是怎么被路由的

官方文档说明：

  • 私信会话会按私聊空间独立路由
  • 群组空间会按空间 ID 独立路由
  • 私聊默认是配对模式
  • 群组空间默认通常要求 @提及

也就是说，Google Chat 不会天然把所有消息都混进同一个长会话里。对团队协作来说，这反而是好事，因为它能把私聊和空间上下文隔离开。

如果用户第一次私聊机器人拿到了配对码，需要在 Gateway 主机上批准：

bash
openclaw pairing approve googlechat <code>

如何做 allowlist 和定向消息

官方支持的目标标识符有：

  • 私信：users/<userId> 或 users/<email>
  • 空间：spaces/<spaceId>

这意味着你可以：

  • 直接允许某个邮箱地址对应的用户
  • 限定只允许某个空间
  • 在 group 配置里给不同空间设置不同的 systemPrompt

如果你在组织里准备正式上线，这一层非常重要。它决定的是“哪些人能用”“哪些空间能触发”“什么场景需要 @ 提及”，而不是单纯把机器人装进去就算完成。

最常见的错误与排查思路

机器人搜不到

优先检查：

  • Chat 应用是否已经切到 Live
  • Visibility 是否包含你的账号
  • 是否在 Google Chat 里按 App name 搜索

收不到消息

通常排查这几项：

  • /googlechat 是否真的可从公网访问
  • audienceType 与 audience 是否和 Chat 应用里的 webhook 地址匹配
  • 服务账号 JSON 路径是否正确
  • Gateway 是否正在运行

Google Chat 能命中地址，但 OpenClaw 不接受

优先怀疑：

  • audience 写错
  • project-number 和 app-url 用混了
  • webhookPath 不是 /googlechat

群里机器人不回复

先看是否满足这几个条件：

  • 当前空间已被允许
  • requireMention 开启时，你是否真的 @ 了机器人
  • botUser 是否正确，便于提及检测

推荐的上线顺序

如果你想把这条链路做稳，我建议按这个节奏：

  1. 先让私聊跑通
  2. 再验证配对流程
  3. 再把机器人加到一个测试空间
  4. 先保留 requireMention: true
  5. 最后再做 allowlist、不同空间提示词和动作能力

Google Chat 不是最省事的渠道，但它一旦配好，会非常适合企业协作环境。真正决定体验的不是“机器人能不能回一句话”，而是你是否把 webhook 安全暴露、身份校验、私聊配对和空间权限这几层一起配对齐。

继续阅读

相关阅读与站内入口

OpenClaw Discord 接入教程，Bot Token Intent 和频道配置

按官方 Discord Bot API 的基本思路完成 token、intent、服务器频道与私信配置。

OpenClaw Telegram 接入教程，Bot 配置和群组权限设置

从 BotFather 创建机器人，到配置 token、群组提及与 allowlist，完整跑通 Telegram 渠道接入。

OpenClaw WhatsApp 接入教程，扫码登录和权限配置指南

按官方 Web 渠道方案完成 WhatsApp 扫码登录、allowlist 配置与 Gateway 启动，适合做主消息入口。

OpenClaw 渠道接入教程，Telegram WhatsApp Discord 选择指南

帮助你先选对聊天入口，再决定如何配置配对、allowlist 和群组/频道策略。

查看全部 OpenClaw 教程

继续浏览安装部署、模型接入、渠道配置和故障排查等完整教程。

前往 Skills 市场

找到更多可直接安装的 Skills 和可复用能力，丰富你的 OpenClaw 使用场景。

准备好开始了吗？

继续探索更多教程，或者去技能市场看看有哪些现成的插件。