Hướng dẫn cấu hình bộ điều hợp đa kênh OpenFang: Đưa Agent của bạn đến mọi nơi

Slug: openfang-channel-setup-guide Danh mục: usage-guides (Hướng dẫn sử dụng) Từ khóa mục tiêu: Cấu hình kênh OpenFang, Bộ điều hợp OpenFang, OpenFang WhatsApp Telegram Mục đích tìm kiếm: Thông tin (Người dùng muốn kết nối Agent với các nền tảng khác nhau) Số từ mục tiêu: ~1800 từ Ngôn ngữ: vi

Bộ điều hợp kênh là gì?

Bộ điều hợp kênh (Channel Adapter) đóng vai trò là cầu nối giữa OpenFang và các nền tảng bên ngoài. Mỗi bộ điều hợp chịu trách nhiệm chuyển đổi tin nhắn từ nền tảng bên ngoài sang định dạng chuẩn mà OpenFang có thể hiểu được, đồng thời chuyển đổi phản hồi của Agent trở lại định dạng gốc của nền tảng đó.

Triết lý thiết kế của OpenFang là "Viết logic Agent một lần, chạy trên 40+ nền tảng". Bạn không cần phải viết lại Agent cho từng nền tảng—chỉ cần cấu hình bộ điều hợp kênh tương ứng là đủ.

Hiện tại, OpenFang hỗ trợ hơn 40 bộ điều hợp kênh, bao gồm các danh mục như nhắn tin tức thời, mạng xã hội, công cụ cộng tác, email và API tùy chỉnh.

Các khái niệm cốt lõi về bộ điều hợp kênh

Tất cả các bộ điều hợp kênh đều chia sẻ các nguyên tắc thiết kế sau:

• Định dạng tin nhắn thống nhất: Dù tin nhắn đến từ kênh nào, chúng đều được chuyển đổi sang định dạng Message chuẩn của OpenFang.
• Sandbox độc lập: Mỗi bộ điều hợp kênh chạy trong một sandbox riêng biệt, sự cố ở một kênh không ảnh hưởng đến các kênh khác.
• Tải lại nóng (Hot-loading): Không cần khởi động lại Agent sau khi thêm hoặc sửa đổi cấu hình kênh.
• Giới hạn tốc độ (Rate limiting): Tích hợp sẵn tính năng giới hạn tốc độ để tránh vi phạm giới hạn API của nền tảng.

Cấu hình các bộ điều hợp kênh phổ biến

Bộ điều hợp CLI

CLI là bộ điều hợp cơ bản nhất, phù hợp cho việc phát triển, gỡ lỗi và sử dụng cục bộ:

[channels.cli]enabled = truehistory_size = 1000              # Số lượng lịch sử hội thoại được lưu giữprompt_style = "rich"            # plain / rich / minimal

Bộ điều hợp CLI hoạt động ngay lập tức mà không cần cấu hình thêm. Hỗ trợ nhập liệu nhiều dòng, tự động hoàn thành lệnh và tô sáng cú pháp.

Bộ điều hợp WhatsApp

WhatsApp là một trong những công cụ nhắn tin tức thời phổ biến nhất thế giới. Thông qua WhatsApp Business API, Agent của bạn có thể tương tác trực tiếp với người dùng trên WhatsApp:

