ChatGPT Telegram 机器人

一个与 OpenAI 的 官方 ChatGPT、DALL·E 和 Whisper API 集成的 Telegram 机器人，用于提供回答。开箱即用，只需极少配置。

截图

演示

插件

特性

• 支持在回答中使用 Markdown 格式
• 使用 /reset 命令重置对话
• 生成回复时显示打字提示
• 可通过指定允许用户列表来限制访问权限
• 支持 Docker 和代理
• 通过 /image 命令使用 DALL·E 生成图像
• 使用 Whisper 转录音频和视频消息（可能需要 ffmpeg）
• 自动总结对话以避免过度消耗 token
• 按用户跟踪 token 使用情况 - 由 @AlexHTW 提供
• 通过 /stats 命令获取个人 token 使用统计信息 - 由 @AlexHTW 提供
• 用户预算和访客预算 - 由 @AlexHTW 提供
• 流式支持
• GPT-4 支持
  • 如果您有权访问 GPT-4 API，只需将 OPENAI_MODEL 参数更改为 gpt-4
• 本地化机器人语言
  • 可用语言 :brazil: :cn: :finland: :de: :indonesia: :iran: :it: :malaysia: :netherlands: :poland: :ru: :saudi_arabia: :es: :taiwan: :tr: :ukraine: :gb: :uzbekistan: :vietnam: :israel:
• 改进的内联查询支持，适用于群组和私聊 - 由 @bugfloyd 提供
  • 要使用此功能，请在 BotFather 中通过 /setinline 命令为您的机器人启用内联查询
