🤖️ 电报聊天机器人

English | Chinese

ChatGPT 电报机器人是一款功能强大的电报机器人，支持与 OpenAI 兼容的大语言模型 API。它使用户能够在电报上进行高效的对话和信息检索。对于 Anthropic、Gemini、Vertex AI、Azure、AWS、XAI、Cohere、Groq、Cloudflare、OpenRouter 等其他提供商的模型支持，请使用我的另一个项目 uni-api 来集成它们。这有助于降低维护成本。感谢您的理解。

✨ 功能

• 多种 AI 模型：支持与 OpenAI 格式兼容的 API。对于 Anthropic、Gemini、Vertex AI、Azure、AWS、XAI、Cohere、Groq、Cloudflare、OpenRouter 等其他提供商的模型，请使用 uni-api 进行集成。同时也支持 one-api/new-api。采用自主研发的 API 请求后端 SDK，不依赖于 OpenAI SDK。
• 多模态问答：支持语音、音频、图片以及 PDF/TXT/MD/Python 文档的问答。用户可以直接在聊天框中上传文件以供使用。
• 模型分组系统：将 AI 模型按逻辑分组，便于选择。模型可以按提供商（如 GPT、Claude 等）或按能力分组。未明确分组的模型会自动归入“OTHERS”组。这使得模型选择更加直观，尤其是在可用模型较多时。
• 群聊主题模式：支持在群聊中启用主题模式，实现不同主题之间的 API、对话历史、插件配置及偏好设置的隔离。
• 丰富的插件系统：支持网络搜索（DuckDuckGo 和 Google）、URL 摘要、ArXiv 论文摘要以及代码解释器。
• 用户友好的界面：允许在聊天窗口内灵活切换模型，并支持类似打字机效果的流式输出。支持精确的 Markdown 消息渲染，利用了我的另一个 项目。
• 高效的消息处理：异步处理消息，多线程回答问题，支持对话隔离，为不同用户提供独立的对话记录。
• 长文本消息处理：自动合并长文本消息，突破电报单条消息长度限制。当机器人的回复超过电报限制时，会将其拆分为多条消息。
• 多用户对话隔离：支持对话隔离和配置隔离，允许在多用户模式和单用户模式之间切换。
• 问题预测：自动生成后续问题，预测用户接下来可能提出的问题。
• 多语言界面：支持简体中文、繁体中文、俄语和英语界面。
• 白名单、黑名单和管理员设置：支持设置白名单、黑名单和管理员。
• 内联模式：允许用户在任何聊天窗口中 @ 机器人来生成答案，而无需在机器人的聊天窗口中提问。
• 便捷部署：支持一键 koyeb、Zeabur、Replit 部署，真正零成本且傻瓜式操作。同时支持 kuma 防休眠，以及 Docker 和 fly.io 部署。

🍃 环境变量

以下是与机器人核心设置相关的环境变量列表：

