# Claude Code Telegram Bot — 手机远程编码

> 最完善的 Telegram 桥接 Claude Code 方案，支持 session 管理、实时流式、语音输入、文件上传

# Claude Code Telegram Bot — 手机远程编码的最佳方案

**a5c-ai/claude-code-telegram-bot** 是目前最完善的 Telegram ↔ Claude Code 桥接方案，让你从手机上获得完整的 agentic 编码体验。

## 核心能力

- **远程控制** — 任何 Telegram 设备操作 Claude Code，无需坐在电脑前
- **Session 管理** — 创建/切换/attach 多 session，支持 Forum Topic 多项目隔离
- **实时流式** — Telegram Bot API 9.3 draft bubbles，逐字符显示 Claude 的思考过程
- **交互式 Q&A** — Claude 的问题变成 inline 按钮，一键确认
- **语音输入** — 语音消息自动转文字（OpenAI Whisper）
- **文件上传** — 文档/图片/代码文件直接传给 Claude 分析
- **Session 发现** — 扫描本地 `~/.claude/history.jsonl`，attach 已有 session

## 架构亮点

不同于每请求 spawn 新进程的简单方案，此项目采用**单 session 单持久进程**架构：
- Claude CLI 长期存活，双向 stdin/stdout 流式 JSON
- 无进程启动开销，session 上下文自然延续
- 原生支持 Claude 的提问-回答流程

## 技术栈

Node.js 18+ | TypeScript 5.3 | Telegraf 4.16 | ULID session ID | SQLite 持久化

## 安装

```bash
npm install -g @a5c-ai/claude-code-telegram-bot
```

配置 `.env`：
```bash
TELEGRAM_BOT_TOKEN=xxx
ALLOWED_USER_IDS=你的Telegram用户ID
```

## 常用命令

| 命令 | 作用 |
|------|------|
| `/new [name] [dir]` | 创建 session |
| `/sessions` | 发现已有 session |
| `/attach abc12345` | attach 已有 session（前8位即可） |
| `/switch <id>` | 切换 session |
| `/abort` | 发送 Ctrl+C |
| `/file <path>` | 查看文件 |
| `/diff` | git diff |

## 流式模式

- `partial` — 逐字符实时 draft bubbles（默认）
- `block` — 分块更新
- `off` — 只发最终结果

## ⚠️ 安全注意

默认启用 `--dangerously-skip-permissions`，Claude 会自动读写文件、执行命令。建议在 Docker/VM 沙箱中运行，不要用于生产服务器或敏感数据系统。

## 对比其他方案

| 特性 | a5c-ai | ccremote | 官方 Plugin |
|------|--------|----------|-------------|
| 持久进程 | ✅ | ❌ | ❌ |
| Session 管理 | ✅ 完整 | ✅ 简单 | ❌ |
| 流式 draft | ✅ | ✅ | ✅ |
| Voice | ✅ | ❌ | ❌ |
| 文件上传 | ✅ | ❌ | ✅ |
| Forum Threading | ✅ | ❌ | ❌ |
| 多用户 | ✅ | ❌ | ❌ |

## 适合谁

- 想**纯手机操作** Claude Code 的开发者
- 需要**多项目切换**和**长时间任务**管理的团队
- 追求**生产级稳定性**和**完整功能**的用户

GitHub: https://github.com/a5c-ai/claude-code-telegram-bot

---

**分类**：软件
**标签**：Claude · Telegram · session
**作者**：Xiao.Xi
**链接**：https://octohz.com/p/1860