메시징 채널 연결

채널은 에이전트가 메시징 플랫폼(Telegram, Discord, Slack, Matrix, WhatsApp, 이메일 등)을 통해 사용자에게 연락하는 수단입니다. 각 채널은 데몬 아래에서 실행되며, 인바운드 메시지를 수신하고, 허용 목록을 적용한 뒤, 플랫폼 API를 통해 에이전트의 응답을 전송합니다. 이 가이드에서는 채널 모델, 운영 전에 반드시 이해해야 할 전면 거부(deny-all) 허용 목록 기본값, 폴링과 웹훅 전달 방식의 차이, 그리고 채널을 추가·조회·제어하는 revka channel 명령어를 설명합니다. CLI에서 첫 번째 채널을 연결할 때 이 가이드를 활용하세요.

플랫폼별 설정 절차는 Telegram 및 Matrix 설정과 Mattermost 및 Nextcloud Talk 설정을 참고하거나, 전체 채널 개요와 채널 카탈로그를 확인하세요. 채널이 실행되는 호스트 프로세스를 시작하려면 대시보드 실행을 먼저 읽어보세요.

채널 개요

모든 채널은 ~/.revka/config.toml의 [channels_config] 네임스페이스 아래에 설정되며, 데몬이 실행될 때 채널 수퍼바이저가 관리합니다. 수퍼바이저는 각 채널에 발신자별 대화 기록, 동시 메시지 처리, 자동 지수 백오프 재연결 기능을 제공합니다.

채널은 revka daemon(게이트웨이 + 채널 + 하트비트 + cron) 내부에서 실행됩니다. revka channel start로 설정된 채널만 단독으로 시작할 수도 있습니다. 채널은 대시보드와 API만 제공하는 revka gateway 단독 실행 환경에서는 동작하지 않습니다.

최소한의 Telegram 채널 블록은 다음과 같습니다.

[channels_config]
message_timeout_secs = 300

[channels_config.telegram]
bot_token = "1234567890:ABCDEFabcdef-your-token"
allowed_users = ["myusername"]
stream_mode = "off"
mention_only = false

message_timeout_secs(기본값 300)는 메시지당 기본 타임아웃이며, 툴 루프 깊이에 따라 [pacing].message_timeout_scale_max(기본값 4)까지 늘어납니다. 플랫폼 공통 채널 필드로는 bot_token/api_key, 허용 목록 필드(아래 참조), mention_only, stream_mode, proxy_url 등이 있습니다. 각 플랫폼의 정확한 키는 Config: 채널, 도구 및 통합과 채널별 카탈로그 페이지에서 확인할 수 있습니다.

허용 목록 동작 방식 (기본값: 전면 거부)

가장 중요한 채널 개념은 모든 채널의 허용 목록은 기본적으로 빈 목록이며, 이는 전면 거부를 의미합니다. 새로 추가된 채널은 연결되어 메시지를 수신하지만, 신원을 명시적으로 추가하기 전까지는 모든 메시지를 무시합니다. 이는 봇을 발견한 불특정 사용자가 에이전트를 조작하는 것을 막기 위한 보안 기본값입니다.

두 가지 특수 케이스:

• 빈 목록 [] → 전면 거부 (아무도 허용되지 않음).
• 단일 항목 "*" → 전체 허용 (모든 발신자 허용). 노출 범위를 충분히 이해한 경우에만 사용하세요.

허용 목록 필드명은 플랫폼마다 다릅니다.

채널	허용 목록 필드
Telegram, Discord, Slack, Mattermost, Matrix, IRC, Lark, Feishu, DingTalk, QQ, Nextcloud Talk, WeCom, Mochat, Twitter	allowed_users
Signal	allowed_from
WhatsApp (Cloud API & Web), WATI	allowed_numbers
Email, Linq, Gmail Push	allowed_senders
iMessage	allowed_contacts
Nostr	allowed_pubkeys
ClawdTalk	allowed_destinations

따라서 전면 거부 Discord 채널과 전체 허용 채널은 allowed_users 값만 다릅니다.

[channels_config.discord]
bot_token = "..."
allowed_users = []        # deny all (default)

# vs.

[channels_config.discord]
bot_token = "..."
allowed_users = ["*"]     # allow all senders

주의