变量名	描述	是否必填
BOT_TOKEN	Telegram 机器人令牌。在 BotFather 上创建一个机器人以获取 BOT_TOKEN。	是
API_KEY	OpenAI 或第三方 API 密钥。	是
MODEL	设置默认的问答模型；默认值为：gpt-5。此选项可通过机器人的“info”命令自由切换，原则上无需设置。	否
WEB_HOOK	每当 Telegram 机器人接收到用户消息时，消息会被传递到 WEB_HOOK，机器人将在那里监听并及时处理接收到的消息。	否
BASE_URL	如果您使用的是 OpenAI 官方 API，则无需设置此参数。如果您使用的是第三方 API，则需要填写第三方代理网站。默认值为：https://api.openai.com/v1/chat/completions	否
NICK	默认为空，NICK 是机器人的名称。只有当用户输入的消息以 NICK 开头时，机器人才会响应；否则，机器人会对任何消息作出回应。尤其是在群聊中，如果没有设置 NICK，机器人会回复所有消息。	否
GOOGLE_API_KEY	如果需要使用 Google 搜索，必须设置此参数。如果不设置该环境变量，机器人将默认提供 DuckDuckGo 搜索服务。	否
GOOGLE_CSE_ID	如果需要使用 Google 搜索，需与 GOOGLE_API_KEY 一起设置。	否
whitelist	设置哪些用户可以访问机器人，并用逗号（,）连接获准使用机器人的用户 ID。默认值为 None，表示机器人对所有人开放。	否
BLACK_LIST	设置哪些用户被禁止访问机器人，并用逗号（,）连接被禁止使用的用户 ID。默认值为 None。	否
ADMIN_LIST	设置管理员列表。只有管理员可以使用 /info 命令来配置机器人。	否
GROUP_LIST	设置可以使用机器人的群组列表。用逗号（,）连接群组 ID。即使群组成员不在白名单中，只要群组 ID 在 GROUP_LIST 中，该群组的所有成员都可以使用机器人。	否
CUSTOM_MODELS	设置自定义模型名称列表。用逗号（,）连接模型名称。如果需要移除某个默认模型，在默认模型名称前加一个连字符（-）。要移除所有默认模型，使用 -all。要创建模型分组，用分号（;）分隔不同分组，用冒号（:）定义分组名称及其包含的模型，例如：CUSTOM_MODELS=-all,command,grok-2;GPT:gpt-5,gpt-3.5-turbo;Claude:claude-3-opus,claude-3-sonnet;OTHERS。未指定分组的模型将自动归入“OTHERS”分组。	否
CHAT_MODE	引入多用户模式，不同用户的配置互不共享。当 CHAT_MODE 为 global 时，所有用户共享同一配置。当 CHAT_MODE 为 multiusers 时，用户的配置彼此独立。	否
temperature	指定大语言模型的温度。默认值为 0.5。	否
GET_MODELS	指定是否通过 API 获取支持的模型。默认值为 False。	否
SYSTEMPROMPT	指定系统提示语，系统提示语是一个字符串，例如：SYSTEMPROMPT=你是 ChatGPT，由 OpenAI 训练的大语言模型。请以对话方式回答问题。。默认值为 None。系统提示语的设置仅在 CHAT_MODE 为 global 时有效。当 CHAT_MODE 为 multiusers 时，无论系统提示语的值如何，该环境变量都不会修改任何用户的系统提示语，因为用户不希望自己的系统提示语被更改为全局系统提示语。	否
LANGUAGE	指定机器人显示的默认语言，包括按钮显示语言和对话语言。默认值为 English。目前仅支持以下四种语言的设置：English、Simplified Chinese、Traditional Chinese、Russian。部署完成后，也可以使用 /info 命令来设置显示语言。	否
CONFIG_DIR	指定存储用户配置文件的文件夹路径。CONFIG_DIR 是用于存储用户配置的文件夹。每次机器人启动时，都会从 CONFIG_DIR 文件夹中读取配置，因此用户每次重启后都不会丢失之前的设置。在本地使用 Docker 部署时，可以通过 -v 参数挂载文件夹来实现配置持久化。默认值为 user_configs。	否
RESET_TIME	指定机器人重置聊天记录的时间间隔。每隔 RESET_TIME 秒，机器人会为除管理员列表以外的所有用户重置聊天记录。每个用户的重置时间不同，根据其上次提问的时间计算下一次重置时间，因此并非所有用户同时重置。默认值为 3600 秒，最小值为 60 秒。	否

以下是与机器人偏好设置相关的环境变量列表。机器人启动后，也可以通过使用 /info 命令并点击“Preferences”按钮来设置偏好：

变量名称	描述	是否必填
PASS_HISTORY	默认值为 9999。机器人会记住对话历史，并在下一次回复时考虑上下文。如果设置为 0，机器人将忘记对话历史，仅考虑当前对话。PASS_HISTORY 的值必须大于或等于 0。它对应于偏好设置中的“聊天历史”按钮。	否
LONG_TEXT	如果用户输入的消息长度超过 Telegram 的限制，并且在短时间内连续发送多条消息，机器人会将这些消息视为一条消息处理。默认值为 True。对应于偏好设置中的“长文本合并”按钮。	否
IMAGEQA	启用图像问答功能，默认设置为模型可以回答图像内容，即默认值为 True。对应于偏好设置中的“图像问答”按钮。	否
LONG_TEXT_SPLIT	当机器人的回复超过 Telegram 的限制时，会将其拆分为多条消息。默认值为 True。对应于偏好设置中的“长文本拆分”按钮。	否
FILE_UPLOAD_MESS	当文件或图片上传成功且机器人完成处理后，机器人会发送一条消息提示上传成功。默认值为 True。这对应于偏好设置中的“文件上传消息”按钮。	否
FOLLOW_UP	自动为用户生成多个相关问题供其选择。默认值为 False。对应于偏好设置中的“问题建议”按钮。	否
TITLE	是否在机器人回复的开头显示模型名称。默认值为 False。对应于偏好设置中的“模型标题”按钮。	否
REPLY	机器人是否应以“回复”格式回复用户的消息。默认值为 False。对应于偏好设置中的“回复消息”按钮。	否

以下是与机器人插件设置相关的环境变量列表：

