Telegram Skill Bot：把 Claude Code 装进手机

起因：一个周末的小烦恼

上周末突然要出门，结果出门后突然想起有个 bug 没修。打开手机想用 Claude Code 看一眼，结果发现——它只能在终端里跑。

回家开电脑？太麻烦了。用 OpenClaw ？我试过，配置 Web 服务器、Nginx 反向代理、HTTPS 证书……折腾了一下午，最后发现我只是想改几行代码而已。

这时候我想：能不能直接在 Telegram 里跟 Claude 聊天？

Telegram 有现成的 Bot API ，不需要自己搭服务器，消息推送也是长连接，安全性由 Telegram 保证。听起来很适合做这件事。

于是周末两天，撸了个 Telegram Bot 版本的 Claude Code 遥控器。

痛点：为什么不用 OpenClaw ？

OpenClaw 是个很棒的项目，但它解决的是"把 Claude 搬到云端"的问题，适合团队协作或者需要完整 Web IDE 的场景。

我的需求更简单：

• 只想在手机上偶尔操作一下，不需要完整的浏览器界面
• 不想折腾服务器配置，端口暴露、防火墙、SSL 证书这些东西太重了
• 已经在用 Claude Code CLI，只是想加个远程入口

所以我需要的是一个"轻量级的后门"，而不是一个完整的 Web 应用。

项目特点

1. 零基础设施

不需要 Web 服务器、不需要端口暴露、不需要配置 HTTPS 。Telegram 自带长连接，消息推送由 Telegram 服务器处理。启动一次就作为守护进程在后台运行，崩溃自动重启，macOS 上还能配置开机自启。

2. 默认安全

• 文件访问沙箱化（--path 参数设置项目根目录）
• 项目内文件自动允许访问，项目外需要 Telegram 内联按钮确认
• 支持用户白名单（ALLOWED_USER_IDS）
• 超过 20 分钟的旧消息自动丢弃

3. 实时流式响应

Claude 的回复不是等全部生成完才显示，而是边思考边更新。使用 Telegram 草稿消息 API ，每 150 字符或 1 秒更新一次。你能看到 Claude 实时打字的过程，就像在终端里用 Claude Code 一样。长消息（超过 4000 字符）自动分段发送，体验很流畅。

4. 语音消息支持

直接发送 Telegram 语音消息，Bot 会自动：

• 下载并检测音频格式（ OGG/AMR/MP3 等）
• 使用 ffmpeg 转换为标准格式
• 通过 OpenAI Whisper API 转录为文字
• 显示转录预览：🎤 Voice: [转录文本]
• 将文字转发给 Claude 处理

在路上也能用语音跟 Claude 对话，不用打字。

5. 智能交互

• Claude 的选项题自动转成 Telegram 内联键盘按钮，点一下就能选
• 回复里的图片、PDF 等文件路径会自动发送为 Telegram 附件
• 每个用户独立的 SDK 连接，支持并发消息（最多 3 条）
• /stop 命令优先级处理：即使消息队列满了也能立即中断 Claude 回复或语音转录

6. 功能完整

• 支持所有 Claude Code 技能（/skill <name>）和斜杠命令（/commit、/xhs-writer 等）
• 支持模型切换（/model 在 Sonnet/Opus/Haiku 之间切换）
• 支持会话恢复（/resume 查看和恢复历史对话）
• 支持历史查看（/history 显示当前会话最近 5 条消息）
• 支持流式中断（/stop 立即停止 Claude 的回复或语音转录）

上手指南

用 Claude Code 自动安装（推荐）

git clone https://github.com/terranc/claude-telegram-bot-bridge
cd claude-telegram-bot-bridge
claude

然后在 Claude Code 提示符里输入 /setup，它会自动帮你：

• 检查系统环境（ Python 3.11+、Claude CLI 、ffmpeg ）
• 收集 Bot Token 和用户白名单
• 询问是否启用语音消息功能（需要 OpenAI API Key ）
• 创建虚拟环境并安装依赖
• 生成 .env 配置文件

/setup 技能支持多语言交互，你可以用中文、英文、日文等任何语言完成安装。

完成后启动：

./start.sh --path /path/to/your/project

手动安装

如果不想用 Claude Code ，也可以直接运行安装脚本：

git clone https://github.com/terranc/claude-telegram-bot-bridge
cd claude-telegram-bot-bridge
./setup.sh

获取 Telegram Bot Token

去 @BotFather 创建一个 Bot ，拿到 Token 。

获取你的 Telegram 用户 ID

给 @userinfobot 发消息，它会告诉你你的用户 ID 。

语音消息配置（可选）

如果想使用语音消息功能，需要：

