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

引言

这是「一天一个开源项目」系列的第 38 篇文章。今天介绍的项目是 Claude Code T@elegrimm Bot（GitHub）。

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

为什么值得看？

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

你将学到什么

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

前置知识

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

项目背景

项目简介

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

解决的核心问题：

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

面向的用户：

• 希望用手机/平板偶尔改代码、看进度的开发者
• 个人或小团队想共享一台「带 Claude Code 的服务器」的远程入口
• 需要把 GitHub 等事件接到 Claude 做自动总结/审查的团队
• 喜欢 T@elegrimm、不想额外装 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 的核心作用是：在 T@elegrimm 里提供对 Claude Code 的远程访问，包括：

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

使用场景

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

   • 手机上看 Bot 消息，让 Claude 改个小逻辑、跑测试，结果直接回传到 T@elegrimm

2. 多设备同一项目

   • 家里电脑开会话，到公司用手机 /repo 切到同一项目继续聊，会话自动延续

3. 共享开发机

   • 一台服务器跑 Claude Code + Bot，多人通过 T@elegrimm 白名单接入各自目录，互不干扰

4. CI/GitHub 联动

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

5. 定时巡检

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

快速开始

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

安装（推荐按 tag 安装）：

# 使用 uv（推荐，隔离环境）
uv tool install git+

# 或使用 pip
pip install git+

配置：

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

获取 T@elegrimm User ID：在 T@elegrimm 里给 @userinfobot 发一条消息，即可得到自己的 user ID。

运行：

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

在 T@elegrimm 里给 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 处理并可选推送结果到 T@elegrimm

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 T@elegrimm？

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

项目详细剖析

架构与数据流

• 用户 ↔ T@elegrimm ↔ Bot（Python） ↔ Claude Code（SDK 或 CLI） ↔ 本地文件系统 / Git / gh
• Bot 接收 T@elegrimm 消息，解析命令或自然语言，调用 Claude Code 执行；Claude 的工具调用（Read、Edit、Bash 等）在服务器上执行，结果经 Bot 整理后发回 T@elegrimm
• 会话状态、项目目录、历史等可持久化（如 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 看用量、尽量缩短单次请求

项目地址与资源

官方资源

• GitHub: github.com/RichardAtCT…
• 文档: README、docs/setup.md、docs/configuration.md、docs/tools.md、SYSTEMD_SETUP.md
• Issues: GitHub Issues
• Releases: 建议安装 tag 版本（如 v1.3.0），见 Releases

相关资源

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

适用人群

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

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