变量名称	描述	是否必填
get_search_results	是否启用搜索插件。默认为 False。	否
get_url_content	是否启用 URL 摘要插件。默认为 False。	否
download_read_arxiv_pdf	是否启用 arXiv 论文摘要插件。默认为 False。	否
run_python_script	是否启用代码解释器插件。默认为 False。	否
generate_image	是否启用图像生成插件。默认为 False。	否
get_time	是否启用日期插件。默认为 False。	否

Fugue 远程部署

一键部署

点击下方按钮，即可在 Fugue 上使用预构建的 Docker 镜像进行一键部署：

打开部署页面后，在环境编辑器中填写 BOT_TOKEN、API 和 BASE_URL，然后进行部署。WEB_HOOK 是可选的。如果你已经为应用拥有公共域名，则将其设置为 https://your-domain/；否则，可以留空。

Koyeb 远程部署

在 Koyeb 上有两种部署方式：一种是使用 Koyeb 提供的 Docker 镜像进行一键部署，另一种是导入本仓库进行部署。这两种方法都是免费的。第一种方法部署简单，但无法自动更新；而第二种方法稍显复杂，却可以实现自动更新。

一键部署

点击下方按钮，即可使用预构建的 Docker 镜像进行一键自动部署：

在环境变量中，填写 BOT_TOKEN、API 和 BASE_URL，然后点击部署按钮。WEB_HOOK 环境变量可以保持原样，Koyeb 会自动分配一个子域名。

仓库部署

1. 分叉本仓库 点击分叉此仓库

2. 部署时，需选择仓库方式，将 Run command 设置为 python3 bot.py，并将 Exposed ports 设置为 8080。

3. 安装 pull 请求，以便自动同步本仓库。

Zeabur 远程部署

一键部署：

若需要后续功能更新，建议采用以下部署方式：

• 首先分叉本仓库，然后注册 Zeabur。目前，Zeabur 不支持免费的 Docker 容器部署。若需使用 Zeabur 部署该项目的机器人，需升级至 Developer Plan。幸运的是，Zeabur 推出了他们的 赞助计划，为本项目的每一位贡献者提供一个月的 Developer Plan。如果你有想要增强的功能，欢迎向本项目提交 pull 请求。
• 从你自己的 Github 仓库导入。
• 设置所需的环境变量，并重新部署。
• 若后续需要功能更新，只需在你的仓库中同步本仓库，然后在 Zeabur 上重新部署，即可获得最新功能。

Replit 远程部署

导入 Github 仓库后，设置运行命令：

pip install -r requirements.txt > /dev/null && python3 bot.py

在工具栏的 Secrets 中添加机器人所需的环境变量，其中：

• WEB_HOOK：Replit 会自动为你分配一个域名，填写 https://appname.username.repl.co
• 请记得开启“Always On”

点击屏幕顶部的运行按钮即可启动机器人。

fly.io 远程部署

官方文档：https://fly.io/docs/

使用 Docker 镜像部署 fly.io 应用程序

flyctl launch --image yym68686/chatgpt:latest

在提示时输入应用程序名称，并选择“否”以不初始化 Postgresql 或 Redis。

按照提示进行部署。官方控制面板中会提供一个二级域名，可用于访问服务。

设置环境变量

flyctl secrets set BOT_TOKEN=bottoken
flyctl secrets set API_KEY=
# 可选
flyctl secrets set WEB_HOOK=https://flyio-app-name.fly.dev/
flyctl secrets set NICK=javis

查看所有环境变量

flyctl secrets list

移除环境变量

flyctl secrets unset MY_SECRET DATABASE_URL

通过 SSH 连接到 fly.io 容器

flyctl ssh issue --agent
# 建立 SSH 连接
flyctl ssh establish

检查 Webhook URL 是否正确

https://api.telegram.org/bot<token>/getWebhookInfo

Docker 本地部署

启动容器

docker run -p 80:8080 --name chatbot -dit \
    -e BOT_TOKEN=your_telegram_bot_token \
    -e API_KEY= \
    -e BASE_URL= \
    -v ./user_configs:/home/user_configs \
    yym68686/chatgpt:latest

或者，如果您想使用 Docker Compose，以下是 docker-compose.yml 示例：

version: "3.5"
services:
  chatgptbot:
    container_name: chatgptbot
    image: yym68686/chatgpt:latest
    environment:
      - BOT_TOKEN=
      - API_KEY=
      - BASE_URL=
      - CUSTOM_MODELS=-all;GPT:gpt-5,gpt-3.5-turbo;Claude:claude-3-opus,claude-3-sonnet
    volumes:
      - ./user_configs:/home/user_configs
    ports:
      - 80:8080

在后台运行 Docker Compose 容器

docker-compose pull
docker-compose up -d

# uni-api
docker-compose -f docker-compose-uni-api.yml up -d