1. OpenAI API Key （用于 Whisper 转录）
2. ffmpeg （用于音频格式转换）

在 .env 文件中配置：

OPENAI_API_KEY=your_openai_api_key
WHISPER_MODEL=whisper-1  # 可选，默认 whisper-1
MAX_VOICE_DURATION=300   # 可选，最大时长（秒），默认 300

语音转录费用约为 $0.006/分钟（以 OpenAI 官方定价为准）。

常用命令

# 前台运行（默认）
./start.sh --path /path/to/project

# 后台守护进程
./start.sh --path /path/to/project -d

# 调试模式（详细日志 + 聊天记录）
./start.sh --path /path/to/project --debug

# 检查运行状态
./start.sh --path /path/to/project --status

# 停止
./start.sh --path /path/to/project --stop

# macOS 开机自启
./start.sh --path /path/to/project --install

# 取消开机自启
./start.sh --path /path/to/project --uninstall

Telegram 内的命令

• /new - 开始新对话
• /model - 切换模型（ Sonnet/Opus/Haiku ）
• /resume - 查看和恢复历史会话
• /history - 显示当前会话最近 5 条消息
• /stop - 停止当前 Claude 回复或语音转录（优先级命令，绕过队列限制）
• /skill <name> - 运行 Claude Code 技能
• /skills - 列出所有可用技能
• 其他斜杠命令（如 /commit、/xhs-writer）直接发送即可

技术细节

架构

• core/bot.py - Telegram Bot 主逻辑，命令处理、权限控制
• core/project_chat.py - Claude SDK 集成，消息队列、工具权限回调
• core/streaming.py - 流式响应处理，实时更新草稿消息
• utils/audio_processor.py - 音频格式检测、ffmpeg 转换、临时文件清理
• utils/transcription.py - Whisper API 调用、重试/退避、空文本验证
• session/ - 会话管理，状态持久化到 JSON
• utils/ - 配置、日志、聊天记录

关键数据流

文本消息流程： 用户消息 → TelegramBot 处理器 → 权限检查 → ProjectChatHandler.process_message() → Claude SDK 流式响应 → 实时更新草稿消息 → 返回 Telegram

语音消息流程： 用户语音 → 下载音频文件 → 格式检测 → ffmpeg 转换（如需要）→ Whisper 转录 → 显示 🎤 Voice: 预览 → 转发给 Claude → 同文本消息流程

权限控制： 工具请求 → _permission_callback() → 项目内自动允许 / 项目外弹出内联按钮 → 用户选择（ Allow / Deny / Allow All ）→ asyncio.Future 模式等待响应（ 60 秒超时）

流式响应： Claude SDK 流 → 每 150 字符或 1 秒触发更新 → Telegram 草稿消息 API → 超过 4000 字符自动分段 → 最终消息发送

优先级命令： /stop 或 /revert → 绕过消息队列限制 → 立即取消活动任务（asyncio.Task.cancel()）→ 清理草稿消息 / 停止 SDK 流 / 删除临时音频文件

数据存储

• 运行时数据：PROJECT_ROOT/.telegram_bot/
  • sessions.json - 用户会话状态
  • logs/bot.log - 主日志（每日轮转）
  • logs/error_YYYYMMDD.log - 错误日志
  • logs/{user_id}_{session_id}_{date}.log - 调试聊天记录
• SDK 对话历史：~/.claude/projects/{PROJECT_DIR_NAME}/*.jsonl

守护进程特性

• 崩溃自动重启，记录退出码和运行时长
• 60 秒内崩溃 5 次后停止重启（防止无限循环）
• 基于 MD5 的依赖缓存，requirements.txt 未变时跳过重装
• 14 天日志轮转

项目地址

GitHub: https://github.com/terranc/claude-telegram-bot-bridge

欢迎提 Issue 或 PR 。如果你也觉得 OpenClaw 太重，可以试试这个方案。

后记

这个项目从想法到能用，大概花了一个周末。后来陆续加了语音消息、流式响应优化、优先级命令等功能，现在已经是我日常开发的必备工具。

有时候工具不需要很完美，够用就行。OpenClaw 是一辆卡车，我这个是一辆自行车——看你要运货还是通勤。

现在我在地铁上也能用手机跟 Claude 对话，让它帮我改代码、跑测试、查日志。实时流式响应让整个体验很流畅，就像在终端里用 Claude Code 一样。语音消息功能让我在路上也能用语音跟 Claude 交流，不用打字。

下一步可能会加个会话回滚功能（/revert），可以回到对话历史的任意节点，恢复代码状态或重新开始。不过这是后话了。

先这样，继续撸代码去了 🚀