企业官网建设流程全解析

OpenClaw Google Chat 渠道插件实战指南：从服务账号配置到 Webhook 消息路由

【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 🦞项目地址: https://gitcode.com/GitHub_Trending/cl/openclaw

导读

本文围绕 OpenClaw 官方 Google Chat 渠道插件@openclaw/googlechat展开，系统讲解如何在 Google Cloud 中创建 Chat 应用、配置服务账号与 HTTP Webhook、通过 Tailscale Funnel / Caddy / Cloudflare Tunnel 安全暴露/googlechat端点，以及 OpenClaw 侧完整的渠道配置、会话路由、入站持久化与排障手段。读完本文，你将能够独立完成 Google Chat 空间与私聊消息的接入，并理解该插件从请求鉴权、空间路由到原生审批卡片投递的完整链路。

插件概览与安装

@openclaw/googlechat是 OpenClaw 官方的 Google Chat 渠道插件，支持Google Chat 空间（spaces）与私聊（direct messages）。它通过 Google Chat API 的HTTP Webhook（仅 HTTP 端点，不使用 Pub/Sub）接收事件，并经由配置的服务账号回消息，具体能力说明见 插件渠道文档。

在 OpenClaw 中安装插件：

openclaw plugins install @openclaw/googlechat

如果从本地 git 检出运行，也可以直接安装本地插件目录：

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

从源码结构看，插件入口 index.ts 通过defineBundledChannelEntry注册了渠道实现（googlechatPlugin）、密钥契约（channelSecrets）与运行时（setGoogleChatRuntime），核心渠道逻辑位于 src/channel.ts（基于createChatChannelPlugin构建）。插件包声明中（package.json）标明渠道 id 为googlechat，依赖google-auth-library与zod，其安装元数据（openclaw.plugin.json）进一步定义了渠道别名gchat、google-chat，并将GOOGLE_CHAT_SERVICE_ACCOUNT/GOOGLE_CHAT_SERVICE_ACCOUNT_FILE作为"已配置"状态的判定环境变量。

快速开始：Google Cloud 侧准备（新手向）

1. 启用 Google Chat API

在 Google Cloud Console 打开 Google Chat API Credentials 页面，若 API 未启用则先启用。

2. 创建服务账号

点击Create Credentials>Service Account，名称可任意（例如openclaw-chat），权限与主体（principals）留空，依次Continue、Done。

3. 生成并下载 JSON 密钥

点击该服务账号 >Keys标签 >Add Key>Create new key>JSON>Create，下载得到的 JSON 文件即为后续认证凭据。

4. 保存密钥文件

将下载的 JSON 文件存放到网关主机上（例如~/.openclaw/googlechat-service-account.json）。

5. 创建 Google Chat 应用

在 Google Cloud Console Chat Configuration 中创建 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，填为你的公网网关地址后跟/googlechat（参见下文 公网 URL 小节）。
• Visibility：勾选Make this Chat app available to specific people and groups in<Your Domain>，并填入你的邮箱。
• 点击Save。

6. 将应用状态设为 Live

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

7. 配置 OpenClaw

将服务账号与 webhook audience（必须与 Chat 应用配置一致）写入 OpenClaw：

• 环境变量方式（仅默认账号）：GOOGLE_CHAT_SERVICE_ACCOUNT_FILE=/path/to/service-account.json；
• 配置文件方式：见下文 配置要点。openclaw channels add --channel googlechat还支持--audience-type、--audience、--webhook-path、--webhook-url等参数（对应 openclaw.plugin.json 中setup.fields定义的 CLI flags：--token <json>、--token-file <path>、--audience-type <type>、--audience <value>、--webhook-path <path>、--webhook-url <url>、--use-env）。

8. 启动网关

启动后，Google Chat 会向你的 webhook 路径（默认/googlechat）POST 事件。

将应用加入 Google Chat

网关运行且你的邮箱已在可见性列表后：

1. 打开 Google Chat；
2. 点击Direct Messages旁的+号；
3. 搜索你配置的App name——由于是私有应用，机器人不会出现在 Marketplace 浏览列表中，需按名称搜索；
4. 选中机器人，点击Add或Chat，发送一条消息即可开始对话。

