Claude Code Channels 쉽게 쓰는 법

Claude Code Channels : 터미널 밖 이벤트를 작업 중 세션으로 보내는 법

Claude Code를 처음 쓰다 보면 이런 생각이 들어요. "내가 자리를 비운 사이에 CI 실패 알림이나 메신저 메시지가 지금 열어 둔 세션으로 바로 들어오면 좋지 않을까?" Channels는 바로 그 상황을 위한 기능입니다.

핵심만 먼저 말하면, Claude Code Channels는 외부 이벤트를 새 세션이 아니라 지금 실행 중인 로컬 세션으로 밀어 넣는 방식이에요. 그래서 Claude가 이미 열어 둔 파일, 현재 작업 문맥, 방금까지의 대화를 그대로 이어받아 반응할 수 있습니다.

• Channels는 실행 중인 Claude Code 세션으로 외부 이벤트를 푸시합니다.
• 대표 예시는 Telegram, Discord, 웹훅입니다.
• 단, 세션이 열려 있을 때만 이벤트를 받을 수 있습니다.
• 현재는 연구 프리뷰 기능이라 버전, 허용 플러그인, 조직 정책 제약이 있습니다.

Channels는 정확히 무엇인가

공식 문서 기준으로 Channels는 MCP 서버가 실행 중인 Claude Code 세션으로 이벤트를 푸시하는 구조예요. 일반적인 MCP 서버가 Claude의 요청을 받을 때만 응답하는 방식이라면, Channels는 반대로 외부 시스템이 먼저 신호를 보내 Claude가 반응하게 만듭니다.

초보자 관점에서는 이렇게 이해하면 충분해요.

Channels의 핵심은 "외부에서 발생한 일을, 내가 열어 둔 Claude Code 세션이 바로 받아서 처리하게 만드는 연결 통로"입니다.

예를 들어 이런 흐름이 가능해집니다.

1. GitHub Actions나 CI가 실패합니다.
2. 그 실패 알림이 Channel을 통해 Claude Code 세션으로 들어옵니다.
3. Claude는 현재 열려 있는 코드베이스를 읽고 원인을 추적합니다.
4. 필요하면 수정 방향을 정리하거나, 연결된 채널에 답장을 보냅니다.

이게 중요한 이유는, Claude가 새로운 클라우드 작업 공간에서 시작하는 게 아니라 내 로컬 작업 문맥 안에서 움직인다는 점 때문입니다.

왜 초보자에게도 이 개념이 중요한가

처음에는 Channels가 고급 기능처럼 보여요. 하지만 실제로는 Claude Code의 자동화 철학을 이해하는 데 아주 좋은 기능입니다.

기존 방식에서는 보통 두 가지 한계가 있었어요.

• 알림은 오지만, 실제 코드를 아는 작업 맥락은 없다
• Claude는 똑똑하지만, 외부 이벤트를 스스로 받을 수는 없다

Channels는 이 둘을 이어 줍니다. 그래서 "알림"과 "실행 중인 작업 세션"이 하나의 흐름으로 붙습니다.

특히 아래 같은 상황에서 감이 빨리 옵니다.

• 빌드 실패가 나면 Claude가 바로 로그를 보고 원인을 파악하게 하고 싶을 때
• 자리 비운 동안 휴대폰 메신저로 Claude에게 질문을 보내고 싶을 때
• 에러 트래커, 배포 시스템, 모니터링 이벤트를 작업 세션에 연결하고 싶을 때

초보자에게 중요한 포인트는 Channels가 "Claude를 더 똑똑하게 만드는 기능"이 아니라, "Claude가 외부 사건을 제때 받아 보게 만드는 연결 방식"이라는 점입니다.

일반 MCP 서버와 무엇이 다른가

여기서 많이 헷갈립니다. MCP와 Channels는 비슷해 보이지만 작동 방식이 다릅니다.

일반 MCP 서버

