Claude Code에 Channels라는 기능이 있다는 것을 알고 사용해 보았습니다.

이것은 Discord나 Telegram 같은 외부 메시징 앱에서 로컬에서 실행 중인 Claude Code 세션으로 메시지를 보내 조작할 수 있는 구조입니다. 즉, 스마트폰의 Discord 앱에서 "이 버그 좀 고쳐줘"라고 보내면, PC에서 실행 중인 Claude Code가 그대로 응답해 줍니다.

이번에는 Discord와의 연동을 설정할 때의 절차와 몇 가지 어려움을 겪었던 포인트를 공유합니다.

• macOS Sequoia
• Claude Code v2.1.165
• Claude Max 플랜 (Anthropic 직접 인증)

Channels를 사용하려면 몇 가지 전제 조건이 있습니다.

먼저, Claude Code는 v2.1.80 이상이 필요합니다. 또한, 인증은 Anthropic 직접 인증(claude.ai 계정 또는 Console API 키)만 대응하며, Amazon Bedrock나 Google Vertex를 통해서는 이용할 수 없습니다.

비용 측면에서는 Claude Code의 구독 내에서 완결되므로 추가 과금은 발생하지 않습니다. 다만, Channels를 통한 주고받음도 통상적인 이용량으로 카운트되므로, Max 플랜의 상한에 빨리 도달할 가능성은 있습니다.

참고로, Channels는 세션을 열어두고 있는 동안에만 동작합니다. Claude Code를 닫으면 메시지를 받을 수 없게 되므로 이 점은 주의가 필요합니다.

Channels 플러그인은 Bun으로 동작하므로, 먼저 설치해 둡니다.

curl -fsSL https://bun.sh/install | bash

Bun의 인스톨러는 ~/.zshrc에만 PATH를 추가합니다. 하지만 Claude Code의 플러그인 프로세스는 로그인 셸(Login Shell)로서 기동하기 때문에 ~/.zprofile을 읽습니다. .zprofile에도 PATH를 추가하지 않으면 플러그인이 기동되지 않습니다.

# ~/.zprofile に以下を追加
export BUN_INSTALL="$HOME/.bun"
export PATH="$BUN_INSTALL/bin:$PATH"

.zshrc는 터미널을 열었을 때(인터랙티브 셸(Interactive Shell)) 읽히는 파일이고, .zprofile은 로그인 셸 기동 시에 읽히는 파일입니다. PATH와 같이 시스템 전체에서 사용하는 환경 변수는 .zprofile에 쓰는 것이 정답이지만, 많은 인스톨러가 .zshrc에만 쓰기 때문에 백그라운드 프로세스에서 문제가 생길 수 있습니다. 저도 이 부분에서 한동안 헤맸습니다.

Discord Developer Portal에서 Bot을 생성합니다.

「New Application」에서 새로운 애플리케이션을 만들고, 원하는 이름을 붙입니다. 저는 kuroko-chan으로 했습니다.

왼쪽 메뉴의 「Bot」을 열고 「Reset Token」을 클릭하면 Bot 토큰이 표시됩니다. 이 토큰은 한 번밖에 표시되지 않으므로 복사해서 따로 적어두세요.

같은 Bot 페이지 하단에 있는 「Message Content Intent」는 ON으로 해두어야 합니다. 이것이 OFF라면 메시지 내용을 읽을 수 없습니다.

왼쪽 메뉴의 「OAuth2 → URL Generator」를 열고, Scopes에서 bot에 체크를 넣습니다.

Bot Permissions에서는 View Channels, Send Messages, Send Messages in Threads, Read Message History, Attach Files, Add Reactions에 체크를 넣습니다.

생성된 URL을 브라우저에서 열면, Bot을 어느 서버에 추가할지 선택할 수 있으므로 제 서버를 선택하여 추가합니다.

여기서부터는 Claude Code의 CLI로 작업합니다. 이번에 이용할 Discord 플러그인은 Anthropic 공식 플러그인 리포지토리(Plugin Repository)에서 공개되어 있습니다.

최근 Desktop 버전(Claude Desktop)을 사용하고 있습니다만, Desktop 버전에서는 /plugin

