OpenAB Gateway

OpenAB Gateway 是獨立的 Webhook 橋接服務，透過 WebSocket 將通訊平台連接到任何正在運行的 OpenAB 實例。

Telegram     ──POST──▶ ┌──────────────────┐
LINE         ──POST──▶ │                  │
Feishu/Lark  ──POST──▶ │  OpenAB Gateway  │ ◀──WebSocket── OAB Pod
Google Chat  ──POST──▶ │     :8080        │   （OAB 主動對外連線）
MS Teams     ──POST──▶ │                  │
                       └──────────────────┘

將此 template 部署於現有 OpenAB 服務（Claude、Cursor、Codex 等）旁，無需重新部署 OAB 即可新增通訊平台支援。可同時啟用一或多個平台，未填寫的留空即可停用。

支援平台

平台	設定章節	必填變數
Telegram	#telegram	TELEGRAM_BOT_TOKEN
LINE	#line	LINE_CHANNEL_SECRET、LINE_CHANNEL_ACCESS_TOKEN
Feishu / Lark	#feishu	FEISHU_APP_ID、FEISHU_APP_SECRET
Google Chat	#google-chat	GOOGLE_CHAT_ENABLED=true、GOOGLE_CHAT_SA_KEY_JSON
MS Teams	#teams	TEAMS_APP_ID、TEAMS_APP_SECRET

前置條件

• 同一個 Zeabur 專案中已有正在運行的 OpenAB 服務
• 以上支援平台至少設定一個

設定步驟

1. 建立 Telegram Bot

1. 在 Telegram 開啟 @BotFather
2. 發送 /newbot 並依照提示操作
3. 複製 Bot Token（例如 123456:ABC-DEF...）→ 貼到 Telegram Bot Token
4. 選填：發送 /setprivacy → Disable，讓 Bot 可以看到群組中所有訊息

2. 部署

填入想啟用平台的 Token 後點擊部署。系統會自動分配公開 HTTPS 網域。可以只啟用 Telegram、只啟用 LINE，或兩者同時啟用。

3. 註冊 Telegram Webhook

部署完成後，向 Telegram 註冊你的 Gateway URL（替換 YOUR_TOKEN、YOUR_DOMAIN，選填 YOUR_SECRET）：

# 不帶 webhook secret（較簡單）
curl "https://api.telegram.org/botYOUR_TOKEN/setWebhook?url=https://YOUR_DOMAIN/webhook/telegram"

# 帶 webhook secret（建議 — 與 TELEGRAM_SECRET_TOKEN 一致）
curl "https://api.telegram.org/botYOUR_TOKEN/setWebhook?url=https://YOUR_DOMAIN/webhook/telegram&secret_token=YOUR_SECRET"

預期回應：{"ok":true,"result":true,"description":"Webhook was set"}

4. 設定 OAB 使用 Gateway

在同一個 Zeabur 專案的 OpenAB 服務中，編輯 /home/agent/.config/openab/config.toml 並加入：

[gateway]
url = "ws://openab-gateway:8080/ws"

儲存後重啟 OpenAB 服務。OAB 會主動對外連線到 Gateway，OAB 本身不需要開放任何 inbound 連接埠。

內部 Hostname： openab-gateway 在同一個 Zeabur 專案內透過內部 DNS 解析。若你的 Gateway 服務名稱不同，請改用對應名稱。

5. 測試

向你的 Telegram Bot 發送訊息。Gateway 收到後透過 WebSocket 轉發給 OAB，OAB 處理後透過 Gateway 回覆。

LINE 設定（選填）

1. 建立 LINE 官方帳號

1. 前往 LINE 官方帳號管理後台 建立帳號
2. 設定 → Messaging API → 啟用 Messaging API
3. 開啟 LINE Developers Console → 你的 Channel：
   • Basic settings → Channel secret → 複製 → 貼到 LINE Channel Secret
   • Messaging API → Channel access token → Issue → 複製 → 貼到 LINE Channel Access Token

2. 設定 Webhook URL

在 LINE Developers Console → Messaging API 頁籤：

1. Webhook URL → 編輯 → 輸入：https://YOUR_DOMAIN/webhook/line
2. Use webhook → 開啟
3. Auto-reply messages → 關閉
4. 點擊 Verify

3. 設定 OAB 使用 LINE

在 config.toml 的 gateway 區塊加入 platform = "line"：

[gateway]
url = "ws://openab-gateway:8080/ws"
platform = "line"

儲存後重啟 OpenAB 服務。

Feishu / Lark 設定（選填）

1. 在 open.feishu.cn（中國版）或 open.larksuite.com（國際版 Lark）建立應用。
2. 啟用 機器人 能力。
3. 事件訂閱 → 選 長連線（Long Connection / WebSocket） 模式 → 加入 im.message.receive_v1 事件。
4. 權限管理 → 授予：im:message、im:message:send_as_bot、contact:user.base:readonly。
5. 從 憑證與基礎資訊 複製 App ID → FEISHU_APP_ID、App Secret → FEISHU_APP_SECRET。
6. 使用 Lark 國際版時，將 FEISHU_DOMAIN 設為 lark；中國版飛書保持 feishu。

預設使用 WebSocket 連線模式，Gateway 會主動對外連線到 Feishu，不需要 公開 webhook URL。

接著設定 OAB 使用 Gateway，並指定 platform = "feishu"：

[gateway]
url = "ws://openab-gateway:8080/ws"
platform = "feishu"

完整指南：docs/feishu.md

Google Chat 設定（選填）

需要 Google Workspace 付費帳號（Business / Enterprise）。一般 @gmail.com 個人帳號無法建立 Google Chat 應用。

1. 在 Google Cloud Console 啟用 Google Chat API。
2. APIs & Services → Google Chat API → Configuration：
   • Connection settings → App URL → 填 https://YOUR_DOMAIN/webhook/googlechat
   • Authentication Audience → 保持預設 HTTP Endpoint URL
3. 建立 Service Account（不需要授予角色），下載 JSON Key。
4. 填入環境變數：
   • GOOGLE_CHAT_ENABLED=true
   • GOOGLE_CHAT_SA_KEY_JSON → 貼上完整的 Service Account JSON（單行）
   • GOOGLE_CHAT_AUDIENCE → https://YOUR_DOMAIN/webhook/googlechat（建議填入以驗證 JWT）

OAB 端設定 platform = "googlechat"。完整指南：docs/google-chat.md

MS Teams 設定（選填）

1. 在 dev.botframework.com 或透過 Azure Bot Service 註冊 Bot Framework 應用。
2. Messaging endpoint 設為 https://YOUR_DOMAIN/webhook/teams。
3. 從 App registration 取得 App ID → TEAMS_APP_ID，建立 client secret → TEAMS_APP_SECRET。
4. 將 Bot 加入 Teams 租戶，並安裝到頻道或對話。

OAB 端設定 platform = "teams"。完整指南：docs/msteams-selfhosted.md

Webhook 端點

路徑	平台
POST /webhook/telegram	Telegram
POST /webhook/line	LINE
POST /webhook/feishu	Feishu/Lark（僅 webhook 模式；預設使用 WebSocket）
POST /webhook/googlechat	Google Chat
POST /webhook/teams	MS Teams
GET /ws	OAB WebSocket（內部使用）
GET /health	健康檢查

連結

• OpenAB GitHub
• Telegram 設定指南
• LINE 設定指南
• Feishu/Lark 設定指南
• Google Chat 設定指南
• MS Teams 設定指南
• Gateway README