公网 URL（Webhook-only）

Google Chat Webhook 需要一个公网 HTTPS 端点。出于安全考虑，只把/googlechat路径暴露到公网，OpenClaw 仪表盘及其他端点保持私有。

方案 A：Tailscale Funnel（推荐）

用 Tailscale Serve 暴露私有仪表盘、用 Funnel 暴露公网 Webhook 路径：

1. 查看网关绑定地址：

   ss -tlnp | grep 18789

   记下 IP（例如127.0.0.1、0.0.0.0或 Tailscale100.x.x.x地址）。

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

   # 绑定 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 路径：

   # 绑定 localhost 时： 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. 验证：

   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 路径：

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

your-domain.com/的其他请求将被忽略或返回 404，仅your-domain.com/googlechat路由到 OpenClaw。

方案 C：Cloudflare Tunnel

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

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

工作原理：从鉴权到消息路由

结合渠道文档（docs/channels/googlechat.md）与源码结构，整体流程如下：

1. Google Chat 向网关 webhook 路径 POST JSON（仅 POST、要求 JSON 内容类型、按 IP 限流）。
2. OpenClaw 在分发前认证每个请求：
   • Chat 应用事件携带Authorization: Bearer <token>，token 在完整 body 解析前即被校验；
   • Google Workspace Add-on 事件把 token 放在 body（authorizationEventObject.systemIdToken）中，会在更严格的预认证预算（16 KB、3 秒）下读取并校验。
3. token 依据audienceType+audience校验：
   • audienceType: "app-url"→ audience 为你的 HTTPS webhook URL；
   • audienceType: "project-number"→ audience 为 Cloud 项目编号；
   • app-url模式下的 Add-on token 还要求appPrincipal设置为应用的数字型 OAuth 2.0 client ID（21 位数字，不是邮箱），否则校验失败并记录警告日志。
4. 消息按空间路由：
   • 空间使用按空间隔离的会话agent:<agentId>:googlechat:group:<spaceId>，回复进入对应消息线程；
   • 私聊默认并入 agent 的主会话；如需按对端拆分会话，可设置session.dmScope。
5. 私聊默认走pairing认证：未知发送者会收到配对码，管理员执行openclaw pairing approve googlechat <code>批准。
6. 群空间默认要求@提及。插件从 Chat 的USER_MENTION注解中识别指向应用的提及；若识别异常可设置botUser（例如users/1234567890）指定应用的用户资源名。
7. 当从 Google Chat 发起 exec/plugin 审批、且配置了稳定的users/<id>审批人时，OpenClaw 会在来源空间或线程投递原生审批卡片（cardsV2）。卡片按钮携带不透明回调 token；只有原生投递不可用时才回退到手动/approve <id> <decision>提示。

入站持久化（Inbound durability）

请求认证通过后，OpenClaw 会先从存储中移除 add-on 授权对象，并在返回200前持久化排队Google ChatMESSAGE事件。若持久化失败则返回503，让 Google Chat 重试，避免确认一个可能丢失的事件。持久化成功的200响应带有x-openclaw-delivery-accepted: durable标记；非消息类 action 的 ack 与错误响应不带该标记，反向代理可据此区分"持久化确认"与普通200。

待处理或可重试的消息在 Gateway 重启后仍存活，并按空间保持串行化处理；插件利用 Google Chat 消息资源名去重，避免在完成记录存在期间产生重复队列条目。非消息类 action 仍走原有分离的 webhook 路径，不享受该持久化队列保证。队列到 agent 边界之间为至少一次投递，因此交接期间崩溃可能重放一次回合。

Targets：投递与白名单标识

投递与 allowlist 使用的目标标识（对应 src/targets.ts 附近的归一化逻辑，源码中normalizeGoogleChatTarget、isGoogleChatSpaceTarget、isGoogleChatUserTarget等实现见 src/channel.deps.runtime.ts）：

• 私聊：users/<userId>（推荐）。
• 空间：spaces/<spaceId>。
• 裸邮箱name@example.com是可变的，仅当channels.googlechat.dangerouslyAllowNameMatching: true时用于 allowlist 匹配。
• 已废弃：users/<email>会被当作用户 id，而非邮箱白名单条目。
• 前缀googlechat:、google-chat:、gchat:均被接受并在匹配前剥离。