将 Docker 镜像打包并上传到 Docker Hub

docker build --no-cache -t chatgpt:latest -f Dockerfile.build --platform linux/amd64 .
docker tag chatgpt:latest yym68686/chatgpt:latest
docker push yym68686/chatgpt:latest

一键重启 Docker 镜像

set -eu
docker pull yym68686/chatgpt:latest
docker rm -f chatbot
docker run -p 8080:8080 -dit --name chatbot \
-e BOT_TOKEN= \
-e API_KEY= \
-e BASE_URL= \
-e GOOGLE_API_KEY= \
-e GOOGLE_CSE_ID= \
-e claude_api_key= \
-v ./user_configs:/home/user_configs \
yym68686/chatgpt:latest
docker logs -f chatbot

此脚本用于通过单个命令重启 Docker 镜像。首先，如果存在名为“chatbot”的现有 Docker 容器，则将其删除。然后，运行一个新的名为“chatbot”的 Docker 容器，暴露 8080 端口，并设置各种环境变量。使用的 Docker 镜像是“yym68686/chatgpt:latest”。最后，跟踪“chatbot”容器的日志。

🚀 源代码本地部署

Python >= 3.10

直接从源代码运行机器人，无需使用 Docker。克隆仓库：

git clone --recurse-submodules --depth 1 -b main --quiet https://github.com/yym68686/ChatGPT-Telegram-Bot.git

安装依赖项：

pip install -r requirements.txt

配置环境变量：

./configure_env.sh

运行：

python bot.py

🧩 插件

该项目支持多种插件，包括：DuckDuckGo 和 Google 搜索、URL 摘要、ArXiv 论文摘要、DALLE-3 绘画以及代码解释器等。您可以通过设置环境变量来启用或禁用这些插件。

• 如何开发插件？

所有与插件相关的代码都位于该仓库中的 git 子模块 aient 中。aient 是我独立开发的一个仓库，用于处理 API 请求、对话历史管理等功能。当您使用带有 --recurse-submodules 参数的 git clone 克隆此仓库时，aient 将自动下载到您的本地机器上。此仓库中的所有插件代码都位于相对路径 aient/src/aient/plugins 下。您可以在此目录中添加自己的插件代码。插件开发流程如下：

1. 在 aient/src/aient/plugins 目录下创建一个新的 Python 文件，例如 myplugin.py。通过在函数上方添加 @register_tool() 装饰器来注册插件。通过 from .registry import register_tool 导入 register_tool。

2. 在 utils/i18n.py 文件中为插件名称添加多种语言的翻译。

完成上述步骤后，您的插件即可使用。🎉

📄 常见问题解答

• WEB_HOOK 环境变量有什么作用？应该如何使用？

WEB_HOOK 是一个 webhook 地址。具体来说，当 Telegram 机器人收到用户消息时，它会将消息发送到 Telegram 服务器，然后由服务器将消息转发到机器人设置的 WEB_HOOK 地址处的服务器。因此，当有消息发送到机器人时，机器人几乎会立即执行处理程序。通过 WEB_HOOK 接收消息比未设置 WEB_HOOK 时响应速度更快。

在使用 Zeabur、Replit 或 Koyeb 等平台部署机器人时，这些平台会为您提供一个域名，您需要将其填写到 WEB_HOOK 中，以便机器人能够接收用户消息。当然，也可以不设置 WEB_HOOK，但机器人的响应时间会稍长一些，尽管差异并不明显，因此通常不需要设置 WEB_HOOK。

在服务器上部署机器人时，您需要使用 nginx 或 caddy 等反向代理工具，将 Telegram 服务器发送的消息转发到您的服务器，以便机器人能够接收用户消息。因此，您需要将 WEB_HOOK 设置为您服务器的域名，并将请求 WEB_HOOK 的流量转发到机器人所在的服务器和相应端口。例如，在 caddy 中，您可以在 caddy 配置文件 /etc/caddy/Caddyfile 中这样配置：

your_webhook_domain.com {
    reverse_proxy localhost:8082
}

• 为什么我无法使用 Google 搜索？

默认情况下提供的是 DuckDuckGo 搜索。Google 搜索的官方 API 需要用户自行申请。它可以提供 GPT 之前无法回答的实时信息，例如微博上的今日热点、特定地点的今日天气，以及某个人物或新闻事件的进展。

• 为什么即使我添加了 Google 搜索 API，仍然无法使用搜索功能？

可能有两种原因：

1. 只有支持工具使用的大型语言模型（LLM）API 才能使用搜索功能。目前，此项目仅支持 OpenAI、Claude 和 Gemini 系列模型的 API 使用搜索功能。其他模型提供商的 API 目前在此项目中不支持工具使用。如果您希望适配某个模型提供商，可以联系维护者。