명령어를 사용할 수 없었기 때문에, 터미널에서 Claude Code를 실행하여 진행했습니다.

claude /plugin install discord@claude-plugins-official

실행하면 플러그인 목록이 표시되므로, discord를 선택합니다.

이어서 토큰을 설정합니다.

claude /discord:configure <봇 토큰>

토큰 설정이 완료되면, Channels 기능이 포함된 상태로 Claude Code를 실행합니다.

claude --channels plugin:discord@claude-plugins-official

실행한 후, Discord에서 Bot에게 DM을 보냅니다. 내용은 「hello」 등 무엇이든 괜찮습니다. 그러면 Bot으로부터 페어링 코드(Pairing Code)가 돌아오므로, Claude Code의 CLI에서 다음을 실행합니다.

/discord:access pair <페어링 코드>

마지막으로 보안 설정으로서, 저에게만 액세스를 제한해 둡니다.

/discord:access policy allowlist

이것으로 DM을 통한 연동은 완료되었습니다. Discord에서 Bot에게 메시지를 보내면, Claude Code가 응답해 줍니다.

DM뿐만 아니라, Discord 서버의 텍스트 채널에서도 멘션(Mention)을 통해 주고받을 수 있습니다.

먼저 Discord 설정에서 「고급 설정 → 개발자 모드」를 ON으로 합니다. 그다음, 상호작용하고 싶은 텍스트 채널을 우클릭하여 「채널 ID 복사」를 선택합니다.

복사한 채널 ID를 사용하여, Claude Code의 CLI에서 다음을 실행합니다.

/discord:access group add <텍스트 채널 ID>

단, 채널을 추가한 것만으로는 멘션에 반응하지 않았습니다. Bot이 어떤 멘션에 반응할지를 나타내는 mentionPatterns (멘션 판정용 패턴 설정)가 미설정되어 있었기 때문입니다. 다음 명령어로 Bot의 멘션 패턴을 설정해야 합니다.

/discord:access set mentionPatterns <@Bot의 사용자 ID>, <@!Bot의 사용자 ID>

Discord의 멘션은 내부적으로 <@사용자 ID>와 <@!사용자 ID> 두 종류의 형식으로 전송되는 경우가 있으므로, 둘 다 등록해 둡니다. Bot의 사용자 ID는 Discord의 개발자 모드에서 Bot의 프로필을 우클릭하여 복사할 수 있습니다.

이제 해당 채널에서 @kuroko-chan 이렇게 해줘라고 멘션을 포함하여 메시지를 보내면 응답하게 됩니다.

Discord의 개발자 모드에서는 서버 이름을 우클릭해도 「서버 ID 복사」가 표시됩니다. group add에 전달하는 것은 서버 ID가 아니라 텍스트 채널의 ID입니다. 서버 ID를 지정해도 에러 없이 등록은 되지만, 메시지가 도착하지 않습니다.

기본적으로는 Discord에서 메시지가 올 때마다 Claude Code 측에서 권한 확인 프롬프트가 표시됩니다. 스마트폰으로 조작하는 용도라면 매번 PC의 터미널에서 허가하는 것은 현실적이지 않으므로, 자동 허가 설정을 해두는 것이 좋다고 생각합니다.

Claude Code의 권한 설정에 대해서는 다음 문서에 자세히 적혀 있습니다.

~/.claude/settings.json의 permissions.allow에 다음을 추가합니다.

{
"permissions": {
"allow": [
...

서버에도 도입할 수 있어서 여러 가지를 정비해 달라고 하려 했으나, 이번에 이용 중인 플러그인에는 서버를 조작하는 툴이 없는 것 같습니다. 이 부분은 앞으로 직접 제작해 보고 싶습니다.

셋업 자체는 그리 복잡하지 않지만, Bun의 PATH를 .zprofile에 작성해야 하는 점이나, 권한 와일드카드 패턴의 포맷, 서버 ID와 채널 ID의 착오 등 은근히 막히는 포인트가 몇 가지 있었습니다.

외출 중에도 스마트폰으로 Claude Code에 지시를 내릴 수 있다는 점은 꽤 편리하므로, 관심 있는 분들은 시도해 보시기 바랍니다.

감사합니다.