OpenFang 多渠道適配器配置指南

12分鐘閱讀

OpenFang 支援 40 餘種渠道適配器。本文詳解六種常用適配器的完整配置：CLI、WhatsApp Business API、Telegram Bot、Discord、Slack Socket Mode 和 Web Chat 掛件。包含多渠道並行運行、上下文共享、安全加固和狀態監控的完整方案。

OpenFang 多渠道適配器配置指南：讓你的 Agent 無處不在

Slug: openfang-channel-setup-guide 分類: usage-guides (使用指南) 目標關鍵詞: OpenFang 渠道配置, OpenFang 適配器, OpenFang WhatsApp Telegram 搜尋意圖: 資訊型（用戶想將 Agent 接入不同平台） 目標字數: ~1800 字 語言: tw

什麼是渠道適配器？

渠道適配器（Channel Adapter）是 OpenFang 與外部平台之間的橋樑。每個適配器負責將外部平台的消息轉換為 OpenFang 可理解的統一格式，並將 Agent 的回應轉回平台的原生格式。

OpenFang 的設計哲學是"一次編寫 Agent 邏輯，在 40+ 個平台上運行"。你不需要為每個平台重寫 Agent——只需配置對應的渠道適配器即可。

目前 OpenFang 支援 40 餘種渠道適配器，覆蓋即時通訊、社群媒體、協作工具、郵件和自定義 API 等類別。

渠道適配器的核心概念

所有渠道適配器共享以下設計原則：

  • 統一消息格式：無論從哪個渠道來的消息，都被轉換為標準的 OpenFang Message 格式
  • 獨立沙箱：每個渠道適配器運行在獨立沙箱中，一個渠道的故障不影響其他渠道
  • 熱載入：添加或修改渠道配置後無需重啟 Agent
  • 速率限制：內建速率限制保護，避免觸發平台 API 限制

常用渠道適配器配置

CLI 適配器

CLI 是最基礎的適配器，適合開發調試和本地使用：

toml
[channels.cli]enabled = truehistory_size = 1000              # 會話歷史保留條數prompt_style = "rich"            # plain / rich / minimal

CLI 適配器開箱即用，無需額外配置。支援多行輸入、指令補全和語法高亮。

WhatsApp 適配器

WhatsApp 是全球使用最廣泛的即時通訊工具之一。透過 WhatsApp Business API，你的 Agent 可以直接與用戶在 WhatsApp 中互動：

toml
[channels.whatsapp]enabled = trueapi_version = "v18.0"phone_number_id = "${WA_PHONE_NUMBER_ID}"access_token = "${WA_ACCESS_TOKEN}"verify_token = "${WA_VERIFY_TOKEN}"[channels.whatsapp.features]media_support = true             # 支援發送圖片/檔案reply_buttons = true             # 支援互動按鈕max_message_length = 4096typing_indicator = true          # 顯示"正在輸入..."

配置步驟：

  1. 在 Meta for Developers 建立 WhatsApp 應用
  2. 獲取 Phone Number ID 和 Access Token
  3. 配置 Webhook URL（你的 OpenFang 伺服器位址 + /webhook/whatsapp）
  4. 在 OpenFang 配置中填入以上資訊

Telegram 適配器

Telegram 是技術社群最受歡迎的通訊平台之一，配置簡單，API 友善：

toml
[channels.telegram]enabled = truebot_token = "${TELEGRAM_BOT_TOKEN}"allowed_users = []               # 留空 = 所有用戶可存取admin_users = ["@your_username"][channels.telegram.features]inline_queries = true            # 支援內聯查詢markdown_support = truefile_upload = truemax_file_size_mb = 50

配置步驟：

  1. 在 Telegram 中與 @BotFather 對話建立 Bot
  2. 獲取 Bot Token
  3. 將 Token 填入設定檔

Discord 適配器

Discord 適配器支援伺服器（Guild）和私訊兩種模式：

toml
[channels.discord]enabled = truebot_token = "${DISCORD_BOT_TOKEN}"application_id = "${DISCORD_APP_ID}"[channels.discord.guilds]server_ids = ["1234567890"]      # 允許的伺服器 ID[channels.discord.features]slash_commands = true            # 支援斜線指令thread_support = true            # 支援討論串embed_messages = true            # 富文本嵌入消息

