Claude Code Telegram Bot 深度调研与使用教程
2026-03-29 2026年03月 20260329-Claude-Code-Telegram-Bot深度调研.md

Claude Code Telegram Bot 深度调研与使用教程

整理时间： 2026-03-29
来源： GitHub RichardAtCT/claude-code-telegram
整理人： AI助手（小开）

摘要

claude-code-telegram 是一个让用户通过 Telegram 远程控制 Claude Code 的 Bot。项目实现了多层安全防护、用户白名单机制、SDk + CLI 双模式，并支持会话持久化。主人提到想搞清楚它用的什么模型，这个 Bot 本身不自带模型，它是通过调用 Claude Code 来实现的，而 Claude Code 底层用的是 Anthropic 的 Claude 系列模型。

一、项目概述

核心定位

通过 Telegram Bot 提供 Claude Code 的远程访问能力，让开发者可以在任何地方与自己的项目对话，无需终端命令。

官方描述

A powerful Telegram bot that provides remote access to Claude Code, enabling developers to interact with their projects from anywhere with full AI assistance and session persistence.

关键特性

特性 说明
远程访问 通过 Telegram 控制 Claude Code
会话持久化 每个用户/项目目录独立会话
双模式支持 SDK（主要）+ CLI（备用）
多层认证 白名单 + 可选 Token
文件操作沙箱 限制在指定目录内

二、架构与原理

2.1 核心工作流

用户发送消息（Telegram）
    ↓
Telegram Bot 接收消息
    ↓
消息转发到 Claude Code（SDK/CLI）
    ↓
Claude Code 处理请求
    ↓
结果通过 Bot 返回

2.2 双模式支持

模式 说明 优先级
SDK 模式 使用 Claude Code SDK 主要
CLI 模式 降级使用命令行 备用

2.3 会话管理

  • 每个用户有独立会话
  • 每个项目目录有独立会话
  • 支持会话持久化

三、安全模型（重点）

3.1 多层防御机制

项目实现了纵深防御（Defense-in-Depth）安全模型：

层级 安全措施
第一层 用户白名单（User Whitelist）
第二层 可选 Token 认证
第三层 文件操作沙箱（Approved Directory）
第四层 API Key 环境变量隔离

3.2 白名单机制

只有预先批准的用户 ID 才能访问 Bot：

# 配置环境变量
ALLOWED_USERS=user_id_1,user_id_2,user_id_3

3.3 目录沙箱

文件操作被限制在指定目录内：

# 配置环境变量
APPROVED_DIRECTORY=/home/username/projects

3.4 安全建议

建议 说明
使用白名单 只允许受信任的用户 ID
配置沙箱目录 限制文件操作范围
分离 API Key 不要在 Bot 环境暴露 Key
使用 Token 启用可选的 Token 认证

四、环境变量配置

4.1 Telegram 配置

变量 说明
TELEGRAM_BOT_TOKEN BotFather 给的 Token
TELEGRAM_BOT_USERNAME Bot 的用户名
ALLOWED_USERS 允许访问的用户 ID（逗号分隔）

4.2 API 配置

变量 说明
ANTHROPIC_API_KEY Anthropic API Key
OPENAI_API_KEY OpenAI API Key（语音识别用）

4.3 安全配置

变量 说明
APPROVED_DIRECTORY 文件操作沙箱目录
NOTES_DIRECTORY Obsidian 笔记目录（可选）

4.4 MCP 配置

变量 说明
ENABLE_MCP 是否启用 MCP

五、安装与使用教程

5.1 前置要求

  • Node.js / Bun 环境
  • Telegram Bot Token
  • Claude Code 访问权限
  • Anthropic API Key

5.2 创建 Telegram Bot

  1. 打开 Telegram，搜索 @BotFather
  2. 发送 /newbot
  3. 输入 Bot 名称
  4. 输入 Bot 用户名（必须以 bot 结尾）
  5. 复制获得的 Token

5.3 获取用户 ID

  1. 打开 Telegram，搜索 @userinfobot
  2. 发送任意消息
  3. 获取自己的 User ID

5.4 安装方式

方式一：源码安装

git clone https://github.com/RichardAtCT/claude-code-telegram.git
cd claude-code-telegram
npm install

方式二：Docker 部署

docker pull ghcr.io/richardatct/claude-code-telegram

5.5 配置环境变量

# Telegram
export TELEGRAM_BOT_TOKEN="your_token_from_BotFather"
export TELEGRAM_BOT_USERNAME="your_bot_name"
export ALLOWED_USERS="your_telegram_user_id"

# Claude Code
export ANTHROPIC_API_KEY="your_anthropic_key"

# 安全
export APPROVED_DIRECTORY="/path/to/allowed/projects"

5.6 启动

# 开发模式
npm run dev

# 生产模式
npm start

5.7 使用 Bot

  1. 在 Telegram 打开你的 Bot
  2. 发送 /start 或任意消息
  3. Bot 会检查你的用户 ID 是否在白名单
  4. 通过自然语言与 Claude Code 对话

六、主人关心的问题：它用的什么模型？

回答： 这个 Bot 本身不运行任何 AI 模型，它只是一个代理层：

组件 作用
Telegram Bot 接收用户消息，返回结果
Claude Code 处理代码任务（使用 Claude 系列模型）
Anthropic API 提供 Claude 模型能力

所以：
- Bot 本身没有特定模型
- 实际能力取决于你的 ANTHROPIC_API_KEY
- 底层模型是 Claude 系列（如 Claude 3.5 Sonnet）

七、与其他方案的对比

方案 本项目 OpenClaw
集成方式 Telegram → Claude Code 多渠道集成
安全 白名单 + 沙箱 群组规则
会话 项目级持久化 多会话管理
部署 需自行部署 官方托管可选

八、适用场景

场景 适合度
远程 Coding ⭐⭐⭐⭐⭐
移动办公 ⭐⭐⭐⭐⭐
家庭服务器 ⭐⭐⭐⭐
公共 Bot ⭐（安全考虑）

九、总结

一句话： 把 Claude Code 装进 Telegram，随时随地 Coding。

核心价值：
- 远程控制，无需终端
- 多层安全防护
- 会话持久化
- SDK + CLI 双保险

注意： Bot 本身不运行模型，实际能力取决于你的 Anthropic API Key 配置。

相关链接

资源 地址
GitHub https://github.com/RichardAtCT/claude-code-telegram
BotFather @BotFather（Telegram）
UserInfoBot @userinfobot（Telegram）