일반 MCP 서버는 Claude가 필요할 때 호출합니다. 다시 말해, Claude가 먼저 "이 시스템 정보 좀 줘"라고 요청해야 동작해요. 수동 조회에 가깝습니다.

Channels

Channels는 외부 시스템이 먼저 이벤트를 밀어 넣습니다. Claude는 그 이벤트를 현재 세션 안에서 받아 즉시 반응합니다. 능동 푸시에 가깝습니다.

이 차이를 한 문장으로 정리하면 이렇습니다.

일반 MCP는 Claude가 데이터를 가지러 가는 방식이고, Channels는 외부 이벤트가 Claude에게 직접 들어오는 방식입니다.

공식 문서도 Channels를 웹 세션, Slack, 일반 MCP, Remote Control과 비교하면서, 이미 실행 중인 로컬 세션에 외부 이벤트를 푸시하는 기능으로 설명합니다.

초보자가 먼저 알아둘 제약

쓰기 전에 기대치를 맞추는 게 좋아요. 현재 문서 기준으로 Channels는 몇 가지 제약이 있습니다.

1. 연구 프리뷰 기능이다

아직 정식 고정 규격이 아니에요. 문서에서도 플래그 문법과 프로토콜 계약이 바뀔 수 있다고 안내합니다.

2. Claude Code 버전과 로그인 방식 조건이 있다

문서 기준으로 Channels는 Claude Code v2.1.80 이상이 필요하고, claude.ai 로그인 기반에서 동작합니다. 콘솔 인증이나 API 키 인증은 지원되지 않습니다.

3. 세션이 열려 있어야 한다

이 부분이 중요해요. 이벤트는 항상 열려 있는 세션으로 들어오기 때문에, Claude Code가 꺼져 있으면 받을 수 없습니다. 늘 켜 두고 쓰려면 백그라운드 프로세스나 지속 실행 터미널 구성이 필요합니다.

4. Team / Enterprise는 조직 설정이 필요하다

개인 Pro/Max와 달리 Team, Enterprise는 관리자가 channelsEnabled를 명시적으로 켜야 합니다. MCP 서버가 연결돼 있어도 이 설정이 꺼져 있으면 채널 메시지는 도착하지 않습니다.

가장 쉬운 이해법: fakechat으로 먼저 체험하기

공식 문서에서 초보자에게 가장 쉬운 시작점은 fakechat입니다. Telegram이나 Discord처럼 외부 서비스를 먼저 붙이지 않아도, 로컬 브라우저 UI로 메시지를 보내고 답을 받는 흐름을 체험할 수 있어요.

대략적인 흐름은 이렇습니다.

1. 플러그인을 설치합니다.
2. Claude Code를 --channels 옵션으로 다시 실행합니다.
3. 로컬 브라우저 UI에서 메시지를 보냅니다.
4. 메시지가 <channel ...> 이벤트 형태로 세션에 들어옵니다.
5. Claude가 작업한 뒤 다시 브라우저 쪽으로 답을 보냅니다.

초보자라면 Telegram이나 Discord보다 먼저 fakechat을 보는 이유가 분명합니다.

• 인증 토큰 준비가 필요 없습니다.
• 채널이 어떤 식으로 메시지를 밀어 넣는지 눈으로 확인할 수 있습니다.
• "아, 이건 메신저 연동 이전에 이벤트 전달 구조를 이해하는 기능이구나"라는 감이 빨리 잡힙니다.

Telegram과 Discord 채널은 어떻게 붙나

공식 지원 예시는 현재 Telegram과 Discord입니다. 두 경우 모두 큰 흐름은 비슷합니다.

1. 각 플랫폼에서 봇을 만듭니다.
2. Claude Code에 공식 플러그인을 설치합니다.
3. 토큰을 설정합니다.
4. claude --channels ...로 Claude Code를 재실행합니다.
5. 봇에게 메시지를 보내 페어링 코드를 받습니다.
6. Claude Code 안에서 페어링을 승인합니다.
7. 마지막으로 allowlist 정책으로 허용된 발신자만 통과시킵니다.

