# Google Chat

> Google Chat 应用支持状态、功能和配置

- 网址：https://funcoding.ai/agents/openclaw/channels/googlechat/
- 来源：OpenClaw 官方文档原文（中文），MIT 许可，同步于 2026-10-11
- 官方原文：https://docs.openclaw.ai/zh-CN/channels/googlechat

---
Google Chat 以官方 `@openclaw/googlechat` 插件的形式运行：通过 Google Chat API webhook（仅限 HTTP 端点，不使用 Pub/Sub）支持私信和聊天室。

## 安装

```bash
openclaw plugins install @openclaw/googlechat
```

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

```bash
openclaw plugins install ./path/to/local/googlechat-plugin
```

## 快速设置（初学者）

1. 创建 Google Cloud 项目并启用 **Google Chat API**。
   - 前往：[Google Chat API Credentials](https://console.cloud.google.com/apis/api/chat.googleapis.com/credentials)
   - 如果尚未启用该 API，请将其启用。
2. 创建 **Service Account**：
   - 点击 **Create Credentials** > **Service Account**。
   - 任意命名（例如 `openclaw-chat`）。
   - 将权限和主体留空（点击 **Continue**，然后点击 **Done**）。
3. 创建并下载 **JSON 密钥**：
   - 点击新建的服务账号 > **Keys** 选项卡 > **Add Key** > **Create new key** > **JSON** > **Create**。
4. 将下载的 JSON 文件存放在 Gateway 网关主机上（例如 `~/.openclaw/googlechat-service-account.json`）。
5. 在 [Google Cloud Console Chat Configuration](https://console.cloud.google.com/apis/api/chat.googleapis.com/hangouts-chat) 中创建 Google Chat 应用：
   - 填写 **Application info**（应用名称、头像 URL、说明）。
   - 启用 **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`（参见[公共 URL](#public-url-webhook-only)）。
   - 在 **Visibility** 下，勾选 **Make this Chat app available to specific people and groups in ``**，然后输入你的电子邮件地址。
   - 点击 **Save**。
6. 启用应用状态：刷新页面，找到 **App status**，将其设置为 **Live - available to users**，然后再次点击 **Save**。
7. 使用服务账号和 webhook 受众配置 OpenClaw（必须与 Chat 应用配置匹配）：
   - 环境变量：`GOOGLE_CHAT_SERVICE_ACCOUNT_FILE=/path/to/service-account.json`（仅限默认账号），或者
   - 配置：参见[配置要点](#config-highlights)。`openclaw channels add --channel googlechat` 也接受 `--audience-type`、`--audience`、`--webhook-path` 和 `--webhook-url`。
8. 启动 Gateway 网关。Google Chat 会向你的 webhook 路径发送 POST 请求（默认为 `/googlechat`）。

## 添加到 Google Chat

Gateway 网关运行后，并且你的电子邮件地址已列入可见性列表：

1. 前往 [Google Chat](https://chat.google.com/)。
2. 点击 **Direct Messages** 旁边的 **+**（加号）图标。
3. 搜索你在 Google Cloud Console 中配置的 **App name**。
   - 由于这是私有应用，该 Bot _不会_出现在 Marketplace 浏览列表中；请按名称搜索。
4. 选择该 Bot，点击 **Add** 或 **Chat**，然后发送消息。

## 公共 URL（仅限 Webhook）

Google Chat webhook 需要公共 HTTPS 端点。为确保安全，**仅将 `/googlechat` 路径**暴露到互联网，并将 OpenClaw 仪表板和其他端点保持为私有。

### 方案 A：Tailscale Funnel（推荐）

使用 Tailscale Serve 提供私有仪表板，并使用 Funnel 提供公共 webhook 路径。

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

   ```bash
   ss -tlnp | grep 18789
   ```

   记下该 IP（例如 `127.0.0.1`、`0.0.0.0` 或 Tailscale `100.x.x.x` 地址）。

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

   ```bash
   # 如果绑定到 localhost（127.0.0.1 或 0.0.0.0）：
   tailscale serve --bg --https 8443 http://127.0.0.1:18789

   # 如果仅绑定到 Tailscale IP：
   tailscale serve --bg --https 8443 http://100.x.x.x:18789
   ```

3. 仅公开 webhook 路径：

   ```bash
   # 如果绑定到 localhost（127.0.0.1 或 0.0.0.0）：
   tailscale funnel --bg --set-path /googlechat http://127.0.0.1:18789/googlechat

   # 如果仅绑定到 Tailscale IP：
   tailscale funnel --bg --set-path /googlechat http://100.x.x.x:18789/googlechat
   ```

4. 如果系统提示，请访问输出中显示的授权 URL，为此节点启用 Funnel。

5. 验证：

   ```bash
   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）

仅代理 webhook 路径：

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

对 `your-domain.com/` 的请求会被忽略或返回 404，而 `your-domain.com/googlechat` 会路由到 OpenClaw。

### 方案 C：Cloudflare Tunnel

配置隧道入口规则，仅路由 webhook 路径：

- **Path**：`/googlechat` -> `http://localhost:18789/googlechat`
- **Default rule**：HTTP 404（Not Found）

## 工作原理

1. Google Chat 将 JSON 以 POST 方式发送到 Gateway 网关 webhook 路径（仅限 POST、要求 JSON 内容类型、按 IP 限速）。
2. OpenClaw 在分发前对每个请求进行身份验证：
   - Chat 应用事件携带 `Authorization: Bearer <token>`；在解析完整正文之前会验证该令牌。
   - Google Workspace 插件事件在正文中携带令牌（`authorizationEventObject.systemIdToken`），验证前会在更严格的预身份验证预算（16 KB、3 s）下读取。
3. 令牌会根据 `audienceType` + `audience` 进行检查：
   - `audienceType: "app-url"` → 受众为你的 HTTPS webhook URL。
   - `audienceType: "project-number"` → 受众为 Cloud 项目编号。
   - `app-url` 下的插件令牌还要求将 `appPrincipal` 设置为应用的数字 OAuth 2.0 客户端 ID（21 位数字，而非电子邮件）；否则验证将失败并记录警告。
4. 消息按聊天室路由：
   - 聊天室获得按聊天室划分的会话 `agent:<agentId>:googlechat:group:<spaceId>`；回复会发送到消息线程。
   - 默认情况下，私信会合并到智能体的主会话中；设置 `session.dmScope` 可为每个对端创建独立的私信会话（参见[会话](https://funcoding.ai/agents/openclaw/concepts/session/)）。
5. 私信访问默认使用配对。未知发送者会收到配对码；使用以下命令批准：
   - `openclaw pairing approve googlechat <code>`
6. 群组聊天室默认要求 @提及。系统通过以应用为目标的 Chat `USER_MENTION` 注解检测提及；如果检测需要应用的用户资源名称，请设置 `botUser`（例如 `users/1234567890`）。
7. 当 Exec 或插件审批从 Google Chat 发起，并且配置了稳定的 `users/<id>` 审批人时，OpenClaw 会在发起审批的聊天室或线程中发布原生审批卡片（`cardsV2`）。卡片按钮携带不透明的回调令牌；仅当原生交付不可用时，才会显示手动 `/approve <id> <decision>` 提示。

### 入站持久性

请求通过身份验证后，OpenClaw 会从存储中移除插件授权对象，并将 Google Chat `MESSAGE` 事件持久地加入队列，然后返回 `200`。如果持久化失败，则返回 `503`，使 Google Chat 能够重试，而不是确认一个可能丢失的事件。

待处理或可重试的消息可在 Gateway 网关重启后保留，仍按聊天室串行处理，并使用 Google Chat 消息资源名称抑制重复的队列条目，前提是活动或保留的完成记录仍然存在。非消息操作继续使用现有的分离式 webhook 路径，并且不享有此持久队列保证。从队列到智能体的边界仍采用至少一次交付，因此在移交期间发生崩溃可能会重放一个轮次。

## 目标

使用以下标识符进行交付和允许列表配置：

- 私信：`users/<userId>`（推荐）。
- 聊天室：`spaces/<spaceId>`。
- 原始电子邮件 `name@example.com` 可变，仅当 `channels.googlechat.dangerouslyAllowNameMatching: true` 时才用于允许列表匹配。
- 已弃用：`users/<email>` 被视为用户 ID，而不是电子邮件允许列表条目。
- 接受并移除前缀 `googlechat:`、`google-chat:` 和 `gchat:`。

## 配置要点

```json5
{
  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",
      appPrincipal: "123456789012345678901", // 仅用于插件验证；数字 OAuth 客户端 ID
      webhookPath: "/googlechat",
      botUser: "users/1234567890", // 可选；有助于检测提及
      allowBots: false,
      dmPolicy: "pairing",
      allowFrom: ["users/1234567890"],
      groupPolicy: "allowlist",
      groups: {
        "spaces/AAAA": {
          enabled: true,
          requireMention: true,
          users: ["users/1234567890"],
          systemPrompt: "仅使用简短回答。",
        },
      },
      typingIndicator: "message",
      mediaMaxMb: 20,
    },
  },
}
```

注意：

- 服务账号凭据：`serviceAccountFile`（路径）、`serviceAccount`（内联 JSON 字符串或对象）或 `serviceAccountRef`（环境变量/文件 SecretRef）。环境变量 `GOOGLE_CHAT_SERVICE_ACCOUNT`（内联 JSON）和 `GOOGLE_CHAT_SERVICE_ACCOUNT_FILE`（路径）仅应用于默认账号。多账号设置使用 `channels.googlechat.accounts.<id>`，其键名相同，包括每个账号的 `serviceAccountRef`。
- 未设置 `webhookPath` 时，默认 webhook 路径为 `/googlechat`；也可由 `webhookUrl` 提供该路径。
- 群组键必须是稳定的聊天室 ID（`spaces/<spaceId>`）。显示名称键已弃用，并会相应记录日志。
- `dangerouslyAllowNameMatching` 会重新启用可变电子邮件主体的允许列表匹配（紧急兼容模式）；Doctor 会对电子邮件条目发出警告。
- 不公开 Google Chat 表情回应操作。该插件使用服务账号身份验证，而 Google Chat 表情回应端点要求用户身份验证。为兼容性仍接受现有的 `actions.reactions` 配置，但它不起作用。
- 原生审批卡片使用 Google Chat `cardsV2` 按钮点击，而不是表情回应事件。审批人来自 `allowFrom` 或 `defaultTo`，且必须是稳定的数字 `users/<id>` 值。
- 消息操作仅公开文本 `send`。Google Chat 附件上传要求用户身份验证，而此插件使用服务账号身份验证，因此不公开出站文件上传。
- `typingIndicator`：`message`（默认）会发布 `_ is typing..._` 占位内容，并将其编辑为第一条回复；`none` 会将其禁用；`reaction` 要求用户 OAuth，在服务账号身份验证下目前会回退到 `message`，并记录错误。
- 入站附件（每条消息的第一个附件）会通过 Chat API 下载到媒体管道，并受 `mediaMaxMb` 限制（默认为 20）。
- 默认忽略由 Bot 编写的消息。启用 `allowBots: true` 后，接受的 Bot 消息会使用共享的 [Bot 循环保护](https://funcoding.ai/agents/openclaw/channels/bot-loop-protection/)：配置 `channels.defaults.botLoopProtection`，然后使用 `channels.googlechat.botLoopProtection` 或 `channels.googlechat.groups.<space>.botLoopProtection` 覆盖。

密钥参考详情：[密钥管理](https://funcoding.ai/agents/openclaw/gateway/secrets/)。

## 故障排查

### 405 Method Not Allowed

如果 Google Cloud Logs Explorer 显示如下错误：

```text
状态代码：405，原因短语：HTTP 错误响应：HTTP/1.1 405 Method Not Allowed
```

则说明 webhook 处理程序未注册。常见原因：

1. **渠道未配置**：缺少 `channels.googlechat` 部分。使用以下命令验证：

   ```bash
   openclaw config get channels.googlechat
   ```

   如果返回“Config path not found”，请添加配置（参阅[配置要点](#config-highlights)）。

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

   ```bash
   openclaw plugins list | grep googlechat
   ```

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

3. **配置更改后未重启 Gateway 网关**：

   ```bash
   openclaw gateway restart
   ```

验证渠道是否正在运行：

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

### 其他问题

- `openclaw channels status --probe` 会显示身份验证错误和缺失的 audience 配置（`audience` 和 `audienceType` 均为必需项）。
- 如果未收到任何消息，请确认 Chat 应用的 webhook URL 和触发器配置。
- 如果提及限制阻止回复，请将 `botUser` 设置为应用的用户资源名称，并检查 `requireMention`。
- 发送测试消息时使用 `openclaw logs --follow`，可查看请求是否到达 Gateway 网关。

## 相关内容

- [渠道概览](https://funcoding.ai/agents/openclaw/channels/) — 所有支持的渠道
- [频道路由](https://funcoding.ai/agents/openclaw/channels/channel-routing/) — 消息的会话路由
- [Gateway 配置](https://funcoding.ai/agents/openclaw/gateway/configuration/)
- [群组](https://funcoding.ai/agents/openclaw/channels/groups/) — 群聊行为和提及限制
- [配对](https://funcoding.ai/agents/openclaw/channels/pairing/) — 私信身份验证和配对流程
- [安全性](https://funcoding.ai/agents/openclaw/gateway/security/) — 访问模型和安全加固