Google Chat（Chat API�?

状态：已就绪，适用于通过 Google Chat API webhook（仅 HTTP）的 DM 和聊天室�?

快速设置（入门�?

创建 Google Cloud 项目并启�?Google Chat API�?
- 前往：Google Chat API 凭证
- 如果 API 未启用，请启用它�?
创建服务账户�?
- 点击 创建凭证 > 服务账户�?
- 随意命名（例�?openclaw-chat）�?
- 留空权限（点�?继续）�?
- 留空有权限的主体（点�?完成）�?
创建并下�?JSON 密钥�?
- 在服务账户列表中，点击您刚创建的账户�?
- 前往密钥选项卡�?
- 点击 添加密钥 > **创建新密�?*�?
- 选择 JSON 并点�?创建�?
将下载的 JSON 文件存储在您�?gateway 主机上（例如 ~/.openclaw/googlechat-service-account.json）�?
�?Google Cloud Console Chat 配置中创�?Google Chat 应用�?
- 填写 应用信息�?
  - 应用名称：（例如 OpenClaw�?
  - 头像 URL：（例如 https://openclaw.ai/logo.png�?
  - 描述：（例如 个人 AI 助手�?
- 启用交互功能�?
- �?功能下，勾�?加入聊天室和群组对话�?
- �?连接设置 下，选择 HTTP 端点 URL�?
- �?*触发�? 下，选择 对所有触发器使用通用 HTTP 端点 URL，并将其设置为您�?gateway 公共 URL，后�?/googlechat�?
  - 提示：运�?openclaw status 找到您的 gateway 公共 URL。
- �?*可见�? 下，勾�?�?<您的�?gt; 中的特定人员和群组可使用�?Chat 应用�?
- 在文本框中输入您的电子邮件地址（例�?[email protected]）�?
- 点击底部�?保存�?
**启用应用状�?*�?
- 保存后，刷新页面�?
- 查找 *应用状�? 部分（通常在保存后靠近顶部或底部）�?
- 将状态更改为 实时 - 用户可用�?
- 再次点击保存�?
使用服务账户路径 + webhook 受众配置 OpenClaw�?
- 环境：GOOGLE_CHAT_SERVICE_ACCOUNT_FILE=/path/to/service-account.json
- 或配置：channels.googlechat.serviceAccountFile: "/path/to/service-account.json"�?
设置 webhook 受众类型 + 值（与您�?Chat 应用配置匹配）�?
启动 gateway。Google Chat �?POST 到您�?webhook 路径�?

添加�?Google Chat

一�?gateway 正在运行且您的电子邮件已添加到可见性列表：

前往 Google Chat�?
点击 直接消息 旁边�?+（加号）图标�?
在搜索栏中（通常添加人的地方），输入您在 Google Cloud Console 中配置的应用名称�?
- 注意：机器人不会出现�?市场”浏览列表中，因为它是一个私人应用。您必须按名称搜索它�?
从结果中选择您的机器人�?
点击添加 �?聊天开�?1:1 对话�?
发�?Hello”来触发助手！

公共 URL（仅 Webhook�?

Google Chat webhook 需要公�?HTTPS 端点。为安全起见�?*仅将 /googlechat 路径**暴露给互联网。将 OpenClaw 仪表板和其他敏感端点保持在您的私有网络上�?

选项 A：Tailscale Funnel（推荐）

�?Tailscale Serve 用于私有仪表板，�?Funnel 用于公共 webhook 路径。这保持 / 私有，同时仅暴露 /googlechat�?

*检查您�?gateway 绑定到什么地址�?
```
ss -tlnp | grep 18789
```
记下 IP 地址（例�?127.0.0.1、0.0.0.0 或您�?Tailscale IP �?100.x.x.x）�?

仅向 tailnet 公开仪表板（端口 8443）：

# 如果绑定�?localhost�?27.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

*仅向公共公开 webhook 路径�?

# 如果绑定�?localhost�?27.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

*授权节点使用 Funnel 访问�? 如果出现提示，请访问输出中显示的授权 URL 以在您的 tailnet 策略中为此节点启�?Funnel�?

*验证配置�?

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 被安全路由到 OpenClaw�?

选项 C：Cloudflare Tunnel

配置隧道的入口规则以仅路�?webhook 路径�?

路径：/googlechat -> http://localhost:18789/googlechat
默认规则：HTTP 404（未找到�?

工作原理

Google Chat �?webhook POST 发送到 gateway。每个请求包含一�?Authorization: Bearer <token> 标头�?
OpenClaw 根据配置�?audienceType + audience 验证令牌�?
- audienceType: "app-url" �?受众是您�?HTTPS webhook URL�?
- audienceType: "project-number" �?受众�?Cloud 项目号�?
消息按聊天室路由�?
- DM 使用会话密钥 agent:<agentId>:googlechat:dm:<spaceId>�?
- 聊天室使用会话密�?agent:<agentId>:googlechat:group:<spaceId>�?
DM 访问默认需要配对。未知发送者收到配对代码；通过以下方式批准�?
- openclaw pairing approve googlechat <code>
聊天室空间默认需�?@-提及。如果提及检测需要应用的用户名，请使�?botUser�?

目标

将这些标识符用于投递和允许列表�?

直接消息：users/<userId>（推荐）�?
原始电子邮件 [email protected] 是可变的，仅�?channels.googlechat.dangerouslyAllowNameMatching: true 时用于直接允许列表匹配�?
已弃用：users/<email> 被视为用�?ID，而不是电子邮件允许列表�?
聊天室：spaces/<spaceId>�?

配置要点

{
  channels: {
    googlechat: {
      enabled: true,
      serviceAccountFile: "/path/to/service-account.json",
      // �?serviceAccountRef: { source: "file", provider: "filemain", id: "/channels/googlechat/serviceAccount" }
      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 重新启用可变的电子邮件主体匹配以允许列表（紧急兼容性模式）�?
�?actions.reactions 启用时，可以通过 reactions 工具�?channels action 使用反应�?
typingIndicator 支持 none、message（默认）�?reaction（反应需要用�?OAuth）�?
附件通过 Chat API 下载并存储在媒体管道中（大小�?mediaMaxMb 限制）�?

Secret 参考详情：密钥管理�?

排查

405 Method Not Allowed

如果 Google Cloud Logs Explorer 显示如下错误�?

status code: 405, reason phrase: HTTP error response: HTTP/1.1 405 Method Not Allowed

这意味着 webhook 处理器未注册。常见原因：

**通道未配�?*：配置中缺少 channels.googlechat 部分。使用以下命令验证：
```
openclaw config get channels.googlechat
```
如果返回”Config path not found”，请添加配置（请参阅配置要点）�?
**插件未启�?*：检查插件状态：
```
openclaw plugins list | grep googlechat
```
如果显示”disabled”，请在配置中添加 plugins.entries.googlechat.enabled: true�?
**Gateway 未重�?*：添加配置后，重�?gateway�?
```
openclaw gateway restart
```

验证通道正在运行�?

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

其他问题

检�?openclaw channels status --probe 是否�?auth 错误或缺少受众配置�?
如果没有消息到达，确�?Chat 应用�?webhook URL + 事件订阅�?
如果提及门控阻止回复，请�?botUser 设置为应用的用户资源名称并验�?requireMention�?
在发送测试消息时使用 openclaw logs --follow 查看请求是否到达 gateway�?