"*"를 사용하면 봇에게 메시지를 보낼 수 있는 누구든 에이전트와 에이전트의 도구, 사용량, 메모리를 이용할 수 있습니다. 명시적인 사용자 ID, 전화번호, 또는 핸들을 목록에 기재하는 것을 권장합니다. 더 넓은 신뢰 모델에 대해서는 보안 모델과 자율성 수준 및 승인을 참고하세요.

폴링 대 웹훅 전달 방식

채널은 두 가지 방식 중 하나로 인바운드 메시지를 수신하며, 이 차이에 따라 공개 주소가 필요한지 여부가 결정됩니다.

• 폴링 / 아웃바운드 연결 채널은 Revka에서 시작하는 연결을 사용합니다(롱 폴링, 봇이 다이얼아웃하는 WebSocket/게이트웨이 연결, 또는 주기적인 REST 폴링). NAT 뒤에서도 동작하며 공개 인바운드 포트가 필요하지 않습니다. Telegram, Discord, Slack, Mattermost, Matrix, Signal, IRC, Bluesky, Reddit, 이메일(IMAP IDLE)이 여기에 해당합니다.
• 웹훅 / 푸시 채널은 플랫폼이 사용자에게 이벤트를 POST해야 하므로, 게이트웨이에 도달할 수 있는 공개 HTTPS 콜백 URL이 필요합니다. WhatsApp Cloud API, WATI, Nextcloud Talk, Linq, Gmail Push, 범용 웹훅 채널이 이 방식으로 동작합니다.

채널	수신 방식	공개 인바운드 포트 필요 여부
Telegram	long-polling	아니요
Discord	Gateway WebSocket	아니요
Slack	Socket Mode / polling	아니요
Mattermost	REST polling	아니요
Matrix	sync API	아니요
Signal	signal-cli SSE bridge	아니요
IRC	TLS socket	아니요
Email (IMAP)	IMAP IDLE	아니요
WhatsApp Cloud API	webhook (push)	예
WATI	webhook (push)	예
Nextcloud Talk	webhook (push)	예
Linq	webhook (push)	예
Gmail Push	Pub/Sub webhook	예
Generic Webhook	HTTP server	대부분 예

플랫폼에 공개 콜백이 필요한 경우, 게이트웨이를 공개 주소에 직접 바인딩하는 대신 터널로 노출하세요. 터널로 게이트웨이 노출과 웹훅 인그레스 API 레퍼런스를 참고하세요. 모든 플랫폼의 전체 전달 방식 매트릭스는 채널 개요에서 확인할 수 있습니다.

첫 번째 채널 추가

가장 빠른 방법은 revka channel add입니다. 채널 유형과 JSON 설정 블록을 인수로 전달하면 config.toml에 기록됩니다. 지원 유형은 telegram, discord, slack, whatsapp, matrix, imessage, email입니다.

1. 채널을 추가합니다. 나중에 참조할 수 있도록 name을 포함하세요. 허용 목록은 여전히 전면 거부가 기본값이므로, 다음 단계에서 본인을 추가할 계획을 세우세요.

   revka channel add telegram '{"bot_token":"123456:YOUR-TOKEN","name":"my-bot"}'

2. 본인을 허용 목록에 추가합니다. Telegram의 경우 전용 헬퍼 명령어가 있습니다. 사용자 이름(@ 없이) 또는 숫자 사용자 ID를 전달하면 허용 목록에 추가됩니다.

   revka channel bind-telegram revka_user
   revka channel bind-telegram 123456789

   다른 플랫폼의 경우, config.toml에서 해당 채널의 허용 목록 필드(예: allowed_users, allowed_numbers, allowed_senders)를 직접 편집하세요.

3. 설정을 확인합니다. 시작하기 전에 채널 상태 검사를 실행하세요.

   revka channel doctor

4. 채널을 시작합니다 (또는 revka daemon으로 전체 런타임을 시작합니다).

   revka channel start

5. 플랫폼에서 봇에게 테스트 메시지를 보냅니다. mention_only = false로 설정하고 본인의 신원이 허용 목록에 있으면 에이전트가 응답합니다.

토큰 입력을 대화형으로 진행하고 싶다면, 온보딩 마법사에 채널 설정 단계가 포함되어 있으며, revka onboard --channels-only를 실행하면 채널 복구 플로우만 다시 실행할 수 있습니다.

