Mila Telegram

Telegram에서 Claude Code 세션을 실행하고 — 계속 실행 상태를 유지하세요.

이것은 공식 Telegram 채널 플러그인(Apache-2.0)의 확장 포크입니다. 원본은 Telegram 봇을 Claude Code 세션에 연결합니다. 이 포크는 실제로 매일 그렇게 작업하기 시작하면 필요해지는 기능들을 추가합니다: 그룹 채팅에서의 팀 협업, 음성 메모, 그리고 세션이 재시작되어도 메시지를 잃지 않는 폴러(poller).

이 포크가 추가하는 것

세션보다 오래 사는 데몬. 원본에서는 Telegram 폴러가 세션 프로세스 안에 있습니다: Claude Code를 재시작하면 그 사이에 보낸 모든 메시지가 사라집니다. 여기서는 폴러가 장기 실행 데몬으로 동작하여 이벤트를 저널 파일에 추가하고, 세션은 시작 시 커서(cursor)부터 이를 재생합니다. 재시작, 크래시, 업그레이드 — 들어오는 메시지는 파일에 대기하다가 세션이 돌아오면 도착합니다.

원탭 승인으로 그룹 자동 참여. 봇을 그룹에 추가하고 /channel_join을 보내세요. 소유자는 개인 채팅에서 4버튼 카드를 받습니다: 모두에게 답장, 멘션 전용, 듣기 전용(봇은 채팅을 듣지만, 그에 대한 답장은 기계적으로 차단됨), 또는 거부. 모든 결정 — 거부 포함 — 은 auth-log.jsonl 저널에 추가되며, 각 연결된 채팅은 chats/<id>.md의 컨텍스트 카드와 생성된 CHATS.md 레지스트리를 얻습니다. 숫자 채팅 ID도, JSON을 직접 편집할 필요도 없습니다; 그룹 메시지는 스스로 허용 목록을 변경할 수 없습니다 — 승인은 소유자의 개인 채팅에서만 발생합니다.

음성 전사. 음성 메모는 선택한 전사 명령( TELEGRAM_VOICE_TRANSCRIBE_CMD 설정)에 전달되며, 텍스트는 오디오와 함께 어시스턴트에게 도달합니다. 설정하지 않으면 음성 메모는 전사 없이 그대로 통과합니다 — 기본값도, 벤더도 없습니다.

답장 인용 컨텍스트. 누군가 이전 메시지에 답장하면, 인용된 텍스트가 새 메시지와 함께 전달되어, 어시스턴트는 채팅의 마지막 내용 대신 실제로 가리킨 메시지에 대해 답변합니다.

원본 플러그인의 모든 기능은 여전히 작동합니다: 페어링, 허용 목록, 멘션 감지, reply / react / edit_message, 사진, 첨부 파일, 타이핑 표시기.

Related MCP server: tsgram-mcp

보안

중요한 머신에 배포하기 전에 이 내용을 읽으세요.

메시지는 신뢰할 수 없는 입력입니다. 누구든 봇에 보내는 모든 것은 콘텐츠로 어시스턴트에게 도달합니다. 허용 목록에 있는 채팅의 누군가는 이를 지시하려 시도할 수 있습니다. 채널을 파일을 읽고 명령을 실행할 수 있는 세션으로 통하는 공개 문으로 취급하세요.

그룹은 기본적으로 멘션이 필요합니다. 승인된 그룹은 requireMention: true로 추가되므로, 봇은 호출될 때만 응답합니다. 이를 끄면 모든 멤버의 모든 메시지가 세션으로 직접 들어갑니다 — 이것은 이론적인 것이 아니라 실제 프롬프트 인젝션 표면입니다. 모든 멤버를 신뢰하는 채팅에서만 끄세요.

첨부 파일이 나갈 수 있습니다. reply 도구는 어시스턴트가 전달하는 모든 절대 경로를 보냅니다. 이것은 의도된 것입니다 — 세션에서 파일을 꺼내는 방법이기 때문입니다 — 하지만 위의 사항과 결합하면 이것은 또한 유출 경로입니다. 메시지와 파일이 머신을 떠나는 사이를 막는 것은 이 플러그인이 아니라 여러분의 권한 설정입니다.

