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 CredentialsService Account名称可任意例如openclaw-chat权限与主体principals留空依次Continue、Done。3. 生成并下载 JSON 密钥点击该服务账号 Keys标签 Add KeyCreate new keyJSONCreate下载得到的 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 inYour 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 路径默认/googlechatPOST 事件。将应用加入 Google Chat网关运行且你的邮箱已在可见性列表后打开 Google Chat点击Direct Messages旁的号搜索你配置的App name——由于是私有应用机器人不会出现在 Marketplace 浏览列表中需按名称搜索选中机器人点击Add或Chat发送一条消息即可开始对话。公网 URLWebhook-onlyGoogle Chat Webhook 需要一个公网 HTTPS 端点。出于安全考虑只把/googlechat路径暴露到公网OpenClaw 仪表盘及其他端点保持私有。方案 ATailscale Funnel推荐用 Tailscale Serve 暴露私有仪表盘、用 Funnel 暴露公网 Webhook 路径查看网关绑定地址ss -tlnp | grep 18789记下 IP例如127.0.0.1、0.0.0.0或 Tailscale100.x.x.x地址。仅向 tailnet 暴露仪表盘端口 8443# 绑定 localhost127.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仅公网暴露 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若提示访问输出中的授权 URL 以在本节点启用 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只代理 webhook 路径your-domain.com { reverse_proxy /googlechat* localhost:18789 }your-domain.com/的其他请求将被忽略或返回 404仅your-domain.com/googlechat路由到 OpenClaw。方案 CCloudflare Tunnel配置隧道 ingress 规则仅路由 webhook 路径Path/googlechat-http://localhost:18789/googlechatDefault ruleHTTP 404Not Found工作原理从鉴权到消息路由结合渠道文档docs/channels/googlechat.md与源码结构整体流程如下Google Chat 向网关 webhook 路径 POST JSON仅 POST、要求 JSON 内容类型、按 IP 限流。OpenClaw 在分发前认证每个请求Chat 应用事件携带Authorization: Bearer tokentoken 在完整 body 解析前即被校验Google Workspace Add-on 事件把 token 放在 bodyauthorizationEventObject.systemIdToken中会在更严格的预认证预算16 KB、3 秒下读取并校验。token 依据audienceTypeaudience校验audienceType: app-url→ audience 为你的 HTTPS webhook URLaudienceType: project-number→ audience 为 Cloud 项目编号app-url模式下的 Add-on token 还要求appPrincipal设置为应用的数字型 OAuth 2.0 client ID21 位数字不是邮箱否则校验失败并记录警告日志。消息按空间路由空间使用按空间隔离的会话agent:agentId:googlechat:group:spaceId回复进入对应消息线程私聊默认并入 agent 的主会话如需按对端拆分会话可设置session.dmScope。私聊默认走pairing认证未知发送者会收到配对码管理员执行openclaw pairing approve googlechat code批准。群空间默认要求提及。插件从 Chat 的USER_MENTION注解中识别指向应用的提及若识别异常可设置botUser例如users/1234567890指定应用的用户资源名。当从 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。裸邮箱nameexample.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提供路径。群组键必须是稳定的空间 idspaces/spaceId。显示名作为键已废弃会记录相应日志。dangerouslyAllowNameMatching重新启用可变的邮箱主体匹配用于 allowlistbreak-glass 兼容模式doctor 会对邮箱条目给出警告。动作支持Google Chat 反应reaction动作不开放——插件使用服务账号认证而 reaction 端点需要用户认证。遗留的不支持反应设置可用openclaw doctor --fix移除。消息动作仅暴露文本send附件上传需要用户认证因此出站文件上传不开放。typingIndicatormessage默认先发送_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 处理器未注册。常见原因渠道未配置缺少channels.googlechat配置段。验证openclaw config get channels.googlechat若返回 Config path not found按上文 配置要点 补全配置。插件未启用检查插件状态openclaw plugins list | grep googlechat若显示 disabled在配置中加入plugins.entries.googlechat.enabled: true。配置修改后未重启网关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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考