项目档案应用项目

Claude Telegram Bot Bridge：通过 Telegram 远程使用 Claude Code 的轻量级机器人安装使用指南

Claude Telegram Bot Bridge 是一个轻量级 Telegram 机器人，将 Claude Code 桥接到移动端。本文介绍如何安装配置，让你能通过手机随时随地与 Claude 对话、执行技能、编辑代码，无需 Web 服务器。支持流式响应、语音转录、文件自动发送等特性。

132PythonStar 于 2026年3月4日2026年9月4日更新

查看 GitHub 仓库

AI 总结

Claude Telegram Bot Bridge 是一个轻量级 Telegram 机器人，将 Claude Code 能力桥接到移动端，让你通过手机随时随地与 Claude 对话、执行技能，无需 Web 服务器或暴露端口。

中文项目介绍

Claude Telegram Bot Bridge 是一个将 Claude Code 功能集成到 Telegram 的轻量级机器人项目。它允许用户通过手机消息与 Claude 进行实时对话、远程执行代码技能、编辑文件，完全摆脱了 Claude Code 必须运行在本地终端的限制。该项目解决了传统远程访问 Claude 的痛点：无需部署复杂的 Web 服务栈，不暴露本地端口，利用 Telegram 本身提供的加密和推送机制实现安全通信。相比 OpenClaw 等方案，它更加轻量、零基础设施，且默认安全。核心功能包括流式响应显示、语音消息自动转录、文件自动发送、会话历史管理、多模型切换等。机器人以守护进程方式运行，支持崩溃自动重启、开机自启和自动更新，提供完善的运维能力。适用于远程开发、移动办公、会议通勤等场景，让开发者能随时随地利用 Claude Code 的强大能力，同时保持本地开发环境的安全性。

详细信息与使用说明

1. 项目定位与用途

Claude Telegram Bot Bridge 是一个轻量级应用程序，定位为 Claude Code 的移动端远程访问网关。它通过 Telegram Bot API 将 Claude Code SDK 的能力桥接到手机端，使用户能在任何地点通过 Telegram 消息与 Claude 交互。主要用途包括远程对话、技能执行、代码编辑和文件搜索，所有操作均通过熟悉的聊天界面完成，无需额外客户端或 Web 界面。项目设计哲学是零基础设施、安全默认、即开即用，适合需要灵活访问 Claude 能力的开发者。

2. 解决的问题

项目核心解决 Claude Code 被绑定在本地终端的问题。当用户离开电脑时，无法快速查看构建结果、请求 Claude 修复 Bug 或运行技能命令。现有方案如 OpenClaw 需要部署 Web 服务栈，存在安全顾虑且过于重量级。本桥接方案通过 Telegram 消息机制实现远程访问，无需开放端口、无需额外认证层，利用 Telegram 的加密和推送保证安全。同时提供渐进式流式响应、语音转录、文件自动发送等增强体验，并具备守护进程、自动更新等运维特性，在便捷性、安全性和运维成本间取得平衡。

3. 适用场景

主要适用于需要远程访问 Claude Code 的开发场景：通勤或会议中快速查询代码逻辑、在 couch 上运行构建或测试命令、外出时紧急修复 Bug、查看 CI/CD 构建结果。也适合需要持久化 Claude 会话但不想部署 Web 服务的团队，或对安全性要求较高、不愿暴露开发环境的情况。由于依赖 Claude CLI 和 Python 环境，更适合 macOS 和 WSL 用户；Windows 原生环境不支持。项目对网络要求不高，Telegram 的推送机制确保低延迟通知。

4. 安装方式

安装需满足前置条件：Python 3.11+、Claude CLI（在 PATH 中或通过 CLAUDE_CLI_PATH 指定）、Telegram Bot Token（从 @BotFather 获取）、ffmpeg 用于音频转换、OpenAI API Key 用于 Whisper 转录。安装步骤：克隆仓库后进入目录，直接运行 `claude` 命令（需 Claude CLI 可用），然后在 Telegram 中向机器人发送 `/setup`，Claude Code 将自动完成系统检查、令牌收集、依赖安装和配置。也可手动复制 `.env.example` 为 `.env` 并填写必要变量，然后运行 `start.sh` 或 `setup.sh`。macOS 用户可使用 `--install` 参数安装 launchd 开机自启。

5. 使用方式

启动后机器人以守护进程运行，在 Telegram 中即可直接与 Claude 对话，响应以流式方式实时更新。主要命令包括：`/skill <name>` 或 `/command <cmd>` 远程调用 Claude Code 技能；`/model` 切换 Sonnet/Opus/Haiku 模型；`/history` 查看最近 5 条消息；`/revert` 回退到历史状态（支持完整恢复、仅对话、仅代码等模式）；`/resume` 恢复历史会话。语音消息自动下载、转码、转录后交由 Claude 处理。文件路径响应自动作为照片或文档发送。每用户最多支持 3 条并发消息，`/stop` 可立即取消运行中的任务。

6. 补充说明与实现特点

项目基于 Python 开发，核心依赖包括 python-telegram-bot、claude-code-sdk、openai 和 pydantic。安全机制包含用户白名单（ALLOWED_USER_IDS）、项目内文件自动访问、外部访问需 Telegram 内联确认、超过 20 分钟的消息自动丢弃。运维方面支持崩溃自动重启（60 秒内 5 次则停止）、MD5 依赖缓存、14 天日志轮换、独立 HTTP 客户端处理网络切换。平台支持 macOS 完整功能，WSL 支持前台运行和基础管理命令，原生 Windows 不支持。代码结构清晰，包含核心模块、交互层、会话管理、工具函数和测试套件。

思维导图

当前仓库信息不足，或结构不够稳定，暂时没有生成可靠的思维导图。

常见问题

如何获取 Telegram Bot Token？

需要在 Telegram 中联系 @BotFather，发送 /newbot 命令并按提示操作，即可创建机器人并获取 Token。然后将 Token 填入项目 .env 文件的 TELEGRAM_BOT_TOKEN 字段。

项目支持哪些操作系统？

完全支持 macOS，包括 launchd 开机自启安装和卸载。WSL（Ubuntu/Debian 风格 Linux 用户态）支持前台运行、守护进程、状态查看和停止命令。原生 Windows（PowerShell/CMD）不支持。

是否需要开放网络端口或部署 Web 服务？

完全不需要。机器人通过 Telegram 的轮询机制接收消息，所有通信均通过 Telegram 的加密通道进行，无需开放任何本地端口，也无需部署 Web 服务器或额外基础设施。

语音消息如何处理？支持哪些格式？

机器人自动下载语音消息，识别格式（支持 OGG、AMR 等），通过 ffmpeg 转换为 MP3，使用 Whisper 或火山引擎进行转录，然后将文本发送给 Claude。转录提供商可通过 TRANSCRIPTION_PROVIDER 环境变量配置。

如何保证安全性？是否有用户权限控制？

安全性通过多层机制保证：用户白名单（ALLOWED_USER_IDS）限制可访问用户；项目目录内文件访问自动允许，外部访问需 Telegram 内联按钮确认；消息超过 20 分钟自动丢弃；所有通信依赖 Telegram 的端到端加密。建议设置白名单并妥善保管 Bot Token。