[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             # Hỗ trợ gửi ảnh/tệpreply_buttons = true             # Hỗ trợ nút tương tácmax_message_length = 4096typing_indicator = true          # Hiển thị "Đang nhập..."

Các bước cấu hình:

1. Tạo ứng dụng WhatsApp tại Meta for Developers
2. Lấy Phone Number ID và Access Token
3. Cấu hình Webhook URL (Địa chỉ máy chủ OpenFang của bạn + /webhook/whatsapp)
4. Nhập các thông tin trên vào cấu hình OpenFang

Bộ điều hợp Telegram

Telegram là một trong những nền tảng liên lạc được cộng đồng kỹ thuật ưa chuộng nhất, cấu hình đơn giản và API thân thiện:

[channels.telegram]enabled = truebot_token = "${TELEGRAM_BOT_TOKEN}"allowed_users = []               # Để trống = tất cả người dùng đều có thể truy cậpadmin_users = ["@your_username"][channels.telegram.features]inline_queries = true            # Hỗ trợ truy vấn nội dòngmarkdown_support = truefile_upload = truemax_file_size_mb = 50

Các bước cấu hình:

1. Trò chuyện với @BotFather trên Telegram để tạo Bot
2. Lấy Bot Token
3. Nhập Token vào tệp cấu hình

Bộ điều hợp Discord

Bộ điều hợp Discord hỗ trợ cả hai chế độ: Máy chủ (Guild) và Tin nhắn riêng (DM):

[channels.discord]enabled = truebot_token = "${DISCORD_BOT_TOKEN}"application_id = "${DISCORD_APP_ID}"[channels.discord.guilds]server_ids = ["1234567890"]      # ID máy chủ được phép[channels.discord.features]slash_commands = true            # Hỗ trợ lệnh gạch chéothread_support = true            # Hỗ trợ luồng thảo luậnembed_messages = true            # Tin nhắn nhúng phong phú

Bộ điều hợp Slack

Phù hợp cho các kịch bản cộng tác nhóm doanh nghiệp:

[channels.slack]enabled = truebot_token = "${SLACK_BOT_TOKEN}"signing_secret = "${SLACK_SIGNING_SECRET}"app_token = "${SLACK_APP_TOKEN}"[channels.slack.features]socket_mode = true               # Sử dụng Socket Mode (Khuyên dùng, không cần URL công khai)thread_replies = truereaction_feedback = true

Slack khuyến nghị sử dụng Socket Mode, không cần cấu hình Webhook URL có thể truy cập công khai, rất phù hợp cho việc triển khai trong mạng nội bộ.

Bộ điều hợp Web Chat

Nhúng cửa sổ trò chuyện OpenFang vào trang web của bạn:

[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 = "Xin chào! Tôi là Agent của OpenFang, tôi có thể giúp gì cho bạn?"placeholder = "Nhập câu hỏi của bạn..."

Sau khi cấu hình xong, hãy thêm đoạn mã sau vào trang web của bạn:

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

Vận hành đa kênh đồng thời

Kiến trúc của OpenFang hỗ trợ đa kênh song song một cách tự nhiên. Cốt lõi của Agent duy trì một trạng thái hội thoại thống nhất, tất cả các kênh đều chia sẻ ngữ cảnh:

# Kích hoạt nhiều kênh cùng lúc[channels]cli.enabled = truewhatsapp.enabled = truetelegram.enabled = truediscord.enabled = truewebchat.enabled = true[channels.routing]strategy = "context_aware"       # round_robin / context_aware / prioritypreserve_context = true          # Duy trì ngữ cảnh giữa các kênh cho cùng một người dùng

Chiến lược định tuyến context_aware có nghĩa là: Nếu người dùng bắt đầu cuộc trò chuyện trên WhatsApp và sau đó chuyển sang Telegram, Agent sẽ tự động tải ngữ cảnh trước đó.

Cấu hình bảo mật kênh

Đa kênh đồng nghĩa với nhiều bề mặt tấn công hơn. OpenFang cung cấp khả năng kiểm soát bảo mật kênh chi tiết:

[channels.security]per_user_rate_limit = 30         # Tối đa 30 tin nhắn mỗi người dùng mỗi phútper_channel_rate_limit = 100     # Tối đa 100 tin nhắn mỗi kênh mỗi phútrequire_auth = ["discord", "slack"]public_channels = ["webchat"]authenticated_channels = ["whatsapp", "telegram", "discord", "slack"][channels.security.content_filter]block_urls = falseblock_attachments = falsemax_prompt_length = 4000

Lời khuyên bảo mật quan trọng:

• Kích hoạt giới hạn tốc độ nghiêm ngặt cho các kênh có thể truy cập công khai (Web Chat).
• Trong môi trường sản xuất, tất cả các kênh không phải CLI đều nên yêu cầu người dùng xác thực.
• Kiểm tra nhật ký truy cập kênh định kỳ.

Giám sát trạng thái kênh

# Xem trạng thái tất cả các kênhopenfang channels list# Ví dụ đầu ra:# 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# Khởi động lại kênh cụ thểopenfang channels restart discord# Xem nhật ký chi tiết của kênhopenfang channels logs telegram --level debug

Câu hỏi thường gặp

Bước tiếp theo

• Hướng dẫn xây dựng quy trình làm việc tự động hóa OpenFang: Sắp xếp Agent đa kênh thành các quy trình tự động.
• Các phương pháp bảo mật tốt nhất cho OpenFang: Bảo vệ việc triển khai Agent đa kênh của bạn.