# Claudeclaw

> Claude Code Channels 텔레그램 연동 설치 가이드. Bun 설치부터 텔레그램 봇 생성, 플러그인 설치, 채널 페어링, 보안 설정까지 Windows/macOS/Linux 초보자도 따라할 수 있는 단계별 안내.

- Skill: `canine89/claudeclaw` (Agent Skill)
- Install (CLI): `npx skillmds@latest add canine89/claudeclaw`
- Raw SKILL.md: https://api.skillmd.com/api/skills/canine89/claudeclaw/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: canine89 (https://skillmd.com/u/canine89)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/canine89/claudeclaw

---


# ClaudeClaw - Claude Code Channels 텔레그램 연동 가이드

Claude Code의 **Channels** 기능을 사용하여 텔레그램에서 직접 Claude에게 작업을 지시할 수 있도록 연동하는 설치 가이드 스킬입니다.

> **Channels란?** Anthropic의 MCP(Model Context Protocol)를 활용하여, 텔레그램 같은 메신저 앱을 실행 중인 내 PC의 Claude Code 세션과 양방향으로 연결해 주는 기능입니다. 컴퓨터 앞을 떠나 이동 중에도 휴대폰 메신저를 통해 Claude에게 코딩 작업을 지시하고, 결과를 실시간으로 받아볼 수 있습니다.

---

## 사전 준비물

| 준비물 | 설명 |
|--------|------|
| **Claude Code CLI** | 시스템에 설치 완료 상태여야 합니다 |
| **유료 플랜** | Claude Pro, Team 등 유료 플랜에 로그인되어 있어야 합니다 |
| **Bun 런타임** | 텔레그램 플러그인 서버가 Bun에서 동작합니다 (아래 설치 방법 참고) |
| **텔레그램 앱** | 모바일 또는 데스크톱 앱 |
| **텔레그램 계정** | 봇 생성을 위해 필요합니다 |

### Bun 설치 (아직 설치하지 않은 경우)

**macOS / Linux:**

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

설치 후 터미널을 새로 열거나 아래 명령어로 환경변수를 적용합니다:

```bash
source ~/.bashrc   # bash 사용자
source ~/.zshrc    # zsh 사용자 (macOS 기본)
```

**Windows (PowerShell 관리자 권한):**

```powershell
powershell -c "irm bun.sh/install.ps1 | iex"
```

> Windows에서는 PowerShell을 **관리자 권한**으로 실행한 뒤 위 명령어를 입력하세요. 설치 후 PowerShell을 새로 열어야 `bun` 명령어가 인식됩니다.

**설치 확인 (모든 OS 공통):**

```bash
bun --version
```

버전 번호가 출력되면 정상 설치된 것입니다.

---

## 1단계: 텔레그램 봇 생성 및 토큰 발급

> 먼저 텔레그램에서 봇을 만들고 API 토큰을 발급받습니다.

### 1-1. BotFather에서 봇 만들기

1. 텔레그램 앱을 열고 검색창에 **@BotFather**를 검색합니다.
2. BotFather 채팅에서 **Start** 버튼을 누릅니다.
3. `/newbot` 명령어를 입력합니다.
4. 봇의 **표시 이름**(예: `My Claude Bot`)을 입력합니다.
5. 봇의 **사용자명**(예: `my_claude_helper_bot`)을 입력합니다.
   - 반드시 `bot`으로 끝나야 합니다.

### 1-2. API 토큰 복사

봇 생성이 완료되면 BotFather가 다음과 같은 메시지를 보냅니다:

```
Use this token to access the HTTP API:
123456789:AAH_이런형식의_긴_문자열
```

이 토큰을 **복사**해 둡니다.

> **주의:** API 토큰은 비밀번호와 같습니다. 절대 다른 사람에게 공유하지 마세요.

---

## 2단계: 텔레그램 플러그인 설치

### 2-1. Claude Code 실행

**macOS / Linux:**

```bash
claude
```

**Windows (PowerShell 또는 명령 프롬프트):**

```powershell
claude
```