revka channel 명령어

revka channel은 CLI에서 통신 채널을 관리합니다. 서브커맨드 목록:

서브커맨드	기능
revka channel list	설정된 모든 채널 목록 표시
revka channel start	설정된 모든 채널 시작
revka channel doctor	설정된 모든 채널의 상태 검사 실행
revka channel add <type> <config_json>	채널 추가 (telegram, discord, slack, whatsapp, matrix, imessage, email)
revka channel remove <name>	설정 이름으로 채널 제거
revka channel bind-telegram <identity>	Telegram 사용자 이름(@ 없이) 또는 숫자 사용자 ID를 허용 목록에 추가
revka channel send <message> --channel-id <NAME> --recipient <TARGET>	일회성 메시지 전송

revka channel list
revka channel add discord '{"bot_token":"...","name":"my-discord"}'
revka channel remove my-bot

일회성 메시지 전송

revka channel send는 대화 없이 이미 설정된 채널을 통해 단일 메시지를 전달합니다. --channel-id는 채널의 설정 이름이고, --recipient는 플랫폼별 대상(채팅 ID, 전화번호 등)입니다. 센서 알림, cron 작업 요약, 배포 알림 등 스크립트 알림 및 자동화 파이프라인용으로 설계되었습니다.

revka channel send 'Someone is near your device.' --channel-id telegram --recipient 123456789

핫 리로드

채널이 실행 중일 때 채널 런타임은 config.toml을 감시하며, 데몬 재시작 없이 다음 인바운드 메시지 수신 시 특정 키를 리로드합니다.

• default_provider
• default_model
• default_temperature
• api_key / api_url
• reliability.* (재시도 및 폴백 공급자)

이를 통해 라이브 채널에서 공급자, 모델, 또는 API 키를 교체하면 다음 메시지에서 변경 사항이 적용됩니다. 채널 추가·제거, 토큰 및 허용 목록 변경 등 그 외 설정은 핫 리로드되지 않으므로, 채널(revka channel start) 또는 데몬을 재시작하여 적용하세요.

참고

인터랙티브 에이전트(revka agent)는 설정 핫 리로드를 지원하지 않으므로 변경 사항을 적용하려면 재시작이 필요합니다. 핫 리로드는 데몬 아래 채널 런타임에만 적용됩니다.

채팅 내 런타임 명령어

텍스트 명령어를 지원하는 채널(예: Telegram, Discord)에서는 허용 목록에 등록된 사용자가 세션을 인라인으로 제어할 수 있습니다.

명령어	효과
/models	사용 가능한 공급자 표시
/models <provider>	현재 세션의 공급자 전환
/model	현재 모델 표시
/model <model-id>	현재 세션의 모델 전환
/new	대화 기록을 초기화하고 새로 시작

문제 해결

• 봇이 연결되지만 응답하지 않습니다. 발신자가 허용 목록에 없는 것입니다. 기본값은 전면 거부([])임을 기억하세요. 본인의 신원을 추가(Telegram의 경우 revka channel bind-telegram <you>, 또는 허용 목록 필드 편집)하고 채널을 재시작하세요.
• 웹훅 채널이 아무것도 수신하지 않습니다. 게이트웨이에 도달할 수 있는 공개 HTTPS 콜백이 필요합니다. 플랫폼의 웹훅 URL이 127.0.0.1이 아닌 터널을 가리키는지 확인하세요. 터널로 게이트웨이 노출을 참고하세요.
• 설정 변경이 적용되지 않습니다. 위의 핫 리로드 키만 다음 메시지에서 적용됩니다. 그 외 변경 사항은 revka channel start를 실행하거나 데몬을 재시작하세요.
• 상태가 이상합니다. revka channel doctor로 채널별 상태 검사를 실행하고, revka doctor로 전체 시스템 진단을 수행하세요.

다음 단계

Telegram 및 Matrix 설정 가장 많이 사용되는 두 개인 채널의 엔드투엔드 설정 방법.

Mattermost 및 Nextcloud Talk 설정 워크스페이스 채널로 팀 채팅을 연결하는 방법.

채널 개요 전체 채널 카탈로그, 특성 모델, 그리고 전달 방식 매트릭스.

revka channel 및 통합 채널 서브커맨드의 완전한 CLI 레퍼런스.