OpenAB Google Chat Bundle

一鍵部署的 OpenAB Google Chat bot — bot agent 與 gateway 打包在一起，貼上 Service Account JSON、在 Google Cloud Console 設定一次 App URL 即可。

前置需求：Google Workspace 帳號（Business / Enterprise 方案）。消費者 @gmail.com 帳號無法建立 Google Chat App。 同時需要可在 Google Cloud Console 啟用 Chat API 並建立 service account 的專案存取權。

部署內容

服務	用途	公開
openab	執行 Kiro CLI 的 OAB agent	否
openab-gateway	Google Chat 事件 → WebSocket 橋接	是（自動 HTTPS）

無需共用 PVC、無需手動修改 config.toml。Agent 的 config.toml 在首次啟動時自動生成，gateway URL 已預先設為 ws://openab-gateway:8080/ws、platform = "googlechat"。

GOOGLE_CHAT_ENABLED=true 與 GOOGLE_CHAT_AUDIENCE（JWT 驗證的 audience）由 bundle 自動設定，無需手動輸入。

設定步驟

1. 啟用 Google Chat API + 建立 Service Account

1. 開 Google Cloud Console → 選擇或建立專案。
2. APIs & Services → Library → 搜 Google Chat API → Enable。
3. APIs & Services → Credentials → + CREATE CREDENTIALS → Service account → 填名稱 → CREATE AND CONTINUE（不需賦予 role）→ DONE。
4. 點剛建立的 service account → Keys tab → ADD KEY → Create new key → JSON → Create。會下載一個 JSON 檔。
5. 開 JSON 檔，複製全部內容，貼到 Service Account JSON（Zeabur UI 會處理單行）。

2. （選填）取得 Kiro API Key

如果你有付費的 Kiro 訂閱，前往 kiro.dev → Settings → API Keys 建立 key，填入 KIRO_API_KEY。免費方案跳過此步驟，於步驟 4 部署後再認證。

3. 部署

點擊部署。系統會自動分配公開 HTTPS 網域給 gateway 服務。

4. 透過 Device Flow 認證 Kiro（僅免費方案）

若步驟 2 已填入 KIRO_API_KEY，跳過此步驟。

待 openab 服務啟動後，於 Zeabur Dashboard 開啟該服務的終端機，執行：

runuser -u agent -- kiro-cli login --use-device-flow

依照畫面顯示的 URL 與 code 完成瀏覽器授權。

5. 於 Google Cloud Console 設定 Chat App

Google Chat App URL 必須在 GCP 手動設定——沒有 API。

1. 打開 openab-gateway 服務頁面 → 查自動分配的網域。
2. 完整 App URL 為：https://<你的_GATEWAY_網域>/webhook/googlechat
3. 回 Google Cloud Console → APIs & Services → Google Chat API → Configuration：
   • App name / Avatar URL / Description：自選。
   • Functionality：勾選 Receive 1:1 messages 與 Join spaces and group conversations。
   • Connection settings：選 App URL → 貼上 URL → Authentication Audience 保持 HTTP Endpoint URL（預設）。
   • Visibility：限制 Workspace 網域或特定使用者。
4. SAVE。

openab-gateway 服務 Instructions 區會顯示已自動填好的完整 App URL，可直接複製。

6. 測試

在 Google Chat（mail.google.com/chat 或獨立 app）內以 app 名稱搜尋 → 開 DM → 發訊息。Gateway 驗證 JWT → 透過 WebSocket 轉發給 OAB → OAB 透過 service account 呼叫 Chat REST API 回覆。

Space / group chat：從 space 的 Apps & integrations 選單邀請 app 加入。

自訂設定

• /home/agent/.config/openab/config.toml — OAB 設定（sessions、reactions 等）。首次啟動時從內建範本建立，[gateway] 區塊已預先設好。如需重建，刪除檔案後重啟服務。
• 映像標籤 — bot 追蹤 floating stable 標籤（ghcr.io/openabdev/openab:stable），OpenAB 推出新穩定版時自動更新。Gateway 目前 pin 在 ghcr.io/openabdev/openab-gateway:0.5.1（尚未發布 :stable 標籤）。可至 Zeabur Dashboard → 服務 → 設定修改映像標籤。

JWT 驗證如何運作

Google Chat 對每個 incoming POST 都會簽 JWT。Gateway：

1. 對 Google public JWKS 驗證 JWT 簽章。
2. 驗證 iss claim 為 [email protected]。
3. 驗證 aud claim 與 GOOGLE_CHAT_AUDIENCE 相符（bundle 自動設為 ${gateway-url}/webhook/googlechat）。

任何被竄改或 replay 的 request 都會被其中一項驗證攔下，回 401。

想換不同的 agent 後端？

本 bundle 預設使用 Kiro。若想用 Claude / Codex / Cursor / Gemini / OpenCode / Hermes / Grok，請改部署對應的 bot template 搭配獨立的 OpenAB Gateway。

想用其他通訊平台？

請參考 OpenAB Telegram Bundle / Feishu Bundle / LINE Bundle / WeCom Bundle / MS Teams Bundle 或獨立的 OpenAB Gateway。

連結

• OpenAB GitHub
• Google Chat 設定指南
• Google Chat API 文件
• 獨立 OpenAB Gateway 模板