内容
# cc-telegram-bot
[](https://github.com/fidpa/cc-telegram-bot/releases)
[](LICENSE)
[](https://www.typescriptlang.org/)
[](https://bun.sh/)
[](https://bun.sh/)
用于远程访问 Claude Code 的安全加固的 Telegram 机器人。
**问题**: 通过 Telegram 使用 `bypassPermissions` 远程运行 Claude Code 需要系统性的安全加固。没有权限提示，Claude 可以读取、写入和执行主机上的任何内容。在进行了两次安全审计（Claude Opus 4.6，OWASP 方法论）后，实施了 24 层加固措施作为纵深防御。本存储库透明地记录了整个过程 —— 包括仍然存在的限制。
## 功能
- **24 层安全措施，纵深防御** -- 从用户允许列表到 HMAC 签名审计日志（参见 [安全架构](#安全架构)）
- **多模态输入** -- 文本、语音消息、照片、文档（PDF 提取）、视频
- **流式响应，实时更新** -- Claude 生成消息时实时编辑
- **扩展思考（关键词触发）** -- 可配置的关键词激活 Claude 的思考模式
- **MCP 服务器集成** -- 通过模型上下文协议（MCP）可扩展（询问用户内联键盘，自定义工具）
- **会话管理** -- 持久化、恢复和切换会话（`/new`，`/stop`，`/resume`）
- **本地语音转录** -- whisper.cpp 使用本地 GGML 模型，无数据离开机器
- **审计日志与 HMAC 完整性** -- 防篡改 JSON 日志，自动旋转
- **输出编辑** -- 所有外发 Telegram 消息防止凭证泄漏
- **环境隔离** -- 在 Claude 启动前从 `process.env` 中剥离机密
- **警报套接字** -- 用于监测脚本的 Unix 域套接字
- **警报历史（SQLite）** -- 每个警报都持久化，用于趋势分析、MTTR 指标和数据驱动的报告
- **群聊支持** -- 允许列表中的群组，@提及或回复机器人激活
- **macOS LaunchAgent** -- 始终在线运行，自动重启
- **Linux systemd** -- 始终在线运行，自动重启和 EOD 计时器
- **模型切换** -- `/model` 命令在 Sonnet、Opus 和 Haiku 之间切换
## 已知限制
> **重要**: 机器人以 `bypassPermissions` 模式运行 Claude Code。这是出于移动 UX 的考虑，但意味着所有安全措施都是纵深防御的防护措施，而不是硬边界。
>
> - 命令阻止列表是尽力而为的（字符串匹配无法防止所有 shell 注入向量）
> - Bash 工具绕过路径验证（Claude 可以通过 shell `cat` 任意文件）
> - 速率限制器状态在重启时重置
>
> 有关完整的分析以及已接受的风险和推荐的缓解措施，请参见 [docs/security-limitations.md](docs/security-limitations.md)。
## 快速开始
### 先决条件
- [Bun](https://bun.sh/) 1.1+
- 来自 [@BotFather](https://t.me/BotFather) 的 Telegram 机器人令牌
- 已安装并认证的 Claude Code CLI（或 Anthropic API 密钥）
- 可选：`whisper-cpp` 用于语音转录（`brew install whisper-cpp`）+ GGML 模型
- 可选：`ffmpeg` 用于语音消息转换（`brew install ffmpeg`）
- 可选：`poppler` 用于 PDF 提取（`brew install poppler`）
### 设置
```bash
# 1. 克隆存储库
git clone https://github.com/fidpa/cc-telegram-bot.git
cd cc-telegram-bot
# 2. 安装依赖
bun install
# 3. 配置环境
cp .env.example .env
# 编辑 .env 文件，填写您的 Telegram 机器人令牌和用户 ID
# 4. （可选）自定义系统提示
# 编辑 CLAUDE.md 以匹配您的用例
# 5. 运行机器人
bun run start
# 6. 测试：向 Telegram 上的机器人发送消息
```
## 机器人命令
| 命令 | 描述 |
|---------|-------------|
| `/start` | 欢迎消息 |
| `/new` | 开始新的对话（清除会话） |
| `/stop` | 停止当前 Claude 会话 |
| `/status` | 显示会话信息和速率限制状态 |
| `/resume` | 恢复之前的对话 |
| `/restart` | 重启机器人进程 |
| `/retry` | 重试最后一次失败的消息 |
| `/model`（`/m`） | 切换 Claude 模型（Sonnet、Opus、Haiku） |
| `/alert` | 向警报会话发送消息（每日上下文） |
## 配置
所有配置均通过环境变量（参见 [.env.example](.env.example)）：
| 变量 | 必需 | 描述 |
|----------|----------|-------------|
| `TELEGRAM_BOT_TOKEN` | 是 | 来自 @BotFather 的机器人令牌 |
| `TELEGRAM_ALLOWED_USERS` | 是 | 以逗号分隔的 Telegram 用户 ID |
| `CLAUDE_WORKING_DIR` | 推荐 | Claude 的工作目录（加载 CLAUDE.md） |
| `CLAUDE_MODEL` | 可选 | 默认 Claude 模型（默认：`claude-sonnet-4-5`） |
| `WHISPER_MODE` | 可选 | `local`（默认）或 `off` -- 语音转录模式 |
| `WHISPER_MODEL_PATH` | 可选 | GGML whisper 模型路径 |
| `WHISPER_LANGUAGE` | 可选 | Whisper 语言代码（默认：`de`） |
| `ALLOWED_PATHS` | 可选 | Claude 可以访问的目录（默认：工作目录，~/Documents，~/Downloads，~/Desktop，~/.claude） |
| `RATE_LIMIT_ENABLED` | 可选 | 启用速率限制（默认：`true`） |
| `RATE_LIMIT_REQUESTS` | 可选 | 每个窗口的请求数（默认：`20`） |
| `RATE_LIMIT_WINDOW` | 可选 | 窗口秒数（默认：`60`） |
| `AUDIT_LOG_PATH` | 可选 | 审计日志位置（默认：`~/.cc-telegram-bot/audit.log`） |
| `AUDIT_LOG_JSON` | 可选 | 日志的 JSON 格式（默认：`true`） |
| `AUDIT_LOG_HMAC_KEY` | 可选 | 日志完整性的 HMAC 密钥（如果未设置，则自动生成） |
| `TELEGRAM_ALLOWED_GROUPS` | 可选 | 群聊支持的以逗号分隔的 Telegram 群组 ID |
| `ALERT_SOCKET_PATH` | 可选 | 警报的 Unix 套接字路径（默认：`/run/cc-telegram-bot/alerts.sock`） |
| `ALERT_SOCKET_SECRET` | 可选 | 套接字身份验证的共享密钥（生产环境中推荐） |
| `ALERT_DB_PATH` | 可选 | SQLite 警报历史数据库（默认：`~/.cc-telegram-bot/alerts.db`） |
| `DAILY_LOG_DIR` | 可选 | 每天的机器人报告目录 |
| `ANTHROPIC_API_KEY` | 可选 | API 密钥（CLI 身份验证的替代方案） |
| `THINKING_KEYWORDS` | 可选 | 触发扩展思考的关键词 |
| `THINKING_DEEP_KEYWORDS` | 可选 | 触发深度思考的关键词（50k 令牌） |
MCP 服务器在 `mcp-config.ts` 中配置（参见 [mcp-config.example.ts](mcp-config.example.ts)）。
## 安全架构
机器人通过 24 层安全措施实现纵深防御：
| # | 层 | 文件 | 描述 |
|---|-------|------|-------------|
| 1 | 用户授权 | security.ts | 基于允许列表的 Telegram 用户 ID 检查 |
| 2 | 速率限制 | security.ts | 带有周期性清理的令牌桶算法 |
| 3 | 输入长度验证 | text.ts | MAX_MESSAGE_LENGTH = 4096 |
| 4 | 路径验证 | security.ts | 带有符号链接解析的 `isPathAllowed()` |
| 5 | 命令阻止列表（字符串） | config.ts | 30+ 个危险模式（fork 炸弹，磁盘破坏） |
| 6 | 命令阻止列表（正则表达式） | security.ts | 40+ 个正则表达式模式，用于鲁棒检测 |
| 7 | 文件操作路径检查 | session.ts | 读取/写入/编辑/全局/ grep 验证为 ALLOWED_PATHS |
| 8 | 安全系统提示 | config.ts | Claude 的 7 条反注入规则 |
| 9 | 内容分隔符 | handlers | `user_document`/`user_caption`/`alert_data` 安全标签 |
| 10 | 机密编辑（日志） | utils.ts | 审计日志中的精确匹配 + 基于模式的编辑 |
| 11 | 审计日志 | utils.ts | JSON 格式，追加，权限为 0o600 |
| 12 | 会话隔离 | session.ts | 每用户会话实例 |
| 13 | 文件权限加固 | config.ts | 数据目录 0o700，审计日志 0o600 |
| 14 | 输出编辑 | streaming.ts | 所有外发 Telegram 消息中的机密被编辑 |
| 15 | 环境转储阻止列表 | security.ts | `printenv`/`env`/`export -p`/`declare` 被阻止 |
| 16 | 环境隔离 | index.ts | 从 `process.env` 中删除 7 个敏感环境变量 |
| 17 | 日志净化 | utils.ts | `console.error`/`warn`：主页路径，堆栈跟踪，机密被编辑 |
| 18 | 审计日志完整性 | utils.ts，config.ts | 每个条目的 HMAC-SHA256 + 自动日志轮换 |
| 19 | 警报内容标签 | alert-socket.ts | `<alert_data>` 标签 + 伪造的前缀剥离 |
| 20 | 警报速率限制 | alert-socket.ts | 10 个警报/分钟滑动窗口 |
| 21 | 警报有效载荷验证 | alert-socket.ts | 带有字段级长度限制的 Zod 模式 |
| 22 | 警报队列 | alert-socket.ts | 有界队列（最大 20）FIFO 排空 |
| 23 | 每用户上下文文件 | session.ts | MCP 上下文按用户 ID 限定 |
| 24 | 脚本语言阻止列表 | security.ts | 通过 python/node/ruby/perl 阻止环境访问 + /proc |
### 凭证泄露防护
四层确保凭证不会到达用户，无论攻击向量如何：
```
攻击
|
+-----------------+-----------------+
| | |
"cat .env" "printenv" 提示注入
| "python -c" "show me the token"
| "/proc/environ" |
| | |
+----+----+ +----+----+ |
| 字符串 | | 正则 | |
| 阻止列表 | | 阻止列表 | |
| L5 X | | L6/24 X | |
+---------+ +---------+ |
|
+----------------+----------------+
| 环境隔离（L16） |
| |
| 7 个环境变量被删除： |
| TELEGRAM_BOT_TOKEN |
| TELEGRAM_ALLOWED_USERS |
| ALERT_SOCKET_SECRET |
| AUDIT_LOG_HMAC_KEY |
| OPENAI_API_KEY 等 X |
+----------------+----------------+
|
如果机密仍然出现在
Claude 的响应中
|
+----------------+----------------+
| 输出编辑（L14） |
| |
| 每个 Telegram 消息都被 |
| 检查已知机密和机密模式 |
| 然后发送。 |
| X |
+----------------+----------------+
|
用户看到：[REDACTED]
```
完整审计报告：[docs/SECURITY_AUDIT_REPORT.md](docs/SECURITY_AUDIT_REPORT.md)
集成示例（Bash/Python 中的警报客户端，cron 作业，systemd 健康检查）：[docs/EXAMPLES.md](docs/EXAMPLES.md)
## 用例
### 完美适用于
- ✅ **远程开发** -- 在 Mac Mini 或服务器上运行 Claude Code，通过手机控制
- ✅ **无头机器** -- 在没有显示器的服务器上访问 Claude（SSH 替代方案，UX 更丰富）
- ✅ **个人自动化** -- 自定义 CLAUDE.md 系统提示 + MCP 工具，用于您特定的工作流程
- ✅ **基础设施监控** -- 警报套接字接收系统警报，Claude 分析并响应
- ✅ **语音优先交互** -- 通过 Telegram 语音消息向 Claude 讲话（本地 whisper.cpp）
### 不推荐
- ❌ **多用户 SaaS** -- 设计用于单个用户或小型受信任组，不适用于公共部署
- ❌ **隔离环境** -- 需要互联网（Telegram API + Claude API）
- ❌ **没有备份的生产服务器** -- `bypassPermissions` 意味着 Claude 可以修改文件；请备份
- ❌ **Windows 主机** -- Bun 和 whisper.cpp 在 Windows 上的支持有限（使用 WSL2）
### 与替代方案比较
| 解决方案 | 安全 | 语音 | 警报套接字 | 流式传输 | 限制 |
|----------|----------|-------|-------------|-----------|------------|
| [linuz90/claude-telegram-bot](https://github.com/linuz90/claude-telegram-bot)（上游） | 基本身份验证 | ✅ | ❌ | ✅ | 无安全审计，无输出编辑 |
| 直接 Claude API | N/A | ❌ | ❌ | ✅ | 无 Telegram，无工具使用，无 MCP |
| 通过 SSH 的 Claude Code | OS 级 | ❌ | ❌ | ❌ | 需要终端，无移动 UX |
| 其他 Telegram AI 机器人 | 各不相同 | 各不相同 | ❌ | 各不相同 | 无 Claude Code 工具使用，无 MCP |
| **此项目** | 24 层 | ✅ | ✅ | ✅ | `bypassPermissions`（有文档） |
**独特价值**：两次记录的安全审计，24 层加固，透明的限制文档，用于基础设施集成的警报套接字，HMAC 审计日志完整性。
## 架构
```
cc-telegram-bot/
+-- src/
| +-- index.ts # 入口点，中间件链，处理程序注册
| +-- config.ts # 环境解析，MCP 加载，安全提示
| +-- session.ts # ClaudeSession 类（Agent SDK，流式传输，持久性）
| +-- security.ts # 速率限制器，路径验证，命令安全
| +-- alert-socket.ts # Unix 套接字监听器，警报提示，EOD 报告
| +-- alert-db.ts # SQLite 警报历史存储（bun:sqlite，WAL 模式）
| +-- formatting.ts # Markdown -> Telegram HTML 转换
| +-- utils.ts # 审计日志，语音转录，输入指示
| +-- types.ts # 共享 TypeScript 类型
| +-- handlers/
| +-- text.ts # 文本消息处理
| +-- voice.ts # 语音 -> 本地 whisper-cli 转录 -> Claude
| +-- photo.ts # 图像分析，媒体组缓冲
| +-- document.ts # PDF 提取，文本文件，存档
| +-- audio.ts # 音频文件转录
| +-- video.ts # 视频消息和视频笔记
| +-- callback.ts # 内联键盘（MCP 询问用户）
| +-- streaming.ts # 共享流状态和状态回调
| +-- commands.ts # 机器人命令处理程序（/start，/new，/model，/alert 等）
| +-- media-group.ts # 媒体组缓冲用于相册
| +-- index.ts # 处理程序导出
+-- ask_user_mcp/ # 用于交互式 Telegram 按钮的 MCP 服务器
+-- scripts/ # 实用脚本（test-alert，trigger-eod-report）
+-- launchagent/ # macOS LaunchAgent，用于始终在线运行
+-- docs/
| +-- security-limitations.md # 架构安全分析
| +-- SECURITY_AUDIT_REPORT.md # 完整的审计报告
| +-- LAUNCHAGENT.md # macOS LaunchAgent 设置指南
| +-- EXAMPLES.md # 使用示例（警报套接字，cron，Python 客户端）
+-- CLAUDE.md # 系统提示（由 Claude 加载）
+-- SECURITY.md # 安全模型文档
```
### 消息流程
```
Telegram -> grammy 处理程序 -> 身份验证检查 -> 速率限制
-> ClaudeSession（Agent SDK）-> 流式响应 -> 输出编辑 -> 审计日志 -> Telegram
警报套接字 -> JSON 验证（Zod）-> 机密检查 -> SQLite 插入 -> 速率限制 -> 警报队列
-> ClaudeSession（用户 ID 0）-> 流式响应 -> SQLite 更新 -> 输出编辑 -> Telegram 群组
```
### 技术栈
| 组件 | 技术 |
|-----------|-----------|
| 运行时 | [Bun](https://bun.sh/) |
| 语言 | TypeScript 5（严格模式） |
| AI 后端 | [Claude Agent SDK](https://docs.anthropic.com/en/docs/build-with-claude/agent-sdk) |
| 语音转录 | [whisper.cpp](https://github.com/ggerganov/whisper.cpp)（本地，GGML 模型） |
| Telegram 库 | [grammY](https://grammy.dev/) |
| 工具集成 | [模型上下文协议（MCP）](https://modelcontextprotocol.io/) |
| 验证 | [Zod](https://zod.dev/) |
### 设计决策
**为什么使用 `bypassPermissions`？** 机器人设计用于移动设备，在那里确认每个文件读取或 shell 命令是不切实际的。相反，安全性依赖于 24 层纵深防御（允许列表，速率限制，路径验证，命令安全，警报验证，输出编辑，审计日志等）。
**为什么使用基于字符串的命令阻止？** 完整的 shell AST 解析是不切实际的，OS 级别的沙箱（容器，bubblewrap）将是适当的解决方案。阻止列表是一种务实的防护措施，可以在记录其限制的同时捕获常见的破坏性模式。
**为什么选择 grammY？** grammY 是最活跃的 TypeScript Telegram 库。它提供类型安全的中间件，内置的并发消息处理运行程序，以及对内联键盘和文件下载的本地支持。
**为什么选择 Bun？** Bun 提供原生 TypeScript 执行，无需构建步骤，快速启动时间和内置 shell 实用程序（`Bun.$`）用于安全子进程执行。机器人作为一个长期运行的进程运行，Bun 的性能特性在此非常适用。
**为什么选择 Agent SDK V1？** Claude Agent SDK 提供对流式传输，工具拦截（用于路径验证和命令安全），会话管理和 MCP 服务器集成的首选支持。它处理多轮对话与工具使用的复杂性，否则需要大量样板代码。
## 需求
**最低要求**：
- [Bun](https://bun.sh/) 1.1+
- 安装并认证Claude Code CLI（或`ANTHROPIC_API_KEY`）
- 来自[@BotFather](https://t.me/BotFather)的Telegram机器人令牌
**可选**：
- `whisper-cpp` + GGML模型（语音转录）
- `ffmpeg`（语音消息转换）
- `poppler`（PDF文本提取）
## 兼容性
**完全支持**：
- macOS 13+ (Ventura) -- LaunchAgent用于始终在线运行
- Ubuntu 22.04 LTS, 24.04 LTS -- systemd服务
- Debian 12 (Bookworm)
- Raspberry Pi OS (64位, ARM64)
**应该能工作**（未经测试）：
- Fedora, Arch Linux（任何支持systemd的发行版，且支持Bun）
- WSL2（无需LaunchAgent；改为使用systemd服务）
**不支持**：
- Windows原生（使用WSL2）
- 32位ARM（Bun需要64位）
## 文档
| 文档 | 描述 |
|----------|-------------|
| [docs/SECURITY_AUDIT_REPORT.md](docs/SECURITY_AUDIT_REPORT.md) | 完整审计：22项发现，7个攻击向量，全部已解决 |
| [docs/security-limitations.md](docs/security-limitations.md) | 5个架构限制，风险已接受 |
| [docs/EXAMPLES.md](docs/EXAMPLES.md) | 警报套接字客户端（Bash、Python、cron、systemd） |
| [docs/LAUNCHAGENT.md](docs/LAUNCHAGENT.md) | macOS LaunchAgent设置，用于始终在线运行 |
| [SECURITY.md](SECURITY.md) | 安全模型和漏洞报告 |
| [.env.example](.env.example) | 所有环境变量及其文档 |
## 自定义指南
本机器人旨在为您的个人用例进行自定义。以下是关键的自定义点：
### 自定义系统提示
编辑您工作目录中的`CLAUDE.md`，定义Claude的角色和行为：
```markdown
# 示例：开发助手
您是一名高级软件工程师。专注于干净的代码、测试和安全。
在进行更改之前，请始终解释您的推理。
```
机器人会自动从`CLAUDE_WORKING_DIR`加载`CLAUDE.md`。
### 添加自定义命令
1. 在`src/handlers/commands.ts`中添加您的命令处理程序
2. 在`src/index.ts`中注册它：
```typescript
bot.command("mycommand", handleMyCommand);
```
### 添加MCP服务器
复制并自定义MCP配置：
```bash
cp mcp-config.example.ts mcp-config.ts
```
将您的MCP服务器添加到`MCP_SERVERS`对象中。支持stdio和HTTP传输。
### 更改允许的路径
在`.env`中设置`ALLOWED_PATHS`，控制Claude可以访问哪些目录：
```bash
ALLOWED_PATHS=/Users/yourname/projects,/Users/yourname/Documents,/Users/yourname/.claude
```
### 在Linux上部署（systemd）
代替macOS LaunchAgent，创建一个systemd服务：
```ini
# /etc/systemd/system/cc-telegram-bot.service
[Unit]
Description=Claude Code Telegram Bot
After=network.target
[Service]
Type=simple
User=youruser
WorkingDirectory=/home/youruser/cc-telegram-bot
ExecStart=/home/youruser/.bun/bin/bun run src/index.ts
Restart=always
RestartSec=5
EnvironmentFile=/home/youruser/cc-telegram-bot/.env
[Install]
WantedBy=multi-user.target
```
```bash
sudo systemctl enable cc-telegram-bot
sudo systemctl start cc-telegram-bot
sudo journalctl -u cc-telegram-bot -f # 查看日志
```
## 贡献
欢迎贡献！请参阅[CONTRIBUTING.md](CONTRIBUTING.md)获取指南。
**需要帮助的领域**：
- 基于容器的部署（Dockerfile用于隔离运行）
- 自动化测试套件（安全检查的单元测试，消息流的集成测试）
- 额外的MCP服务器示例（日历、笔记、家庭自动化）
- 多语言系统提示模板
- Webhook模式作为长轮询的替代方案
- 用于审计日志分析的Grafana仪表板
## 致谢与属性
本项目是基于[claude-telegram-bot](https://github.com/linuz90/claude-telegram-bot)由[Fabrizio Rinaldi](https://github.com/linuz90)创建的衍生作品，许可证为MIT。
原始项目提供了Telegram到Claude-Code的桥梁架构。本衍生作品添加了系统安全强化（两次文档审计的24层），凭证泄漏预防，HMAC审计日志完整性，环境隔离，输出编辑，警报套接字集成和始终在线运行。
额外依赖：
- [grammY](https://grammy.dev/) -- Telegram Bot API框架
- [whisper.cpp](https://github.com/ggerganov/whisper.cpp) -- 本地语音转录
## 许可证
MIT许可证 - 请参阅[LICENSE](LICENSE)
(c) 2025 [Fabrizio Rinaldi](https://github.com/linuz90) （原始：claude-telegram-bot）
(c) 2026 [Marc Allgeier](https://github.com/fidpa) （衍生：cc-telegram-bot）
## 作者
Marc Allgeier ([@fidpa](https://github.com/fidpa))
**我为什么要构建这个**：我想从手机使用Claude Code -- 发送消息，获取响应，远程在Mac Mini上运行命令。上游项目给了我桥梁，但在一个我关心的机器上运行带有`bypassPermissions`的AI代理需要系统化的安全方法。两次安全审计发现了7个攻击向量中的22项发现，所有这些都已解决，从而形成了24层强化。仍然有5个架构限制，它们是透明记录的。本项目表明，安全工作与编写代码一样，关于诚实的文档。
## 另见
- [lydia-bible-bot](https://github.com/fidpa/lydia-bible-bot) -- 相同的架构，圣经学习领域（安全审计，MCP圣经查找，GDPR）
- [telegram-multi-device-monitor](https://github.com/fidpa/telegram-multi-device-monitor) -- 通过Telegram的多设备监控（Python/Bash，警报去重）
- [ubuntu-server-security](https://github.com/fidpa/ubuntu-server-security) -- 服务器强化（14个组件，CIS基准）
- [step-ca-internal-pki](https://github.com/fidpa/step-ca-internal-pki) -- 具有自动续期和监控的内部PKI
- [bash-production-toolkit](https://github.com/fidpa/bash-production-toolkit) -- 生产就绪的Bash库
---
**2026年1月起生产测试** | 24层安全保护 | ~3,500行TypeScript | ~1,200行文档
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器