> **팁:** 설치 과정에서 매번 승인을 누르기 번거롭다면 `claude --dangerously-skip-permissions`로 실행할 수 있습니다. 설치가 끝나면 일반 모드로 다시 실행하세요.

### 2-2. 플러그인 설치

Claude Code 프롬프트에 아래 명령어를 입력합니다:

```
/plugin install telegram@claude-plugins-official
```

- 설치 범위(scope)를 물으면 **project** 또는 **user** 중 원하는 범위를 선택합니다.
  - `user`: 모든 프로젝트에서 사용 가능 (추천)
  - `project`: 현재 프로젝트에서만 사용
- 아직 **프리뷰(Preview)** 기능이므로 일부 불안정할 수 있습니다.

> **플러그인을 찾을 수 없다는 에러가 나올 때:** `/plugin marketplace update claude-plugins-official`을 먼저 실행하여 목록을 갱신한 뒤 다시 시도하세요.

---

## 3단계: 토큰 설정

1단계에서 BotFather로부터 발급받은 텔레그램 토큰을 Claude Code에 등록합니다.

```
/telegram:configure <발급받은_토큰>
```

예시:

```
/telegram:configure 123456789:AAH_이런형식의_긴_문자열
```

엔터를 눌러 설정을 적용합니다.

---

## 4단계: Channels 플래그로 재시작

> **이 단계가 매우 중요합니다.** `--channels` 플래그 없이 실행하면 텔레그램 연동이 동작하지 않습니다.

현재 실행 중인 Claude Code 세션을 종료합니다:

```
exit
```

그런 다음, `--channels` 플래그를 추가하여 다시 실행합니다:

**macOS / Linux:**

```bash
claude --channels plugin:telegram@claude-plugins-official
```

**Windows (PowerShell):**

```powershell
claude --channels plugin:telegram@claude-plugins-official
```

터미널에 채널 수신 관련 메시지가 표시되면 정상입니다.

> **메시지가 안 나오면:** 2단계의 플러그인 설치가 제대로 되었는지 확인하세요. Claude Code를 완전히 종료 후 다시 시도해 보세요.

---

## 5단계: 기기 페어링 (Pairing)

### 5-1. 텔레그램에서 봇 시작

1. 텔레그램 앱으로 돌아갑니다.
2. 1단계에서 만든 봇을 검색합니다 (설정한 사용자명으로).
3. **Start** 버튼을 누르거나 `/start`를 입력합니다.

### 5-2. 페어링 코드 확인

봇이 **6자리 페어링 코드**를 답장으로 보냅니다.

> **페어링 코드가 안 오면:**
> - 4단계의 `--channels` 플래그 실행이 정상적으로 되었는지 확인하세요.
> - 봇에게 `/start`를 다시 입력해 보세요.
> - BotFather에서 토큰이 맞는지 확인하세요.

### 5-3. Claude Code에서 페어링 완료

Claude Code 프롬프트로 돌아와서 아래 명령어로 기기를 연결합니다:

```
/telegram:access pair <6자리_페어링_코드>
```

예시:

```
/telegram:access pair 482951
```

승인(Yes) 프롬프트가 나오면 **Yes**를 선택합니다.

---

## 6단계: 보안 설정 (Allowlist)

> **반드시 수행하세요!** 초기 페어링 모드에서는 봇 주소를 아는 누구나 메시지를 보낼 수 있습니다. 본인만 사용할 수 있도록 접근 정책을 변경해야 합니다.

Claude Code 프롬프트에 아래 명령어를 입력합니다:

```
/telegram:access policy allowlist
```

승인(Yes)을 누르면:
- 허용 목록(Allowlist)에 등록된 본인만 소통 가능
- 타인의 접근이 완전히 차단됩니다

> **왜 필요한가요?** Allowlist 없이는 누구나 봇을 통해 Claude에 접근할 수 있어 보안 위험이 있습니다.

---

## 7단계: 연동 테스트

### 7-1. 간단한 메시지 테스트

텔레그램 봇 채팅창에 입력합니다:

```
Hi Claude
```

Claude Code 터미널에 메시지가 표시되고 응답이 오면 **연동 성공**입니다!

### 7-2. 작업 명령 테스트

