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 字 语言: zh

什么是渠道适配器？

渠道适配器（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 部署