Telegram에서 Claude Code를 위한 TeleClaude

# TeleClaude: 자체 호스팅 텔레그램 봇으로 격리된 Claude 코드 세션 구현

OpenClaw 서비스 종료 후 개발자들이 텔레그램을 통해 Claude Code에 접근하지 못하게 되었습니다. TeleClaude가 이를 해결합니다: Bun 기반 TypeScript 앱으로 로컬 Claude Code CLI 프로세스를 실행하며, 슈퍼그룹 토픽의 메시지를 격리된 프로젝트 디렉터리로 라우팅합니다. 본인 Claude 구독의 OAuth 인증을 사용해 중간자 없이 운영됩니다.

아키텍처와 라우팅

TeleClaude는 Grammy를 통해 텔레그램 봇 API에 연결됩니다. 슈퍼그룹 토픽의 모든 메시지가 전용 Claude Code 프로세스를 생성하며, 각자 독립된 프로젝트 폴더를 가집니다. 세션 연속성, 컨텍스트 압축, 메모리 중복 제거를 지원합니다.

텔레그램 봇 API → Grammy 라우터 → 프로세스 매니저 → Claude Code CLI (토픽별)

주요 구성 요소:

• 토픽 기반 라우팅과 컨텍스트 주입.
• TTL, 동시성 제한, 정리 기능이 있는 프로세스 매니저.
• 파일 기반 메모리: SOUL.md (성격), main-memory.md (공유 지식 베이스), topic-memory.md (프로젝트 히스토리).

메모리 시스템과 계층

세션을 넘어 컨텍스트를 유지하기 위해 메모리를 3계층으로 구조화했습니다:

project/
├── SOUL.md              # 대화 스타일, 규칙
├── main-memory.md       # 공유 지식 베이스 심볼릭 링크
├── topic-memory.md      # 자동 업데이트 프로젝트 히스토리
└── memory/
    ├── people/
    ├── services/
    ├── shared/
    └── projects/

Claude Code가 topic-memory.md를 스스로 업데이트합니다. 재시작이나 세션 리셋 시 파일에서 컨텍스트를 다시 로드합니다. 중복 제거는 주기적으로 파일 간 중복을 제거합니다.

프로젝트 자동화와 압축

슈퍼그룹의 새 토픽이 생성되면 templates/에서 디렉터리를 자동 생성합니다. 봇이 SOUL.md, main-memory.md를 연결하고 메모리를 초기화합니다. 첫 메시지로 전체 컨텍스트가 준비된 Claude Code를 시작합니다.

컨텍스트 한도에 가까워지면 압축이 작동: 핵심 사실을 메모리에 저장하고 세션을 리셋합니다. /compact 명령으로 수동 실행 가능합니다.

TeleClaude 주요 기능

• 토픽 라우팅: 격리된 프로세스와 디렉터리.
• 영속 메모리: 프로젝트 간 접근 가능한 3계층 구조.
• 자동 프로젝트 생성: 새 토픽용 템플릿.
• 음성 메시지: 선택적 로컬 Whisper 전사.
• 스트리밍: 입력 중 표시와 점진적 업데이트.
• 모델: Opus, Sonnet, Haiku 또는 Claude Code 로컬.
• 관리: TTL, 제한, 프로세스 종료.

설치와 설정

필수: Bun 1.0+, 인증된 Claude Code CLI, 텔레그램 봇, 토픽 지원 슈퍼그룹.

git clone https://github.com/devladpopov/teleclaude.git
cd teleclaude
bun install
cp .env.example .env
cp config/settings.example.json config/settings.json
bun run start

settings.json에서 allowedUsers, ttlMinutes (기본 30), maxConcurrent (5), claudePath 설정.

봇 명령어

| 명령어 | 설명 |

|--------|------|

| /help | 명령어 목록 |

| /status | 활성 프로세스, 상태 |

| /ttl N | 유휴 타임아웃 (1–1440분) |

| /name <이름> | 토픽 이름 변경 |

| /reset | 메모리 보존하며 리셋 |

| /kill | 토픽 프로세스 중지 |

| /memory | 메모리 통계 |

TeleClaude vs OpenClaw

| 항목 | TeleClaude | OpenClaw |

|------|------------|----------|

| 호스팅 | 자체 호스팅 | 클라우드 |

| 백엔드 | Claude Code CLI | API |

| 인증 | 본인 OAuth 구독 | 관리형 |

| 비용 | Claude 구독만 | 추가 요금 |

| 메모리 | 파일 기반, 영속 | 내장형 |

주요 장점

• 창 전환 없이 완전한 토픽 격리.
• Claude 구독 외 비용 없음.
• 자동 압축과 컨텍스트 복구.
• Whisper 음성 지원과 스트리밍 응답.
• MIT 라이선스, 커스터마이징 가능한 템플릿과 설정.

— Editorial Team