Agent：Claude Code Telegram Bot - 直接在 Telegram 中使用 Claude Code

本文介绍 Agent，一个基于 Claude Code CLI 的 Telegram Bot 项目。该项目让你可以直接在 Telegram 中与 Claude Code 进行交互，支持智能输出过滤、文件上传和会话持久化等功能。

项目简介

Agent 是由 Schreezer (Chirag Agggarwal) 开发的开源项目，提供了一个直接的 Telegram 接口来与 Claude Code CLI 进行交互。截至目前，该项目在 GitHub 上已获得 30 stars 和 2 forks，主要使用 JavaScript 编写，采用 Apache 2.0 许可证。

与传统的 OpenRouter 路由方式不同，Agent 直接将所有消息路由到本地的 Claude Code CLI，通过 PTY（伪终端）实现完整的终端仿真，支持 Claude Code 的所有交互功能。

核心特性

• 直接 Claude Code 访问：所有消息直接路由到 Claude Code CLI，无需 OpenRouter 中转
• 智能输出清理：基于 LLM 的过滤功能，自动去除噪声并格式化输出，适合移动端阅读
• PTY 会话管理：完整的终端仿真，支持 Claude Code 的交互式功能
• 文件上传集成：通过 Telegram 上传文件，在 Claude Code 会话中直接访问
• 会话持久化：即使在 Claude Code 重启后，对话上下文也能保持
• 模块化架构：代码结构清晰，易于维护和扩展

技术栈

• Node.js - 运行时环境
• node-pty - PTY 终端仿真
• node-telegram-bot-api - Telegram Bot API 封装
• Google Gemini 2.5 Flash - 用于输出清理的 LLM
• Winston - 日志记录

安装指南

前置要求

• Node.js >= 18
• npm 或 pnpm
• Claude Code CLI (@anthropic-ai/claude-code)

安装步骤

# 克隆仓库
git clone https://github.com/Schreezer/Agent.git
cd Agent

# 安装依赖
npm install

# 安装 Claude Code CLI
npm install -g @anthropic-ai/claude-code

# 配置环境变量
cp .env.example .env
# 编辑 .env 文件，填入你的配置

# 创建日志目录
mkdir logs

配置说明

必需的环境变量

可选的环境变量

快速开始

# 启动 Bot
npm start

# 开发模式（支持热重载）
npm run dev

Telegram 命令

工作流程

用户消息 → MessageHandler → ClaudeCodeManager (PTY) → Claude Code CLI
                                              ↓
用户 ← OutputCleanerService (LLM) ← SessionManager ← Claude Code 输出

1. 用户发送消息 → 直接通过 PTY 路由到 Claude Code CLI
2. Claude Code 处理 → 完整的交互式终端会话
3. 输出生成 → 使用 ⏺ 符号模式检测输出完成
4. LLM 清理 → OutputCleanerService 基于对话上下文过滤噪声
5. 清理后的输出 → 通过 Telegram 发送给用户

核心组件

ClaudeCodeManager

• 使用 PTY 会话编排 Claude CLI 交互
• 管理 Agent 生命周期和智能输出检测
• 处理认证和命令路由
• 使用模块化工具组件（ClaudeAuthenticator、PTYSessionHandler、OutputDetector）

SessionManager

• 跟踪 Claude Code 会话和对话历史
• 管理每个聊天的文件上传和存储
• 提供会话统计和清理功能
• 维护 LLM 清理的对话上下文

OutputCleanerService

• 使用 LLM（Gemini 2.5 Flash）智能过滤 Claude Code 输出
• 去除噪声、ANSI 代码、进度指示器和重复内容
• 为移动端聊天优化格式化
• 基于对话上下文做出更好的清理决策

MessageHandler

• 将所有 Telegram 消息直接路由到 Claude Code
• 处理文件上传和命令处理
• 管理用户对 Claude Code 问题的回复
• 协调输出清理和传递

项目结构

Agent/
├── src/
│   ├── managers/
│   │   ├── ClaudeCodeManager.js    # 通过 PTY 编排 Claude CLI
│   │   └── SessionManager.js       # 会话和对话跟踪
│   ├── handlers/
│   │   ├── MessageHandler.js       # Telegram 消息路由
│   │   └── CallbackHandler.js      # 内联键盘处理
│   ├── services/
│   │   └── OutputCleanerService.js # 基于 LLM 的输出过滤
│   ├── utils/
│   │   ├── ClaudeAuthenticator.js  # Claude Code 认证
│   │   ├── PTYSessionHandler.js    # PTY 进程管理
│   │   ├── OutputDetector.js       # 处理状态检测
│   │   ├── fileManager.js          # 文件上传处理
│   │   └── logger.js               # Winston 日志
│   └── OpenRouterClaudeBot.js      # 主 Bot 编排器
├── config/
│   └── config.js                   # 配置管理
├── telegram-uploads/               # 用户上传文件（自动创建）
├── index.js                        # 入口文件
└── package.json

技术亮点

PTY 集成

• 使用 node-pty 实现完整的终端仿真
• 支持交互式提示和问题
• 处理 ANSI 代码和转义序列
• 实时输出流和智能缓冲

输出处理管道

1. 缓冲管理：分块收集 Claude 输出
2. 智能检测：使用 ⏺ 符号识别 Claude 等待状态 vs 处理中状态
3. LLM 清理：过滤噪声、合并相关输出、为移动端格式化
4. Telegram 传递：处理消息分块和格式化

会话管理

• 上下文保持：即使 Claude Code 退出，会话也能保持
• 自动重启：完成的会话在用户发送新消息时自动重启
• 单会话限制：新的 Claude 会话会自动终止现有会话
• 文件集成：上传的文件保存到 ./telegram-uploads/chat_<id>/ 并可供 Claude 访问

注意事项

• 需要有效的 Claude Code CLI 安装和认证
• 建议使用 OpenRouter API Key 以获得更好的输出清理效果
• 文件上传存储在本地 telegram-uploads 目录中
• 日志文件保存在 logs/ 目录中

项目链接

• GitHub 仓库: https://github.com/Schreezer/Agent
• 许可证: Apache License 2.0