# 一天一个开源项目（第38篇）：Claude Code Telegram - 用 Telegram 远程用 Claude Code，随时随地聊项目

> 一天一个开源项目（第38篇）：Claude Code Telegram - 用 Telegram 远程用 Claude Code，随时随地聊项目

- 原文链接: https://laojin.blog/repost/20260304_claude_code_telegram_bot
- 作者: 冬奇Lab（老金转载）
- 原始出处: https://juejin.cn/post/7612468027527725082
- 发布日期: 2026-03-04
- 标签: Claude Code, Telegram, 开源项目, 转载

---

> 本文为转载文章，原作者：**冬奇Lab**
>
> [原文链接](https://juejin.cn/post/7612468027527725082)

---

## 引言

> "A Telegram bot that gives you remote access to Claude Code. Chat naturally with Claude about your projects from anywhere — no terminal commands needed."

这是「一天一个开源项目」系列的第 38 篇文章。今天介绍的项目是 **Claude Code Telegram Bot**（[GitHub](https://github.com/RichardAtCT/claude-code-telegram "https://github.com/RichardAtCT/claude-code-telegram")）。

想在手机或平板上继续和 Claude 聊项目、改代码，又不想开电脑或 SSH？**Claude Code Telegram Bot** 把 **Claude Code** 接到 **Telegram**：在聊天里用自然语言让 Claude 读文件、改代码、跑测试，**会话按项目持久化**，支持 **Agentic 模式**（默认）和 **Classic 模式**（类终端 13 命令），还可接 **Webhook**（如 GitHub 事件）、**定时任务**和**主动通知**。内置白名单、目录沙箱、限流与审计日志，适合个人或小团队「随时随地用 Claude 写代码」。

**为什么值得看？**

- 📱 **随时随地**：手机、平板、任意有 Telegram 的设备都能和 Claude 聊项目
- 💬 **自然对话**：默认 Agentic 模式，无需记命令，像聊天一样让 Claude 读/改/跑
- 📂 **会话持久化**：按用户+项目目录自动保持会话，换设备也能接着聊
- 🔔 **事件驱动**：Webhook（GitHub 等）、Cron 定时任务、主动推送到指定群/私聊
- 🔒 **安全设计**：白名单、目录沙箱、限流、路径校验、审计日志
- ⚙️ **双模式**：Agentic（对话） / Classic（/cd、/ls、/git 等 13 命令）

### 你将学到什么

- Claude Code Telegram Bot 的定位与两种交互模式（Agentic / Classic）
- 安装与配置（uv/pip、.env 必填项、Telegram User ID）
- 基本对话流程与 /verbose、/repo、GitHub 工作流
- Webhook、Scheduler、Notification 的开启与配置思路
- 安全机制（白名单、沙箱、限流、审计）
- 与「仅本地 Claude Code」或「纯 SSH 远程」的对比

### 前置知识

- 已安装 **Claude Code CLI** 并完成认证
- 有 **Telegram** 账号，会从 @BotFather 获取 Bot Token
- 本地 **Python 3.11+**（运行 Bot 的服务端）

---

## 项目背景

### 项目简介

**Claude Code Telegram Bot** 是一个**通过 Telegram 远程访问 Claude Code 的 Bot**。在 Telegram 里和 Bot 对话，即可让运行在你服务器上的 Claude Code 对指定项目目录进行读文件、编辑、执行命令等操作，并保持**按项目维度的会话**，实现「在任何设备上用自然语言和 Claude 一起写代码」。

**解决的核心问题**：

- Claude Code 主要在本地终端使用，外出或移动设备难以接入
- 需要一种轻量、免 SSH、免复杂配置的远程访问方式
- 希望会话能按项目保留，多设备续聊
- 部分场景需要事件驱动（如 PR 推送时自动让 Claude 总结）

**面向的用户**：

- 希望用手机/平板偶尔改代码、看进度的开发者
- 个人或小团队想共享一台「带 Claude Code 的服务器」的远程入口
- 需要把 GitHub 等事件接到 Claude 做自动总结/审查的团队
- 喜欢 Telegram、不想额外装 App 的用户

### 作者/团队介绍

- **作者**：**RichardAtCT**（[GitHub](https://github.com/RichardAtCT/claude-code-telegram "https://github.com/RichardAtCT/claude-code-telegram")）
- **致谢**：Claude by Anthropic、python-telegram-bot

### 项目数据

- ⭐ **GitHub Stars**: 约 1.8k
- 🍴 **Forks**: 约 213
- 📦 **版本**: v1.4.0（README 示例中推荐 v1.3.0 等 tag，以 Releases 为准）
- 📄 **License**: MIT
- 📚 **文档**: README、docs/setup.md、docs/configuration.md、docs/tools.md、SYSTEMD\_SETUP.md 等

**技术栈**：Python 3.11+、[python-telegram-bot](https://github.com/python-telegram-bot/python-telegram-bot "https://github.com/python-telegram-bot/python-telegram-bot")、Claude Code SDK（主）/ CLI（备）、Poetry/uv。

---

## 主要功能

### 核心作用

Bot 的核心作用是：**在 Telegram 里提供对 Claude Code 的远程访问**，包括：

1. **自然语言对话**：用文字让 Claude 分析、编辑、解释代码，无需记终端命令
2. **会话持久化**：按用户 + 项目目录保存会话，跨设备、跨时间续聊
3. **双模式**：**Agentic**（默认，纯对话）与 **Classic**（/cd、/ls、/pwd、/git 等 13 条命令 + 内联键盘）
4. **事件驱动**：Webhook 接收外部事件（如 GitHub）、定时任务（Cron）、主动通知到指定聊天
5. **安全与管控**：白名单用户、目录沙箱、限流、用量/成本限制、审计日志

### 使用场景

1. **通勤/外出时轻量改代码**

   - 手机上看 Bot 消息，让 Claude 改个小逻辑、跑测试，结果直接回传到 Telegram
2. **多设备同一项目**

   - 家里电脑开会话，到公司用手机 /repo 切到同一项目继续聊，会话自动延续
3. **共享开发机**

   - 一台服务器跑 Claude Code + Bot，多人通过 Telegram 白名单接入各自目录，互不干扰
4. **CI/GitHub 联动**

   - PR、Push 等通过 Webhook 发给 Bot，由 Claude 自动做摘要、代码审查，结果推到指定群或频道
5. **定时巡检**

   - 用 Scheduler 配置每日/每周任务，让 Claude 做代码健康检查、依赖更新建议等，结果通过 Notification 推送

### 快速开始

**环境**：Python 3.11+、已安装并认证的 Claude Code CLI、从 @BotFather 获取的 Telegram Bot Token。

**安装（推荐按 tag 安装）**：

```
# 使用 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
```

**配置**：

```
cp .env.example .env
# 编辑 .env，至少配置：
# TELEGRAM_BOT_TOKEN=...        # 来自 @BotFather
# TELEGRAM_BOT_USERNAME=...     # Bot 用户名
# APPROVED_DIRECTORY=...        # 允许访问的项目根目录，如 /Users/you/projects
# ALLOWED_USERS=123456789       # 你的 Telegram User ID（逗号分隔多用户）
```

**获取 Telegram User ID**：在 Telegram 里给 [@userinfobot](https://t.me/userinfobot "https://t.me/userinfobot") 发一条消息，即可得到自己的 user ID。

**运行**：

```
make run        # 生产运行
make run-debug  # 带调试日志
```

在 Telegram 里给 Bot 发消息即可开始使用。详细步骤与 Claude 认证方式见 [docs/setup.md](https://github.com/RichardAtCT/claude-code-telegram/blob/main/docs/setup.md "https://github.com/RichardAtCT/claude-code-telegram/blob/main/docs/setup.md")。

### 核心特性

1. **Agentic 模式（默认）**

   - 纯自然语言交互；Bot 内部调用 Claude Code SDK（主）或 CLI（备），展示工具调用与推理过程
   - 命令：`/start`、`/new`、`/status`、`/verbose`、`/repo`；可选 `ENABLE_PROJECT_THREADS` 时的 `/sync_threads`
2. **Classic 模式**

   - 设置 `AGENTIC_MODE=false` 启用；13 条命令：`/start`、`/help`、`/new`、`/continue`、`/end`、`/status`、`/cd`、`/ls`、`/pwd`、`/projects`、`/export`、`/actions`、`/git`，配合内联键盘、目录导航、快捷操作
3. **会话持久化**

   - 按用户 + 项目目录（工作目录）维度的会话持久化，换设备或稍后回来可继续同一会话
4. **/verbose 级别**

   - `0`：仅最终回复（安静）
   - `1`（默认）：工具名 + 简短推理
   - `2`：工具名 + 输入 + 更长推理
5. **/repo 与 GitHub 工作流**

   - `/repo` 列出工作区内的仓库，`/repo <name>` 切换目录并延续会话；服务器上配置 `gh auth login` 后，可直接在对话中让 Claude 执行 `gh repo list`、`gh issue list`、克隆、建分支、推送等
6. **Webhook API 服务**

   - `ENABLE_API_SERVER=true` 启动 FastAPI 服务；支持 GitHub（HMAC-SHA256）与通用 Bearer 认证，将事件转发给 Claude 处理并可选推送结果到 Telegram
7. **Scheduler 与 Notification**

   - Cron 表达式配置定时任务；Notification 将 Agent 输出推送到指定 `NOTIFICATION_CHAT_IDS`，支持按聊天限流
8. **安全与管控**

   - 白名单（ALLOWED\_USERS）、目录沙箱（APPROVED\_DIRECTORY、路径穿越防护）、限流（RATE\_LIMIT\_\*）、单用户成本上限（CLAUDE\_MAX\_COST\_PER\_USER）、审计日志与安全事件记录
9. **16 种可配置工具**

   - 通过 `CLAUDE_ALLOWED_TOOLS` 等做 allowlist/disallowlist，详见 [docs/tools.md](https://github.com/RichardAtCT/claude-code-telegram/blob/main/docs/tools.md "https://github.com/RichardAtCT/claude-code-telegram/blob/main/docs/tools.md")
10. **Project Threads 模式**

    - `ENABLE_PROJECT_THREADS=true` 时按项目/话题严格路由；支持 private 或 group 模式，需在 BotFather 开启 Threaded mode；`/sync_threads` 同步话题列表

### 项目优势

| 对比项 | Claude Code Telegram | 仅本地 Claude Code | 纯 SSH + 终端 |
| --- | --- | --- | --- |
| 移动端 | ✅ 任意有 Telegram 的设备 | ❌ 需本机/远程桌面 | ⚠️ 需 SSH 客户端 |
| 交互方式 | 自然语言 + 可选命令 | 终端命令 | 纯终端 |
| 会话持久化 | ✅ 按项目自动 | 视本地会话 | 需自行管理 |
| 事件驱动 | ✅ Webhook + Cron + 通知 | 无 | 需自建 |
| 安全与审计 | 白名单/沙箱/限流/审计 | 本机权限 | 需自行加固 |
| 上手成本 | 装 Bot + 配 .env | 装 CLI | 配 SSH + 终端 |

**为什么选 Claude Code Telegram？**

- 不换工作流：仍是 Claude Code 能力，只是入口从终端变成 Telegram，适合「偶尔远程」或「多设备同一项目」
- 会话不丢：按项目持久化，换设备也能接着聊
- 可扩展：Webhook + Scheduler + Notification 能接 CI、日报、提醒等
- 安全可控：白名单、沙箱、成本上限、审计，适合个人或小团队自建

---

## 项目详细剖析

### 架构与数据流

- **用户** ↔ **Telegram** ↔ **Bot（Python）** ↔ **Claude Code（SDK 或 CLI）** ↔ **本地文件系统 / Git / gh**
- Bot 接收 Telegram 消息，解析命令或自然语言，调用 Claude Code 执行；Claude 的工具调用（Read、Edit、Bash 等）在服务器上执行，结果经 Bot 整理后发回 Telegram
- 会话状态、项目目录、历史等可持久化（如 SQLite），支持迁移与审计

### 项目结构（概要）

- **`src/`**：Bot 主逻辑、Claude 集成、命令处理、Webhook/Scheduler/Notification
- **`config/`**：配置示例（如 `projects.example.yaml` 用于 Project Threads）
- **`docs/`**：setup、configuration、tools 等
- **`tests/`**：单元与集成测试
- **`.env.example`**、**`Makefile`**：环境变量模板与常用命令（run、test、lint、bump 等）

### 配置要点

- **必填**：`TELEGRAM_BOT_TOKEN`、`TELEGRAM_BOT_USERNAME`、`APPROVED_DIRECTORY`、`ALLOWED_USERS`
- **Claude**：`ANTHROPIC_API_KEY`（可选，若已用 CLI 认证）；`CLAUDE_MAX_COST_PER_USER`、`CLAUDE_TIMEOUT_SECONDS`
- **模式**：`AGENTIC_MODE`、`VERBOSE_LEVEL`
- **限流**：`RATE_LIMIT_REQUESTS`、`RATE_LIMIT_WINDOW`
- **事件**：`ENABLE_API_SERVER`、`API_SERVER_PORT`、`GITHUB_WEBHOOK_SECRET`、`WEBHOOK_API_SECRET`、`ENABLE_SCHEDULER`、`NOTIFICATION_CHAT_IDS`
- **Project Threads**：`ENABLE_PROJECT_THREADS`、`PROJECT_THREADS_MODE`、`PROJECTS_CONFIG_PATH`、`PROJECT_THREADS_CHAT_ID` 等

完整选项见 [docs/configuration.md](https://github.com/RichardAtCT/claude-code-telegram/blob/main/docs/configuration.md "https://github.com/RichardAtCT/claude-code-telegram/blob/main/docs/configuration.md") 与 `.env.example`。

### 排错提示（README）

- **Bot 无响应**：检查 Token、ALLOWED\_USERS、Claude Code 是否已安装并可访问、`make run-debug` 看日志
- **Claude 不工作**：SDK 模式检查 `claude auth status` 或 ANTHROPIC\_API\_KEY；CLI 模式检查 `claude --version` 与 `CLAUDE_ALLOWED_TOOLS`
- **费用偏高**：设 `CLAUDE_MAX_COST_PER_USER`、用 `/status` 看用量、尽量缩短单次请求

---

## 项目地址与资源

### 官方资源

- 🌟 **GitHub**: [github.com/RichardAtCT…](https://github.com/RichardAtCT/claude-code-telegram "https://github.com/RichardAtCT/claude-code-telegram")
- 📚 **文档**: README、[docs/setup.md](https://github.com/RichardAtCT/claude-code-telegram/blob/main/docs/setup.md "https://github.com/RichardAtCT/claude-code-telegram/blob/main/docs/setup.md")、[docs/configuration.md](https://github.com/RichardAtCT/claude-code-telegram/blob/main/docs/configuration.md "https://github.com/RichardAtCT/claude-code-telegram/blob/main/docs/configuration.md")、[docs/tools.md](https://github.com/RichardAtCT/claude-code-telegram/blob/main/docs/tools.md "https://github.com/RichardAtCT/claude-code-telegram/blob/main/docs/tools.md")、[SYSTEMD\_SETUP.md](https://github.com/RichardAtCT/claude-code-telegram/blob/main/SYSTEMD_SETUP.md "https://github.com/RichardAtCT/claude-code-telegram/blob/main/SYSTEMD_SETUP.md")
- 🐛 **Issues**: [GitHub Issues](https://github.com/RichardAtCT/claude-code-telegram/issues "https://github.com/RichardAtCT/claude-code-telegram/issues")
- 📦 **Releases**: 建议安装 tag 版本（如 v1.3.0），见 [Releases](https://github.com/RichardAtCT/claude-code-telegram/releases "https://github.com/RichardAtCT/claude-code-telegram/releases")

### 相关资源

- **Claude Code**：安装与认证见官方文档
- **Telegram Bot API**：@BotFather 创建 Bot、获取 Token
- **python-telegram-bot**：Bot 框架文档

### 适用人群

- 希望用**手机/平板**偶尔参与编码、看 Claude 输出的开发者
- 需要**多设备、同一项目会话**的个人或小团队
- 想用 **Webhook / 定时任务** 把 GitHub 或 CI 与 Claude 打通的团队
- 喜欢 **Telegram**、希望减少额外 App 的远程开发用户

---

*欢迎来我中的[个人主页](https://home.wonlab.top "https://home.wonlab.top")找到更多有用的知识和有趣的产品*