father-bot/chatgpt_telegram_bot: a self-hosted ChatGPT and Claude bot for Telegram

What the bot actually replaces

The project targets a specific annoyance: the web chat interfaces for OpenAI and Anthropic are rate limited, tied to a browser tab, and shared with everyone else on the plan. This bot moves the conversation into Telegram, where the client is already installed on the user's phone and desktop. The README frames it as putting the models "right inside Telegram, with your own API keys and no daily limits." The absence of daily limits is not a feature the project implements; it follows from the fact that requests go straight to the API provider and are billed there. There is no intermediary quota to hit.

Who it is for: one person or a small group who already pays for API access and wants a private interface. The allowed_telegram_usernames setting exists precisely for this. Leaving it empty opens the bot to anyone who finds it, which the README states plainly. A public bot on your own key is an open wallet, so the whitelist is the difference between a personal tool and a donation to strangers.

How a message travels: Telegram, bot.py, MongoDB, OpenRouter

The repository layout separates four concerns. bot/bot.py holds the Telegram handlers, streaming logic and commands. bot/openai_utils.py does model dispatch across the native OpenAI API and OpenRouter, plus token counting and vision input. bot/config.py loads three YAML files: config.yml for tokens and settings, models.yml for the model catalog with pricing and capabilities, and chat_modes.yml for the prompt text behind each of the 15 modes.

Conversation state does not live in memory. bot/database.py stores users and dialogs in MongoDB, which is why docker-compose.yml brings up a mongo service with a named volume at /data/db and a mongo-express container on port 8081 for inspection. That choice has consequences. Restarting the bot does not lose history, but it also means the bot cannot run as a single container without an external database. The compose file carries a comment reading "TODO: add auth" on the mongo service, and the port binding is restricted to 127.0.0.1, so the database is not exposed to the network by default. Anyone who edits that binding to 0.0.0.0 removes the only thing standing between an unauthenticated MongoDB and the internet.

Model routing is config-driven. OpenAI models go through the native SDK; Claude and GPT-5.5 go through OpenRouter, which requires openrouter_api_key. The README notes that any other OpenRouter-routed model works if you declare provider: openrouter in config/models.yml.

Installing it and sending a first message

The README's quick start needs three credentials: an OpenAI API key, a Telegram bot token from @BotFather, and optionally an OpenRouter key for Claude and GPT-5.5. After cloning, the config files are copied from their examples and edited in place.

mv config/config.example.yml config/config.yml
mv config/config.example.env config/config.env
# then edit config/config.yml — set telegram_token, openai_api_key (and openrouter_api_key for Claude/GPT-5.5)

The .env file holds the values docker-compose.yml interpolates, such as MONGODB_PORT, MONGODB_PATH, MONGO_EXPRESS_PORT and the mongo-express basic auth pair. The bot is then started with the compose file, passing that env file explicitly.

docker-compose --env-file config/config.env up --build

The Dockerfile builds on python:3.12-slim, installs ffmpeg (needed for voice handling), then installs requirements.txt, which pins python-telegram-bot[rate-limiter]==20.8, openai>=1.40.0,<2.0.0, tiktoken, PyYAML, pymongo and python-dotenv. The compose service runs python3 bot/bot.py and live-mounts ./config into /code/config, so editing config.yml and restarting the container applies changes without a rebuild.

Once the containers are up, message the bot on Telegram. The README lists the commands: /new for a fresh dialog, /mode to pick one of the 15 chat modes, /retry to regenerate the last answer, /settings to choose a model, /balance to see API spend, and /help. Group usage is not automatic; the README says to run /help_group_chat for setup instructions.

Where it breaks: model catalogs, vision, and the OpenRouter split

