一款将 Claude Code 接入 Telegram 的 Python 机器人，支持远程 AI 编程、会话持久化、Webhook 自动化及安全沙箱，适合移动开发与远程运维场景。

Claude Code Telegram Bot#

项目简介#

Claude Code Telegram Bot 是连接即时通讯平台 Telegram 与 Anthropic Claude Code 能力的中间件层。其核心目标是打破 Claude Code 仅限本地终端或 IDE 的使用边界，允许开发者通过移动端或远程桌面以自然语言对话的形式操控 Claude Code 执行代码编写、重构、调试及文件操作。

该项目不仅提供了基础的聊天网关，还内置了完整的会话生命周期管理（自动持久化与恢复）、企业级安全控制（用户白名单、目录沙箱、速率限制）以及扩展的事件驱动架构。这意味着除了手动交互外，用户还可通过 GitHub Webhooks 或内置 Job Scheduler 触发 Claude 执行自动化任务，并将结果推送到指定的 Telegram 群组或频道。

核心功能#

交互模式#

Agentic Mode (默认): 自然语言驱动，无需记忆复杂指令，Claude 自动解析意图并执行。支持 /start, /new, /status, /verbose, /repo 五个核心指令。
Classic Mode: 传统 CLI 风格，提供 /cd, /ls, /pwd, /projects 等 13 个类终端命令，适合习惯命令行的用户。
Multi-verbosity: 通过 /verbose 0|1|2 控制输出详细度（静默/正常/详细），适应不同场景的信息需求。

会话与存储#

Session Persistence: 基于用户 ID 和项目目录自动持久化会话，支持断点续传，无需重复上下文。
Project Threads: 支持多项目切换与管理，每个项目维护独立的会话上下文。
Media Support: 支持向 Claude 上传图片与文件进行多模态分析。

自动化与事件#

Webhook API Server: 内置 FastAPI 服务，支持 GitHub (HMAC-SHA256) 和 Generic (Bearer Token) 两种认证方式，实现外部事件触发。
Job Scheduler: 基于 APScheduler 的 Cron 任务调度，支持定时触发 Claude 执行任务（如每日代码检查）。
Notification Service: 支持分片推送与广播，内置速率限制，防止消息刷屏。

安全与管控#

Access Control: 基于 Telegram User ID 的白名单机制，非授权用户无法交互。
Sandbox Isolation: 目录沙箱隔离，限制 Claude 仅能访问批准的目录，防止越权操作敏感文件。
Cost Control: 支持 CLAUDE_MAX_COST_PER_USER 配置，按用户设定消费上限（USD）。
Rate Limiting: 请求频率限制，防止滥用。
Audit Logging: 记录操作日志，便于审计与追溯。

Claude 集成#

Dual Backend: 支持 SDK (推荐) 与 CLI (回退) 两种模式与 Claude 交互。
Tool Management: 支持对 16 种内置工具进行 Allowlist/Disallowlist 配置，精细控制 Claude 能力（如禁用网络访问）。
Cost Tracking: 实时跟踪 API 调用成本。

架构设计#

核心组件#

MessageOrchestrator (src/bot/orchestrator.py): 核心路由层，负责将 Telegram 消息分发至 Agentic 或 Classic 处理器。
Claude Integration (src/claude/): 使用 Facade 模式封装 SDK 与 CLI 两种后端实现，统一调用接口。
Storage Layer (src/storage/): 基于 SQLite 的数据持久层，采用 Repository 模式，管理会话状态、调度任务等数据。
Security (src/security/): 处理用户认证、权限校验及令牌管理。
Event Bus (src/events/): 异步 Pub/Sub 系统，解耦 Webhook/Scheduler 触发与 Claude 执行逻辑。
API Server (src/api/): 基于 FastAPI 的 Webhook 接收服务。

数据流#

直接交互流:

User Message → Telegram API → Middleware (Auth/RateLimit) 
    → MessageOrchestrator → ClaudeIntegration → Claude API/CLI 
    → Response → Telegram

事件驱动流:

External Event (GitHub/Cron) → Webhook/API Server → EventBus 
    → AgentHandler → ClaudeIntegration → AgentResponseEvent 
    → NotificationService → Telegram

快速开始#

环境要求#

Python 3.11 或更高版本
Claude Code CLI (已安装并配置)
Telegram Bot Token (通过 @BotFather 获取)

安装#

推荐方式 (从 Release 安装):

# 使用 uv
uv tool install git+https://github.com/RichardAtCT/claude-code-telegram@v1.3.0

# 使用 pip
pip install git+https://github.com/RichardAtCT/claude-code-telegram@v1.3.0

源码开发:

git clone https://github.com/RichardAtCT/claude-code-telegram.git
cd claude-code-telegram
make dev  # 依赖 Poetry 进行环境构建

配置#

复制 .env.example 为 .env，填写关键配置：

# 基础配置
TELEGRAM_BOT_TOKEN=your_bot_token
TELEGRAM_BOT_USERNAME=your_bot_username
APPROVED_DIRECTORY=/path/to/your/projects
ALLOWED_USERS=123456789,987654321

# Claude 配置 (推荐 SDK 模式)
USE_SDK=true
ANTHROPIC_API_KEY=sk-ant-...
CLAUDE_MAX_COST_PER_USER=10.0
CLAUDE_TIMEOUT_SECONDS=300
CLAUDE_ALLOWED_TOOLS=Read,Write,Edit,Bash

# 模式配置
AGENTIC_MODE=true
VERBOSE_LEVEL=1

# 事件驱动平台 (可选)
ENABLE_API_SERVER=false
ENABLE_SCHEDULER=false

运行#

make run          # 生产模式运行
make run-debug    # 调试模式 (详细日志)

使用场景#

移动开发: 通过 Telegram 在任何设备上使用 Claude Code
团队共享: 多用户共享 Claude Code 访问
自动化任务: 通过 webhook/scheduler 触发 Claude 执行任务
远程项目管理: 管理多个项目，自动恢复会话

示例交互#

User: Can you help me add error handling to src/api.py?
Bot: I'll analyze src/api.py and add error handling...
     [Claude reads code, suggests improvements, applies changes]

User: Run the tests to make sure nothing broke.
Bot: Running pytest...
     All 47 tests passed. The error handling changes are working correctly.

版本信息#

当前版本: v1.3.0
主要语言: Python (99.6%)
许可证: MIT License

Claude Code Telegram Bot