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/並更新環境變量。