Telegram Bot — AI skill for Claude Code

Telegram Bot

使用 Python + python-telegram-bot + Claude CLI 建立的智能 Telegram Bot，支援 AI 對話、圖片生成等功能。

功能特色

• AI 對話：整合 Claude CLI，支援智能對話
• 圖片生成：透過 MCP 工具（nanobanana）生成圖片
• 即時通知：AI 處理時顯示 Tool 執行狀態
• 權限控制：用戶白名單（預設拒絕）、群組白名單
• 群組支援：需 @Bot 或回覆 Bot 才會回應
• 服務管理：支援 systemd 服務安裝

專案結構

telegram-bot/
├── main.py              # 主程式
├── services/
│   └── claude_agent.py  # Claude CLI 整合
├── scripts/
│   ├── start.sh             # 啟動腳本
│   ├── install-service.sh   # 安裝 systemd 服務
│   └── uninstall-service.sh # 卸載服務
├── .env                 # 環境變數（不納入版控）
├── .env.example         # 環境變數範例
├── .mcp.json            # MCP 工具配置（不納入版控）
├── .mcp.json.example    # MCP 配置範例
├── pyproject.toml       # 專案設定
└── README.md            # 本文件

快速開始

1. 建立 Telegram Bot

1. 在 Telegram 找 @BotFather
2. 發送 /newbot 建立新 Bot
3. 記下 Bot Token
4. 發送 /setprivacy → 選擇 Bot → Disable（允許收到群組訊息）

2. 安裝依賴

cd telegram-bot

# 安裝 uv（如果還沒有）
curl -LsSf https://astral.sh/uv/install.sh | sh

# 安裝依賴
uv sync

3. 設定環境變數

cp .env.example .env
nano .env

編輯 `.env`：

# ============ Telegram 設定 ============

# Bot Token（必填）
TELEGRAM_BOT_TOKEN=your_bot_token_here

# 用戶白名單（必填，逗號分隔）
# 留空 = 拒絕所有人（但 /status 仍可查詢自己的 ID）
ALLOWED_USER_IDS=123456789

# 管理員 ID（選填，Bot 啟動時會收到通知）
ADMIN_USER_ID=123456789

# 群組白名單（選填，逗號分隔）
# 留空 = 不允許任何群組
ALLOWED_GROUP_IDS=-1001234567890

# ============ AI 設定 ============

# 是否啟用 AI
AI_ENABLED=true

# AI 模型（opus, sonnet, haiku）
AI_MODEL=sonnet

# 是否顯示 Tool 執行通知
AI_NOTIFY_TOOLS=true

# System Prompt
AI_SYSTEM_PROMPT=你是一個友善的助手。請用繁體中文回答。

# 允許的工具（逗號分隔）
AI_ALLOWED_TOOLS=WebSearch,WebFetch,Read

# ============ MCP 工具設定 ============

# Nanobanana 圖片生成（使用 Gemini API）
NANOBANANA_GEMINI_API_KEY=your_gemini_api_key_here
NANOBANANA_MODEL=gemini-3-pro-image-preview

4. 設定 MCP 工具（選填）

如需使用圖片生成等 MCP 工具：

cp .mcp.json.example .mcp.json
nano .mcp.json

編輯 `.mcp.json`，將路徑改為你的專案路徑：