ChatGPT-Telegram-Workers: a Telegram ChatGPT bot on Cloudflare Workers

What ChatGPT-Telegram-Workers actually solves

The problem is not calling an AI model. The problem is that a Telegram bot needs a long-running process to receive webhooks, and a long-running process needs a host, a deployment pipeline and a bill. This project removes the host. It runs the bot as a Cloudflare Worker, so Telegram posts updates to a URL that Cloudflare serves, and the Worker calls the AI provider and answers. There is no server to keep alive between messages.

The README frames the target user directly: "The simplest and fastest way to deploy your own ChatGPT Telegram bot." That is a personal-scale framing. The features list includes a web admin panel delivered as a Telegram Mini App, custom commands for switching models and presets, streaming output, text-to-image generation and a plugin system. Those are the features of a bot you run for yourself, a small group, or a community where you are willing to be the operator.

It is not a multi-tenant product. The README describes no accounts, quotas or per-user billing, so if you are looking for a service where strangers pay you for access, this is the wrong layer.

How the Worker, the KV store and the AI providers fit together

The architecture is a request handler plus a configuration store. Telegram sends an update to the Worker URL. The Worker reads its configuration from a KV namespace, which the README describes as "Simple KV-based configuration". That configuration holds the bot token and the AI provider settings. The Worker then calls the selected provider and returns the reply to Telegram.

The provider list is broad: OpenAI, Cloudflare AI, Cohere, Anthropic, Mistral, DeepSeek and Groq, with a link to a configuration document for the rest. Because the provider is a configuration value rather than a hard-coded client, switching models or vendors is a config change, not a redeploy of new code. The repository layout supports that reading: packages/ is a pnpm workspace with separate build targets for ai, config, telegram, plugins, agent, web and core, and the root package.json exposes matching scripts such as build:ai, build:config, build:telegram and build:plugins.

The web admin panel is the other half. It is a Telegram Mini App, meaning you open it from inside Telegram rather than from a browser tab, and it manages AI providers and settings. That is where you would change a model or a system prompt without editing files. The README also mentions custom commands for "quick switching of models, switching of robot presets", so the same settings are reachable from chat.

The plugin system is the extension point. The README links a plugin document and the repository has a plugins/ directory plus a build:plugins script, so plugins are compiled as part of the workspace rather than loaded at runtime from a remote URL.

Installing ChatGPT-Telegram-Workers on Cloudflare Workers

The README points at a one-click deploy button. According to the README, Cloudflare clones the repo, creates the KV namespace, asks for your bot token, and deploys. That is the shortest path and it avoids a local toolchain entirely.

If you prefer to work locally, the repository is a pnpm workspace. The Dockerfile shows the build sequence the maintainers use, installing a pinned pnpm and running the server build:

npm install -g [email protected]
pnpm install --frozen-lockfile
pnpm run build:server

The Docker image runs the built Node entry point on port 8787, which is the port the compose file publishes:

EXPOSE 8787
CMD ["node", "/app/dist/node.js"]

For a self-hosted run, docker-compose.yaml mounts two files read-only, a config.json and a wrangler.jsonc, and maps 8787:8787. The compose file ships with network_mode: 'host' and a comment saying to change it if you reach a proxy port on the host, so the default assumes host networking. Before starting the container you need both mounted files to exist on your machine, because the mounts are read-only.

There is also a .dev.vars.example at the top level, which is the conventional place for local Worker secrets. The README does not spell out the full contents, so read that file rather than guessing variable names. A first real use is then ordinary: create a bot with BotFather, put the token where the deploy flow or your local config expects it, deploy, and send the bot a message. If the Worker is reachable and the token is right, the reply comes back in the chat.

Where this design gets uncomfortable

The configuration model is the first limitation. A KV namespace is a key-value store, not a database with per-user records. The README calls the configuration simple, and it is, but simple cuts both ways: there is no described mechanism for rate limiting one noisy user, tracking spend per person, or revoking a single person's access while leaving everyone else alone. If your bot is in a group where one member discovers it can generate images, you have no documented lever short of changing the configuration for everyone.

The second limitation is operational. A Worker is only as reachable as the URL Telegram is given, and a self-hosted Docker run adds a container, a mounted config file and a port to keep alive. The repository documents no health endpoint or rollback procedure; the README is silent on what happens when a deploy breaks a working bot. Cloudflare's own dashboard is the rollback mechanism, and that is outside this project.

The third is scope. The README advertises text-to-image generation and a plugin system, but it does not describe content moderation, abuse handling or cost ceilings. Every message your bot answers is billed by whichever provider you configured. A bot that is public in any meaningful sense is a bot whose bill you cannot predict from the documentation alone. For a private bot among people you know, that is fine. For an open bot, it is the reason to look elsewhere.

Compared with a long-running bot framework

The obvious alternative is a conventional Telegram bot built on a framework such as grammY or Telegraf, running on a VPS or a container platform. The difference is not the Telegram API, which both use. It is where state and lifecycle live.

A framework bot keeps a process running. That gives you an in-memory conversation store, background jobs, scheduled tasks and a debugger you can attach to. It also gives you a server to patch, a process to restart and a bill that does not go to zero when nobody is talking. ChatGPT-Telegram-Workers inverts that: no process between messages, configuration in KV, and the platform handling the HTTP endpoint. You trade control over the runtime for not having one.

There is a second, quieter difference. A framework bot usually stores conversation history in a database you chose, so you can query it, export it or delete it. Here the configuration is KV-based and the README describes no conversation history store, so long-term memory across restarts is not something the documentation promises. If your bot needs to remember a user across days, confirm how that works before you build on it.

Licence, maintenance and upgrade cost

The project is MIT licensed, and the package.json declares "license": "MIT" with the author listed as tbxark. MIT is permissive: you can use, modify and redistribute it, including in commercial settings, provided the copyright notice and permission notice are preserved. That is a statement about the licence text, not legal advice for your situation.

The practical cost of MIT here is that you also inherit the operational surface. You are the one holding the AI provider key, the bot token and the KV namespace. Nothing in the licence obliges anyone to support your deployment.

On maintenance, the repository is not archived, and the last push was on 2026-09-14. The most recent tagged release listed is 1.10.7 from 2025-02-27. That gap between release tags and commits is worth noting: the codebase is moving, but the version number you would pin to is older than the work on master.

Upgrade cost is shaped by the v1 to v2 migration document the README links. If you are starting fresh you skip that entirely. If you are on v1, the migration path is documented and should be read before you pull. The workspace layout also means a local build pulls many packages through pnpm, so a from-source upgrade is a real build, not a file copy.

Editorial conclusion

Adopt it if you want a personal or small-group Telegram ChatGPT bot that runs on Cloudflare's free tier, you are comfortable pasting an OpenAI key into a KV-backed config, and you accept that the bot only answers people who talk to it. Do not adopt it if you need per-user quotas, billing, or a hosted service that hides the API key from you; the README describes none of those. Before you point it at real users, verify three things: that your bot token and AI provider key are stored where you expect, that the KV namespace the deploy flow creates is the one your Worker reads, and that the model and system prompt you set in the admin panel survive a redeploy.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. tbxark/ChatGPT-Telegram-Workers on GitHub