OpenClaw Google Chat 接入指南：Service Account 配置、Webhook 公网暴露与空间访问控制

OpenClaw 通过 Google Chat API 的 HTTP Webhook 接入，支持 DM 和 Space（空间/群组）。需要 Google Cloud 项目、Service Account 和可公网访问的 HTTPS 端点。

快速接入（8 步）#

1. 创建 Google Cloud 项目并启用 Chat API#

访问 Google Chat API 凭证页，启用 API。

2. 创建 Service Account#

Create Credentials → Service Account，命名（如 openclaw-chat），权限和访问控制留空。

3. 下载 JSON Key#

点击刚创建的 Service Account → Keys 标签 → Add Key → Create new key → JSON → 下载。

将 JSON 文件存放到 Gateway 主机（如 ~/.openclaw/googlechat-service-account.json）。

4. 创建 Google Chat 应用#

访问 Google Cloud Console 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：设置公网 URL，格式：https://your-gateway/googlechat
• Visibility：添加你的 Google 账号邮箱

5. 启用应用状态#

保存后刷新页面，找到 App status → 设置为 Live - available to users → 再次保存。

6. 配置 OpenClaw#

{
  "channels": {
    "googlechat": {
      "enabled": true,
      "serviceAccountFile": "~/.openclaw/googlechat-service-account.json",
      "audienceType": "app-url",
      "audience": "https://your-gateway-host/googlechat",
      "webhookPath": "/googlechat",
      "dm": {
        "policy": "pairing",
        "allowFrom": ["users/1234567890"]
      },
      "groupPolicy": "allowlist",
      "groups": {
        "spaces/AAAA": {
          "allow": true,
          "requireMention": true,
          "users": ["users/1234567890"]
        }
      }
    }
  }
}

环境变量方式：

export GOOGLE_CHAT_SERVICE_ACCOUNT_FILE=/path/to/service-account.json

7. 暴露公网 Webhook#

Google Chat 要求 HTTPS 公网端点。只暴露 /googlechat 路径，保护其他接口。

方案 A：Tailscale Funnel（推荐）

# 私网访问控制台
tailscale serve --bg --https 8443 http://127.0.0.1:18789

# 只公开 webhook 路径
tailscale funnel --bg --set-path /googlechat http://127.0.0.1:18789/googlechat

# 验证
tailscale serve status
tailscale funnel status

公网 URL：https://<node-name>.<tailnet>.ts.net/googlechat

方案 B：Caddy 反向代理

方案 C：Cloudflare Tunnel

8. 完成配对#

openclaw gateway
# 在 Google Chat 中搜索应用名称并添加
# 发送消息后
openclaw pairing approve googlechat <CODE>

添加到 Google Chat#

1. 打开 Google Chat
2. 点击 Direct Messages 旁的 +
3. 搜索你的 App name（注意：私有应用不在 Marketplace 中，必须按名称搜索）
4. 选择 Bot → Add 或 Chat
5. 发送消息触发助手

工作原理#

1. Google Chat 发送带 Authorization: Bearer <token> 的 Webhook POST
2. OpenClaw 验证 token（先于读取 Body）
3. 按 Space 路由 Session：
   • DM：agent:<id>:googlechat:dm:<spaceId>
   • Space：agent:<id>:googlechat:group:<spaceId>

目标标识符格式#

避免使用邮箱作为标识符——邮箱可变，只在开启 dangerouslyAllowNameMatching: true 时生效。

访问控制配置#

{
  "channels": {
    "googlechat": {
      "dm": { "policy": "allowlist", "allowFrom": ["users/123456789"] },
      "groupPolicy": "allowlist",
      "groups": {
        "spaces/AAAA": {
          "requireMention": true,
          "users": ["users/123456789"],
          "systemPrompt": "简短回答。"
        }
      }
    }
  }
}

空间特定系统提示 systemPrompt 可以为不同群组设置不同的 Agent 行为。

故障排查#

405 Method Not Allowed：确认 Webhook URL 正确，Gateway 正在运行，路径完全匹配（包含 /googlechat）。

Bot 不出现在搜索结果：私有应用不在 Marketplace，必须按精确名称搜索；确认应用 Visibility 已添加你的邮箱。

Webhook 验证失败：检查 audienceType 和 audience 是否与 Google Chat 应用配置一致。

Bot 不回复 Space 消息：默认需要 @提及；检查 requireMention 和 users 白名单。

原文：Google Chat - OpenClaw | 来源：OpenClaw 官方文档