이벤트 저널은 신뢰 경계입니다. 데몬은 이벤트를 파일에 쓰고 세션은 이를 재생합니다; 그 파일에 쓸 수 있는 무엇이든 Telegram의 목소리로 말합니다. 저널과 그 디렉토리는 0600/0700으로 생성되며, 브리지는 두 가지 메서드의 허용 목록만 재생하므로 위조된 줄이 임의의 메서드를 호출할 수 없습니다. 상태 디렉토리를 자신만 쓸 수 있는 파일시스템에 두세요.

토큰은 ~/.claude/channels/telegram/.env에 0600 권한으로 저장되며, 로그에 기록되기 전에 오류 출력에서 제거됩니다.

사전 요구 사항

• Bun — MCP 서버는 Bun에서 실행됩니다: curl -fsSL https://bun.sh/install | bash

설정

1. 봇을 만듭니다. @BotFather에게 메시지를 보내고 /newbot을 보낸 다음 받은 토큰(앞의 숫자와 콜론을 포함한 전체)을 복사하세요.

2. 플러그인을 설치합니다. Claude Code 세션에서:

/plugin marketplace add shakhruz/mila-telegram
/plugin install mila-telegram@mila

3. 서버에 토큰을 제공합니다.

/telegram:configure 123456789:AAHfiqksKZ8...

이것은 TELEGRAM_BOT_TOKEN=...을 ~/.claude/channels/telegram/.env에 기록합니다. 직접 해당 파일을 작성하거나 셸에서 변수를 설정할 수도 있습니다 — 셸이 우선합니다.

한 머신에서 여러 봇을 실행하려면 인스턴스마다 TELEGRAM_STATE_DIR을 다른 디렉토리로 지정하세요.

4. 채널 플래그로 재실행합니다. 서버는 이 플래그 없이는 연결되지 않습니다:

claude --channels plugin:mila-telegram@mila

5. 페어링합니다. 봇에게 DM을 보내면 6자리 코드로 답장합니다. 세션에서:

/telegram:access pair <code>

6. 잠급니다. 페어링은 여러분의 ID를 캡처하기 위해 존재합니다. 등록이 끝나면 허용 목록으로 전환하여 낯선 사람이 페어링 코드를 받지 못하게 하세요:

/telegram:access policy allowlist

데몬 실행

데몬이 재시작을 자유롭게 만드는 핵심입니다. receiver.ts를 선택한 프로세스 슈퍼바이저 — macOS의 launchd, Linux의 systemd — 아래에서 서비스로 실행하고, 환경에 RECEIVER_DAEMON=1을 설정하세요:

RECEIVER_DAEMON=1 bun /path/to/plugin/receiver.ts

이것은 이벤트를 $TELEGRAM_STATE_DIR/inbound/events.jsonl에 기록합니다. 세션이 시작되어 데몬이 살아있는 것을 발견하면 폴링 대신 해당 저널에서 읽으므로, 둘이 Telegram API를 두고 충돌하지 않습니다. 데몬이 실행 중이 아니면 세션은 원본 플러그인과 정확히 동일하게 직접 폴링합니다 — 데몬은 선택 사항입니다.

구성

접근 제어

DM 정책, 그룹, 멘션 감지, 전달 구성, 스킬 명령 및 access.json 스키마는 ACCESS.md 를 참조하세요.

ID는 숫자 사용자 ID입니다 — @userinfobot에서 확인하세요. ackReaction은 Telegram의 고정 이모지 허용 목록만 수락합니다.

어시스턴트에 노출되는 도구

수신 메시지는 자동으로 타이핑 표시기를 트리거합니다.

기록 없음, 검색 없음

Telegram의 Bot API는 둘 다 제공하지 않습니다. 봇은 도착하는 메시지만 볼 수 있습니다 — 채팅의 과거를 가져올 방법이 없습니다. 어시스턴트가 이전 컨텍스트가 필요하면 여러분에게 요청해야 합니다. 이것은 이 플러그인의 한계가 아니라 Telegram의 한계이며, 사진이 도착 시 즉시 다운로드되는 이유이기도 합니다.

라이선스 및 저작자 표시

Apache-2.0. 이것은 anthropics/claude-plugins-official의 telegram 채널 플러그인에서 수정된 포크이며, 저작권은 Anthropic, PBC에 있습니다. 변경 목록은 NOTICE를 참조하세요.