OpenFang 다중 채널 어댑터 설정 가이드

13분 읽기

OpenFang은 40여 개의 채널 어댑터를 지원합니다. 본 가이드에서는 CLI, WhatsApp Business API, Telegram Bot, Discord, Slack Socket Mode, Web Chat 위젯 등 6가지 주요 어댑터의 상세 설정을 다룹니다. 다중 채널 동시 실행, 컨텍스트 공유, 보안 강화 및 상태 모니터링을 위한 완벽한 솔루션을 제공합니다.

OpenFang 다중 채널 어댑터 설정 가이드: 어디서나 함께하는 Agent

Slug: openfang-channel-setup-guide 분류: usage-guides (사용 가이드) 목표 키워드: OpenFang 채널 설정, OpenFang 어댑터, OpenFang WhatsApp Telegram 검색 의도: 정보형 (사용자가 Agent를 다양한 플랫폼에 연결하고자 함) 목표 글자 수: ~1800자 언어: ko

채널 어댑터란 무엇인가요?

채널 어댑터(Channel Adapter)는 OpenFang과 외부 플랫폼을 연결하는 가교입니다. 각 어댑터는 외부 플랫폼의 메시지를 OpenFang이 이해할 수 있는 표준 형식으로 변환하고, Agent의 응답을 해당 플랫폼의 기본 형식으로 다시 변환하는 역할을 합니다.

OpenFang의 설계 철학은 "Agent 로직을 한 번 작성하여 40개 이상의 플랫폼에서 실행"하는 것입니다. 플랫폼마다 Agent를 다시 작성할 필요 없이, 해당 채널 어댑터만 설정하면 됩니다.

현재 OpenFang은 인스턴트 메시징, 소셜 미디어, 협업 도구, 이메일 및 사용자 정의 API 등 40여 개의 채널 어댑터를 지원합니다.

채널 어댑터의 핵심 개념

모든 채널 어댑터는 다음과 같은 설계 원칙을 공유합니다:

  • 통합 메시지 형식: 어떤 채널에서 온 메시지든 표준 OpenFang 메시지 형식으로 변환됩니다.
  • 독립적인 샌드박스: 각 채널 어댑터는 독립된 샌드박스에서 실행되므로, 한 채널의 장애가 다른 채널에 영향을 주지 않습니다.
  • 핫 리로드(Hot Reload): 채널 설정을 추가하거나 수정해도 Agent를 재시작할 필요가 없습니다.
  • 속도 제한(Rate Limiting): 내장된 속도 제한 기능으로 플랫폼 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와 대화하여 봇 생성
  2. Bot Token 획득
  3. 설정 파일에 Token 입력

Discord 어댑터

Discord 어댑터는 서버(Guild) 및 개인 메시지(DM) 모드를 모두 지원합니다:

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 트레이트를 구현하여 사용자 정의 어댑터를 생성할 수 있습니다:

``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 배포 보호하기