2. 如果您正在使用 OpenAI、Claude 和 Gemini 系列模型的 API，但无法使用搜索功能，可能是因为搜索功能尚未启用。您可以通过 /info 命令进入设置界面，检查是否已开启搜索功能。

3. 如果您使用的是 OpenAI、Claude 或 Gemini 系列模型的 API，请确保您使用的是官方 API。如果您使用的是第三方中继 API，提供商可能是通过网页爬取的方式为您提供 API。而通过网页爬取提供的 API 无法使用工具功能，这意味着本项目的所有插件都无法使用。如果您确认自己使用的是官方 API 但仍无法成功搜索，请联系开发者。

• 如何切换模型？

您可以在聊天窗口中使用 /info 命令在 GPT-3.5、GPT-4、GPT-4o 等不同模型之间进行切换。

• 能否部署到群组中？

可以。该机器人支持白名单机制，以防止滥用和信息泄露。

• 为什么将机器人添加到群组后无法正常对话？

如果这是您首次将机器人加入群聊，您需要在 BotFather 中将群组隐私设置为“禁用”，然后将机器人从群聊中移除并重新添加，这样机器人就能正常使用了。

另一种方法是将机器人设为管理员，这样它就可以正常工作。然而，如果您想将机器人添加到一个您不是管理员的群聊中，第一种方法更为合适。

另外一种可能性是 GROUP_LIST 设置的并非当前群聊的 ID。请检查是否已正确设置 GROUP_LIST。需要注意的是，GROUP_LIST 是指群组的 ID，而不是群组名称。群组 ID 以负号开头，后跟一串数字。

• GROUP_LIST、ADMIN_LIST 和白名单的设置如何影响机器人的行为？

如果未设置白名单，所有人都可以使用机器人。若设置了白名单，则只有白名单中的用户才能使用机器人。如果设置了 GROUP_LIST，则只有 GROUP_LIST 中的群组可以使用机器人。如果同时设置了白名单和 GROUP_LIST，那么群组内的所有人都可以使用机器人，但只有白名单中的用户可以与机器人进行私聊。如果设置了 ADMIN_LIST，则只有 ADMIN_LIST 中的用户可以使用 /info 命令来更改机器人的设置。如果没有设置 ADMIN_LIST，则所有人都可以使用 /info 命令来修改机器人的配置。此外，GROUP_LIST 也可以包含频道，频道 ID 同样以负号开头，后接一串数字。

• BASE_URL 应该如何设置？

BASE_URL 支持所有后缀，包括：https://api.openai.com/v1/chat/completions、https://api.openai.com/v1 和 https://api.openai.com/。机器人会根据不同的用途自动分配不同的端点。

• 是否必须配置 web_hook 环境变量？

web_hook 并非必需的环境变量。您只需根据应用功能需求，设置域名（需与 WEB_HOOK 一致）及其他必要的环境变量即可。

• 我使用 Docker Compose 部署了机器人。如果文档存储在服务器本地，应将其挂载到哪个目录才能生效？是否需要额外配置或修改代码？

您可以直接通过聊天框将文档发送给机器人，机器人会自动解析文档内容。要使用文档问答功能，您需要先启用历史对话功能。无需对文档进行额外处理。

• 我仍然无法让机器人正常工作……我想在群组中使用它，已经将 ADMIN_LIST 设置为自己，GROUP_LIST 设置为该群组，白名单保持为空。然而，只有我可以在该群组中使用机器人，其他成员却提示没有权限，这是怎么回事？

以下是排查步骤：请仔细检查 GROUP_LIST 是否正确。Telegram 群组的 ID 以负号开头，后接一串数字。如果不正确，请使用此机器人 bot 重新获取群组 ID。

• 我上传了文档，但机器人并未根据文档内容作出响应，这是为什么？

要使用文档问答功能，您必须先启用历史记录功能。您可以通过 /info 命令开启历史记录，或者将环境变量 PASS_HISTORY 设置为大于 2 的值，以默认启用历史记录功能。请注意，启用历史记录会产生额外费用，因此本项目默认不启用历史记录功能。这意味着在默认设置下，问答功能无法使用。在使用此功能前，您需要手动开启历史记录功能。

• 设置了 NICK 后，当我使用 @ 提及机器人时没有反应，只有当消息以昵称开头时才会回复。如何让机器人既能响应昵称，也能响应 @机器人名呢？