텔레그램에서 실제 작업 명령을 보내봅니다:

```
현재 디렉토리에 index.html 파일 만들어줘
```

Claude Code가 요청을 수신하고 작업을 수행한 뒤, 텔레그램으로 결과를 돌려보내는 것을 확인합니다.

---

## 문제 해결 (트러블슈팅)

| 증상 | 해결 방법 |
|------|-----------|
| `bun: command not found` | Bun 설치 후 터미널을 새로 열었는지 확인. Windows는 PowerShell 재시작 |
| 플러그인 설치 실패 | 인터넷 연결 확인. `/plugin marketplace update claude-plugins-official` 실행 후 재시도 |
| `--channels` 실행 후 채널 메시지가 안 나옴 | 플러그인이 정상 설치되었는지 확인. Claude Code 완전 종료 후 재시작 |
| 텔레그램 봇에서 페어링 코드가 안 옴 | 봇에 `/start` 다시 입력. BotFather에서 토큰이 맞는지 확인. `--channels` 플래그로 실행했는지 확인 |
| `/telegram:access pair` 실패 | 코드를 정확히 입력했는지 확인. 시간이 지나면 코드가 만료될 수 있으니 `/start`로 새 코드를 받으세요 |
| 페어링 후에도 메시지가 안 옴 | Claude Code 재시작 시 반드시 `--channels plugin:telegram@claude-plugins-official` 플래그를 포함했는지 확인 |
| API 토큰 오류 | BotFather에서 `/token` 명령으로 토큰 재확인. `/telegram:configure`로 다시 설정 |
| Windows에서 Claude Code가 실행 안 됨 | Node.js 및 npm이 설치되어 있는지 확인. PowerShell 관리자 권한으로 실행 |

---

## Windows 사용자 참고 사항

- **터미널 선택:** PowerShell 또는 Windows Terminal 사용을 권장합니다. 기본 명령 프롬프트(cmd)도 가능하지만, PowerShell이 더 안정적입니다.
- **경로 구분자:** Windows에서는 파일 경로에 `\`(백슬래시)를 사용하지만, Claude Code 내 명령어에서는 `/`를 사용해도 무방합니다.
- **방화벽:** Windows Defender 방화벽이 연결을 차단할 수 있습니다. Claude Code나 Bun이 네트워크 접근을 요청하면 **허용**을 선택하세요.
- **백그라운드 실행:** 텔레그램 연동을 유지하려면 Claude Code 터미널 창을 열어 둔 채로 유지해야 합니다. 터미널을 닫으면 연결이 끊어집니다.

---

## 참고: 전체 명령어 요약 (Quick Reference)

```bash
# 0. Bun 설치 (macOS/Linux)
curl -fsSL https://bun.sh/install | bash

# 0. Bun 설치 (Windows PowerShell 관리자 권한)
# powershell -c "irm bun.sh/install.ps1 | iex"

# 1. Claude Code 실행
claude

# 2. 텔레그램 플러그인 설치
/plugin install telegram@claude-plugins-official

# 3. API 토큰 설정 (BotFather에서 발급받은 토큰)
/telegram:configure YOUR_BOT_TOKEN

# 4. Claude Code 종료 후 --channels 플래그로 재시작
exit
claude --channels plugin:telegram@claude-plugins-official

# 5. 텔레그램 봇에서 받은 6자리 페어링 코드로 연결
/telegram:access pair YOUR_6DIGIT_CODE

# 6. 보안 설정 (Allowlist)
/telegram:access policy allowlist
```

---

## 추가 활용

- **커스텀 채널 확장**: Anthropic의 'Build your own channel' 문서를 참고하면 텔레그램 외에도 자체 서비스(SaaS 등)에서 Claude 세션에 프롬프트를 직접 보내는 구조를 만들 수 있습니다.
- **Discord 연동**: 디스코드 개발자 포털(Developer Portal)에서 봇을 생성하고 토큰을 발급받은 뒤, 비슷한 과정으로 플러그인을 연동할 수 있습니다.
- **활용 예시**: 슬랙 봇, 디스코드 봇, 자체 웹 대시보드 등에서 Claude Code로 작업 지시 가능