MINARAGoogle Chat
通过服务账号 JWT 验证接入 Google Workspace Chat，入站活动由 [email protected] 签名。
🟡 出站通过服务账号，入站经 JWT 验证 适用于 Google Workspace 部署。出站时从服务账号 JSON 密钥生成短效访问 token；入站时验证每条 POST 是否由
[email protected]签名。
功能概览
- 出站文本：通过
POST https://chat.googleapis.com/v1/{space}/messages发送{text}，支持话题串（thread.name）。 - 入站 webhook：路径为
/webhooks/google-chat。Google 为每条入站请求附加由[email protected]签发的 bearer JWT。 - 访问 token 缓存：TTL 1 小时，提前 5 分钟刷新。
- 本版本仅支持纯文本。 Cards v2、对话框、斜杠命令及附件下载暂未实现。
- 每条消息文本上限 4096 字符。
配置步骤
1. 创建 Google Cloud 项目与服务账号
- 进入 Google Cloud Console，选择（或新建）一个用于 Chat 应用的项目。
- 进入"APIs & Services"→"Enable APIs"，启用 Google Chat API。
- 进入"IAM & Admin"→"Service Accounts"→"Create Service Account"，填写名称（如
minara-chat-bot）。 - 创建完成后，打开该服务账号，进入"Keys"标签，点击"Add Key"→"JSON"，保存下载的文件。
2. 配置 Chat 应用
- 在同一 Google Cloud 项目中，进入 Google Chat API→"Configuration"标签。
- 填写 App name、Avatar URL、Description，内容合理即可。
- Functionality：勾选"Receive 1:1 messages"与"Join spaces and group conversations"。
- Connection settings：选择"App URL"，将端点设为
https://<your-host>/webhooks/google-chat。 - Authentication Audience：选择一项并记录：
- "Project Number"：audience 为 12 位 GCP 项目编号。
- "HTTP endpoint URL"：audience 为你的端点 URL。
- Permissions：选择"Specific people and groups"或你的域。
3. 将服务账号 JSON 放入沙盒
CLAUDE.md §4 要求服务账号密钥必须存放在 data / 沙盒目录下。将下载的 JSON 移动到 ~/.minara/sandbox/（或你的 MINARA_DATA_DIR 对应路径）：
mv ~/Downloads/<project>-<hash>.json ~/.minara/sandbox/google-chat-sa.json
chmod 600 ~/.minara/sandbox/google-chat-sa.json4. 获取默认 Space
将 Chat 应用添加到某个 Space（或从测试账号私信该机器人）后，从 URL 中获取 Space 资源名，格式为 spaces/AAAA1234567，保存为 GOOGLE_CHAT_DEFAULT_SPACE_ID。
5. 配置 Minara
minara auth messaging add
# 从列表中选择 `google_chat`。或直接设置环境变量：
GOOGLE_CHAT_SERVICE_ACCOUNT_JSON_PATH=/Users/you/.minara/sandbox/google-chat-sa.json
GOOGLE_CHAT_DEFAULT_SPACE_ID=spaces/AAAA1234567
GOOGLE_CHAT_AUDIENCE=1234567890GOOGLE_CHAT_AUDIENCE 必须与 Workspace 控制台中的值完全一致。若控制台选择了"Project Number"，填纯数字；若选择了"HTTP endpoint URL"，填完整 URL（含控制台显示的末尾斜杠）。
6. 测试
minara auth messaging test google_chat入站 webhook
Google 入站 JWT 包含以下声明：
| 声明 | 预期值 |
|---|---|
iss（签发方） | [email protected] |
aud（audience） | 与 GOOGLE_CHAT_AUDIENCE 一致 |
| 签名 | RS256，通过 https://www.googleapis.com/service_accounts/v1/jwk/[email protected] 发布的 X.509 证书验证 |
| 时钟偏差 | ±5 分钟 |
JWKS 缓存 24 小时；kid 未命中时自动处理密钥轮换。
接受的事件类型：MESSAGE（用户在应用所在 Space 中发言）。其他类型（ADDED_TO_SPACE、REMOVED_FROM_SPACE、CARD_CLICKED）将被丢弃。
限制与注意事项
GOOGLE_CHAT_AUDIENCE须逐字节匹配。 入站 401 最常见的原因是该环境变量与控制台设置不一致。若选择"Project Number"，必须填写字面数字字符串，不得有前导零。- 服务账号 JSON 路径须在沙盒内。 依据 CLAUDE.md §4（仅允许沙盒内文件引用）。工厂函数在启动时读取该文件；轮换密钥需重启服务。
- 一个 JSON 对应一个 audience。 若在控制台更改"Authentication Audience"，必须在同一小时内同步更新
GOOGLE_CHAT_AUDIENCE。 - 不支持卡片。 Cards v2 消息与对话框暂未在任何方向上接入。
故障排查
"401 Unauthorized on inbound"
GOOGLE_CHAT_AUDIENCE与控制台不一致。打开 Chat API Configuration 页面，逐字复制 audience 值。
"Missing required scope" on outbound
- 该服务账号缺少
https://www.googleapis.com/auth/chat.bot权限范围。工厂函数会自动请求该范围；请确认服务账号所属项目已启用 Chat API。
"Service-account JSON not found"
GOOGLE_CHAT_SERVICE_ACCOUNT_JSON_PATH指向沙盒外路径，或文件不存在。请将文件移至~/.minara/sandbox/并更新环境变量。