在群聊场景下，如果未设置环境变量 NICK，机器人会接收所有群组消息并作出回应。因此，设置 NICK 是必要的。设置 NICK 后，机器人只会对以 NICK 开头的消息作出响应。所以，如果您希望使用 @ 提及机器人时获得回复，只需将 NICK 设置为 @机器人名即可。这样一来，当您在群组中 @ 机器人时，机器人会检测到消息以 @机器人名开头，并作出相应回复。

• 历史记录会保留多少条消息？

其他所有模型均采用官方设定的上下文长度限制，例如 gpt-3.5-turbo-16k 的上下文长度为 16,000 token，gpt-5 的上下文长度为 128,000 token，而 Claude3/3.5 的上下文长度为 200,000 token。这一限制是为了节省用户的成本，因为大多数场景并不需要过高的上下文长度。

• 如何从模型列表中删除默认的模型名称？

您可以使用 CUSTOM_MODELS 环境变量来实现。例如，如果您想添加 gpt-5 并从模型列表中移除 gpt-3.5，可以将 CUSTOM_MODELS 设置为 gpt-5,-gpt-3.5。如果您想一次性删除所有默认模型，可以将 CUSTOM_MODELS 设置为 -all,gpt-5。

• 如何将模型分组？

您可以使用带有特殊语法的 CUSTOM_MODELS 环境变量：

1. 使用分号 (;) 分隔不同的组；
2. 使用冒号 (:) 定义组名及其包含的模型；
3. 在同一组内，使用逗号 (,) 分隔各个模型。

例如：

CUSTOM_MODELS=-all;GPT:gpt-5,gpt-4,gpt-3.5-turbo;Claude:claude-3-opus,claude-3-sonnet,claude-3-haiku;Gemini:gemini-1.5-pro,gemini-1.0-pro;command,grok-2

这将创建三个组：“GPT”、“Claude”和“Gemini”，每个组分别包含相应的模型。“command”和“grok-2”没有明确归属的组，因此它们会被自动归入“OTHERS”组。

如果即使没有未分组的模型也想包含一个空的“OTHERS”组，可以在最后添加“OTHERS”：

CUSTOM_MODELS=-all;GPT:gpt-5;Claude:claude-3-opus;OTHERS

• 对话隔离具体是如何工作的？

对话始终是基于不同的窗口而非不同用户进行隔离的。这意味着在同一群聊窗口、同一主题以及同一私聊窗口中，都被视为同一个对话。CHAT_MODE 只影响配置是否被隔离。在多用户模式下，每个用户的插件配置、偏好设置等都是独立的，互不影响。而在单用户模式下，所有用户共享相同的插件配置和偏好设置。然而，对话历史始终是隔离的。对话隔离是为了保护用户隐私，确保用户的对话历史、插件配置、偏好设置等不会被其他用户看到。

• 为什么 Docker 镜像很久没有更新了？

Docker 镜像仅存储程序的运行环境。目前程序的运行环境非常稳定，环境依赖几乎没有变化，因此 Docker 镜像并未更新。每次重新部署 Docker 镜像时，都会拉取最新的代码，所以无需担心 Docker 镜像的更新问题。

• 为什么容器启动后会报错“http connect error 或 telegram.error.TimedOut: Timed out”？

这个问题很可能是由于部署 Docker 的服务器无法连接到 Telegram 服务器，或者 Telegram 服务器本身不稳定导致的。

1. 大多数情况下，只需重启服务、检查服务器网络环境，或等待 Telegram 服务恢复即可。
2. 此外，您也可以尝试通过 Webhook 与 Telegram 服务器通信，这可能会解决问题。

• 如何让 Docker 容器无限重试而不是一开始就停止？

Docker 中的 --restart unless-stopped 参数用于设置容器的重启策略。具体来说：

1. unless-stopped：该策略表示容器会在停止时自动重启，除非它是被手动停止的。也就是说，如果容器因错误或系统重启而停止，它会自动重启；但如果您手动停止容器（例如使用 docker stop 命令），它将不会自行重启。 这个参数对于需要持续运行的服务非常有用，因为它可以确保服务在意外中断后自动恢复，而无需人工干预。

2. 示例：假设您有一个运行 Web 服务器的 Docker 容器，并希望它在崩溃或系统重启时自动重启，但在您手动停止时则不重启。您可以使用以下命令：

docker run -d --name my-web-server -p 80:80 --restart unless-stopped my-web-server-image

在这个例子中，名为 my-web-server 的 Web 服务器容器将在除手动停止以外的情况下自动重启。

• 切换模型时，我需要重新输入提示词吗？

是的，因为切换模型会重置对话历史，所以需要重新输入提示词。

• PASS_HISTORY 的合适值是多少？