Slack 適配器

適合企業團隊協作場景：

toml
[channels.slack]enabled = truebot_token = "${SLACK_BOT_TOKEN}"signing_secret = "${SLACK_SIGNING_SECRET}"app_token = "${SLACK_APP_TOKEN}"[channels.slack.features]socket_mode = true               # 使用 Socket Mode（推薦，無需公網 URL）thread_replies = truereaction_feedback = true

Slack 推薦使用 Socket Mode，無需配置公網可存取的 Webhook URL，適合內網部署。

Web Chat 適配器

在你的網站上嵌入一個 OpenFang 對話視窗：

toml
[channels.webchat]enabled = trueport = 3000cors_origins = ["https://your-site.com"][channels.webchat.ui]theme = "auto"                   # light / dark / autologo_url = "/assets/agent-logo.png"welcome_message = "你好！我是 OpenFang Agent，有什麼可以幫助你的？"placeholder = "輸入你的問題..."

配置完成後，在你的網頁中添加：

html
<script src="https://your-server:3000/widget.js"></script><script>OpenFangWidget.init({ position: 'bottom-right' })</script>

多渠道同時運行

OpenFang 的架構天然支援多渠道並行。Agent 核心維護一個統一的會話狀態，所有渠道共享上下文：

toml
# 同時啟用多個渠道[channels]cli.enabled = truewhatsapp.enabled = truetelegram.enabled = truediscord.enabled = truewebchat.enabled = true[channels.routing]strategy = "context_aware"       # round_robin / context_aware / prioritypreserve_context = true          # 同用戶跨渠道保持上下文

context_aware 路由策略意味著：如果用戶在 WhatsApp 上開始了對話，之後切換到 Telegram 繼續，Agent 會自動載入之前的上下文。

渠道安全配置

多渠道意味著更多攻擊面。OpenFang 提供了細粒度的渠道安全控制：

toml
[channels.security]per_user_rate_limit = 30         # 每用戶每分鐘最多 30 條消息per_channel_rate_limit = 100     # 每渠道每分鐘最多 100 條消息require_auth = ["discord", "slack"]public_channels = ["webchat"]authenticated_channels = ["whatsapp", "telegram", "discord", "slack"][channels.security.content_filter]block_urls = falseblock_attachments = falsemax_prompt_length = 4000

關鍵安全建議：

  • 公網可存取的渠道（Web Chat）啟用嚴格的速率限制
  • 生產環境中，非 CLI 渠道都應要求用戶認證
  • 定期審計渠道存取日誌

渠道狀態監控

bash
# 查看所有渠道狀態openfang channels list# 輸出範例：# Channel        Status    Messages/24h   Errors   Latency# cli            ✅ active       0           0         -# telegram       ✅ active     156          2       120ms# whatsapp       ✅ active      89          0       250ms# discord        ⚠️ degraded    43          5       500ms# webchat        ✅ active      12          0        45ms# 重啟指定渠道openfang channels restart discord# 查看渠道詳細日誌openfang channels logs telegram --level debug

常見問題

添加新渠道需要重啟 Agent 嗎？
不需要。OpenFang 支援熱載入渠道配置：

``bash
openfang channels reload
``

不同渠道的對話歷史是互通的嗎？
預設是互通的。同一用戶的對話歷史在所有渠道間共享，切換渠道不會丟失上下文。如果你需要渠道隔離，可以配置 preserve_context = false。
WhatsApp 適配器需要 WhatsApp Business 帳號嗎？
是的。WhatsApp 適配器使用 WhatsApp Business Platform API，需要一個經過驗證的 Business 帳號。個人 WhatsApp 帳號不支援 API 接入。
如何添加自定義渠道適配器？
OpenFang 提供了 Channel SDK。實現 ChannelAdapter trait 即可建立自定義適配器：

``rust
use openfang::channels::{ChannelAdapter, Message};

struct MyCustomChannel;
impl ChannelAdapter for MyCustomChannel {
async fn receive(&self) -> Vec<Message> { /* ... */ }
async fn send(&self, msg: Message) -> Result<()> { /* ... */ }
}
``

下一步

  • OpenFang 自動化工作流搭建指南：將多渠道 Agent 編排為自動化流程
  • OpenFang 安全最佳實踐：保護你的多渠道 Agent 部署