이 구조에서 초보자가 꼭 기억할 부분은 두 가지예요.

• 채널은 자동으로 모두에게 열려 있지 않습니다.
• 내가 허용한 발신자만 메시지를 보낼 수 있게 막는 보안 장치가 기본 흐름에 포함됩니다.

문서에서도 approved channel plugin마다 sender allowlist를 유지한다고 설명합니다. 허용되지 않은 발신자는 조용히 버려집니다.

실제로 Claude는 이벤트를 어떻게 받나

Channels reference 문서는 이 부분을 아주 명확하게 보여 줍니다. 채널 서버는 notifications/claude/channel 형식으로 이벤트를 보내고, Claude Code 안에서는 그 이벤트가 <channel> 태그로 들어옵니다.

예를 들면 이런 식이에요.

이 구조에서 읽어야 할 포인트는 간단합니다.

• 본문 content는 실제 메시지 내용입니다.
• meta 값들은 태그 속성으로 들어갑니다.
• source는 어느 채널에서 왔는지 보여 줍니다.

즉, Channel은 단순한 채팅 메시지라기보다 메타데이터가 붙은 구조화된 이벤트 전달 방식에 가깝습니다.

초보자가 Channels reference에서 꼭 이해해야 할 핵심은, 채널 이벤트가 그냥 텍스트 한 줄이 아니라 content + meta 조합으로 Claude 세션에 들어온다는 점입니다.

단방향 채널과 양방향 채널

문서를 보면 채널은 크게 두 가지로 나뉩니다.

단방향 채널

웹훅, 알림, 모니터링 이벤트처럼 "들어오기만 하는" 채널입니다. Claude는 이벤트를 읽고 세션 안에서 반응하지만, 같은 경로로 다시 답장을 보내지는 않습니다.

양방향 채널

Telegram, Discord 같은 채팅 브리지 형태입니다. 이 경우 채널 서버가 reply 같은 도구를 노출해서 Claude가 다시 메시지를 보낼 수 있습니다.

여기서 구조가 조금 더 개발자스럽지만, 초보자도 개념만은 알아두면 좋아요.

• 채널임을 알리려면 capabilities.experimental['claude/channel']가 필요합니다.
• 양방향으로 쓰려면 tools: {}를 열고 reply 도구를 등록합니다.
• instructions에는 Claude가 어떤 이벤트를 받고 어떻게 답할지 적어 둡니다.

이걸 아주 쉽게 바꾸면 이렇습니다.

단방향 채널은 "알림 통로"이고, 양방향 채널은 "메신저 브리지"입니다.

직접 만들고 싶다면: 커스텀 채널의 최소 구조

Reference 문서는 webhook.ts 예제로 직접 채널을 만드는 방법도 보여 줍니다. 초보자 기준에서는 코드를 외우기보다 구조를 이해하면 충분합니다.

커스텀 채널의 최소 구성은 보통 세 가지입니다.

1. MCP 서버를 만들고 채널 capability를 선언한다
2. HTTP POST나 외부 이벤트를 받아 mcp.notification()으로 전달한다
3. 필요하면 reply 도구를 추가해 양방향으로 확장한다

즉, Channels는 완전히 새로운 별도 시스템이 아니라 MCP 서버를 채널 규약에 맞게 확장한 형태라고 보면 됩니다.

이 관점이 중요한 이유는, 이미 MCP 개념을 조금 아는 사람이라면 Channels를 훨씬 쉽게 이해할 수 있기 때문입니다.

언제 Channels를 쓰고, 언제 다른 기능을 써야 할까

공식 문서는 Channels를 다른 기능과 비교해 줍니다. 초보자 입장에서 이 비교는 꽤 중요해요.

Claude Code on the web

새로운 클라우드 샌드박스에서 독립 작업을 시키는 데 더 가깝습니다. 지금 내 로컬 세션을 이어받는 방식은 아닙니다.