PASS_HISTORY 的数值严格等于对话历史中的消息数量。推荐值为 2，因为系统提示词占一条消息。如果设置为 0，PASS_HISTORY 会自动重置为 2，以确保对话正常进行。当 PASS_HISTORY 小于或等于 2 时，机器人只会记住当前的一问一答，下次不会再记住之前的问答内容。PASS_HISTORY 的最大值没有限制，但请注意，对话历史中的消息越多，每次对话的成本就越高。如果没有设置 PASS_HISTORY，其默认值为 9999，表示对话历史中的消息数为 9999 条。

• Bot Token 是否可以有多个？

目前还不支持多个 Bot Token，未来会支持。

• 如何使用机器人指令？

1. /info：机器人 /info 指令可以查看机器人的配置信息，包括当前使用的模型、API 地址、API 密钥等。还可以更改机器人的显示语言、偏好设置以及插件配置。

2. /start：机器人 /start 指令可以查看机器人的使用说明、使用方法和功能介绍。您可以通过 /start 指令设置 API 密钥。如果您有官方的 OpenAI API 密钥，请使用以下命令：/start your_api_key。如果您使用的是第三方 API 密钥，请使用以下命令：/start https://your_api_url your_api_key。

3. /reset：机器人 /reset 指令可以清除机器人的对话记录，并强制机器人停止生成回复。如果您想重置系统提示词，请使用以下命令：/reset your_system_prompt。但是，/reset 指令不会恢复机器人的显示语言、偏好设置、插件配置、使用的模型、API 地址、API 密钥、系统提示词等。

4. /model：机器人 /model 指令允许您快速切换 AI 模型，而无需通过 /info 菜单。只需使用 /model model_name 即可切换到特定模型。例如：/model gpt-5 切换到 GPT-5，或 /model claude-3-opus 切换到 Claude 3 Opus。此命令为对话过程中快速更换模型提供了更便捷的方式。

• 如果 Koyeb 部署失败怎么办？

Koyeb 的免费服务有时会有些不稳定，因此部署失败的情况比较常见。您可以尝试重新部署，如果仍然不行，可以考虑切换到其他平台。😊

• 为什么我使用 CUSTOM_MODELS 删除某个模型后，再次用 /info 命令查看时，默认模型名称又出现了？

如果您使用 docker-compose.yml 进行部署，请不要在 CUSTOM_MODELS 的值周围添加引号。错误用法：CUSTOM_MODELS="gpt-5,-gpt-3.5"，否则会导致环境变量解析错误，从而使得默认模型名称重新出现。错误写法会被解析为删除 gpt-3.5 模型，因此默认的 gpt-3.5 模型并不会被删除。正确的写法是：CUSTOM_MODELS=gpt-5,-gpt-3.5。

同样的规则也适用于模型分组。错误：CUSTOM_MODELS="GPT:gpt-5;Claude:claude-3-opus"。正确：CUSTOM_MODELS=GPT:gpt-5;Claude:claude-3-opus。如果您的分组名称或模型名称包含特殊字符，请注意转义处理。

• 我如何同时使用多个 API 提供商？例如，同时使用 Gemini 和 OpenAI？

该项目一次只能配置一个 API 提供商。例如，如果将 BASE_URL 设置为 Gemini 的 API 端点，则无法同时使用 OpenAI 的 API。若需同时使用多个提供商，必须采用 uni-api 项目。uni-api 可以将不同提供商的各种 API 格式转换为标准的 OpenAI 格式。由于本项目仅支持 OpenAI API 格式，因此通过 uni-api 可以同时使用来自数十家不同提供商的模型。需要注意的是，“OpenAI 格式”并不意味着只能使用 OpenAI 的模型；许多其他提供商（如 Gemini、Groq、Cloudflare 等）也支持通过与 OpenAI 兼容的 API 格式进行调用。

• 为什么你们改变了 API 密钥的整体基础？现在如果不更换 API，我就无法同时使用 Grok 和 Gemini 了？

开发者删除了除 OpenAI 格式之外的其他 API。目前，若要使用其他格式的 API，必须通过开发者的另一个项目 uni-api 将其转换为 OpenAI 格式。借助 uni-api, 您可以同时在 Telegram 机器人中配置并使用数十家不同的提供商。这样做的目的是降低维护成本，因为开发者只需维护 uni-api 即可适配所有最新功能。当然，Gemini 官方也支持 OpenAI 格式的端点，例如：https://generativelanguage.googleapis.com/v1/chat/completions。

参考资料

https://core.telegram.org/bots/api

https://github.com/acheong08/ChatGPT

https://github.com/franalgaba/chatgpt-telegram-bot-serverless