The most concrete limitation is drift between the README and reality. The supported-models table lists GPT-4o mini as the default with input at $0.00015 per 1K tokens, alongside GPT-5.5 and Claude Opus 4.8 routed through OpenRouter. Those entries come from different eras of the project, and the README's own changelog shows the model menu being refreshed in June 2026. A model name that a provider has retired will fail at request time, not at startup, so a bot can come up cleanly and only break when someone sends a message. Because models.yml is the source of truth for dispatch, that file is what to check first when a reply never arrives.

The second limitation is provider fragmentation. OpenAI models use the native API while Claude and GPT-5.5 need OpenRouter, which means two keys, two billing relationships and two sets of rate limits. The README does not document a fallback path when OpenRouter is unreachable or the key is missing; the model selection simply depends on it. If you only hold an OpenAI key, the Claude entries in the model list are decorative.

Vision is model-dependent rather than universal. The README describes sending an image so that "any vision-capable model" reads it, and the capability column in the table marks which ones qualify. Picking a non-vision model and sending a photo is a case the README does not describe. Streaming, controlled by enable_message_streaming, is a separate toggle with its own failure surface: a stream that stalls mid-answer looks different from a request that never starts.

Compared with a hosted Telegram ChatGPT bot

The obvious alternative is a public bot someone else operates, such as the project's own @jadvebot or any of the many hosted bots people search for. The difference is where the key lives and who pays. A hosted bot holds the API key, absorbs the cost, and therefore imposes its own limits, model menu and retention policy. You get zero setup and no server. You also get no control over which model answers, no access to /balance because the spend is not yours, and no way to know what happens to your conversation history.

Self-hosting inverts every one of those. You supply the key, so the bill is yours and visible through /balance. You choose the model per chat through /settings. History sits in your own MongoDB volume. The price is operational: a Docker host, a MongoDB instance, and the job of keeping the pinned dependencies current. The README's own compose file leaves MongoDB authentication as an open TODO, which is a fair summary of the maintenance burden this approach carries.

A second alternative is running the model locally behind an OpenAI-compatible endpoint. The config supports this through openai_api_base, which the README describes as a custom base URL with LocalAI given as the example, and null for the default. That path removes per-token API cost entirely, at the price of hardware and of whatever quality gap the local model has against the hosted ones.

Licence, upgrades and what maintenance costs you

The project is MIT licensed, which permits commercial use, modification and redistribution provided the copyright notice and permission notice are retained. That is a permissive arrangement and it does not oblige you to publish changes. It also means no warranty: the licence disclaims liability, so a misconfigured whitelist that lets strangers spend your API credit is your problem, not the maintainers'. This is a description of the licence text, not legal advice.

The upgrade surface is small but real. requirements.txt pins python-telegram-bot at 20.8 and bounds the OpenAI SDK below 2.0.0, so a major SDK release will not arrive silently, but it will also not be adopted without a deliberate edit. The Dockerfile pins Python 3.12. The last push to the repository was on 2026-06-14, and the most recent release, v1.6, carries the same date and the title "OpenRouter, Claude & GPT-5.5". Before that, v1.5 landed in April 2024 and v1.4 in April 2023, so release cadence has been uneven rather than steady. Plan upgrades around your own provider deprecations rather than around upstream releases.

Because config is live-mounted, most changes cost a container restart, not a rebuild. Model edits, chat-mode prompt edits and token changes all fall into that category. Only dependency or code changes require rebuilding the image.

Editorial conclusion

Adopt it if you already hold an OpenAI or OpenRouter key and want a Telegram front end you control, with per-user access control and a balance command instead of a subscription. Do not adopt it if you want a hosted service with no infrastructure, or if you cannot run MongoDB alongside the bot. Before deploying, check that config/models.yml still lists the model names your provider accepts, since the README itself mixes GPT-4o era entries with newer OpenRouter ones, and confirm whether you need the OpenRouter key for the model you intend to use.

Frequently asked questions

Official sources

1. father-bot/chatgpt_telegram_bot on GitHub
2. License: MIT
3. Project website
4. README
5. Releases