Claude Code v2.1.80+
리서치 프리뷰
Claude Code Channels, 세션 켜둬야만 됩니다
텔레그램으로 Claude Code에 메시지를 보내면 AI가 알아서 코드를 짜준다는 이야기, 들어보셨을 겁니다. Anthropic이 3월 20일 공식 출시한 Claude Code Channels가 바로 그 기능입니다. 근데 막상 쓰려고 보면 “왜 메시지가 안 오지?”라는 상황부터 생깁니다. 세션이 꺼지면 아무것도 안 됩니다. 이게 핵심입니다.
(텔레그램·디스코드·iMessage)
(Free 사용 불가)
(Node·Deno도 가능)
Claude Code Channels가 뭔지, 한 줄로 정리하면
Claude Code Channels는 텔레그램·디스코드·iMessage 같은 메신저에서 보낸 메시지를 실행 중인 Claude Code 세션 안으로 직접 밀어 넣는 기능입니다. (출처: Claude Code 공식 문서, 2026.03.20) 2026년 3월 20일 리서치 프리뷰로 출시됐으며, Claude Code v2.1.80 이상이 필요합니다.
이 기능이 나오기 전까지 Claude Code는 터미널 앞에 앉아 있어야만 쓸 수 있었습니다. Remote Control 기능이 있었지만, 이건 모바일에서 이미 열린 세션을 “조종”하는 개념이었고, 외부 메신저와의 연동은 없었습니다. Channels는 거기에 한 단계 더 나아가서, 메신저 자체를 Claude Code의 입출력 창구로 씁니다. 텔레그램으로 “이 파일 리팩토링해줘”라고 보내면, Claude Code가 로컬 파일에 접근해 작업하고 텔레그램으로 결과를 답장합니다.
💡 공식 문서와 실제 설정 절차를 같이 놓고 보면 이런 구조가 보입니다: Channels는 “텔레그램 챗봇”이 아닙니다. MCP(Model Context Protocol) 서버가 외부 메신저와 Claude Code 세션 사이의 브릿지 역할을 합니다. 그래서 MCP 서버가 꺼지면, 즉 세션이 꺼지면 메시지도 안 옵니다.
Anthropic의 공식 GitHub 리포지터리 claude-plugins-official에 텔레그램·디스코드·iMessage 플러그인이 올라와 있고, 이걸 /plugin install 명령으로 설치하는 구조입니다. (출처: Claude Code Channels Reference, 2026.03.20)
세션이 꺼지면 메시지가 안 오는 이유
많은 분들이 “텔레그램으로 보내면 Claude Code가 알아서 받아서 처리하겠지”라고 생각합니다. 실제로는 다릅니다. 공식 문서에 이렇게 나와 있습니다: “Events only arrive while the session is open.” 세션이 열려있는 동안에만 이벤트가 도착합니다. (출처: Claude Code Channels 공식 문서, 2026.03.20) 이 한 문장이 Channels의 작동 방식 전체를 결정합니다.
왜 이런 구조냐면, Channels는 클라우드 서버에서 돌아가는 hosted 에이전트가 아닙니다. 로컬 머신에서 Claude Code가 실행 중일 때, 그 세션 안으로 외부 메시지를 주입하는 방식입니다. 채널 플러그인은 MCP 서버로서 Claude Code가 서브프로세스로 실행시키는 구조입니다. (출처: Claude Code Channels Reference) 클라우드에 항상 떠있는 봇이 아닙니다.
⚠️ 실용적 의미
상시 운영을 원한다면 백그라운드 터미널, tmux 세션, 또는 VPS에서 Claude Code를 계속 실행해둬야 합니다. 컴퓨터를 꺼두거나 Claude Code 세션을 종료하면, 그 사이에 온 텔레그램 메시지는 도착하지 않습니다.
이건 OpenClaw처럼 클라우드 기반으로 24시간 돌아가는 에이전트 프레임워크와 근본적으로 다른 설계 철학입니다. Anthropic은 의도적으로 로컬 세션 기반으로 만들었습니다. 공식 문서에서도 “for an always-on setup, run Claude in a background process or persistent terminal”이라고 직접 안내하고 있습니다.
따라서 Channels를 쓰기 전에 먼저 결정해야 할 게 있습니다. 내 머신에서 Claude Code를 항상 켜둘 수 있느냐. 그게 안 된다면 VPS 같은 원격 서버를 쓸 의향이 있느냐. 이 조건이 안 되면 Channels의 “언제든 텔레그램으로 지시” 기능은 반쪽짜리가 됩니다.
텔레그램·디스코드·iMessage, 어떻게 연결하나
① 공통 요구사항
세 채널 모두 Claude Code v2.1.80 이상, Bun 런타임 설치, Pro/Max/Team/Enterprise 요금제가 필요합니다. Free 플랜에서는 Channels를 쓸 수 없습니다. Bun이 없으면 플러그인 설치 자체가 안 됩니다. bun --version으로 먼저 확인하세요.
② 텔레그램 연결 절차
- 텔레그램 BotFather에서
/newbot으로 봇 토큰 발급 - Claude Code 터미널:
/plugin install telegram@claude-plugins-official /telegram:configure <토큰>실행claude --channels plugin:telegram@claude-plugins-official로 재시작- 텔레그램에서 봇에 DM → 페어링 코드 수령 →
/telegram:access pair <코드>
③ 디스코드 연결 절차
- Discord Developer Portal에서 앱 생성 → Bot 토큰 복사
- Bot 설정에서 “Message Content Intent” 활성화 필수
/plugin install discord@claude-plugins-official/discord:configure <토큰>claude --channels plugin:discord@claude-plugins-official로 재시작 → 봇에 DM 후 페어링
④ iMessage (macOS 전용)
iMessage는 macOS에서만 됩니다. 봇 토큰이나 외부 서비스 없이, 로컬 Messages 데이터베이스를 직접 읽고 AppleScript로 답장하는 방식입니다. 자신에게 보낸 메시지는 자동으로 통과되고, 다른 연락처는 /imessage:access allow로 추가합니다. (출처: Claude Code Channels 공식 문서)
💡 페어링 코드를 통한 허용 목록 방식은 처음부터 의도된 보안 설계입니다. 아무나 봇에 메시지를 보내도 Claude Code 세션에는 전달이 안 됩니다. 다음 섹션에서 이 보안 설정을 빠트렸을 때 어떤 일이 생기는지 설명합니다.
보안 설정을 빠트리면 생기는 문제
공식 문서에 한 줄이 딱 나와있습니다: “An ungated channel is a prompt injection vector.” 허용 목록 없이 열어둔 채널은 프롬프트 인젝션 벡터가 됩니다. (출처: Claude Code Channels Reference) 쉽게 말하면, 봇 토큰을 아는 누구든 Claude Code 세션에 악의적인 명령을 주입할 수 있다는 뜻입니다.
그래서 공식 플러그인(텔레그램·디스코드)은 발신자 ID 기반 허용 목록을 씁니다. 중요한 건 방 ID가 아니라 발신자 ID로 게이팅해야 한다는 점입니다. 그룹 채팅에서는 방 ID와 발신자 ID가 다릅니다. 방 ID로 게이팅하면 그룹에 있는 아무나 Claude Code 세션에 메시지를 보낼 수 있게 됩니다. (출처: Claude Code Channels Reference — Gate inbound messages 섹션)
⚠️ 특히 주의할 상황
Permission Relay 기능(원격으로 도구 실행을 승인/거부)을 쓴다면 보안이 더 중요합니다. 채널을 통해 메시지를 보낼 수 있는 사람은 Claude Code의 도구 실행을 원격으로 승인할 수도 있습니다. 파일 쓰기, Bash 실행, 코드 수정 같은 권한까지 원격으로 제어되는 구조입니다. 공식 문서에도 “허용 목록에 추가하는 발신자에게 그 권한을 줄 수 있는지 확인하라”고 직접 명시되어 있습니다.
Claude Code가 권한 확인 프롬프트를 만나면 세션이 잠시 멈춥니다. Permission Relay를 설정해두면 이 프롬프트를 텔레그램이나 디스코드로 받고 원격으로 승인/거부할 수 있습니다. 터미널 앞에 없어도 “yes abcde” 또는 “no abcde” (5자리 요청 ID 포함)로 답장하면 처리됩니다. 이 ID 체계는 의도적으로 0, l, 1, I 같이 혼동되는 문자를 제외하고 a-z에서 5자리를 씁니다. 폰에서 타이핑할 때 실수를 줄이기 위한 설계입니다.
Remote Control과 다른 점, 표로 비교하면
Claude Code에는 이미 Remote Control 기능이 있었습니다. claude.ai 앱이나 모바일 앱에서 로컬 세션을 원격으로 조종하는 기능입니다. 그런데 Channels와 Remote Control은 완전히 다른 용도입니다.
| 항목 | Channels | Remote Control | Web Session |
|---|---|---|---|
| 연결 방식 | 외부 이벤트 → 세션 주입 | Claude 앱에서 세션 조종 | 클라우드 샌드박스 신규 생성 |
| 사용 플랫폼 | 텔레그램·디스코드·iMessage | claude.ai / Claude 앱 | 브라우저 |
| 로컬 파일 접근 | ✅ 실제 로컬 파일 | ✅ 실제 로컬 파일 | ❌ GitHub 클론만 |
| 세션 지속성 | 세션 열린 동안만 | 세션 열린 동안만 | 작업당 독립 |
| 적합한 상황 | CI 알림·메신저 지시·웹훅 | 진행 중 세션 추가 지시 | 독립 비동기 작업 |
💡 Channels와 Remote Control을 놓고 보면 이런 차이가 보입니다: Remote Control은 “Claude Code 세션을 폰에서 조종”이고, Channels는 “외부 시스템이 Claude Code 세션에 이벤트를 보내는 것”입니다. 방향이 반대입니다. CI 파이프라인 빌드 실패 알림을 Claude Code가 받아서 자동으로 처리하게 하려면 Remote Control이 아니라 Channels를 써야 합니다.
Team·Enterprise 조직이라면 확인할 게 따로 있습니다
Pro/Max 개인 요금제는 Channels가 기본 활성화되어 있고, 사용자가 --channels 플래그로 세션마다 선택해서 씁니다. 반면 Team/Enterprise 플랜은 기본값이 비활성화입니다. (출처: Claude Code Channels 공식 문서 — Enterprise controls)
관리자가 channelsEnabled: true를 설정하지 않으면 MCP 서버 자체는 연결되더라도 채널 메시지가 도착하지 않습니다. 스타트업 경고만 뜨고 동작은 안 하는 상태입니다. 조직 내에서 Team 플랜을 쓰고 있는데 Channels가 안 된다면, 관리자에게 claude.ai Admin 설정에서 활성화 여부를 확인해달라고 요청해야 합니다.
| 설정 항목 | 역할 | 미설정 시 |
|---|---|---|
| channelsEnabled | 채널 기능 마스터 스위치 | 전체 차단 |
| allowedChannelPlugins | 허용 플러그인 목록 지정 | Anthropic 기본 목록 적용 |
allowedChannelPlugins를 설정하면 Anthropic 기본 목록 대신 조직 고유 목록이 적용됩니다. 내부 CI 알림 채널이나 자체 플러그인을 추가하고 싶을 때 씁니다. 주의할 점은 이 항목을 설정하는 순간 기존 Anthropic 공식 플러그인 목록 전체가 대체됩니다. 텔레그램·디스코드를 계속 쓰려면 직접 목록에 명시해야 합니다.
Q&A
마치며
Claude Code Channels는 분명히 쓸모 있는 기능입니다. 특히 개발 중에 자리를 비워야 할 때, 또는 CI 파이프라인 이벤트를 Claude Code에 자동으로 전달하고 싶을 때 진가를 발휘합니다. 하지만 “텔레그램에서 메시지 보내면 AI가 알아서 다 한다”는 식의 기대는 조금 조정할 필요가 있습니다.
세션 상시 가동 조건, Bun 설치, Pro 이상 요금제, 발신자 허용 목록 설정까지 해야 제대로 돌아갑니다. 이 네 가지 중 하나라도 빠지면 “왜 안 되지?”를 반복하게 됩니다. 특히 Team/Enterprise 플랜이라면 관리자 설정부터 확인하는 게 첫 번째입니다.
리서치 프리뷰 단계라 앞으로 변경이 있을 수 있습니다. 쓰기 전에 공식 문서를 한 번 훑어보는 걸 권장합니다.
본 포스팅 참고 자료
본 포스팅은 Claude Code v2.1.80+ / 2026.03.29 기준으로 작성되었습니다. 본 포스팅 작성 이후 서비스 정책·UI·기능이 변경될 수 있습니다. 최신 정보는 공식 문서에서 확인하세요.
댓글 남기기