https://github.com/gpchelkin/scdlbot/blob/d64d14f6c6d357ba818e80b8a0a9291c2146d6fe/scdlbot/__main__.py#L8

该消息所使用的 Markdown 渲染是我另一个项目 md2tgmd。

DuckDuckGo AI：https://github.com/mrgick/duck_chat

赞助商

我们感谢以下赞助商的支持：

• @fasizhuanqian：300 USDT

• @ZETA：$380

• @yuerbujin：¥1200

• @RR5AM：¥300

• @IKUNONHK：30 USDT

• @miya0v0：30 USDT

• @Zeabur：$25

• @Bill_ZKE：20 USDT

• @wagon_look：¥50

如何赞助我们

如果您希望支持我们的项目，可以通过以下方式赞助：

1. PayPal

2. USDT-TRC20，USDT-TRC20 钱包地址：TLFbqSv5pDu5he43mVmK1dNx7yBMFeN7d8

3. 微信

4. 支付宝

感谢您的支持！

星标历史

许可证

本项目采用 GPLv3 许可证，这意味着您可以自由地复制、分发和修改该软件，但前提是所有修改及衍生作品也必须以相同许可证发布。

ChatGPT-Telegram-Bot 快速上手指南

环境准备

在部署前，请确保你拥有以下环境和凭证：

• 运行环境：支持 Docker 的服务器（推荐），或 Python 3.9+ 环境。
• Telegram Bot Token：
  1. 在 Telegram 中搜索并打开 @BotFather。
  2. 发送 /newbot 创建新机器人。
  3. 按提示设置名称和用户名，获取最终的 BOT_TOKEN。
• 大模型 API Key：
  • OpenAI 官方 Key，或兼容 OpenAI 格式的第三方 API Key（如 One-API、New-API 等）。
  • 若需使用 Claude、Gemini 等其他模型，建议先通过 uni-api 进行统一接入。

安装步骤

推荐使用 Docker 进行一键部署，最简单且易于维护。

方法一：Docker 部署（推荐）

1. 拉取镜像

   docker pull yym68686/chatgpt:latest
   

2. 启动容器 将下方的 YOUR_BOT_TOKEN 和 YOUR_API_KEY 替换为你的实际凭证。如需持久化配置用户数据，可挂载 user_configs 目录。

   docker run -d \
     --name chatgpt-bot \
     -e BOT_TOKEN="YOUR_BOT_TOKEN" \
     -e API_KEY="YOUR_API_KEY" \
     -e MODEL="gpt-4o" \
     -v $(pwd)/user_configs:/app/user_configs \
     --restart always \
     yym68686/chatgpt:latest
   

   国内加速提示：如果拉取 Docker 镜像速度慢，建议使用国内镜像加速器（如阿里云、腾讯云容器镜像服务）配置 Docker Daemon 后重试。

方法二：无服务器部署（零成本方案）

项目支持一键部署到以下平台，适合个人免费试用：

• Koyeb / Zeabur / Replit：直接导入 GitHub 仓库，在环境变量设置中填入 BOT_TOKEN 和 API_KEY 即可启动。
• Fly.io：需安装 flyctl 命令行工具进行部署。

基本使用

部署成功后，无需重启即可通过 Telegram 客户端进行配置和使用。

1. 启动对话

在 Telegram 中搜索你设置的机器人用户名，点击 Start 或发送 /start。

2. 核心功能体验

• 日常问答：直接发送文字消息，机器人将流式返回答案。
• 多模态交互：直接发送图片、语音、PDF/TXT/MD/Python 文件，机器人会自动解析内容并回答相关问题。
• 切换模型：发送 /info 命令，点击弹出的按钮即可在不同模型组（如 GPT, Claude 等）之间切换。
• 插件使用：
  • 联网搜索：发送包含链接的消息或直接提问最新事件（需在环境变量开启 get_search_results=True 或通过 /info -> Preferences 开启）。
  • 代码解释器：发送数学问题或数据处理需求，机器人会自动编写并执行 Python 代码。

3. 群聊集成

• 将机器人邀请至群组。
• 默认行为：机器人会回复群内所有消息。
• 指定回复：设置环境变量 NICK（例如 NICK=@MyBot），机器人仅当消息以该昵称开头时才回复。
• 话题模式：在支持 Topic 的群组中，机器人可隔离不同话题的对话历史和配置。

4. 高级配置（可选）

如需修改默认行为（如白名单、系统提示词、搜索插件开关等），请在启动命令的 -e 参数中添加相应环境变量，或在运行后通过 /info -> Preferences 图形化界面动态调整。

例如，仅允许特定用户访问：

-e whitelist="123456789,987654321"

(注：用户 ID 可通过向 @userinfobot 发送消息获取)