Claude in Slack

팀 대화 맥락에서 작업을 시작하기 좋습니다. 하지만 현재 내 로컬 세션으로 외부 이벤트를 밀어 넣는 기능과는 성격이 다릅니다.

일반 MCP 서버

Claude가 필요할 때 읽으러 가는 도구입니다. 푸시 이벤트 중심은 아닙니다.

Remote Control

내가 멀리서 직접 세션을 조종하는 기능에 가깝습니다. 반면 Channels는 외부 시스템이 세션에 신호를 보내는 데 초점이 있습니다.

정리하면 이렇게 구분하면 됩니다.

이미 열려 있는 로컬 Claude Code 세션이 외부 사건에 반응해야 한다면 Channels가 가장 잘 맞습니다.

처음 쓰는 사람을 위한 현실적인 추천 순서

처음부터 Telegram 봇, Discord 권한, 커스텀 웹훅까지 한 번에 붙이면 오히려 헷갈립니다. 문서 흐름대로 아래 순서가 가장 무난해요.

1. 먼저 fakechat으로 채널 이벤트 흐름을 체험합니다.
2. 그다음 Telegram 또는 Discord 중 익숙한 하나만 붙여 봅니다.
3. 여기서 페어링과 allowlist 개념을 이해합니다.
4. 마지막으로 CI, 에러 트래커, 배포 알림용 커스텀 채널을 검토합니다.

이 순서가 좋은 이유는, 초반에는 기술보다 개념이 더 중요하기 때문입니다. "채널이 세션 안으로 이벤트를 넣는다"는 그림만 잡히면 그다음은 플랫폼별 설정 차이일 뿐입니다.

초보자가 자주 놓치는 주의사항

마지막으로 실전에서 자주 놓치는 포인트를 정리해 둘게요.

세션이 닫혀 있으면 메시지도 오지 않는다

Channels는 항상 열려 있는 세션을 전제로 합니다. 백그라운드 실행 전략이 없으면 기대한 자동화가 성립하지 않을 수 있어요.

권한 프롬프트가 뜨면 멈출 수 있다

문서에서도, 사용자가 자리를 비운 동안 권한 승인 프롬프트가 뜨면 세션이 멈출 수 있다고 설명합니다. 완전 무인 실행을 꿈꾼다면 이 동작을 먼저 이해해야 합니다.

개발용 채널은 허용 목록과 별개로 테스트 플래그가 필요하다

연구 프리뷰 단계에서는 커스텀 채널을 만들 때 --dangerously-load-development-channels 같은 별도 테스트 플래그가 필요합니다. 정식 허용 플러그인과 개발 중 채널은 같은 취급이 아닙니다.

신뢰하지 않는 채널은 붙이지 않는 게 맞다

외부 이벤트가 현재 세션으로 들어온다는 말은 곧, 문맥이 아주 강한 작업 공간에 영향을 줄 수 있다는 뜻이기도 합니다. 문서가 allowlist와 조직 정책을 강조하는 이유가 여기에 있습니다.

요약하면

Claude Code Channels는 외부 메시지나 웹훅을 지금 실행 중인 Claude Code 세션으로 밀어 넣는 기능입니다. 일반 MCP처럼 Claude가 필요할 때 조회하는 구조가 아니라, 외부 시스템이 먼저 신호를 보내 Claude가 로컬 문맥 안에서 바로 반응하게 만듭니다.

초보자라면 fakechat으로 구조를 먼저 이해하고, 그다음 Telegram이나 Discord, 마지막으로 커스텀 웹훅 채널로 확장해 보는 순서가 가장 좋습니다. 문서를 읽을 때는 설치 명령보다 먼저, 세션 기반, 푸시 방식, 단방향/양방향, allowlist, 연구 프리뷰 제약 이 다섯 가지를 머릿속에 넣어 두면 전체 구조가 훨씬 쉽게 보입니다.