• 支持 2023 年 6 月 13 日宣布的新模型 (https://openai.com/blog/function-calling-and-other-api-updates)
• 支持 函数（插件），可通过第三方服务扩展机器人的功能
  • 天气、Spotify、网页搜索、文本转语音等。有关可用插件的列表，请参阅 此处
• 支持非官方的 OpenAI 兼容 API - 由 @kristaller486 提供
• （新增！）支持 GPT-4 Turbo 和 DALL·E 3 [于 2023 年 11 月 6 日宣布] (https://openai.com/blog/new-models-and-developer-products-announced-at-devday) - 由 @AlexHTW 提供
• （新增！）文本转语音支持 [于 2023 年 11 月 6 日宣布] (https://platform.openai.com/docs/guides/text-to-speech) - 由 @gilcu3 提供
• （新增！）视觉支持 [于 2023 年 11 月 6 日宣布] (https://platform.openai.com/docs/guides/vision) - 由 @gilcu3 提供
• （新增！）GPT-4o 模型支持 [于 2024 年 5 月 12 日宣布] (https://openai.com/index/hello-gpt-4o/) - 由 @err09r 提供
• （新增！）o1 和 o1-mini 模型的初步支持

其他特性 - 需要帮助！

如果您想帮忙，请查看 问题 部分并贡献！如果您想协助翻译，请查看 翻译手册

欢迎随时提交 PR！

先决条件

• Python 3.9+
• 一个 Telegram 机器人及其令牌（请参阅 教程）
• 一个 OpenAI 账户（请参阅 配置 部分）

开始使用

配置

通过复制 .env.example 并将其重命名为 .env，然后根据需要编辑所需参数来自定义配置：

参数	描述
OPENAI_API_KEY	您的 OpenAI API 密钥，可从 这里 获取
TELEGRAM_BOT_TOKEN	您的 Telegram 机器人令牌，使用 BotFather 获取（请参阅 教程)
ADMIN_USER_IDS	管理员的 Telegram 用户 ID。这些用户可以访问特殊的管理命令、信息，并且没有预算限制。管理员 ID 不必添加到 ALLOWED_TELEGRAM_USER_IDS 中。注意：默认情况下无管理员 (-)
ALLOWED_TELEGRAM_USER_IDS	允许与机器人交互的 Telegram 用户 ID 列表，以逗号分隔（使用 getidsbot 查找您的用户 ID）。注意：默认情况下，所有人 都被允许 (*)

可选配置

以下参数是可选的，可以在 .env 文件中设置：

预算

参数	描述	默认值
BUDGET_PERIOD	决定所有预算适用的时间范围。可用周期：daily (每天重置预算)、monthly (每月1号重置预算)、all-time (永不重置预算)。更多信息请参阅预算手册	monthly
USER_BUDGETS	以逗号分隔的列表，为 ALLOWED_TELEGRAM_USER_IDS 列表中的每个用户设置自定义的 OpenAI API 费用使用上限（单位：美元）。对于 * 用户列表，将 USER_BUDGETS 的第一个值分配给每位用户。注意：默认情况下，对任何用户均不设置限制（*）。更多信息请参阅预算手册	*
GUEST_BUDGET	所有访客用户的使用上限金额（单位：美元）。访客用户是指不在 ALLOWED_TELEGRAM_USER_IDS 列表中的群聊用户。如果用户预算中未设置使用上限（即 USER_BUDGETS=*），则此值将被忽略。更多信息请参阅预算手册	100.0
TOKEN_PRICE	每1000个 token 的美元价格，用于在使用统计中计算费用信息。数据来源：https://openai.com/pricing	0.002
IMAGE_PRICES	一个包含3个元素的逗号分隔列表，分别对应不同图像尺寸的价格：256x256、512x512 和 1024x1024。数据来源：https://openai.com/pricing	0.016,0.018,0.02
TRANSCRIPTION_PRICE	每分钟音频转录的美元价格。数据来源：https://openai.com/pricing	0.006
VISION_TOKEN_PRICE	每1000个 token 图像理解的美元价格。数据来源：https://openai.com/pricing	0.01
TTS_PRICES	一个包含两种文本转语音模型价格的逗号分隔列表：tts-1 和 tts-1-hd。数据来源：https://openai.com/pricing	0.015,0.030

有关可能的预算配置，请查看预算手册。

其他可选配置选项

参数	描述	默认值
ENABLE_QUOTING	是否在私聊中启用消息引用	true
ENABLE_IMAGE_GENERATION	是否通过 /image 命令启用图像生成	true
ENABLE_TRANSCRIPTION	是否启用音频和视频消息的转录功能	true
ENABLE_TTS_GENERATION	是否通过 /tts 命令启用文本转语音功能	true
ENABLE_VISION	在支持的模型中是否启用视觉功能	true
PROXY	用于 OpenAI 和 Telegram 机器人代理（例如 http://localhost:8080）	-
OPENAI_PROXY	仅用于 OpenAI 的代理（例如 http://localhost:8080）	-
TELEGRAM_PROXY	仅用于 Telegram 机器人的代理（例如 http://localhost:8080）	-
OPENAI_MODEL	用于生成回复的 OpenAI 模型。所有可用模型可在 这里 查看	gpt-4o
OPENAI_BASE_URL	非官方 OpenAI 兼容 API 的端点 URL（例如 LocalAI 或 text-generation-webui）	默认 OpenAI API URL
ASSISTANT_PROMPT	设置助手语气和行为的系统消息	You are a helpful assistant.
SHOW_USAGE	是否在每次回复后显示 OpenAI token 使用情况信息	false
STREAM	是否以流式方式返回响应。注意：若启用且 N_CHOICES 大于 1，则不兼容	true
MAX_TOKENS	ChatGPT API 返回的最大 token 数量上限	GPT-3 为 1200，GPT-4 为 2400
VISION_MAX_TOKENS	视觉模型返回的最大 token 数量上限	gpt-4o 为 300
VISION_MODEL	用于视觉到语音转换的模型。允许值：gpt-4o	gpt-4o
ENABLE_VISION_FOLLOW_UP_QUESTIONS	若为 true，则在向机器人发送图片后，它将一直使用配置的 VISION_MODEL 直至对话结束。否则，它将使用 OPENAI_MODEL 继续对话。允许值：true 或 false	true
MAX_HISTORY_SIZE	为避免过度消耗 token，内存中最多保留的消息数量，超过此数量时将对对话进行摘要处理	15
MAX_CONVERSATION_AGE_MINUTES	对话自最后一条消息起最长持续时间（分钟），超过此时间将重置对话	180
VOICE_REPLY_WITH_TRANSCRIPT_ONLY	是否仅用转录内容回复语音消息，还是同时提供基于转录内容的 ChatGPT 回复	false
VOICE_REPLY_PROMPTS	由分号分隔的短语列表（如 Hi bot;Hello chat）。若转录内容以其中任一短语开头，则即使 VOICE_REPLY_WITH_TRANSCRIPT_ONLY 设置为 true，也会被视为提示语	-
VISION_PROMPT	一句短语（如 What is in this image）。视觉模型会将其作为提示来解读所上传的图片。若发送给机器人的图片带有说明文字，则该说明文字将覆盖此参数	What is in this image
N_CHOICES	对每条输入消息生成的回答数量。注意：若启用 STREAM，将此值设置为大于 1 将无法正常工作	1
TEMPERATURE	介于 0 和 2 之间的数值。数值越高，输出越随机	1.0
PRESENCE_PENALTY	介于 -2.0 和 2.0 之间的数值。正值会根据新 token 是否已出现在文本中对其惩罚	0.0
FREQUENCY_PENALTY	介于 -2.0 和 2.0 之间的数值。正值会根据新 token 在文本中出现的频率对其进行惩罚	0.0
IMAGE_FORMAT	Telegram 接收图片的模式。允许值：document 或 photo	photo
IMAGE_MODEL	要使用的 DALL·E 模型。可用模型有 dall-e-2 和 dall-e-3，当前可用模型可在 这里 查看	dall-e-2
IMAGE_QUALITY	DALL·E 图像的质量，仅适用于 dall-e-3 模型。可选值：standard 或 hd，请注意 定价差异。	standard
IMAGE_STYLE	DALL·E 图像生成的风格，仅适用于 dall-e-3 模型。可选值：vivid 或 natural。可用风格可在 这里 查看。	vivid
IMAGE_SIZE	DALL·E 生成的图片尺寸。对于 dall-e-2，必须是 256x256、512x512 或 1024x1024；对于 dall-e-3 模型，则必须是 1024x1024。	512x512
VISION_DETAIL	视觉模型的细节参数，详见 Vision Guide。允许值：low 或 high	auto
GROUP_TRIGGER_KEYWORD	若设置，群聊中的机器人仅会对以该关键词开头的消息做出回应	-
IGNORE_GROUP_TRANSCRIPTIONS	若设置为 true，机器人将不会处理群聊中的转录内容	true
IGNORE_GROUP_VISION	若设置为 true，机器人将不会处理群聊中的视觉查询	true
BOT_LANGUAGE	机器人通用消息的语言。目前支持的语言有：en、de、ru、tr、it、fi、es、id、nl、zh-cn、zh-tw、vi、fa、pt-br、uk、ms、uz、ar。欢迎贡献更多语言翻译	en
WHISPER_PROMPT	为提高 Whisper 转录服务的准确性，尤其是针对特定名称或术语，可以设置自定义提示。Speech to text - Prompting	-
TTS_VOICE	要使用的文本转语音声音。允许值：alloy、echo、fable、onyx、nova 或 shimmer	alloy
TTS_MODEL	要使用的文本转语音模型。允许值：tts-1 或 tts-1-hd	tts-1

更多详情请查看官方 API 参考文档。

函数

参数	描述	默认值
ENABLE_FUNCTIONS	是否使用函数（又称插件）。您可以此处了解更多关于函数的信息	true（如果模型支持）
FUNCTIONS_MAX_CONSECUTIVE_CALLS	模型在单次响应中可连续调用的最大函数次数，超过此值将显示面向用户的消息	10
PLUGINS	要启用的插件列表（完整列表见下文），例如：PLUGINS=wolfram,weather	-
SHOW_PLUGINS_USED	是否显示本次响应中使用了哪些插件	false

可用插件

名称	描述	必需的环境变量	依赖
weather	提供任何地点的每日天气及未来7天的预报（由Open-Meteo提供支持）	-
wolfram	WolframAlpha 查询（由WolframAlpha提供支持）	WOLFRAM_APP_ID	wolframalpha
ddg_web_search	网页搜索（由DuckDuckGo提供支持）	-	duckduckgo_search
ddg_image_search	图片或 GIF 搜索（由DuckDuckGo提供支持）	-	duckduckgo_search
crypto	实时加密货币汇率（由CoinCap提供支持）——由@stumpyfr开发	-
spotify	Spotify 热门歌曲/艺人、当前播放的歌曲以及内容搜索（由Spotify提供支持）。需要进行一次性授权。	SPOTIFY_CLIENT_ID、SPOTIFY_CLIENT_SECRET、SPOTIFY_REDIRECT_URI	spotipy
worldtimeapi	获取最新的世界时间（由WorldTimeAPI提供支持）——由@noriellecruz开发	WORLDTIME_DEFAULT_TIMEZONE
dice	在聊天中发送一个骰子！	-
youtube_audio_extractor	从 YouTube 视频中提取音频	-	pytube
deepl_translate	将文本翻译成任意语言（由DeepL提供支持）——由@LedyBacer开发	DEEPL_API_KEY
gtts_text_to_speech	文本转语音（由 Google Translate API 提供支持）	-	gtts
whois	查询 WHOIS 域名数据库——由@jnaskali开发	-	whois
webshot	根据给定的 URL 或域名截取网站截图——由@noriellecruz开发	-
auto_tts	使用 OpenAI API 进行文本转语音——由@Jipok开发	-

环境变量

变量	描述	默认值
WOLFRAM_APP_ID	Wolfram Alpha 应用程序 ID（仅 wolfram 插件需要，可在此获取）	-
SPOTIFY_CLIENT_ID	Spotify 应用程序客户端 ID（仅 spotify 插件需要，可在开发者控制台找到）	-
SPOTIFY_CLIENT_SECRET	Spotify 应用程序客户端密钥（仅 spotify 插件需要，可在开发者控制台找到）	-
SPOTIFY_REDIRECT_URI	Spotify 应用程序重定向 URI（仅 spotify 插件需要，可在开发者控制台找到）	-
WORLDTIME_DEFAULT_TIMEZONE	默认时区，例如 Europe/Rome（仅 worldtimeapi 插件需要，时区标识符可从这里获取）	-
DUCKDUCKGO_SAFESEARCH	DuckDuckGo 安全搜索设置（on、off 或 moderate）（可选，适用于 ddg_web_search 和 ddg_image_search）	moderate
DEEPL_API_KEY	DeepL API 密钥（deepl 插件需要，可在此获取）	-

安装

克隆仓库并进入项目目录：

git clone https://github.com/n3d1117/chatgpt-telegram-bot.git
cd chatgpt-telegram-bot

从源码安装

1. 创建虚拟环境：

python -m venv venv

2. 激活虚拟环境：

# 对于 Linux 或 macOS：
source venv/bin/activate

# 对于 Windows：
venv\Scripts\activate

3. 使用 requirements.txt 文件安装依赖项：

pip install -r requirements.txt

4. 使用以下命令启动机器人：

python bot/main.py

使用 Docker Compose

运行以下命令以构建并运行 Docker 镜像：

docker compose up

即用型 Docker 镜像

您也可以使用 Docker Hub 上的 Docker 镜像：

docker pull n3d1117/chatgpt-telegram-bot:latest
docker run -it --env-file .env n3d1117/chatgpt-telegram-bot

或者使用 GitHub Container Registry：

docker pull ghcr.io/n3d1117/chatgpt-telegram-bot:latest
docker run -it --env-file .env ghcr.io/n3d1117/chatgpt-telegram-bot

手动构建 Docker 镜像

docker build -t chatgpt-telegram-bot .
docker run -it --env-file .env chatgpt-telegram-bot

Heroku

以下是使用 Heroku 部署的 Procfile 示例（感谢 err09r！）：

worker: python -m venv venv && source venv/bin/activate && pip install -r requirements.txt && python bot/main.py

致谢

• ChatGPT 来自 OpenAI
• python-telegram-bot
• jiaaro/pydub

免责声明

本项目为个人项目，与 OpenAI 无任何关联。

许可证

本项目根据 GPL 2.0 许可证发布。更多信息请参阅仓库中包含的 LICENSE 文件。

ChatGPT Telegram Bot 快速上手指南

环境准备

在开始之前，请确保满足以下前置条件：

• 操作系统：Linux, macOS 或 Windows
• Python 版本：3.9 或更高版本
• 依赖项：
  • 一个 Telegram Bot Token（通过 @BotFather 获取）
  • 一个 OpenAI API Key（需具备访问权限）
  • （可选）若需处理音视频转录功能，建议安装 ffmpeg

安装步骤

1. 克隆项目

从 GitHub 拉取最新代码：

git clone https://github.com/n3d1117/chatgpt-telegram-bot.git
cd chatgpt-telegram-bot

2. 创建虚拟环境并安装依赖

推荐使用 Python 虚拟环境以避免依赖冲突：

python -m venv venv
source venv/bin/activate  # Windows 用户请使用: venv\Scripts\activate
pip install -r requirements.txt

国内加速提示：如遇下载缓慢，可使用清华源加速安装： pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

3. 配置环境变量

复制示例配置文件并重命名为 .env：

cp .env.example .env

编辑 .env 文件，填入必要的参数：

# OpenAI API 密钥
OPENAI_API_KEY=sk-your-openai-api-key

# Telegram Bot Token (从 @BotFather 获取)
TELEGRAM_BOT_TOKEN=your-telegram-bot-token

# 允许使用的用户 ID (留空或填 * 表示允许所有人，建议填写具体 ID 以限制访问)
# 可通过 @getidsbot 查询你的 Telegram User ID
ALLOWED_TELEGRAM_USER_IDS=*

# 管理员 ID (拥有特殊命令权限且无预算限制，多个 ID 用逗号分隔)
ADMIN_USER_IDS=-

基本使用

启动机器人

在终端中运行以下命令启动服务：

python bot.py

若看到类似 Starting bot... 的日志且无报错，即表示启动成功。

测试交互

1. 打开 Telegram，找到你创建的机器人。
2. 发送任意文本消息（例如："Hello"），机器人将调用 ChatGPT 返回回答。
3. 常用命令：
   • /reset：重置当前对话上下文。
   • /image <描述>：生成图片（需开启 ENABLE_IMAGE_GENERATION）。
   • /stats：查看个人 Token 使用统计（需配置预算功能）。

进阶提示

• 模型切换：如需使用 GPT-4 或 GPT-4o，请在 .env 中添加或修改 OPENAI_MODEL=gpt-4 或 OPENAI_MODEL=gpt-4o。
• Docker 部署：项目支持 Docker 运行，若已安装 Docker，可直接使用 docker-compose up -d 启动（需先配置 .env）。