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

冬奇Lab2026-03-02 20:32

引言

"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）。

想在手机或平板上继续和 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）
  • 致谢：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、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 安装）：

bash 复制代码 
# 使用 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

配置：

bash 复制代码 
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 发一条消息，即可得到自己的 user ID。

运行：

bash 复制代码 
make run        # 生产运行
make run-debug  # 带调试日志

在 Telegram 里给 Bot 发消息即可开始使用。详细步骤与 Claude 认证方式见 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

  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 与 .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 看用量、尽量缩短单次请求

项目地址与资源

官方资源

相关资源

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

适用人群

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

欢迎来我中的个人主页找到更多有用的知识和有趣的产品

相关推荐
格砸3 小时前
从入门到辞职｜从ChatGPT到OpenClaw，跟上智能时代的进化
前端·人工智能·后端
可观测性用观测云3 小时前
可观测性 4.0：教系统如何思考
人工智能
sunny8653 小时前
Claude Code 跨会话上下文恢复：从 8 次纠正到 0 次的工程实践
人工智能·开源·github
小笼包包仔3 小时前
OpenClaw 多Agent软件开发最佳实践指南
人工智能
smallyoung4 小时前
AgenticRAG：智能体驱动的检索增强生成
人工智能
_skyming_4 小时前
OpenCode 如何做到结果不做自动质量评估，为什么结果还不错？
人工智能
南山安4 小时前
手写 Cursor 核心原理：从 Node.js 进程到智能 Agent
人工智能·agent·设计
掘金安东尼4 小时前
如何为 AI 编码代理配置 Next.js 项目
人工智能
aircrushin5 小时前
轻量化大模型架构演进
人工智能·架构
热门推荐
01GitHub 镜像站点02OpenClaw 使用和管理 MCP 完全指南03OpenClaw + 飞书（Feishu）环境搭建指南04【OpenClaw 本地实战 Ep.3】突破瓶颈：强制修改 openclaw.json 解锁 32k 上下文记忆05Claude Code + GLM4.7 避坑指南：解决 Unable to connect to Anthropic services06OpenClaw优化飞书API 额度已耗尽问题07Clawdbot部署教程：解决‘gateway token missing’授权问题的完整步骤08小黑课堂计算机二级WPSoffice题库软件下载安装教程（2026年3月最新版）09OpenClaw大龙虾机器人完整安装教程10Window 10部署openclaw报错node.exe : npm error code 128