Google Chat（Chat API）

状态：通过 Google Chat API Webhook（仅 HTTP）支持私信和 Space。

快速设置（新手）

1. 创建 Google Cloud 项目并启用 Google Chat API
   • 前往：Google Chat API Credentials
   • 若 API 未启用，先启用它
2. 创建服务账号：
   • 点击 Create Credentials > Service Account
   • 随意命名（如 openclaw-chat）
   • 权限留空（点击 Continue）
   • 访问主体留空（点击 Done）
3. 创建并下载 JSON Key：
   • 在服务账号列表中点击刚创建的账号
   • 前往 Keys 选项卡
   • 点击 Add Key > Create new key
   • 选择 JSON 并点击 Create
4. 将下载的 JSON 文件存放到 Gateway 主机上（如 ~/.openclaw/googlechat-service-account.json）
5. 在 Google Cloud Console Chat 配置 创建 Google Chat App：
   • 填写应用信息：
     • 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，设置为 Gateway 公网 URL 加 /googlechat
     • 提示：运行 openclaw status 查找 Gateway 公网 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 受众配置 OpenClaw：
   • 环境变量：GOOGLE_CHAT_SERVICE_ACCOUNT_FILE=/path/to/service-account.json
   • 或配置：channels.googlechat.serviceAccountFile: "/path/to/service-account.json"
8. 设置 Webhook 受众类型 + 值（与 Chat App 配置匹配）
9. 启动 Gateway，Google Chat 会向你的 Webhook 路径 POST 请求

添加到 Google Chat

Gateway 运行且邮箱已添加到可见性列表后：

1. 前往 Google Chat
2. 点击直接消息旁的 + 图标
3. 在搜索栏中输入 Google Cloud Console 中配置的 App name
   • 注意：Bot 不会出现在"Marketplace"浏览列表中，因为它是私有应用，必须按名称搜索
4. 从结果中选择你的 Bot
5. 点击 Add 或 Chat 开始 1:1 对话
6. 发送"Hello"触发助手！

公网 URL（仅 Webhook）

Google Chat Webhook 需要公网 HTTPS 端点。出于安全考虑，只将 /googlechat 路径暴露到公网，其他敏感端点保持在私有网络。

方案 A：Tailscale Funnel（推荐）

使用 Tailscale Serve 处理私有仪表板，使用 Funnel 处理公网 Webhook 路径，保持 / 私有同时只暴露 /googlechat：

# 将仪表板暴露给 tailnet（8443 端口）
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

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

私有仪表板：https://<node-name>.<tailnet>.ts.net:8443/

注意：此配置在重启后持久保存。要删除，运行 tailscale funnel reset 和 tailscale serve reset。

方案 B：反向代理（Caddy）

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

方案 C：Cloudflare Tunnel

配置隧道入口规则只路由 Webhook 路径：

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

工作原理

1. Google Chat 向 Gateway 发送 Webhook POST，每个请求包含 Authorization: Bearer <token> 头部
   • OpenClaw 在读取/解析完整 Webhook 正文之前验证 Bearer 认证
2. OpenClaw 根据配置的 audienceType + audience 验证 Token：
   • audienceType: "app-url" → 受众是你的 HTTPS Webhook URL
   • audienceType: "project-number" → 受众是 Cloud 项目编号
3. 消息按 Space 路由：
   • 私信使用会话密钥 agent:<agentId>:googlechat:direct:<spaceId>
   • Space 使用会话密钥 agent:<agentId>:googlechat:group:<spaceId>
4. 私信访问默认使用配对模式，未知发送者收到配对码；审批：openclaw pairing approve googlechat <code>
5. 群组 Space 默认需要 @提及；若提及检测需要应用的用户名，使用 botUser

投递目标

使用以下标识符进行投递和白名单：

• 私信：users/<userId>（推荐）
• 裸邮箱仅在 channels.googlechat.dangerouslyAllowNameMatching: true 时用于直接白名单匹配
• Space：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"],
      },
      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 字符串）内联传递
• serviceAccountRef 也支持（env/file SecretRef），包括 channels.googlechat.accounts.<id>.serviceAccountRef 下的每账号引用
• 若未设置 webhookPath，默认 Webhook 路径为 /googlechat
• dangerouslyAllowNameMatching 重新启用可变邮箱主体匹配（紧急兼容模式）
• 回应通过 reactions 工具和 channels action 提供（需启用 actions.reactions）
• 消息操作暴露 send（文本）和 upload-file（显式附件发送）
• typingIndicator 支持 none、message（默认）和 reaction（回应需要用户 OAuth）

Secrets 参考：Secrets 管理。

故障排除

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 部分不在配置中，验证：

   openclaw config get channels.googlechat

   若返回"Config path not found"，添加配置（见上方配置示例）

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

   openclaw plugins list | grep googlechat

   若显示"disabled"，在配置中添加 plugins.entries.googlechat.enabled: true

3. Gateway 未重启：添加配置后重启：

   openclaw gateway restart

验证渠道运行中：

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

其他问题

• 运行 openclaw channels status --probe 检查认证错误或缺少受众配置
• 若无消息到达，确认 Chat App 的 Webhook URL 和事件订阅
• 若提及门控阻止回复，将 botUser 设置为应用的用户资源名称并检查 requireMention
• 发送测试消息时运行 openclaw logs --follow 查看请求是否到达 Gateway

相关文档：

• Gateway 配置
• 安全
• 回应