Channels로 세션에 이벤트 푸시
기준일: 2026-07-26
난이도: 중급
공식 기준: Push events into a running session with channels, Channels reference
Channel은 이미 열린 Claude Code 세션으로 이벤트(채팅 메시지, CI 알림, 웹훅 등)를 밀어 넣는 MCP 서버입니다. Claude가 이벤트를 읽고 같은 채널로 회신할 수 있습니다(양방향 브리지). 세션이 닫히면 이벤트가 도착하지 않으므로 always-on이 필요하면 백그라운드/지속 터미널에서 Claude를 둡니다.
핵심 개념
| 항목 | 내용 |
|---|---|
| 상태 | research preview (claude --help에 플래그가 안 보일 수 있으나 동작) |
| 인증 | Anthropic: claude.ai 또는 Console API key. Bedrock / Agent Platform / Foundry 미지원 |
| 설치 | 플러그인 (Bun 필요). 기본 세트: Telegram, Discord, iMessage, fakechat |
| 세션 opt-in | claude --channels plugin:<name>@claude-plugins-official |
| 접근 제어 | sender allowlist (pairing 또는 handle allow) |
| Team/Enterprise | Owner가 channelsEnabled 등으로 명시 enable 필요 |
회신은 터미널에 본문이 안 보일 수 있습니다. 터미널에는 tool call·확인("sent")이, 실제 문구는 Telegram/Discord 등에 나타납니다.
다른 연동과의 차이
| 기능 | 역할 |
|---|---|
| Claude Code on the web | GitHub 기반 새 클라우드 세션 |
| Slack | 멘션으로 웹 세션 스폰 |
| 일반 MCP | Claude가 당겨 쓰는 도구 (푸시 없음) |
| Remote Control | 로컬 세션을 claude.ai/모바일에서 조종 |
| Channels | 외부 소스가 로컬 세션으로 푸시 |
선택 기준
적합한 예: 폰에서 Telegram으로 로컬 작업 지시, CI/웹훅을 열려 있는 세션에 주입, 자리 비운 동안 알림 반응.
부적합: 노트북이 꺼진 무인 실행 → Routines. 새 클라우드 샌드박스 위임 → web/Slack.
실습
공통 준비
- Claude Code 설치·인증
- Bun (
bun --version) - Team/Enterprise: admin이 channels enable
- 마켓플레이스: 필요 시
/plugin marketplace add anthropics/claude-plugins-official후/plugin marketplace update claude-plugins-official
fakechat (로컬 데모)
/plugin install fakechat@claude-plugins-official
설치 범위는 user scope 권장. 종료 후:
claude --channels plugin:fakechat@claude-plugins-official
브라우저 http://localhost:8787에서 메시지 입력 → 세션에 ← fakechat · … 형태로 도착 → Claude가 reply tool 호출.
여러 플러그인은 공백으로:
claude --channels plugin:telegram@claude-plugins-official plugin:discord@claude-plugins-official
Telegram (요약)
- BotFather로 봇 생성, 토큰 복사
/plugin install telegram@claude-plugins-official/telegram:configure <token>→~/.claude/channels/telegram/.env(또는TELEGRAM_BOT_TOKEN)claude --channels plugin:telegram@claude-plugins-official- 봇에 메시지 → pairing code →
/telegram:access pair <code> /telegram:access policy allowlist
Discord (요약)
- Developer Portal 앱·봇, Message Content Intent, 초대 권한(View Channels, Send Messages, Threads, History, Attach Files, Add Reactions)
/plugin install discord@claude-plugins-official/discord:configure <token>(또는DISCORD_BOT_TOKEN)claude --channels plugin:discord@claude-plugins-official- DM pairing →
/discord:access pair <code>→/discord:access policy allowlist
iMessage (macOS)
- Messages DB Full Disk Access (터미널/IDE)
/plugin install imessage@claude-plugins-officialclaude --channels plugin:imessage@claude-plugins-official- 자기 자신에게 메시지(self-chat은 접근 제어 우회)
- 다른 발신자:
/imessage:access allow +15551234567또는 Apple ID 이메일
커스텀 채널·웹훅 수신기: Channels reference. 개발 중 테스트: --dangerously-load-development-channels (프리뷰 계약·위험 인지 후).
권한 프롬프트
자리 비운 동안 권한 프롬프트가 나오면 세션이 멈출 수 있습니다. permission relay capability를 선언한 채널은 원격 승인 가능. 무인 사용 시 --dangerously-skip-permissions는 신뢰 환경에서만. explicit ask 규칙, org connector ask, requiresUserInteraction MCP는 여전히 프롬프트됩니다.
-p non-interactive에서는 터미널 입력 필요 도구(객관식, plan 승인 등)가 비활성화되어 대기 없이 진행합니다.
보안과 엔터프라이즈
- 승인된 플러그인만 allowlist sender의 메시지를 전달; 그 외는 silent drop
.mcp.json만으로는 부족 — 반드시 해당 세션의--channels에 이름이 있어야 함- permission relay 가능 시 allowlist sender는 도구 승인 권한까지 가짐
| 관리 설정 | 역할 |
|---|---|
channelsEnabled |
마스터 스위치. Team/Enterprise 기본 차단, Console API는 기본 허용(managed settings 배포 시 키 설정 필요) |
allowedChannelPlugins |
허용 플러그인 목록으로 Anthropic 기본 목록 대체. channelsEnabled: true 필요 |
{
"channelsEnabled": true,
"allowedChannelPlugins": [
{ "marketplace": "claude-plugins-official", "plugin": "telegram" },
{ "marketplace": "claude-plugins-official", "plugin": "discord" }
]
}
Pro/Max 개인(조직 없음): org 검사 생략, 세션마다 --channels로 opt-in.
체크리스트
- Bun과 올바른 Anthropic 인증을 확인했다.
- 플러그인을 user scope로 설치하고
--channels로 재시작했다. - pairing / allowlist로 sender를 제한했다.
- Team/Enterprise면 Owner enable과
allowedChannelPlugins를 확인했다. - 커스텀 채널은 channels-reference와 개발 플래그 위험을 이해했다.
다음 단계
- Channels reference — 커스텀 채널·웹훅
- Remote Control — 푸시 대신 원격 조종
- 스케줄 작업 — 타이머 폴링
- 권한 관리 — 무인 권한 모드