配置要点（Config highlights）

完整配置示例（JSON5）：

{ channels: { googlechat: { enabled: true, serviceAccountFile: "/path/to/service-account.json", // 或 serviceAccount: { source: "file", provider: "filemain", id: "/channels/googlechat/serviceAccount" } audienceType: "app-url", audience: "https://gateway.example.com/googlechat", appPrincipal: "123456789012345678901", // add-on 校验专用；数字型 OAuth client 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: "Short answers only.", }, }, typingIndicator: "message", mediaMaxMb: 20, }, }, }

要点说明：

• 服务账号凭据：serviceAccountFile（路径）或serviceAccount（内联 JSON 字符串、对象，或 env/file/exec/store 类型的 SecretRef）。环境变量GOOGLE_CHAT_SERVICE_ACCOUNT（内联 JSON）与GOOGLE_CHAT_SERVICE_ACCOUNT_FILE（路径）仅作用于默认账号。多账号场景使用channels.googlechat.accounts.<id>，键名相同，支持每账号独立的serviceAccountSecretRef。
• 策略继承：账号省略dmPolicy、groupPolicy时继承渠道根配置；显式账号策略优先。根默认分别为pairing与allowlist。accounts.default中的共享设置优先级低于根；其凭据、enabled、dangerouslyAllowNameMatching不会被子账号继承。
• Webhook 路径：未设置webhookPath时默认/googlechat；也可用webhookUrl提供路径。
• 群组键：必须是稳定的空间 id（spaces/<spaceId>）。显示名作为键已废弃，会记录相应日志。
• dangerouslyAllowNameMatching：重新启用可变的邮箱主体匹配用于 allowlist（break-glass 兼容模式）；doctor 会对邮箱条目给出警告。
• 动作支持：Google Chat 反应（reaction）动作不开放——插件使用服务账号认证，而 reaction 端点需要用户认证。遗留的不支持反应设置可用openclaw doctor --fix移除。消息动作仅暴露文本send；附件上传需要用户认证，因此出站文件上传不开放。
• typingIndicator：message（默认）先发送_<Bot> is typing..._占位消息并在首个回复时编辑替换；none关闭；reaction需要用户 OAuth，在服务账号认证下会记录错误并回退为message。
• 入站附件：每条消息的第一个附件会通过 Chat API 下载进入媒体管线，受mediaMaxMb（默认 20）限制。Google Drive 文件不下载，agent 会收到"附件不可用"提示并要求直接上传文件；其他不支持的附件来源同理。多条附件会附带未处理附件数量的计数提示；超限附件保留其大小限制提示。
• 机器人消息：默认忽略机器人账号发送的消息。设置allowBots: true后，接受的机器人消息走共享的机器人循环保护机制（bot-loop-protection）：配置channels.defaults.botLoopProtection，再用channels.googlechat.botLoopProtection或channels.googlechat.groups.<space>.botLoopProtection覆盖。
• 自定义 emoji 列表不可用：Google Chat 的customEmojis.list端点需要用户认证（chat.customemojis或chat.customemojis.readonlyscope），而本插件仅以服务账号 +chat.botscope 认证，无法访问该端点。
• 密钥引用细节参见 Secrets Management。

排障指南

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. 配置修改后未重启网关：

   openclaw gateway restart

验证渠道是否在运行：

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

其他常见问题

• openclaw channels status --probe可暴露认证错误与缺失的 audience 配置（audience与audienceType都必填）。
• 若收不到消息，确认 Chat 应用的 webhook URL 与 trigger 配置正确。
• 若被 @提及门槛挡住回复，将botUser设为应用的用户资源名，并检查requireMention。
• 发送测试消息时执行openclaw logs --follow，可确认请求是否到达网关。

相关资源

• 渠道总览 —— OpenClaw 支持的全部渠道
• 渠道路由 —— 消息的会话路由
• 网关配置
• 配对机制 —— 私聊认证与配对流程
• 网络暴露与安全加固

【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 🦞项目地址: https://gitcode.com/GitHub_Trending/cl/openclaw